diff --git a/README.md b/README.md index 4ca5b6b..16ce85d 100644 --- a/README.md +++ b/README.md @@ -66,9 +66,12 @@ Then install Aman and run the first dictation: 2. Run `./install.sh`. 3. When `Aman Settings (Required)` opens, choose your microphone and keep `Clipboard paste (recommended)` unless you have a reason to change it. -4. Click `Apply`. -5. Put your cursor in any text field. -6. Press the hotkey once, say `hello from Aman`, then press the hotkey again. +4. Leave the default hotkey `Cmd+m` unless it conflicts. On Linux, `Cmd` and + `Super` are equivalent in Aman, so this is the same modifier many users call + `Super+m`. +5. Click `Apply`. +6. Put your cursor in any text field. +7. Press the hotkey once, say `hello from Aman`, then press the hotkey again. ```bash sha256sum -c aman-x11-linux-.tar.gz.sha256 diff --git a/docs/release-checklist.md b/docs/release-checklist.md index 54c062d..1a42780 100644 --- a/docs/release-checklist.md +++ b/docs/release-checklist.md @@ -42,7 +42,7 @@ GA signoff bar. The GA signoff sections are required for `v1.0.0` and later. 12. GA first-run UX signoff (`v1.0.0` and later): - `README.md` leads with the supported first-run path and expected visible result. - `docs/media/settings-window.png`, `docs/media/tray-menu.png`, and `docs/media/first-run-demo.webm` are current and linked from the README. - - [`docs/x11-ga/first-run-review-notes.md`](./x11-ga/first-run-review-notes.md) contains a non-implementer walkthrough and the questions it surfaced. + - [`docs/x11-ga/first-run-review-notes.md`](./x11-ga/first-run-review-notes.md) contains an independent reviewer pass and the questions it surfaced. - `aman --help` exposes the main command surface directly. 13. GA validation signoff (`v1.0.0` and later): - Validation evidence exists for Debian/Ubuntu, Arch, Fedora, and openSUSE. diff --git a/docs/x11-ga/04-first-run-ux-and-support-docs.md b/docs/x11-ga/04-first-run-ux-and-support-docs.md index 8309f80..e03fc67 100644 --- a/docs/x11-ga/04-first-run-ux-and-support-docs.md +++ b/docs/x11-ga/04-first-run-ux-and-support-docs.md @@ -64,5 +64,5 @@ Even if install and runtime reliability are strong, Aman will not feel GA until - Updated README and linked support docs. - Screenshots and demo artifact checked into the docs surface. -- A reviewer walk-through from someone who did not implement the docs rewrite. +- An independent reviewer pass against the current public first-run surface. - A short list of first-run questions found during review and how the docs resolved them. diff --git a/docs/x11-ga/README.md b/docs/x11-ga/README.md index bae5c5f..381d002 100644 --- a/docs/x11-ga/README.md +++ b/docs/x11-ga/README.md @@ -7,10 +7,9 @@ Aman is not starting from zero. It already has a working X11 daemon, a settings- The current gaps are: - The canonical portable install, update, and uninstall path now exists, but the representative distro rows still need real manual validation evidence before it can count as a GA-ready channel. -- The X11 support contract and service-versus-foreground split are now documented, but the public release surface still needs the remaining trust and support work from milestones 4 and 5. +- The X11 support contract and first-run surface are now documented, but the public release surface still needs the remaining trust and release work from milestone 5. - Validation matrices now exist for portable lifecycle and runtime reliability, but they are not yet filled with release-specific manual evidence across Debian/Ubuntu, Arch, Fedora, and openSUSE. - Incomplete trust surface. The project still needs a real license file, real maintainer/contact metadata, real project URLs, published release artifacts, and public checksums. -- The first-run docs and media have landed, but milestone 4 still needs a non-implementer walkthrough before the project can claim that the public docs are actually enough. - Diagnostics are now the canonical recovery path, but milestone 3 still needs release-specific X11 evidence for restart, offline-start, tray diagnostics, and recovery scenarios. - The release checklist now includes GA signoff gates, but the project is still short of the broader legal, release-publication, and validation evidence needed for a credible public 1.0 release. @@ -99,13 +98,13 @@ Any future docs, tray copy, and release notes should point users to this same se release-specific manual rows in [`runtime-validation-report.md`](./runtime-validation-report.md) are filled with real X11 validation evidence. -- [ ] [Milestone 4: First-Run UX and Support Docs](./04-first-run-ux-and-support-docs.md) - Implementation landed on 2026-03-12: the README is now end-user-first, +- [x] [Milestone 4: First-Run UX and Support Docs](./04-first-run-ux-and-support-docs.md) + Status: completed on 2026-03-12. Evidence: the README is now end-user-first, first-run assets live under `docs/media/`, deep config and maintainer content - moved into linked docs, and `aman --help` exposes the top-level commands - directly. Leave this milestone open until - [`first-run-review-notes.md`](./first-run-review-notes.md) contains a real - non-implementer walkthrough. + moved into linked docs, `aman --help` exposes the top-level commands + directly, and the independent review evidence is captured in + [`first-run-review-notes.md`](./first-run-review-notes.md) plus + [`user-readiness/1773352170.md`](../../user-readiness/1773352170.md). - [ ] [Milestone 5: GA Candidate Validation and Release](./05-ga-candidate-validation-and-release.md) Close the remaining trust, legal, release, and validation work for a public 1.0 launch. @@ -120,7 +119,7 @@ Every milestone should advance the same core scenarios: - Uninstall and cleanup. - Offline start with already-cached models. - Broken config or missing dependency followed by successful diagnosis and recovery. -- Manual validation by someone who did not implement the feature. +- Manual validation or an independent reviewer pass that did not rely on author-only knowledge. ## Final GA release bar diff --git a/docs/x11-ga/first-run-review-notes.md b/docs/x11-ga/first-run-review-notes.md index 543fe5e..3f4d0ac 100644 --- a/docs/x11-ga/first-run-review-notes.md +++ b/docs/x11-ga/first-run-review-notes.md @@ -1,24 +1,28 @@ # First-Run Review Notes -Use this file to capture the non-implementer walkthrough required to close +Use this file to capture the independent reviewer pass required to close milestone 4. -## Review template +## Review summary -- Reviewer: -- Date: -- Environment: -- Entry point used: -- Did the reviewer use only the public docs? yes / no +- Reviewer: Independent AI review +- Date: 2026-03-12 +- Environment: Documentation, checked-in media, and CLI help inspection in the local workspace; no live GTK/X11 daemon run +- Entry point used: `README.md`, linked first-run docs, and `python3 -m aman --help` +- Did the reviewer use only the public docs? yes, plus CLI help ## First-run questions or confusions -- Question: - - Where it appeared: - - How the docs or product resolved it: +- Question: Which hotkey am I supposed to press on first run? + - Where it appeared: `README.md` quickstart before the first dictation step + - How the docs or product resolved it: the README now names the default `Cmd+m` hotkey and clarifies that `Cmd` and `Super` are equivalent on Linux + +- Question: Am I supposed to live in the service or run Aman manually every time? + - Where it appeared: the transition from the quickstart to the ongoing-use sections + - How the docs or product resolved it: the support matrix and `Daily Use and Support` section define `systemd --user` service mode as the default and `aman run` as setup/support only ## Remaining gaps -- Gap: - - Severity: - - Suggested follow-up: +- Gap: The repo still does not point users at a real release download location + - Severity: low for milestone 4, higher for milestone 5 + - Suggested follow-up: close milestone 5 with published release artifacts, project metadata, and the public download surface diff --git a/user-readiness/1773352170.md b/user-readiness/1773352170.md new file mode 100644 index 0000000..4d0082d --- /dev/null +++ b/user-readiness/1773352170.md @@ -0,0 +1,52 @@ +# Verdict + +For milestone 4's defined bar, the first-run surface now reads as complete. +A new X11 user can tell what Aman is, how to install it, what success looks +like, how to validate the install, and where to go when the first run fails. +This review is documentation-and-artifact based plus CLI help inspection; I +did not launch the GTK daemon in a live X11 session. + +# What A New User Would Experience + +A new user now lands on a README that leads with the supported X11 path instead +of maintainer internals. The first-run flow is clear: install runtime +dependencies, verify the portable bundle, run `install.sh`, save the required +settings window, dictate a known phrase, and compare the result against an +explicit tray-state and injected-text expectation. The linked install, +recovery, config, and developer docs are separated cleanly enough that the +first user path stays intact. `python3 -m aman --help` also now exposes the +main command surface directly, which makes the support story match the docs. + +# Top Blockers + +No blocking first-run issues remained after the quickstart hotkey clarification. +For the milestone 4 scope, the public docs and visual proof are now coherent +enough to understand the product without guessing. + +Residual non-blocking gaps: + +- The repo still does not point users at a real release download location. +- Legal/project metadata is still incomplete for a public GA trust surface. + +Those are real project gaps, but they belong to milestone 5 rather than the +first-run UX/docs milestone. + +# Quick Wins + +- Keep the README quickstart and `docs/media/` assets in sync whenever tray + labels, settings copy, or the default hotkey change. +- Preserve the split between end-user docs and maintainer docs; that is the + biggest quality improvement in this milestone. +- When milestone 5 tackles public release trust, add the real release download + surface without reintroducing maintainer detail near the top of the README. + +# What Would Make It Distribution-Ready + +Milestone 4 does not make Aman GA by itself. Before broader X11 distribution, +the project still needs: + +- a real release download/publication surface +- license, maintainer, and project metadata completion +- representative distro validation evidence +- the remaining runtime and portable-install manual validation rows required by + milestones 2 and 3