docs: clarify backend startup and first API test

[lopadova]

Goal\nMake the README unambiguous for a junior who has never used AQA: start the application backend, start AQA's admin/backend, run the first test, and understand how to author a real scenario.\n\n## Changes\n- Two-process explanation with Terminal 1/Terminal 2 commands\n- Bundled Bun API absolute-beginner path\n- Concrete executable idempotency API scenario\n- Explicit risk-to-invariant-to-scenario linkage\n- Progress/lesson updates\n\n## Verification\n- README markdown link check passed\n- git diff --check passed\n- Commands compared against CLI and bundled example scripts\n\n## Review policy\nOperator has opted out of Copilot review for this side-project phase; all technical/documentation checks remain mandatory.

[cloudflare-workers-and-pages]

Deploying agentic-qa-kit with    Cloudflare Pages

Latest commit:	b3bcab8
Status:	✅  Deploy successful!
Preview URL:	https://6b2920ef.agentic-qa-kit.pages.dev
Branch Preview URL:	https://task-docs-readme-zero-to-fir.agentic-qa-kit.pages.dev

View logs

[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-20T18:53:34.113909Z	d9b279b	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.

[Copilot]

Copilot review overview

🟡 Changes recommended

The documented setup and scenario flow has multiple unresolved moderate issues that prevent reliable execution and validation.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 4

Open (4)

• Example commands use missing project files and profile · New
• Precondition does not authenticate or gate execution · New
• Idempotency check does not verify duplicate prevention · New
• Referenced risk IDs are undeclared · New

What changed in this PR

Clarifies beginner onboarding for starting the application and AQA backends, running the first test, and authoring scenarios.

Changes:

• Adds two-terminal startup instructions.
• Documents the bundled Bun API walkthrough.
• Adds an idempotency scenario and updates progress and lessons.

File	Summary	Final review findings
README.md	Beginner setup, backend usage, and scenario guidance.	7 moderate findings: initialize/build from the correct directory and use the generated profile; configure sut.base_url; provide valid risk references; authenticate supported preconditions; add stronger duplicate-prevention assertions; fix heading structure. One nit concerns the walkthrough ordering.
docs/​PROGRESS.md	Records onboarding progress.	1 nit: update the entry because the documented example flow currently fails before execution.
docs/​LESSON.md	Captures onboarding lessons.	No findings.

---

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

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d9b279bd2f

ℹ️ 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

README workflow and scenario issues currently prevent a reliable beginner setup and execution.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 2 · 5

Open (7)

• Scope http_status evaluation to the referenced probe · New
• Scope response_contains evaluation to the referenced probe · New
• Use --force instead of unsupported --overwrite flag · New
• Run root e2e:ecosystem script from repository root · New
• Avoid hard-coded idempotency key across repeated runs · New
• Add auth and JSON content type to protected POST probes · New
• Use AQA_HTTP_SECRET_QA_TOKEN for HTTP secret import · New

Resolved since last review (4)

• Referenced risk IDs are undeclared
• Idempotency check does not verify duplicate prevention
• Precondition does not authenticate or gate execution
• Example commands use missing project files and profile

Previously missed (1)

In code that hasn't changed since last review

Place terminal block after initialization and base URL configuration

README.md:410

This block is placed before the walkthrough's aqa init step, so a junior following the documented order gets .aqa/project.yaml not found before any test runs. Also, init leaves sut.base_url unset unless the user configures it, which disables the HTTP driver. Make this terminal block explicitly follow initialization and base-URL configuration.