Add full-surface documentation refresh spec

[aram356]

Summary

Important

Retargeted on 2026-09-21: the base changed from rc/202608 to main and the head was force-pushed from the rc-scoped refresh (1c6b23a54, preserved at branch spec-docs-refresh-rc) to a docs-only transplant verified against main. The three earlier approvals were given for the rc-scoped diff and predate this change — please re-review.

Brings the documentation content of the refresh to main now, rather than waiting for the rc/202608 release merge. Scope is documentation surfaces only: the docs site, top-level and crate READMEs, the four adapter smoke scripts the guides teach, and the documentation-snippet compile test. The refresh's Rust doc-comments, route-contract tests, startup diagnostics, and CI workflow changes are not included; they land with the release merge from spec-docs-refresh-rc.

What differs from the rc-scoped version reviewers approved

Everything was re-verified against main, and the guides were re-pointed where the branches diverge:

• The rc-only ts audit ad-templates and ts config ad-templates command families are removed from the CLI guide. Every remaining documented command was probed against a ts binary built from this branch.
• check-documentation.sh is not included: main's rustdoc does not yet pass with warnings denied (29 intra-doc-link errors that the rc-scoped refresh fixes). testing.md documents the two documentation checks that do run on main.
• scripts/README.md lists only scripts that exist here; CI-gate links point at AGENTS.md (CLAUDE.md is a symlink on main).
• Conflicts with main's newer CHANGELOG.md, README.md, TESTING.md, and auction README resolved to main's side; configuration.md keeps both main's initial-deployment steps and the refresh's secret-field migration guidance.

Verification

• cd docs && npm run lint && npm run format && npm run build — clean; the build fails on dead links and passed.
• cargo test --test documentation_snippets — the documented integration fixture compiles against main's core.
• ./scripts/smoke-axum.sh — boots main's Axum adapter end to end.
• A claims scan extracted every referenced script path, repository path, and route from the transplanted docs and checked each against this tree; the only remaining flags are deliberate (the sentence stating docs/public/CNAME intentionally does not exist, and the gitignored dist/ directory).

Relation to the release branch

The full rc-scoped refresh (with the code changes and the review history above) is preserved at spec-docs-refresh-rc and merges into rc/202608 with the release. When rc later merges to main, its versions supersede these files and restore the rc-only material. Merging this PR publishes the docs site from main via deploy-docs.yml.

Follow-ups

• Pin spin in .tool-versions and add Spin to the adapter-first-success smoke matrix #1164 — pin spin and add Spin to the adapter-first-success smoke matrix.
• Resolve trusted_client_ip.shared_secret through the secret store instead of the app-config blob #1186 — move trusted_client_ip.shared_secret to secret-store resolution.
• Separate PRs for the governance amendment and the sensitive-data exception policy.

[jevansnyc]

The PR description no longer matches the branch. It still describes the docs-parity tooling that 9dfb956 removed: the "Settings parity (WP3)" block, the settings --check / generate --check / check --all gates, the docs-parity lock hash, and the CLI golden provenance. The "Final documentation-refresh acceptance" section cites head f682c05d and a 107-commit, 140,494-insertion range. The head is 5c043a32, and the diff against rc/202608 is 202 files, +6,113 / -3,602. The WP8 row says cargo doc -D warnings and doctests run in CI, but CLAUDE.md on this branch now lists them under "Manual documentation gates" and says CI does not block on them.

The description becomes the merge record, so please rewrite it against the current head. A short summary of what changed plus the test plan is enough. The generated ledger sections (SHA-256 manifests, "immutable inputs", artifact digests, the Spin receipt with an expiry date) can go; the decision record under docs/internal/audits/ already carries that material.

[jevansnyc]

On the "Review feedback" comment from 2026-09-14 (#1049 (comment)): it is posted from the PR author's account but written as a third-party review, down to "Verdict: Merge it". It also has a "Correction to something I said earlier" about {{RUST_VERSION}} rendering literally, and nobody said that anywhere on this PR. That reads like an automated review pasted verbatim. If a tool produced it, say which one at the top. A merge verdict under the author's name is confusing for anyone reading this thread later.

Two related items:

• The follow-up comment says Add a new-engineer setup page alongside the onboarding guide #1165 was closed because its content moved into this PR. Add a new-engineer setup page alongside the onboarding guide #1165 is still open as a draft against this branch. Please close it, or say what it still carries.
• "Independent review found no Critical or Important issues" appears in the last two status comments. Who or what did that review? If it is an automated pass, name the tool. Otherwise drop the line; it is not something the rest of us can check.

[prk-Jr]

Summary

Full-surface documentation refresh plus deterministic parity enforcement: 202 files, ~6.1k insertions / ~3.6k deletions against rc/202608. Reviewed the whole diff — the Rust and TypeScript changes are overwhelmingly doc comments, new #[cfg(test)] route-contract tests, and test-fixture hardening; the only runtime deltas are additive startup diagnostics on Cloudflare and Spin. Public APIs, routes, status codes, and successful-request behaviour are unchanged. All 21 GitHub checks pass on the reviewed head.

1 of the inline comments below carries a one-click GitHub suggestion — use Commit suggestion to apply it as a commit on the PR branch.

Non-blocking

♻️ refactor

• Canonical CI gate list omits the two template-cache harness steps — see inline at CLAUDE.md:382

Cross-cutting / body-level findings

• 📝 Spin startup diagnostic now writes directly to stderr — crates/trusted-server-adapter-spin/src/logging.rs replaces log::error! with a direct writeln!(io::stderr(), ...). This is a deliberate, well-documented deviation from the repo's "use log macros, not println!/eprintln!" convention: the EdgeZero Spin logger initializer is a no-op, so the boot failure would otherwise be invisible, and writing directly avoids claiming the process-global logger. Flagging it only so the exception is visible to future reviewers — no action requested.
• 📝 Cloudflare startup errors now log the full Report debug — crates/trusted-server-adapter-cloudflare/src/app.rs adds worker::console_error! with {error:?} under #[cfg(target_arch = "wasm32")]. The response body still exposes only user_message(), and this matches the pre-existing Spin behaviour, so it is not a new disclosure class. worker is an unconditional cfg(target_arch = "wasm32") dependency, so the cfg gate compiles on both the native and --features cloudflare wasm legs.
• 👍 Smoke scripts never mutate the tracked working tree — scripts/smoke-fastly.sh copies fastly.toml/edgezero.toml into an isolated mktemp -d project and symlinks crates/, so ts config push --local and the seeded ts_secrets blocks land only in the throwaway workspace. smoke_remove_workspace additionally refuses to rm -rf any path outside the generated prefix. That is a meaningfully safer shape than "mutate and restore on trap", and the three sibling scripts follow the same pattern. Secret values are obviously synthetic (smoke-admin-password-32-bytes-ok, etc.).
• 👍 Route-registration contract tests across all four adapters — complete_route_registration_set_matches_the_prechange_contract in the Fastly/Axum/Cloudflare/Spin route suites pins the exact (method, path) set, and the matching startup_error_route_set_... tests pin the fallback router. Combined with the existing parity suite this makes a silent route/method regression during a docs-driven refactor very hard to land.
• 👍 docs/public/CNAME removal and deploy-docs.yml provenance assertion — dropping the your-custom-domain.com placeholder is correct (it would have hijacked the Pages custom domain), and the new grep -R --fixed-strings "$GITHUB_SHA" .vitepress/dist step is backed by a real emitter: docs/.vitepress/config.mts injects provenanceBanner() into every page's parsed markdown and validates the SHA shape, so the assertion cannot silently pass on an unstamped build.
• 📝 Docs build is enforced on PRs — worth recording since the new Documentation checks workflow is workflow_dispatch-only: the dead-link-failing VitePress build still runs on every PR via format.yml's format-docs job ("Build with VitePress (fails on dead links)"). TESTING.md and the new ## Manual documentation gates section both state the manual-only scope explicitly, so the split is intentional and documented.

CI Status

• cargo fmt: PASS
• cargo test: PASS
• cargo test (axum native): PASS
• cargo test (cloudflare) / cargo check (cloudflare native + wasm32-unknown-unknown): PASS
• cargo check/build/test (spin native + wasm32-wasip1): PASS
• cargo test (cross-adapter parity): PASS
• cargo test (ts CLI, native): PASS
• vitest: PASS
• format-typescript: PASS
• format-docs: PASS
• prepare integration artifacts: PASS
• integration tests: PASS
• integration tests (Fastly EC lifecycle): PASS
• browser integration tests: PASS
• adapter first success (axum): PASS
• adapter first success (fastly): PASS
• adapter first success (cloudflare): PASS
• Analyze (rust): PASS
• Analyze (javascript-typescript): PASS
• Analyze (actions): PASS
• CodeQL: PASS
• Documentation checks: not run (workflow_dispatch only, by design)

No required checks are configured on this branch.

[jevansnyc]

checks out sans 2 minor comments which are fine to move forward with outside of housekeeping

[aram356]

Housekeeping from the two 2026-09-17 comments is done:

• The PR description is rewritten against the current head (1c6b23a): the withdrawn docs-parity tooling sections, stale head SHA, old diff counts, and ledger material are gone, and the rustdoc commands are described as manual gates, matching CLAUDE.md.
• The 2026-09-14 "Review feedback" comment now opens with an attribution note: it was generated by an automated Claude Code review agent and posted from my account, and its verdict and self-correction are the tool's, not a maintainer's.
• The "independent review found no Critical or Important issues" line is removed from the status comment; it referred to an automated pass I cannot attribute precisely, so it is dropped rather than named.
• Add a new-engineer setup page alongside the onboarding guide #1165 is now actually closed as superseded (the earlier claim that it was already closed was wrong, and the status comment says so).
• prk-Jr's gate-list suggestion is applied in 1c6b23a, adding the two template-cache harness steps to the canonical list.
• ChristianPavilonis's shared_secret storage-contract follow-up is filed as Resolve trusted_client_ip.shared_secret through the secret store instead of the app-config blob #1186.

[aram356]

Retargeted per maintainer decision: base is now main and the head is force-pushed to a docs-only transplant verified against main (853eb45). The rc-scoped refresh that ChristianPavilonis, prk-Jr, and jevansnyc approved is preserved unchanged at spec-docs-refresh-rc (tip 1c6b23a) and remains the content that merges into rc/202608 at release time. The approvals above predate this retarget and applied to that rc diff, so please re-review against the new, smaller diff; the description lists exactly what changed relative to the approved version. #1187, which briefly carried this transplant, is closed in favor of this PR.