Skip to content

Update trusted server documentation for August 2026 release #1038

Description

@aram356

Description

Update Trusted Server documentation across all surfaces for the August 2026 release.

A full-surface audit (VitePress site, root/crate markdown, in-code docs, config templates) found systemic drift: fabricated/dead content (nonexistent endpoints, Equativ, removed config keys), incomplete references (5 of 15 Settings sections undocumented, 7 of 14 integrations missing from the overview), missing coverage (no Cloudflare/Spin/Axum deployment guides, no telemetry/tsjs/EdgeZero pages, 7 of 10 crates without READMEs), publishing hygiene (75 internal spec/plan files published to the public site, sensitive values in fastly.toml), and zero CI enforcement of doc correctness.

Design spec: docs/superpowers/specs/2026-08-19-documentation-refresh-design.md (PR #1049, branch spec-docs-refresh), including per-surface source-of-truth map, full audit finding index with file:line citations, and ground-truth inventories (routes, config sections, integration capability matrix, CLI tree).

Work packages (all land in PR #1049 together with the spec, one commit per package)

  • WP1: Publishing and policy hygiene (srcExclude, CNAME, fastly.toml sensitive values, empty /guide/ page, slash-command/PR-template gate alignment)
  • WP2: Remove fabricated and dead content (dead endpoints, Equativ, RequestWrapper, GAM/Kargo pages, auction README rot, FAQ_POC.md, CHANGELOG/.env.example repairs)
  • WP3: Configuration reference completion (trusted-server.example.toml + configuration.md parity with all 15 Settings sections and 14 integration configs)
  • WP4: API reference rebuild from adapter route tables with per-adapter availability matrix
  • WP5: New coverage pages and navigation repair (deployment guides, EdgeZero, telemetry/Tinybird, tsjs, GPT handoff, adserver_mock; un-orphan real integration pages; TESTING.md rewrite)
  • WP6: Root markdown and crate READMEs (README/CONTRIBUTING refresh, READMEs for 7 crates, governance corrections)
  • WP7: In-code documentation (core module index, platform/ docs, crate headers, key module docs, tsjs JSDoc)
  • WP8: Enforcement (docs build on PRs, cargo doc -D warnings in CI, doctests actually running, dependabot gaps)

Absorbed issues

PR #1049 also resolves #277 (nonexistent .with_asset in integration docs, folded into WP2) and #341 (script_guard coverage in the integration guide, folded into WP5).

Done when

  • Every endpoint, config key, command, and code path named in documentation exists in code on main, with adapter-specific availability stated.
  • Every shipped surface is documented: all 14 integration IDs, 15 config sections, 4 deployment targets, all ts commands, telemetry, tsjs.
  • The public docs site publishes only intended pages; no sensitive real-world values remain in tracked config.
  • CI fails on dead docs links, broken intra-doc links, and failing doctests.

Affected area

Documentation

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

Projects

No projects

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions