Resolve Anvil trust and docs review findings

bin/anvil.ts

@@ -38,7 +38,10 @@ function printHelp(version: string): void {
   console.log(
     "  npx @lambdacurry/anvil <command> [...args]    Alternate launcher; Bun and Node.js >= 20 must already be installed",
   );
-  console.log("  bun add -g @lambdacurry/anvil && anvil <command> [...args]");
+  console.log("  bun add -g @lambdacurry/anvil                 Global install");
+  console.log(
+    "  anvil <command> [...args]                    Run after global install",
+  );
   console.log("");
   console.log("Commands:");
   console.log("  audit      Run full rule audit (scripts/audit.ts)");

docs-site/astro.config.mjs

@@ -43,6 +43,11 @@ export default defineConfig({
             { label: 'Drift Detection', slug: 'guides/drift-detection' },
             { label: 'Bootstrap Rules', slug: 'guides/bootstrap' },
             { label: 'Mine PR History', slug: 'guides/mine-pr' },
+          ],
+        },
+        {
+          label: 'Proof Process',
+          items: [
             { label: 'First User Proof', slug: 'guides/first-user-proof' },
             {
               label: 'First User Proof Packet',

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-19
+> Generated: 2026-07-23
 
 ## Installation
 
@@ -559,7 +559,7 @@ Only on the full AI-backed path, Anvil may send a **focused subset of audit cont
 | Drift / coverage scoring | stays local | stays local |
 | Markdown output | stays local | stays local |
 | Provider credentials | stay local | stay local |
-| Synthesis context | not sent | may be sent (opt-in only) |
+| Synthesis context | not sent | sent to an auto-detected or explicitly selected provider; use `--ci` to stay local |
 
 ## FAQ
 

docs-site/src/content/docs/guides/byok-trust-model.md

@@ -52,7 +52,7 @@ Only on the full AI-backed path, Anvil may send a **focused subset of audit cont
 | Drift / coverage scoring | stays local | stays local |
 | Markdown output | stays local | stays local |
 | Provider credentials | stay local | stay local |
-| Synthesis context | not sent | may be sent (opt-in only) |
+| Synthesis context | not sent | sent to an auto-detected or explicitly selected provider; use `--ci` to stay local |
 
 ## FAQ
 

docs/byok-trust-model.md

@@ -62,7 +62,7 @@ The intent is to send only what is needed for the optional interpretation/synthe
 | Drift / coverage scoring | stays local | stays local |
 | Markdown audit output | stays local unless you choose where to save/share it | stays local unless you choose where to save/share it |
 | Provider credentials | stay local | stay local |
-| Focused audit context for synthesis | not sent | may be sent only after explicit opt-in |
+| Focused audit context for synthesis | not sent | sent to an auto-detected or explicitly selected provider; use `--ci` to stay local |
 
 This table is the practical rule: use `--ci` when you need a fully local boundary; use the default `audit` path when you want the full AI-backed product output.
 
@@ -77,7 +77,7 @@ Anvil never sends:
 ## Operator responsibilities
 
 BYOK shifts provider trust decisions to the operator. You are responsible for:
-- choosing whether to enable provider-backed synthesis at all
+- choosing the local-only `--ci` path or the default provider-backed path
 - selecting the provider and model you trust
 - supplying provider credentials through your local environment
 - deciding whether the target repo is appropriate for external synthesis
@@ -90,7 +90,9 @@ You control provider/model selection with flags such as:
 - `--ai-provider`
 - `--ai-model`
 
-That means the operator, not Anvil, chooses whether any external provider is involved.
+The default `audit` path auto-detects an available provider. The operator chooses
+the fully local boundary by passing `--ci`, or can select a specific provider with
+the flags above.
 
 ## Practical decision rule
 

scripts/public-cli-docs-contract.test.ts

@@ -27,9 +27,35 @@ test("mine-pr docs require the gh CLI and do not promise a token-only fallback",
   );
 });
 
-test("first-user proof pages are discoverable from the public docs sidebar", () => {
+test("operator proof pages have a separate public docs sidebar section", () => {
   const config = readRepoFile("docs-site/astro.config.mjs");
 
+  expect(config).toContain("label: 'Proof Process'");
   expect(config).toContain("slug: 'guides/first-user-proof'");
   expect(config).toContain("slug: 'guides/first-user-proof-packet'");
+
+  const guidesStart = config.indexOf("label: 'Guides'");
+  const proofStart = config.indexOf("label: 'Proof Process'");
+  const referenceStart = config.indexOf("label: 'Reference'");
+  const guidesSection = config.slice(guidesStart, proofStart);
+  const proofSection = config.slice(proofStart, referenceStart);
+
+  expect(guidesSection).not.toContain("slug: 'guides/first-user-proof'");
+  expect(guidesSection).not.toContain("slug: 'guides/first-user-proof-packet'");
+  expect(proofSection).toContain("slug: 'guides/first-user-proof'");
+  expect(proofSection).toContain("slug: 'guides/first-user-proof-packet'");
+});
+
+test("BYOK docs describe provider auto-detection without an opt-in claim", () => {
+  const docs = [
+    readRepoFile("docs/byok-trust-model.md"),
+    readRepoFile("docs-site/src/content/docs/guides/byok-trust-model.md"),
+  ];
+
+  for (const doc of docs) {
+    expect(doc).not.toContain("opt-in only");
+    expect(doc).not.toContain("only after explicit opt-in");
+    expect(doc).toContain("auto-detected or explicitly selected provider");
+    expect(doc).toContain("use `--ci` to stay local");
+  }
 });

scripts/published-cli-contract.test.ts

@@ -154,8 +154,12 @@ test("CLI help spells out the supported launcher paths", () => {
     "npx @lambdacurry/anvil <command> [...args]    Alternate launcher; Bun and Node.js >= 20 must already be installed",
   );
   expect(stdout).toContain(
-    "bun add -g @lambdacurry/anvil && anvil <command> [...args]",
+    "bun add -g @lambdacurry/anvil                 Global install",
   );
+  expect(stdout).toContain(
+    "anvil <command> [...args]                    Run after global install",
+  );
+  expect(stdout).not.toContain("&& anvil");
 });
 
 test("repo README and public installation guide match the published launcher contract", () => {