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.