Add full-surface documentation refresh spec

.claude/commands/check-ci.md

@@ -1,11 +1,5 @@
-Run all CI checks locally, in order. Stop and report if any step fails.
+Run every check in the [canonical CI gate list](/CLAUDE.md#ci-gates), in its
+documented order. Stop and report if any gate fails.
 
-1. `cargo fmt --all -- --check`
-2. `cargo clippy-fastly && cargo clippy-axum && cargo clippy-cloudflare`
-3. `cargo test-fastly && cargo test-axum && cargo test-cloudflare`
-4. `cargo check-cloudflare` (wasm32-unknown-unknown target check, mirrors CI)
-5. `cd crates/trusted-server-js/lib && npx vitest run`
-6. `cd crates/trusted-server-js/lib && npm run format`
-7. `cd docs && npm run format`
-
-Report a summary of all results when done.
+Report the result of each canonical gate. Do not maintain a separate gate list
+in this command.

.claude/commands/review-changes.md

@@ -1,5 +1,8 @@
 Review all staged and unstaged changes in the working tree.
 
+Use the [canonical CI gate list](/CLAUDE.md#ci-gates) as the sole source for
+required verification. Do not copy its commands into this file.
+
 1. Run `git diff` and `git diff --cached` to see all changes.
 2. Review each changed file for:
    - Correctness and logic errors

.claude/commands/test-all.md

@@ -1,13 +1,6 @@
-Run the full test suite for both Rust and JavaScript.
+Run the Rust and JavaScript test gates from the
+[canonical CI gate list](/CLAUDE.md#ci-gates). Do not maintain a separate test
+command list in this file.
 
-```bash
-cargo test-fastly && cargo test-axum && cargo test-cloudflare
-```
-
-Then run JS tests:
-
-```bash
-cd crates/trusted-server-js/lib && npx vitest run
-```
-
-Report results for both. If any test fails, investigate and suggest a fix.
+Report each test-gate result. If a test fails, investigate it before reporting
+the command complete.

.claude/commands/test-crate.md

@@ -2,16 +2,10 @@ Test a specific crate by name.
 
 Usage: /test-crate $ARGUMENTS
 
-Run:
+Use the target-aware test rules referenced by the
+[canonical CI gate list](/CLAUDE.md#ci-gates). Select the canonical adapter or
+JavaScript gate that covers `$ARGUMENTS`; do not substitute a bare workspace
+test. For a host-only crate without a covering alias, follow the host-target
+procedure in `CLAUDE.md`.
 
-```bash
-cargo test -p $ARGUMENTS
-```
-
-If $ARGUMENTS is "js" or "javascript", run:
-
-```bash
-cd crates/trusted-server-js/lib && npx vitest run
-```
-
-Report results and investigate any failures.
+Report the selected canonical rule and its result. Investigate any failure.

.claude/commands/verify.md

@@ -1,12 +1,5 @@
-Full verification: build, test, and lint the entire project.
+Run full repository verification from the
+[canonical CI gate list](/CLAUDE.md#ci-gates). That region is the sole source
+for required gate commands; do not maintain a copy here.
 
-1. `cargo build-fastly && cargo build-axum && cargo build-cloudflare`
-2. `cargo build --package trusted-server-adapter-fastly --release --target wasm32-wasip1`
-3. `cargo fmt --all -- --check`
-4. `cargo clippy-fastly && cargo clippy-axum && cargo clippy-cloudflare`
-5. `cargo test-fastly && cargo test-axum && cargo test-cloudflare`
-6. `cd crates/trusted-server-js/lib && npx vitest run`
-7. `cd crates/trusted-server-js/lib && npm run format`
-8. `cd docs && npm run format`
-
-Report results for each step. Stop and investigate if any step fails.
+Report every canonical gate result. Stop and investigate if any gate fails.

.github/pull_request_template.md

@@ -21,22 +21,15 @@ Closes #
 
 ## Test plan
 
-<!-- How did you verify this works? Check all that apply -->
-
-- [ ] `cargo test-fastly && cargo test-axum`
-- [ ] `cargo clippy-fastly && cargo clippy-axum`
-- [ ] `cargo fmt --all -- --check`
-- [ ] JS tests: `cd crates/trusted-server-js/lib && npx vitest run`
-- [ ] JS format: `cd crates/trusted-server-js/lib && npm run format`
-- [ ] Docs format: `cd docs && npm run format`
-- [ ] WASM build: `cargo build --package trusted-server-adapter-fastly --release --target wasm32-wasip1`
-- [ ] Manual testing via `fastly compute serve`
-- [ ] Other: <!-- describe -->
+<!-- Follow the canonical gates; do not copy their command list here. -->
+
+- [ ] Completed the [canonical CI gate list](/CLAUDE.md#ci-gates)
+- Evidence: <!-- Record exact results and any scoped additional checks. -->
 
 ## Checklist
 
 - [ ] Changes follow [CLAUDE.md](/CLAUDE.md) conventions
 - [ ] No `unwrap()` in production code — use `expect("should ...")`
-- [ ] Uses `tracing` macros (not `println!`)
+- [ ] Uses `log` macros (not `println!`)
 - [ ] New code has tests
 - [ ] No secrets or credentials committed

AGENTS.md

@@ -17,13 +17,20 @@ If you cannot read `CLAUDE.md`, follow these rules:
 
 1. Present a plan and get approval before coding.
 2. Keep changes minimal — do not refactor unrelated code.
-3. Run tests after every code change — use the workspace aliases defined in `.cargo/config.toml`:
-   - `cargo test-fastly` — Fastly adapter + core (wasm32-wasip1 via Viceroy)
-   - `cargo test-axum` — Axum dev server adapter (native)
-   - `cargo test-cloudflare` — Cloudflare Workers adapter (native host)
-   Do NOT use bare `cargo test --workspace` — it will attempt to compile the Fastly adapter for the host target.
-4. Run `cargo fmt --all -- --check` and `cargo clippy-fastly && cargo clippy-axum && cargo clippy-cloudflare`.
-5. Run JS tests with `cd crates/trusted-server-js/lib && npx vitest run` when touching JS/TS code.
-6. Use `error-stack` (`Report<E>`) for error handling — not anyhow, eyre, or thiserror.
-7. Use `log` macros (not `println!`) and `expect("should ...")` (not `unwrap()`).
-8. Target is `wasm32-wasip1` — no Tokio or OS-specific dependencies in core crates.
+
+<!-- BEGIN GENERATED CI GATES: source CLAUDE.md#ci-gates -->
+
+Every PR must pass:
+
+1. `cargo fmt --all -- --check`
+2. `cargo clippy-fastly && cargo clippy-axum && cargo clippy-cloudflare && cargo clippy-cloudflare-wasm && cargo clippy-spin-native && cargo clippy-spin-wasm`
+3. `cargo test-fastly && cargo test-axum && cargo test-cloudflare && cargo test-spin`
+4. `cargo test --manifest-path crates/trusted-server-integration-tests/Cargo.toml --test parity`
+5. JS build and test (`cd crates/trusted-server-js/lib && npx vitest run`)
+6. JS format (`cd crates/trusted-server-js/lib && npm run format`)
+7. Docs format (`cd docs && npm run format`)
+<!-- END GENERATED CI GATES -->
+
+8. Use `error-stack` (`Report<E>`) for error handling — not anyhow, eyre, or thiserror.
+9. Use `log` macros (not `println!`) and `expect("should ...")` (not `unwrap()`).
+10. Target is `wasm32-wasip1` — no Tokio or OS-specific dependencies in core crates.

CLAUDE.md

@@ -274,6 +274,12 @@ impl core::error::Error for MyError {}
 - Do not write or commit real domains, customer names, credentials,
   configuration values, or other potentially sensitive real-world information in
   comments, tests, docs, or examples.
+- Sensitive-data exceptions are limited to these types: vendor URL,
+  hash-pinned fake-credential fixture, historical example, service ID, and
+  project-owned public domain.
+- Record every exception before use with its exact type and scope, owner,
+  rationale, and expiry timestamp. Ownerless, expired, broad, or untyped
+  exceptions are prohibited.
 
 ---
 

docs/.vitepress/config.mts

@@ -38,6 +38,14 @@ export default withMermaid(
     description:
       'Edge computing for ad serving, consent signal handling, and edge cookie (EC) generation',
     base: '/trusted-server',
+    srcExclude: [
+      'superpowers/**',
+      'internal/**',
+      'epics/**',
+      'guide/onboarding.md',
+      'README.md',
+      'business-use-cases.md',
+    ],
 
     // Replace version placeholders like {{NODEJS_VERSION}} with values from .tool-versions
     markdown: {
@@ -58,8 +66,7 @@ export default withMermaid(
       // https://vitepress.dev/reference/default-theme-config
       nav: [
         { text: 'Home', link: '/' },
-        { text: 'Guide', link: '/guide/getting-started' },
-        { text: 'Business Value', link: '/business-use-cases' },
+        { text: 'Guide', link: '/guide/' },
         { text: 'Roadmap', link: '/roadmap' },
       ],
 

docs/business-use-cases.md

@@ -1,5 +1,11 @@
 # Business Use Cases
 
+> [!CAUTION]
+> **Unverified planning material.** The claims, metrics, projections, and
+> capabilities in this document have not been validated against the current
+> implementation. Do not treat them as shipped behavior or product
+> commitments.
+
 Scenarios where publishers can realize measurable value with Trusted
 Server across revenue, consent handling, performance, and user
 experience.

docs/guide/index.md

@@ -0,0 +1,30 @@
+# Guide
+
+Use these guides to understand Trusted Server, configure a deployment, and
+contribute to the project.
+
+## Start here
+
+- [What is Trusted Server?](/guide/what-is-trusted-server)
+- [Getting Started](/guide/getting-started)
+
+## Core concepts
+
+- [Edge Cookies](/guide/edge-cookies)
+- [GDPR Compliance](/guide/gdpr-compliance)
+- [Ad Serving](/guide/ad-serving)
+- [First-Party Proxy](/guide/first-party-proxy)
+- [Asset Routes](/guide/asset-routes)
+
+## Development
+
+- [Architecture](/guide/architecture)
+- [Configuration](/guide/configuration)
+- [CLI](/guide/cli)
+- [Testing](/guide/testing)
+- [Integration Guide](/guide/integration-guide)
+
+## Reference
+
+- [API Reference](/guide/api-reference)
+- [Error Reference](/guide/error-reference)