Add full-surface documentation refresh spec

[aram356]

Summary

• Single PR for the full documentation refresh: the design spec plus all eight work packages land here, one commit (or small series) per package, reviewable commit-by-commit.
• The spec was synthesized from a four-track audit of main at 2e85a1cdc (VitePress site, root/crate markdown, in-code docs, config templates), every finding cited at file:line, with ground-truth inventories (routes with per-adapter availability, all 15 Settings sections, 14-integration capability matrix, ts CLI tree) as appendices.

Changes

File	Change
docs/superpowers/specs/2026-08-19-documentation-refresh-design.md	Design spec: audit findings, source-of-truth map, eight work packages, acceptance criteria
WP1 (upcoming commits)	Publishing/policy hygiene: srcExclude, CNAME, fastly.toml sensitive values, empty /guide/ page, gate alignment
WP2	Remove fabricated/dead content: dead endpoints, Equativ, RequestWrapper, .with_asset, GAM/Kargo pages, auction README rot, FAQ_POC.md, CHANGELOG/.env.example repairs
WP3	Config reference parity with all 15 Settings sections and 14 integration configs
WP4	API reference rebuilt from adapter route tables with availability matrix
WP5	New pages: deployment guides, EdgeZero, telemetry/Tinybird, tsjs, GPT handoff, adserver_mock, script guards; nav repair; TESTING.md rewrite
WP6	Root markdown and crate READMEs
WP7	In-code docs: core module index, platform/ docs, crate headers, tsjs JSDoc
WP8	Enforcement: docs build on PRs, cargo doc -D warnings, doctests in CI, dependabot gaps

Closes

Closes #1038
Closes #277
Closes #341

Test plan

• Docs format: cd docs && npm run format (passes on the spec)
• Docs build: cd docs && npm run lint && npm run build (after WP commits land)
• cargo fmt --all -- --check and target-matched clippy/tests for crates touched by WP7
• cargo doc --no-deps warning-free for core and adapters (WP7/WP8)
• Acceptance greps from WP2-WP4 included in this description when work lands
• Other: spec content verified against main at 2e85a1cdc by four parallel read-only audits, then realigned to rc/202608 (new [cache] section, admin EC diagnostics routes, restructured CLI)

Checklist

• Changes follow CLAUDE.md conventions
• No secrets or credentials committed

Settings parity (WP3)

Generated from the checked settings record at 18f4d6b2eb2abdaef43b0b5f4b8c15d52be3eba0.

Settings roots (17/17)

• [auction]
• [cache]
• [consent]
• [creative_opportunities]
• [debug]
• [ec]
• [[handlers]]
• [image_optimizer]
• [integrations.*]
• [proxy]
• [publisher]
• [request_signing]
• [response_headers]
• [rewrite]
• [tester_cookie]
• [tinybird]
• [trusted_client_ip]

Deploy-validated integration IDs (14/14)

• adserver_mock
• aps
• datadome
• didomi
• google_tag_manager
• gpt
• gpt_diagnostics
• lockr
• nextjs
• osano
• permutive
• prebid
• sourcepoint
• testlight

Provider profile schemas (3/3; 14 fields)

Profile	Fields	Provider timeout default
aps	5	800 ms
prebid-server	7	1000 ms
standard	2	Auction timeout

Directional field dispositions (18/18)

The checked axes are lifecycle, key identity, serialization, runtime use, and secret handling.

Path	Lifecycle	Key identity	Serialization	Runtime	Secret handling
AssetOriginAuth.s3_sig_v4	deprecated	alias of AssetOriginAuth.s3_sigv4	skipped	deserialization only	none
DataDomeConfig.server_side_key_secret_name	canonical	canonical	serialized	active	store resolved
DataDomeConfig.server_side_key_secret_store	deprecated	canonical	skipped	normalized away	none
DataDomeProtectionTestBypassConfig.credential_secret_name	canonical	canonical	serialized	active	store resolved
DataDomeProtectionTestBypassConfig.credential_secret_store	deprecated	canonical	skipped	normalized away	none
Ec.passphrase	canonical	canonical	serialized	active	store resolved
EcPartner.api_token	canonical	canonical	serialized	active	store resolved
EcPartner.ts_pull_token	canonical	canonical	serialized	active	store resolved
Handler.password	canonical	canonical	serialized	active	store resolved
Publisher.proxy_secret	canonical	canonical	serialized	active	store resolved
S3SigV4AuthConfig.access_key_id	canonical	canonical	serialized	active	store resolved
S3SigV4AuthConfig.secret_access_key	canonical	canonical	serialized	active	store resolved
S3SigV4AuthConfig.secret_store	deprecated	canonical	skipped	normalized away	none
S3SigV4AuthConfig.session_token	canonical	canonical	serialized	active	store resolved
TinybirdSettings.access_token_secret	deprecated	canonical	skipped	normalized away	accepted, then discarded
TinybirdSettings.auction_token_secret	canonical	canonical	serialized	active	store resolved
TinybirdSettings.secret_store	deprecated	canonical	skipped	normalized away	none
TrustedClientIpConfig.shared_secret	canonical	canonical	serialized	active	deliberately inline

Secret classifications

• 11 store-resolved paths: publisher proxy secret; EC passphrase and two partner-token paths; handler password; Tinybird auction token; DataDome server key and test-bypass credential; S3 access key, secret key, and optional session token.
• trusted_client_ip.shared_secret is deliberately inline and may appear in diff/dry-run/confirmation output.
• tinybird.access_token_secret is accepted, discarded, and omitted from serialized config.
• The four deprecated secret_store selectors are accepted and normalized away; none is recommended by the example template.

Exact WP3 checks

• settings --check, generate --check, snippets --check, classify --check, scan --check, links --local --check, and check --all
• Standalone docs-parity: format, all-target/all-feature clippy with warnings denied, and 398 tests
• cargo test-fastly config: 12 Fastly adapter tests and 199 core tests selected; no failures
• Docs: ESLint, Prettier, and VitePress build
• Root and standalone Cargo lockfile hashes unchanged; origin/rc/202608 remains 07dfc1c6dddf69345ded17bd2d40a3d01bb39bcf

Adapter first-success smokes (WP5 deployment)

Hosted receipts use implementation SHA 2f1f11c2cf94cf0b5606e107672d6386d283959a. The Spin receipt was repeated at 552dbeebe63aa6c742f2def95565bfcc80076513; the smoke script is byte-identical at both commits.

Axum

./scripts/smoke-axum.sh

Sequence: resolve/build ts and the Axum binary; start an isolated loopback sentinel origin; initialize and strictly validate the app config; run ts config push --adapter axum --local; read the generated envelope; launch one isolated Axum process for missing config, each missing secret, and the positive case.

Cleanup: the EXIT INT TERM trap stops the active Axum process and sentinel origin, then removes the generated temporary workspace and .edgezero state.

Oracle: HTTP 200; body contains SMOKE_ORIGIN_SENTINEL; rewritten URL targets the Axum listener; original origin URL is absent. Independent failures: missing TRUSTED_SERVER_CONFIG; missing handlers[0].password; missing publisher.proxy_secret; missing ec.passphrase. Each failure requires HTTP 500, its exact startup diagnostic, and live adapter/origin processes.

Receipt: Integration Tests / adapter smoke (Axum).

Fastly

./scripts/smoke-fastly.sh

Sequence: resolve/build ts and release Wasm; start an isolated loopback sentinel origin; initialize and strictly validate the app config; prove /health is 200 while an unconfigured publisher request fails; run ts config push --adapter fastly --local; seed the three ts_secrets entries; remove each secret independently; restore all entries and run the positive publisher case through fastly compute serve.

Cleanup: the EXIT INT TERM trap stops the active Fastly process and sentinel origin, restores fastly.toml byte-for-byte, restores or removes .fastly.toml.edgezero-lock according to its initial state, and removes the temporary workspace.

Oracle: HTTP 200; body contains SMOKE_ORIGIN_SENTINEL; rewritten URL targets the Fastly listener; original origin URL is absent. Independent failures: missing config-store key while health remains 200; missing handler_password; missing publisher_proxy_secret; missing ec_passphrase. Each publisher failure requires HTTP 500, its exact startup diagnostic, and live Fastly/origin processes.

Receipt: Integration Tests / adapter smoke (Fastly).

Cloudflare

./scripts/smoke-cloudflare.sh

Sequence: require the exact Wrangler pin; resolve/build ts and the Worker bundle; start an isolated loopback sentinel origin; initialize and strictly validate the app config; map the logical store to TRUSTED_SERVER_KV; run ts config push --adapter cloudflare --local; read trusted_server_config back with the explicit binding and local flags; encode the envelope as TRUSTED_SERVER_CONFIG.app_config; generate one isolated Wrangler manifest per missing binding and the positive case; run each with wrangler dev.

Cleanup: the EXIT INT TERM trap stops the active Wrangler process and sentinel origin and removes the temporary workspace, including generated manifests and local Wrangler KV state.

Oracle: HTTP 200; body contains SMOKE_ORIGIN_SENTINEL; rewritten URL targets the Wrangler listener; original origin URL is absent. Independent failures: missing env.TRUSTED_SERVER_CONFIG; missing env.handler_password; missing env.publisher_proxy_secret; missing env.ec_passphrase. Each failure requires HTTP 500, a binding inventory that omits only the selected binding while retaining its control binding, the normalized exact diagnostic, and live Wrangler/origin processes.

Receipt: Integration Tests / adapter smoke (Cloudflare).

Spin

./scripts/smoke-spin.sh

Sequence: resolve/build ts and release Wasm; start an isolated loopback sentinel origin; initialize and strictly validate the app config; prove a pre-push publisher request fails; map the logical store to default; run ts config push --adapter spin --local; launch one spin up process with each encoded secret variable omitted independently; launch the positive case with all three variables.

Cleanup: the EXIT INT TERM trap stops the active Spin process and sentinel origin and removes the temporary workspace, including the generated manifest, component logs, and .spin/sqlite_key_value.db.

Oracle: HTTP 200; body contains SMOKE_ORIGIN_SENTINEL; rewritten URL targets the Spin listener; original origin URL is absent. Independent failures: missing default/trusted_server_config; missing encoded handler-password variable; missing encoded publisher-proxy-secret variable; missing encoded EC-passphrase variable. Each failure requires HTTP 503, the controlled config-push/one-variable delta, the normalized exact diagnostic, and live Spin/origin processes; a generic degraded-router 503 is insufficient.

Time-bounded receipt: local run passed at 552dbeebe63aa6c742f2def95565bfcc80076513 with Spin 4.1.0 (c0b3726, 2026-08-25), Rust 1.95.0 on aarch64-apple-darwin, and owner documentation-maintainers; expires 2026-10-07T00:00:00Z.

Final documentation-refresh acceptance

• Exact head: f682c05df07f89bdbda61c2372d3f3f34e5c8de2
• Exact base: 07dfc1c6dddf69345ded17bd2d40a3d01bb39bcf (rc/202608)
• Base range: 107 commits, 267 paths, 140,494 insertions, and 3,300 deletions.
• Hosted workflows on that exact head: Run Format — success, Documentation automation — success, Run Tests — success, Integration Tests — success, and CodeQL Advanced — success.
• Check publishers: GitHub Actions published the format, documentation, test, capture, and integration checks; GitHub Advanced Security published CodeQL. Representative exact-head jobs: Format documentation parity, Documentation automation parity, Linux CLI capture, macOS CLI capture, browser integration, and Rust CodeQL.
• Local acceptance: the complete Task 18 matrix and Task 19 remediation matrix passed, including release WASM builds; all four first-success smokes; docs lint, format, and build; JavaScript lint, format, 13 builds, and 949 tests with type checking; warning-denied rustdoc/doctests; generated no-diff checks; actionlint; shellcheck and bash -n for the seven workflow scripts; and standalone docs-parity formatting, warning-denied Clippy, full tests, and check --all. The final docs-parity run passed 38 library, 35 classification, 27 CLI, 13 CLI-help, five dependency, six gate, 33 integration, two JSDoc, 62 link, 11 Markdown, two README, 70 route, 74 scanner, 24 settings, five snippet, and seven workflow tests. The reviewed sensitive manifest is SHA-256 007c971f2d2b5bf1db923cf3ea45501917069a9a2a2b3534ff10e507abcc9661 and governs 5,476 exact occurrences without changing the exception count.
• Workflow policy: every external action uses an exact reviewed release tag; no action is SHA-pinned or branch-pinned. Every new multi-command workflow operation delegates to one of seven checked shell scripts. The new workflow and writer implementation does not invoke Python.
• Runtime scope: Cloudflare and Spin add only startup diagnostic logging required by the negative smokes. Public APIs, routes, response bodies, status behavior, and successful-request behavior are unchanged.
• Documentation scope: public onboarding moved to docs/internal/onboarding.md under the approved containment package; the public documentation was rewritten and expanded across configuration, routes, integrations, all four adapters, testing, telemetry, TSJS, architecture, and deployment. This change is a documentation refresh plus deterministic parity enforcement, not tooling alone.
• Immutable inputs: root Cargo.lock SHA-256 9bb34225c5b8d1da39c75c3a8143d905f4b7d228a8986dc93d7e58a4196b4bba; docs-parity lock SHA-256 234a21b4831ec92fca081bc389dad6bdff1bc18d3a715f41831e2067a95e2ffb.
• CLI golden provenance: authenticated source workflow 34316723321 at 0dcf054063dd6f746b1bb44ca58418d23efae887; Linux artifact ID 10090397245, digest sha256:ff23327b542aca834c118a53313f50722164a1f92a52a563543979907310e7f4; macOS artifact ID 10090451966, digest sha256:1844e6f1536b375fec8a7a92a18a6403831f289f5710d40684ae8fee4619563a. Two authenticated imports retained Linux help SHA-256 d1cae561a509fac817befdca1ba733a2582dba87d322cf4c2efccce9729a6786, macOS help SHA-256 cecd3a524ff6c50459b446dfe95980be0cdb037e1934ea0ab2a389aa6472f450, and capture-manifest SHA-256 fc51a476a716e7b18ccd4a0dd9b912698448d78a26ecc65b7d1c139a4b3ddf2c. The exact-final-head capture jobs also passed without changing the reviewed goldens.
• Release-pending, not claimed here: live Pages/CNAME verification after merge to main; the first real scheduled external-link run; dependency submission plus graph visibility; and optional main branch-protection activation after the new contexts report from the expected apps. The committed release runbook owns these operations.