# Milestone 4: First-Run UX and Support Docs

## Why this milestone exists

Even if install and runtime reliability are strong, Aman will not feel GA until a first-time user can understand it quickly. This milestone makes the supported path obvious and removes author-only knowledge from the initial experience.

## Problems it closes

- The current README mixes end-user, maintainer, and benchmarking material too early.
- There is no short happy path with an expected visible result.
- The repo has no screenshots or demo artifact showing that the desktop workflow is real.
- The support and diagnostics story is not yet integrated into first-run documentation.
- CLI help discoverability is weaker than the documented command surface.

## In scope

- Rewrite the README so the top of the file is end-user-first.
- Split end-user, developer, and maintainer material into clearly labeled sections or separate docs.
- Add a 60-second quickstart that covers:
  - runtime dependency install
  - portable Aman install
  - first launch
  - choosing a microphone
  - triggering the first dictation
  - expected tray or notification behavior
  - expected injected text result
- Add a "validate your install" flow using `aman doctor` and `aman self-check`.
- Add screenshots for the settings window and tray menu.
- Add one short demo artifact showing a single install-to-dictation loop.
- Add troubleshooting for the common failures identified in milestone 3.
- Update `aman --help` so the top-level command surface is easy to discover.
- Align README language, tray copy, About/Help copy, and diagnostics wording.

## Out of scope

- New GUI features beyond what is needed for clarity and supportability.
- New branding or visual redesign unrelated to usability.
- Wayland onboarding.

## Dependencies

- Milestone 1 support contract.
- Milestone 2 install/update/uninstall flow.
- Milestone 3 diagnostics and recovery model.

## Definition of done: objective

- The README leads with the supported user path before maintainer content.
- A 60-second quickstart exists and includes an expected visible result.
- A documented install verification flow exists using diagnostics.
- Screenshots exist for the settings flow and tray surface.
- One short demo artifact exists for the happy path.
- Troubleshooting covers the top failure classes from milestone 3.
- Top-level CLI help exposes the main commands directly.
- Public docs consistently describe service mode, manual mode, and diagnostics.

## Definition of done: subjective

- A first-time evaluator can understand the product without guessing how it behaves.
- Aman feels like a user-facing desktop tool rather than an internal project.
- The docs reduce support load instead of creating new questions.

## Evidence required to close

- Updated README and linked support docs.
- Screenshots and demo artifact checked into the release or docs surface.
- A reviewer walk-through from someone who did not implement the docs rewrite.
- A short list of first-run questions found during review and how the docs resolved them.