[joemooney]

People can begin AIDA through the conversational coding workflow they already use. The newcomer guide separates operator setup, explains durable intent and capture limits, and renders from one Markdown source into the static showcase. README/overview entry copy, first-project links, mobile entry and uninstall guidance agree with that journey. Setup help precedes initialization, Markdown entry links resolve, and the shared template hides its decorative brand symbol.

Validation at author head 1b3eeaa9956bce0c5d156b6f2045579a7c6b9016: make check-ci-fast completed all 35 gates successfully at this exact head. Guide output was rebuilt from its source and shared template; this change adds no runtime authority or deployment behavior. Two fresh author self-check rounds caught and removed an unsupported link-description promise; the final round found no scoped findings. Author checks provide no independent approval or merge-hold clearance. Advisor review and bottom-up integration remain required.

[joemooney]

Advisor review of the whole docs stack 3096-3103 is in the AIDA mailbox (to codex, subject 'Docs stack 3096-3103: restack onto main + review rulings'). Summary: rebase the stack onto main, keeping main's #3093 intro sentence; #3102 must keep 'run aida init in a fresh clone'; bundle the listed small fixes in one push, then each PR gets a fresh review and ships bottom-up.

[joemooney]

Review: PR-3096 — ⚠️ Request changes (round 1, head 0282a96)

Acceptance criterion	Status	Evidence
AC1 conversational journey, operator setup labeled separately, no mutation commands or autonomy required	✅ verified	docs/getting-started.md: conversation-first sections; separate ## One-time operator setup section; "Autonomous delivery is an option… not a prerequisite"
AC2 guide and site page agree; overview/README route readers to it	⚠️ partial	README Quick start, what-is-aida.{md,html}, and first-project.md route correctly. docs/README.md:21, docs/user-guide.md:15 and OVERVIEW.md:1048 still describe the old install/first-requirement guide
AC3 one source renders into the shared accessible layout (navigation, provenance, local assets); thin build	⚠️ unverified by test	Reviewer re-ran build.py in isolation and the output matched byte-for-byte. Template has a skip link, lang, a labeled nav, aria-current, a source link, and local CSS. No drift check exists
AC4 no promise of automatic capture; CLI/MCP facts verified	✅ verified	"AIDA does not automatically record every utterance…". MCP is opt-in via init_cmd.rs:554,559 (generate_mcp_json = claude && with_mcp). --agent, --footprint full and aida dev status match --help

Findings

1. minor (AC2): docs/README.md:21, docs/user-guide.md:15 and OVERVIEW.md:1048 still describe the guide as covering install (cargo/binary/Docker/source) and a first requirement. Update them to the new framing.
2. minor (AC3 untested): nothing checks that getting-started.html matches the build.py output. Add a --check mode, or a small test reachable from check-ci-fast.
3. cosmetic: the site page's "AIDA overview" link opens raw ../what-is-aida.md, even though ../what-is-aida.html exists.
4. cosmetic: the index.html "Getting started" button is now an internal link but still shows the external ↗ glyph.
5. cosmetic: build.py inline() applies the link and bold regexes inside code spans. This is latent: the current source doesn't trigger it.
6. cosmetic: the "existing AIDA project" sentence should link README.md#cloning-an-existing-aida-project.

CI: all green at head (run 40980731224).
Rework: aida rework TASK-B6B1278890774EF993D2EBC327862470-106 --work --resume --reason "PR-3096 review: fix stale guide descriptions + add HTML drift check"

[joemooney]

Advisor ruling — docs stack round 2 (reviewed heads 3096@0282a960 … 3103@d2257801). Rule-once: this is the whole round; no follow-up PRs.

APPROVED as-is: 3097, 3098, 3099, 3100, 3103 (their non-blocking nits are bundled below or accepted).
CHANGES REQUIRED: 3096, 3101, 3102.

HOW TO APPLY (important — avoids re-reviewing all eight):

• Do NOT rebase or force-push. Add NEW commits on the affected branch, then propagate upward by MERGING each lower branch into the next one up (106-work -> 107-work -> ... -> 113-work), plain pushes.
• Approved PRs whose own diff is unchanged get a base-only re-record; only 3096, 3101, 3102 and 3103 (which carries the bundle) get fresh reviews.

3096 (TASK-106) — fix on branch task-…-106-work:
a. AC2: update the routing entries that still describe the old guide: docs/README.md:21, docs/user-guide.md:15, OVERVIEW.md:1048 (install now lives in README#install).
b. build.py inline(): map what-is-aida.md -> what-is-aida.html.
c. docs/showcase/index.html: drop the external-link glyph on the now-internal Getting started button.
d. docs/getting-started.md: link README.md#cloning-an-existing-aida-project from the 'existing AIDA project' sentence.
Accepted (no change): inline() backtick/regex ordering — latent, no current source hits it.
AC3 drift check: satisfied by the shared --check in 3101 below.

3101 (TASK-111) — fix on branch task-…-111-work:
a. Add python3 docs/showcase/build.py --check (render every generated output to memory, diff against the tracked files, non-zero exit naming each drifted file; covers getting-started.html, library.html, search-data.js and every manifest page). Wire it into .github/workflows/ci.yml next to python3 docs/cli/verify-manual.py --static so make check-ci-fast runs it.
b. Search index: strip Markdown links to their text (text -> text) instead of a blanket character-class strip; keep legitimate punctuation.
c. Reject duplicate manifest outputs and the reserved names library.html / index.html.
d. Drop the dead .guide table / .table-scroll CSS (no table rendering exists).
e. Replace the whole-page 'the source guide' string replace with a template placeholder for the footer provenance.
f. library.js: compute the excerpt offset on the same string you slice.

3102 (TASK-112) — fix on branch task-…-112-work:
a. docs/storage-modes.md:79-83 'New developer setup': add the aida init (or aida node acquire) step before any spec creation, matching operator-setup.md:17 / README.md:93 / getting-started.md:48.
b. docs/cli/10-storage.md:155, docs/storage-modes.md:51, docs/admin-guide.md:231: reword 'auto-rebuilt' / 'stale-check rebuilds automatically' to the bounded-read contract of the chapter intro.
c. docs/multi-node.md 'Check identity and routing': restore the per-user queue-file inspection (ls .aida-store/registry/queues/ or aida queue list --local --user <other>) and the concrete fix (pin export AIDA_USER=<id> per machine; --user for one-offs).

3103 (TASK-113) — bundle on branch task-…-113-work (after merging 112 into it):
a. Report reproduction commands use the pinned base 1db74db and a three-dot diff.
b. Swap the severity: onboarding/MCP misstatements Critical-or-Important as appropriate; the broken admin-guide link not above them.
c. build.py: move import sys to module imports; parse --overview with the existing argument handling.
d. Bundled from approved slices: build.py alt text uses the SVG's <title>/ (fixes 3097/3098/3099 generic alt); index.html 'Configure your operating model ↗' wraps the arrow in an aria-hidden span; page-template.html puts {{graphic}} after the h1; docs/showcase/README.md lists every generated page, not only getting-started; docs/configuration-guide.md:11,39 says aida protocol list / aida protocol seed before aida protocol show task --lane docs.
Accepted (no change): 14px SVG labels (the SVG scales; readable at mobile width); repo-relative source links (the showcase is published from the repo).

Validate: make check-ci-fast (now including build.py --check). Then mail the advisor the new head SHAs of all eight; I will re-review 3096/3101/3102/3103 and ship bottom-up.

[joemooney]

Review: PR-3096 — head 4661f8a1cd3 (3 commits; reviewed via merge-base diff)

Acceptance criterion	Status	Evidence
AC1 conversational journey; operator setup labeled separately; no mutation commands or autonomy required	✅ verified	docs/getting-started.md (conversation → record → return → delegate; ## One-time operator setup)
AC2 guide + site entry page agree; overview/README route to it	⚠️ partial	README, OVERVIEW, what-is-aida (md+html), user-guide, docs/README and showcase index route correctly. But the rewrite left stale inbound references in first-project.md (findings 1–2)
AC3 one source renders into shared accessible layout, thin build path	✅ verified manually	python3 docs/showcase/build.py reproduces getting-started.html byte-identically; styles.css+guide.css; skip link, lang, aria-current, footer provenance. No automated freshness check (finding 3)
AC4 no promise to record every utterance; CLI/MCP facts current	✅ verified	capture-limits paragraph; --with-mcp opt-in (init_cmd.rs:554,559), --agent, --footprint full, aida mcp-serve, aida dev status match --help/source

Findings

1. minor: docs/first-project.md:78 points to an aida init inventory at getting-started.md#one-time-operator-setup, but the inventory no longer exists. Repoint it to cli/01-getting-started.md#aida-init.
2. minor: docs/first-project.md:9 (install link) and :522 ("install options and the command quick-reference") describe content the rewrite removed.
3. minor: no regeneration/diff check keeps showcase/getting-started.html in sync with build.py. All four ACs are untraced.
4. cosmetic: the build.py docstring claims emphasis support, but only **strong** is implemented.
5. cosmetic: the operator block runs aida init before aida init --help.
6. cosmetic: in page-template.html, the brand ✳ is not aria-hidden (index.html hides it).
7. cosmetic: the README links showcase/getting-started.html, which GitHub shows as raw source.

CI: all required jobs green; merge-hold-gate red as expected (hold marker).
Verdict: Request changes. One small doc round should clear all seven.

[joemooney]

Final-round author update at 1b3eeaa9956bce0c5d156b6f2045579a7c6b9016.

Corrected the first-project installation/setup references and next-step description, narrowed builder support prose to bold, put init help before init, hid the decorative brand glyph in the shared template/output, and linked README to the Markdown source.

All lower-stack fixes are included by ordinary merges; no rebases or force pushes. Two fresh author self-check rounds: removed a newly introduced target-description promise identified in round 1; round 2 found no scoped findings. These are author checks, with no independent-review or hold-clearance authority.

Validation: make check-ci-fast completed all 35 gates successfully at this exact head

[joemooney]

Review: PR-3096 (head 1b3eeaa, 26 commits behind main; diff taken from the merge-base)

Spec	Verdict	Evidence
TASK-B6B1278890774EF993D2EBC327862470-106	✅ PASS	see below

Acceptance criteria

• Conversational journey, separate operator setup, no mutation commands or autonomous delivery required. Verified in docs/getting-started.md: the conversation sections come first, the "One-time operator setup" section is labeled, and the guide says "You do not need to memorize requirement-mutation commands" and "Autonomous delivery is an option… not a prerequisite."
• Guide and site entry agree; overview and README route readers to the guide; no unrelated rewrites. Verified: docs/showcase/getting-started.html is generated from the same source. README Quick start, OVERVIEW.md:1048, docs/README.md, docs/user-guide.md and what-is-aida.{md,html} link to the guide. index.html adds a nav entry and the CTA.
• One source page in the shared, accessible layout, with navigation, provenance and local assets; thin build. Verified: build.py (95 lines, stdlib only, one entry in PAGES). The template has a skip link, aria-current, an aria-hidden glyph and a "Generated from the source guide" footer, and uses local styles.css and guide.css. Re-running python3 docs/showcase/build.py reproduces the committed HTML byte for byte.
• No promise of total capture; CLI/MCP facts checked against help. Verified: the guide says "AIDA does not automatically record every utterance or observe work outside those tools." The --with-mcp opt-in, the --agent profiles and the mcp-serve stdio claims match current aida init --help and aida mcp-serve --help. All link anchors resolve: README #install and #cloning-an-existing-aida-project, cli/01-getting-started.md#aida-init, cli/07, cli/10 and the MCP matrix.

Round-3 advisor items (1, 2, 4, 5, 6, 7): all fixed at this head. Item 3 was accepted with no action.

CI: green at 1b3eeaa (run 41071572528). merge-hold-gate is the hold from the earlier changes-requested round. It is not a code failure.

Non-blocking follow-ups (filed as findings):

1. docs/first-project.md:74-75 and docs/cli/01-getting-started.md:13 still say aida init writes the MCP registration. MCP is now opt-in via --with-mcp, as the new guide correctly says. This belongs to the operator-reference refresh slice.
2. build.py has no --check mode and no gate runs it, so the generated page can drift from its source. The round-3 rationale "gated by build.py --check" does not match the code.

Recommendation: Approved.