fix(docs): match first-audit output contract

[jaruesink]

What changed

• describe the real first-run terminal summary plus saved Markdown report
• name the default report path and clarify that --output selects a path
• remove the stale unqualified alpha.5 proof-packet cue
• retain a current alpha.6 smoke packet and add a docs contract assertion

Why

Resolves SFD-271. The prior success text promised Markdown on stdout even though alpha.6 prints progress and scores, then writes the full report to disk.

Verification

• bun run lint
• bun run format:check
• bun run typecheck
• bun test
• npm run build in docs-site
• rendered-page text checks for both affected pages
• pinned alpha.6 smoke run retained in docs/proofs/internal/2026-07-19-sfd-271-doc-output-contract.md

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 98a16c85-cda0-4494-bc8b-8214a20fd4e0

📥 Commits

Reviewing files that changed from the base of the PR and between 0b369de and 4d500cc.

📒 Files selected for processing (5)

• docs-site/public/llms-full.txt
• docs-site/src/content/docs/guides/first-user-proof-packet.md
• scripts/first-user-proof-docs.test.ts
• scripts/proof-lane-contract.ts
• scripts/verify-proof-lane-docs.ts

---

📝 Walkthrough

Summary by CodeRabbit

• Documentation

  • Updated first-audit guidance to reflect terminal progress, then a concise score summary, followed by a “Audit report written: ” message.
  • Clarified default report location (docs/audits/<repo>-audit-<date>.md) and how --output controls the save path (including relative paths from the current working directory).
  • Hard-pinned the first-user proof packet walkthrough to 0.1.0-alpha.6 and aligned the related --version cross-check examples.
  • Replaced older success/output samples with a new “Example terminal finish” snippet.

• Tests

  • Strengthened automated checks for the updated success text, report-path expectations, and pinned proof-packet command layouts.

Walkthrough

The documentation now describes audit results as concise terminal summaries followed by saved Markdown reports, including default and explicit output paths. Proof-packet guidance is pinned to 0.1.0-alpha.6, with an internal contract record and automated documentation assertions.

Changes

Audit output documentation

Layer / File(s)	Summary
Document saved report flow docs-site/src/content/docs/getting-started/first-audit.md, docs-site/public/llms-full.txt	First-audit guidance now documents terminal score summaries, Audit report written: <path>, default report locations, --output path selection, and AI-backed report priorities.
Pin proof packet and record output contract docs-site/src/content/docs/guides/first-user-proof-packet.md, docs-site/public/llms-full.txt, docs/proofs/internal/2026-07-19-sfd-271-doc-output-contract.md	Proof-packet instructions use the pinned 0.1.0-alpha.6 repo-root command, while the internal contract records the observed saved-report behavior.
Validate public documentation wording scripts/proof-lane-contract.ts, scripts/verify-proof-lane-docs.ts, scripts/first-user-proof-docs.test.ts	Exported command contracts, verification expectations, and tests enforce pinned commands, saved-report wording, default path guidance, and the absence of stdout-oriented descriptions.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• lambda-curry/anvil#69: Updates related first-run documentation contract assertions.
• lambda-curry/anvil#72: Covers related proof-packet version and saved-report wording assertions.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately summarizes the docs change to the first-audit output contract.
Description check	✅ Passed	The description covers what changed, why, and verification, but it does not follow the template exactly and omits the review checklist section.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/sfd-271-first-audit-output-contract

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs-site/src/content/docs/guides/first-user-proof-packet.md`:
- Line 22: Enforce the alpha.6 proof-version contract across all affected sites:
in docs-site/src/content/docs/guides/first-user-proof-packet.md:22, replace the
variable-version wording and command with the literal `@0.1.0-alpha.6` command;
regenerate docs-site/public/llms-full.txt:662 with that same command; and update
scripts/first-user-proof-docs.test.ts:166-170 to assert the exact alpha.6
command while rejecting <exact-version> and `@alpha`.

In `@scripts/first-user-proof-docs.test.ts`:
- Around line 166-170: Update the assertions in the first-user proof packet test
to require the literal command reference `@0.1.0-alpha.6`, rather than only
checking its descriptive sentence. Add negative assertions rejecting
@<exact-version>, floating `@alpha`, and variable-version examples so the public
proof workflow remains pinned to the exact published CLI version.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 94fd0564-7193-4479-9bcc-78b6c5a14485

📥 Commits

Reviewing files that changed from the base of the PR and between 5679390 and 0b369de.

📒 Files selected for processing (5)

• docs-site/public/llms-full.txt
• docs-site/src/content/docs/getting-started/first-audit.md
• docs-site/src/content/docs/guides/first-user-proof-packet.md
• docs/proofs/internal/2026-07-19-sfd-271-doc-output-contract.md
• scripts/first-user-proof-docs.test.ts