fix(docs): match first-audit output contract

docs-site/public/llms-full.txt

@@ -3,7 +3,7 @@
 > AI rules audit engine — score, detect drift, and improve rules in any AI-assisted codebase.
 
 > Source: https://lambda-curry.github.io/anvil/
-> Generated: 2026-07-18
+> Generated: 2026-07-19
 
 ## Installation
 
@@ -241,8 +241,9 @@ anvil audit \
 
 **Success looks like this:**
 
-- Anvil prints a markdown report right away
-- you see rule files found, coverage gaps, and drift issues
+- the terminal shows progress, then a concise score summary
+- the final terminal line names the saved Markdown report: `Audit report written: <path>`
+- without `--output`, the report is saved under `docs/audits/<repo>-audit-<date>.md` relative to the directory where you ran Anvil
 - nothing leaves your machine
 
 ## If you already have a provider and want the richer report
@@ -307,35 +308,29 @@ If no provider is available, rerun the recommended first run above.
 1. **Discovery** — Anvil finds all rule surface files (CLAUDE.md, AGENTS.md, `.cursor/rules/`, `ai-rules/`, etc.)
 2. **Drift detection** — stale globs, missing path references, date-stale entries
 3. **Coverage scoring** — gaps against a community baseline of common rule categories
-4. **Report** — scored markdown output to stdout; on the full AI-backed lane, this includes synthesized improvement priorities when a provider is available
+4. **Report** — the terminal prints a concise score summary and the full Markdown report is written to the path named by `Audit report written: <path>`; on the full AI-backed lane, the saved report includes synthesized improvement priorities when a provider is available
 
-## Example output
+## Example terminal finish
 
 ```text wrap
-Anvil Audit — /path/to/my-repo
-Rule files found: 3
-Guardrail score: 22/35
-
-Coverage gaps:
-  • No rule covers: error handling patterns
-  • No rule covers: security/secrets hygiene
-
-Drift issues (2):
-  • CLAUDE.md:14 — glob 'src/legacy/**' matches 0 files (medium)
-  • AGENTS.md:8 — referenced path 'docs/arch.md' not found (low)
+✅ Structural Lint Score: 78/100 (3.9/5)
+✅ Guardrail Readiness Score: 22/35 (Established)
+✅ Audit report written: /path/to/my-repo/docs/audits/my-repo-audit-2026-07-19.md
 ```
 
+Open the reported path to read the full Markdown audit, including coverage gaps, drift issues, and remediation guidance.
+
 ## After your first successful audit
 
-### Save the report
+### Choose the report path
 
 ```bash wrap
 bunx @lambdacurry/anvil audit \
   --target ./my-repo \
   --output ./audit-report.md
 ```
 
-The `--output` flag writes the full markdown report to the specified path. Relative paths resolve from your current shell cwd.
+Anvil always saves the full Markdown report. Use `--output` when you want to choose its path instead of the default `docs/audits/<repo>-audit-<date>.md`. Relative paths resolve from your current shell cwd.
 
 ### AI provider behavior
 
@@ -661,11 +656,10 @@ Paste the single command below from that repo's root; it saves `./anvil-audit.md
 Send back whether it worked first try, the first useful fix the report pointed to, and the saved report file or excerpt.
 
 ```bash wrap
-bunx @lambdacurry/anvil@<exact-version> audit --target . --ci --output ./anvil-audit.md
+bunx @lambdacurry/anvil@0.1.0-alpha.6 audit --target . --ci --output ./anvil-audit.md
 ```
 
-Replace `<exact-version>` with the published build you want validated. The alpha.5 proof packet uses one repo-root saved-report command so the tester is not choosing between layouts.
-The pinned `0.1.0-alpha.6` proof packet uses `--ci`.
+The current proof packet is pinned to `0.1.0-alpha.6` and uses one repo-root saved-report command with `--ci`, so the tester is not choosing between versions or layouts.
 
 Helpful docs:
 - Getting started: https://lambda-curry.github.io/anvil/getting-started/first-audit
@@ -686,7 +680,7 @@ If you want one extra cross-check, this should print the same pinned version:
 
 ```bash wrap
 bunx \
-  @lambdacurry/anvil@<exact-version> \
+  @lambdacurry/anvil@0.1.0-alpha.6 \
   --version
 ```
 
@@ -721,7 +715,7 @@ Save one small packet with these fields:
 - `Saved report path or screenshot link`
 - `Follow-up issue or doc fix created`
 
-If the tester used global `anvil`, keep both the pinned `bun add -g @lambdacurry/anvil@<exact-version>` line and the `anvil audit ...` line together in `Exact command`. If the tester stayed on `bunx` or `npx`, keep the optional `--version` line on that same launcher instead of switching to global `anvil`.
+If the tester used global `anvil`, keep both the pinned `bun add -g @lambdacurry/anvil@0.1.0-alpha.6` line and the `anvil audit ...` line together in `Exact command`. If the tester stayed on `bunx` or `npx`, keep the optional `--version` line on that same launcher instead of switching to global `anvil`.
 If the packet keeps the local report path, keep the same path the retained audit command wrote with `--output`; use a screenshot or approved external link only when the retained artifact is intentionally something else.
 
 Count the proof as complete only if the tester is outside Lambda Curry, the run succeeds on a real repo, the retained audit command keeps the pinned `0.1.0-alpha.6` local-only `--ci` spelling, the packet includes a real artifact, and any rough edge becomes a follow-up.

docs-site/src/content/docs/getting-started/first-audit.md

@@ -66,8 +66,9 @@ anvil audit \
 
 **Success looks like this:**
 
-- Anvil prints a markdown report right away
-- you see rule files found, coverage gaps, and drift issues
+- the terminal shows progress, then a concise score summary
+- the final terminal line names the saved Markdown report: `Audit report written: <path>`
+- without `--output`, the report is saved under `docs/audits/<repo>-audit-<date>.md` relative to the directory where you ran Anvil
 - nothing leaves your machine
 
 ## If you already have a provider and want the richer report
@@ -132,35 +133,29 @@ If no provider is available, rerun the recommended first run above.
 1. **Discovery** — Anvil finds all rule surface files (CLAUDE.md, AGENTS.md, `.cursor/rules/`, `ai-rules/`, etc.)
 2. **Drift detection** — stale globs, missing path references, date-stale entries
 3. **Coverage scoring** — gaps against a community baseline of common rule categories
-4. **Report** — scored markdown output to stdout; on the full AI-backed lane, this includes synthesized improvement priorities when a provider is available
+4. **Report** — the terminal prints a concise score summary and the full Markdown report is written to the path named by `Audit report written: <path>`; on the full AI-backed lane, the saved report includes synthesized improvement priorities when a provider is available
 
-## Example output
+## Example terminal finish
 
 ```text wrap
-Anvil Audit — /path/to/my-repo
-Rule files found: 3
-Guardrail score: 22/35
-
-Coverage gaps:
-  • No rule covers: error handling patterns
-  • No rule covers: security/secrets hygiene
-
-Drift issues (2):
-  • CLAUDE.md:14 — glob 'src/legacy/**' matches 0 files (medium)
-  • AGENTS.md:8 — referenced path 'docs/arch.md' not found (low)
+✅ Structural Lint Score: 78/100 (3.9/5)
+✅ Guardrail Readiness Score: 22/35 (Established)
+✅ Audit report written: /path/to/my-repo/docs/audits/my-repo-audit-2026-07-19.md
 ```
 
+Open the reported path to read the full Markdown audit, including coverage gaps, drift issues, and remediation guidance.
+
 ## After your first successful audit
 
-### Save the report
+### Choose the report path
 
 ```bash wrap
 bunx @lambdacurry/anvil audit \
   --target ./my-repo \
   --output ./audit-report.md
 ```
 
-The `--output` flag writes the full markdown report to the specified path. Relative paths resolve from your current shell cwd.
+Anvil always saves the full Markdown report. Use `--output` when you want to choose its path instead of the default `docs/audits/<repo>-audit-<date>.md`. Relative paths resolve from your current shell cwd.
 
 ### AI provider behavior
 

docs-site/src/content/docs/guides/first-user-proof-packet.md

@@ -16,11 +16,10 @@ Paste the single command below from that repo's root; it saves `./anvil-audit.md
 Send back whether it worked first try, the first useful fix the report pointed to, and the saved report file or excerpt.
 
 ```bash wrap
-bunx @lambdacurry/anvil@<exact-version> audit --target . --ci --output ./anvil-audit.md
+bunx @lambdacurry/anvil@0.1.0-alpha.6 audit --target . --ci --output ./anvil-audit.md
 ```
 
-Replace `<exact-version>` with the published build you want validated. The alpha.5 proof packet uses one repo-root saved-report command so the tester is not choosing between layouts.
-The pinned `0.1.0-alpha.6` proof packet uses `--ci`.
+The current proof packet is pinned to `0.1.0-alpha.6` and uses one repo-root saved-report command with `--ci`, so the tester is not choosing between versions or layouts.
 
 Helpful docs:
 - Getting started: https://lambda-curry.github.io/anvil/getting-started/first-audit
@@ -41,7 +40,7 @@ If you want one extra cross-check, this should print the same pinned version:
 
 ```bash wrap
 bunx \
-  @lambdacurry/anvil@<exact-version> \
+  @lambdacurry/anvil@0.1.0-alpha.6 \
   --version
 ```
 
@@ -76,7 +75,7 @@ Save one small packet with these fields:
 - `Saved report path or screenshot link`
 - `Follow-up issue or doc fix created`
 
-If the tester used global `anvil`, keep both the pinned `bun add -g @lambdacurry/anvil@<exact-version>` line and the `anvil audit ...` line together in `Exact command`. If the tester stayed on `bunx` or `npx`, keep the optional `--version` line on that same launcher instead of switching to global `anvil`.
+If the tester used global `anvil`, keep both the pinned `bun add -g @lambdacurry/anvil@0.1.0-alpha.6` line and the `anvil audit ...` line together in `Exact command`. If the tester stayed on `bunx` or `npx`, keep the optional `--version` line on that same launcher instead of switching to global `anvil`.
 If the packet keeps the local report path, keep the same path the retained audit command wrote with `--output`; use a screenshot or approved external link only when the retained artifact is intentionally something else.
 
 Count the proof as complete only if the tester is outside Lambda Curry, the run succeeds on a real repo, the retained audit command keeps the pinned `0.1.0-alpha.6` local-only `--ci` spelling, the packet includes a real artifact, and any rough edge becomes a follow-up.

docs/proofs/internal/2026-07-19-sfd-271-doc-output-contract.md

@@ -0,0 +1,33 @@
+# SFD-271 — first-run output contract recheck
+
+**Date:** 2026-07-19 04:22 CT
+**Package:** `@lambdacurry/anvil@0.1.0-alpha.6`
+**Target:** current `lambda-curry/anvil` checkout at `5679390`
+
+## Exact smoke command
+
+```bash
+bunx @lambdacurry/anvil@0.1.0-alpha.6 audit \
+  --target . \
+  --ci \
+  --output /tmp/sfd-271-anvil-audit.md
+```
+
+## Observed result
+
+- Exit code: `0`
+- Terminal output showed progress and ended with a concise score summary.
+- The full Markdown report was written to the named path; it was not printed to stdout.
+- The saved report contained 382 lines and began with `# Anvil Audit — repo`.
+
+Terminal finish:
+
+```text
+✅ Structural Lint Score: 98/100 (4.9/5)
+✅ Guardrail Readiness Score: 35/35 (Hardened)
+✅ Audit report written: /tmp/sfd-271-anvil-audit.md
+```
+
+## Documentation disposition
+
+The public First Audit page now describes the observed terminal summary plus saved-report behavior, names the default `docs/audits/<repo>-audit-<date>.md` path, and explains that `--output` selects a path rather than enabling report saving. The public proof packet now presents only the current pinned `0.1.0-alpha.6` story; the unqualified alpha.5 cue was removed.

scripts/first-user-proof-docs.test.ts

@@ -12,6 +12,7 @@ import {
   plainRepoRootExactVersionAuditCommand,
   threeLineOpener,
   wrappedExactVersionCommand,
+  wrappedPinnedVersionCommand,
 } from "./proof-lane-contract.ts";
 
 const REPO_ROOT = resolve(import.meta.dir, "..");
@@ -105,21 +106,22 @@ test("public proof guides mirror the current-version opener contract", () => {
 
   for (const doc of [publicGuide, publicPacket]) {
     expectAll(doc, [...threeLineOpener]);
-    expectAll(doc, [
-      plainRepoRootExactVersionAuditCommand,
-      "exact pinned command",
-      "unpinned examples",
-    ]);
+    expectAll(doc, ["exact pinned command", "unpinned examples"]);
     expect(doc).not.toContain("--output ./your-repo/anvil-audit.md");
     expect(doc).not.toContain("```bash\n");
   }
 
+  expect(publicGuide).toContain(plainRepoRootExactVersionAuditCommand);
+
   expectAll(publicPacket, [
-    joinCommandLines(wrappedExactVersionCommand),
+    plainPinnedRepoRootAuditCommand,
+    joinCommandLines(wrappedPinnedVersionCommand),
     "Install path: bunx / npx / global install",
     "Saved report path or screenshot link",
     `retained audit command keeps the pinned \`${version}\` local-only \`--ci\` spelling`,
   ]);
+  expect(publicPacket).not.toContain("@<exact-version>");
+  expect(publicPacket).not.toContain("@lambdacurry/anvil@alpha");
 });
 
 test("first-run docs fence proof testers away from floating alpha commands", () => {
@@ -146,6 +148,32 @@ test("first-run docs fence proof testers away from floating alpha commands", ()
   }
 });
 
+test("first-run success text matches the terminal summary and saved Markdown report", () => {
+  const firstAudit = readRepoFile(
+    "docs-site/src/content/docs/getting-started/first-audit.md",
+  );
+  const publicPacket = readRepoFile(
+    "docs-site/src/content/docs/guides/first-user-proof-packet.md",
+  );
+
+  expectAll(firstAudit, [
+    "the terminal shows progress, then a concise score summary",
+    "Audit report written: <path>",
+    "docs/audits/<repo>-audit-<date>.md",
+    "Anvil always saves the full Markdown report.",
+  ]);
+  expect(firstAudit).not.toContain("prints a markdown report right away");
+  expect(firstAudit).not.toContain("scored markdown output to stdout");
+
+  expect(publicPacket).toContain(
+    "The current proof packet is pinned to `0.1.0-alpha.6` and uses one repo-root saved-report command with `--ci`",
+  );
+  expect(publicPacket).toContain(plainPinnedRepoRootAuditCommand);
+  expect(publicPacket).not.toContain("@<exact-version>");
+  expect(publicPacket).not.toContain("@lambdacurry/anvil@alpha");
+  expect(publicPacket).not.toContain("The alpha.5 proof packet");
+});
+
 test("getting-started and BYOK notes match the current pinned packet", () => {
   const guide = readRepoFile("docs/getting-started.md");
   const byok = readRepoFile("docs/byok-trust-model.md");
@@ -203,10 +231,10 @@ test("generated llms-full preserves the pinned proof-lane handoff contract", ()
   const llmsFull = readRepoFile("docs-site/public/llms-full.txt");
 
   expectAll(llmsFull, [
-    "keep using the exact pinned `bunx @lambdacurry/anvil@<exact-version> ...` command from that outreach note",
+    `The current proof packet is pinned to \`${version}\` and uses one repo-root saved-report command with \`--ci\``,
     pinnedProofPacketUsesCiNote,
     "https://lambda-curry.github.io/anvil/guides/first-user-proof-packet",
-    plainRepoRootExactVersionAuditCommand,
+    plainPinnedRepoRootAuditCommand,
   ]);
 
   expect(llmsFull).not.toContain(

scripts/proof-lane-contract.ts

@@ -85,6 +85,10 @@ export const wrappedParentDirExactVersionAuditCommand =
 
 export const wrappedExactVersionCommand = buildWrappedVersionCommandLines();
 
+export const wrappedPinnedVersionCommand = buildWrappedVersionCommandLines({
+  packageToken: `@lambdacurry/anvil@${expectedVersion}`,
+});
+
 export const wrappedPinnedRepoRootAuditCommand = buildWrappedAuditCommandLines({
   output: canonicalSavedReportPath,
   packageToken: `@lambdacurry/anvil@${expectedVersion}`,

scripts/verify-proof-lane-docs.ts

@@ -8,7 +8,7 @@ import {
   plainPinnedRepoRootAuditCommand,
   plainRepoRootExactVersionAuditCommand,
   threeLineOpener,
-  wrappedExactVersionCommand,
+  wrappedPinnedVersionCommand,
 } from "./proof-lane-contract.ts";
 
 export { expectedVersion } from "./proof-lane-contract.ts";
@@ -118,8 +118,8 @@ const HOMEPAGE_FIRST_AUDIT_BLOCK = [
   "  --ci",
 ] as const;
 const PROOF_PACKET_BLOCKS = [
-  [plainRepoRootExactVersionAuditCommand],
-  wrappedExactVersionCommand,
+  [plainPinnedRepoRootAuditCommand],
+  wrappedPinnedVersionCommand,
 ] as const;
 const FIRST_USER_PROOF_BLOCKS = [
   [plainRepoRootExactVersionAuditCommand],