docs: establish Docbank's authority-led public site

[wesm]

Docbank gets one public surface with three tiers: a product page at /, an authority-lifecycle guide at /guide/, and operator documentation at /docs/. Every page has an exact Markdown twin, and /llms.txt indexes the machine-readable surface. The visual system is self-contained: teal on ink, local Inter and JetBrains Mono, native SVG diagrams, and captures from a synthetic vault.

Deployment is narrow and verifiable. make docs-build assembles only allowlisted public inputs (72 static files, ~1.34 MB, hard 10 MiB cap), builds consume one exact orphan docs-assets commit rather than a mutable branch, and make docs-deploy DOCS_SOURCE=<full-sha> accepts only a release-eligible source, then inspects and revalidates the unpromoted build before promotion. Pull-request jobs receive no Vercel credentials. A Playwright suite reviews all three built tiers in Chromium and WebKit: keyboard navigation, dialog focus return, narrow layouts, reduced motion, accessible images, and computed contrast.

Merge gates

Draft until:

• the product stack through [E13–S9 15/15] Add a bounded daemon-first MCP server #239 lands and the site's routes and capability claims are reconciled against the landed code;
• the remaining processing-interface captures are generated and the complete orphan image set is reviewed;
• the corresponding software release is published and a post-tag documentation-only source is selected;
• Vercel credentials are configured at their documented boundaries and a maintainer explicitly authorizes merge and promotion.

No preview or production deployment has been created from this branch. The root README keeps its reachable orphan-branch image URL until the first production promotion; a follow-up documentation-only PR then repoints it at the live site asset before the public docs-assets branch advances.

🤖 Generated with Claude Code

[roborev-ci]

roborev: Combined Review (f4c442d)

Verdict: High-severity credential-exfiltration risk, plus two medium-severity documentation build and asset-reference issues.

High

• Candidate-controlled deployment code executes with production credentials — .github/workflows/deploy-docs.yml:50-71, .github/workflows/deploy-docs.yml:55-66; scripts/validate-docs-release.sh:47-53
  The release validator permits changes to scripts/deploy-docs.sh, while the protected deployment job checks out and executes that candidate-controlled script with Vercel secrets. A documentation commit could exfiltrate credentials or deploy unauthorized content.
  Fix: Run immutable, trusted deployment logic from main or a pinned trusted checkout; treat the selected source only as build content and remove deployment/validation scripts from the candidate allowlist.

Medium

• docs-serve fails without synchronized documentation assets — Makefile:111-112
make docs-serve invokes buildSite without first running docs-assets-sync, so fresh checkouts or asset-ref changes lack the required cache and the watcher cannot fetch updated assets.
  Fix: Make docs-serve depend on docs-assets-sync, or synchronize pinned assets before each rebuild.

• Existing asset references use obsolete paths — scripts/docs-assets.txt:1-11
  Published Markdown and README.md still reference nested raw.githubusercontent.com/.../docs-assets/... URLs, which will return 404 with the new flat orphan-tree contract. The verifier does not detect these external URLs.
  Fix: Migrate references to /assets/generated/<name>.png or canonical https://docbank.ai/assets/generated/<name>.png paths, and validate Markdown image targets.

---

Reviewers: 2 done | Synthesis: codex, 10s | Total: 14m49s

[roborev-ci]

roborev: Combined Review (09a9083)

Verdict: High-severity credential-execution risk, plus two medium-severity documentation asset issues.

High

• Release-gated documentation changes can execute with Vercel credentials — .github/workflows/deploy-docs.yml:50-71, scripts/validate-docs-release.sh:42-58
  The selected source is checked out and its deployment scripts, Vercel configuration, and ignore rules run with production Vercel credentials. Because these executable files are permitted as documentation-only changes, a malicious commit could exfiltrate VERCEL_TOKEN or alter the deployment. Run deployment logic from a trusted pinned revision, treat the selected source only as static input, and exclude deployment scripts, workflow files, vercel.json, and .vercelignore from source-controlled release changes.

Medium

• docs-serve does not synchronize pinned screenshot assets — Makefile:111-112, scripts/docs/build.mjs:100-107
  A fresh checkout, or a changed asset pin while the watcher is running, fails when .cache/docs-assets/<ref> is absent. Synchronize assets before the initial build and before rebuilds triggered by manifest or ref changes.

• Documentation still references mutable or missing screenshot URLs — scripts/docs-assets.txt:1-11, docs/index.md:37, docs/tour.md:19-55
  Existing Markdown references raw.githubusercontent.com/.../docs-assets/screenshots/..., including assets absent from the new pinned set such as tui-storage-backup.png. Update documentation and README.md links to canonical /assets/generated/<manifested-name>.png URLs, and validate Markdown asset references.

---

Reviewers: 2 done | Synthesis: codex, 9s | Total: 15m17s

[wesm]

@salmonumbrella i'm grinding on this some, would appreciate your feedback after I push the incoming iteration

[roborev-ci]

roborev: Combined Review (5637028)

Verdict: 1 High-severity and 3 Medium-severity findings require attention.

High

• .github/workflows/deploy-docs.yml:71 executes source-controlled scripts/deploy-docs.sh with VERCEL_TOKEN. Because the trusted validator permits changes to deployment and build files, a malicious docs-only commit could exfiltrate the token during maintainer-triggered deployment and publish attacker-controlled documentation. Use trusted pinned deployment logic or verify executable-file hashes before exposing production secrets.

Medium

• Makefile:111-112, scripts/docs/build.mjs:101-106: make docs-serve does not synchronize pinned screenshot assets before the initial buildSite, so a fresh checkout fails before the server starts. Sync assets before the initial build and when the manifest or ref changes.

• scripts/deploy-docs.sh:36-43: The deployment stdout is treated as a single URL, but Vercel emits progress/status text, causing URL validation to fail. Use machine-readable output or explicitly extract and validate the deployment URL.

• scripts/docs/verify-site.mjs:119-120; existing references including README.md:19 and docs/tour.md:19: Published pages still reference old nested raw.githubusercontent.com screenshot paths. Since the verifier skips external URLs, these bypass pinned flat asset generation and will break when the old layout is removed. Replace them with canonical /assets/generated/<name>.png URLs and validate image references.

---

Reviewers: 2 done | Synthesis: codex, 9s | Total: 14m29s

[roborev-ci]

roborev: Combined Review (8b416a5)

Verdict: The change has one High-severity security issue and three Medium-severity correctness and release-safety issues.

High

• .github/workflows/ci.yml:56-68; .github/workflows/deploy-docs.yml:50-71 — Workflows expose Vercel credentials while running scripts from the selected repository source, allowing merged contributors to modify deployment scripts and exfiltrate VERCEL_TOKEN or alter production deployment. Use immutable trusted scripts or inline credential-bearing operations.

Medium

• scripts/docs/serve.mjs:203-205 — The watcher monitors docs/, while builds create and remove temporary entries there, potentially triggering continuous rebuilds. Move temporary files outside the watched tree or ignore generated paths.

• docs/index.md:37; scripts/docs/build.mjs:156-164 — Absolute deployed asset URLs prevent local previews from loading the locally staged pinned assets. Rewrite URLs for local HTML or provide a local-origin asset scheme.

• website/index.md:90-121; website/guide.md:97-104 — Public pages claim hybrid/semantic/reranked retrieval and MCP support, contradicting current documentation and implementation. Align claims with the released product or defer them until implemented and released.

---

Reviewers: 2 done | Synthesis: codex, 11s | Total: 17m21s

[roborev-ci]

roborev: Combined Review (65b3a32)

Verdict: High-risk deployment credential exposure, plus three medium-severity documentation and tooling issues.

Critical

None reported.

High

• Trusted deployment executes untrusted source-controlled code — .github/workflows/deploy-docs.yml:50-71, scripts/validate-docs-release.sh:42-58
  • The release allowlist permits changes to deployment/CI helpers, while the production job checks out the selected source and runs deployment scripts with Vercel credentials. A malicious docs-only commit could exfiltrate secrets or alter the deployment.
  • The same risk affects ci.yml:56-68, which runs source-controlled scripts/docs/* code while VERCEL_TOKEN is present.
  • Pin deployment orchestration and secret-bearing helpers to trusted main/release code; treat the selected SHA only as documentation input and deploy a prebuilt artifact without secrets.

Medium

• Non-portable find -maxdepth breaks cached assets on macOS — scripts/sync-docs-assets.sh:62

  • BSD find does not support -maxdepth, causing valid caches to be rejected and triggering network fetches.
  • Replace it with portable shell/glob-based enumeration.

• Public site overstates product capabilities — website/index.md:88-121

  • Processing, semantic retrieval, and MCP are presented as available despite MCP being unimplemented and the documentation identifying these capabilities as unfinished.
  • Remove or qualify the claims until the dependent functionality ships.

• Preview server can terminate on concurrent rebuild requests — scripts/docs/serve.mjs:162-171

  • A rebuild can replace the site directory after lstat but before createReadStream, producing an unhandled asynchronous ENOENT.
  • Open the file before replacement or handle stream errors safely.

---

Reviewers: 2 done | Synthesis: codex, 32s | Total: 13m4s

[roborev-ci]

roborev: Combined Review (2cc6d36)

Verdict: No Medium, High, or Critical findings were identified.

All reported issues are Low severity and omitted per the requested criteria.

---

Reviewers: 2 done | Synthesis: codex, 5s | Total: 19m56s

[salmonumbrella]

@wesm tag me for feedback when you're ready