docs: make README production-grade and junior-friendly

[lopadova]

Goal\nRewrite the README so a junior can install AQA, run a first project journey, understand the product and see its differentiators versus conventional testing tools.\n\n## Included\n- Complete shipped feature inventory and honest evidence boundary\n- Differentiator comparison matrix and concrete ecommerce example\n- Source, package and ecosystem installation paths\n- Copy/paste first-project walkthrough\n- CI, replay, ingestion, mutation/holdout, DR and custom-pack examples\n- Updated roadmap/status references and documentation lessons\n\n## Verification\n- Explicit README and roadmap link checks passed with markdown-link-check\n- git diff --check passed\n- CLI help was compared against documented commands\n- The repository's technical CI remains required\n\n## Review policy\nThe operator previously opted out of Copilot review for this side-project phase; no secrets or production-provider claims are introduced. Technical CI gates remain mandatory.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-20T11:15:04.297813Z	2eef964	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[cloudflare-workers-and-pages]

Deploying agentic-qa-kit with    Cloudflare Pages

Latest commit:	edf4509
Status:	✅  Deploy successful!
Preview URL:	https://fd2a42f9.agentic-qa-kit.pages.dev
Branch Preview URL:	https://task-docs-readme-product-ref.agentic-qa-kit.pages.dev

View logs

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2eef964591

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Copilot review overview

🟡 Changes recommended

Several new copy/paste instructions fail on clean checkouts or use invalid CLI arguments.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 8 · 1

Open (9)

• Install Playwright browsers before running the E2E suite · New
• Use the package bin mapping for the aqa executable · New
• Separate Bash and PowerShell command examples · New
• Use a finding ID from the generated report · New
• Document GitHub Packages authentication in the CI workflow · New
• Correct risk baseline output and overwrite behavior · New
• Use the generated run ID instead of the seed value · New
• Provide a base URL when running aqa verify · New
• Move the progress entry to the newest-first position · New

What changed in this PR

This PR makes the documentation more comprehensive and junior-friendly while clarifying repository versus production evidence boundaries.

Changes:

• Adds product inventory, comparison matrix, and ecommerce example.
• Adds installation paths, first-project walkthrough, CI setup, and cookbook examples.
• Updates roadmap status and records documentation lessons.

File	Description
README.md	Expanded onboarding and product documentation.
docs/​PROGRESS.md	Records the README refresh.
docs/​LESSON.md	Adds documentation truthing guidance.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🟡 Changes recommended

Several documented commands and workflows can mislead first-time users or fail on repeat execution.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 1 · 4

Open (5)

• Make the CLI version check report the installed package version · New
• Use a shell-safe relative path instead of the placeholder · New
• Link the risk to a scenario or clarify authoring is required · New
• Refer to the run directory instead of a finding directory · New
• Add the new pack to the selected profile · New

Resolved since last review (9)

• Provide a base URL when running aqa verify
• Use the generated run ID instead of the seed value
• Correct risk baseline output and overwrite behavior
• Document GitHub Packages authentication in the CI workflow
• Use a finding ID from the generated report
• Separate Bash and PowerShell command examples
• Use the package bin mapping for the aqa executable
• Install Playwright browsers before running the E2E suite
• Move the progress entry to the newest-first position

[Copilot]

Copilot review overview

🔵 Needs a closer look

The published-package path lacks the newly documented commands, and the DR example omits the signed release-gate command.

Review effort: Lite
Findings: None

Resolved since last review (5)

• Make the CLI version check report the installed package version
• Add the new pack to the selected profile
• Refer to the run directory instead of a finding directory
• Link the risk to a scenario or clarify authoring is required
• Use a shell-safe relative path instead of the placeholder

Previously missed (2)

In code that hasn't changed since last review

Published CLI package lacks documented v2 commands

README.md:191

Path B is not executable for the v2 commands documented below. The latest tagged release (v1.10.0) still packages @aqa/kit 1.9.0, and its CLI does not expose verify, ingest, dr, risk, or mutation; a junior following this published-package path will hit unknown-command errors. Either publish/version a bundle containing these verbs and pin that version here, or explicitly limit Path B to the older CLI surface and route the v2 examples through the source path.

Restore validation does not perform release-gate binding

README.md:594

The commands shown above do not perform the release-gate binding: aqa dr restore only validates restore evidence against the inventory. Signed production evidence is bound only by the separate aqa dr release-gate ... --public-key ... --public-key-id ... command, so this paragraph currently overstates what the example proves. Add that invocation or state explicitly that the shown commands stop at internal consistency validation.