Skip to content

docs: establish Docbank's authority-led public site - #241

Draft
wesm wants to merge 5 commits into
mainfrom
docs/tiered-site
Draft

docs: establish Docbank's authority-led public site#241
wesm wants to merge 5 commits into
mainfrom
docs/tiered-site

Conversation

@wesm

@wesm wesm commented Aug 30, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

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-ci Bot commented Aug 30, 2026

Copy link
Copy Markdown

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-ci Bot commented Aug 30, 2026

Copy link
Copy Markdown

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

wesm commented Aug 30, 2026

Copy link
Copy Markdown
Member Author

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

@roborev-ci

roborev-ci Bot commented Aug 30, 2026

Copy link
Copy Markdown

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

@wesm wesm self-assigned this Sep 4, 2026
@roborev-ci

roborev-ci Bot commented Sep 4, 2026

Copy link
Copy Markdown

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-ci Bot commented Sep 4, 2026

Copy link
Copy Markdown

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-ci Bot commented Sep 4, 2026

Copy link
Copy Markdown

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

salmonumbrella commented Sep 4, 2026

Copy link
Copy Markdown
Contributor

@wesm tag me for feedback when you're ready

wesm and others added 5 commits September 8, 2026 19:12
@wesm
docs: define Docbank's tiered public site
8f0ae94 
Docbank's incoming processing and retrieval stack needs a public identity
that explains source authority, governed derivatives, bounded agent access,
and recovery as one system.

Fix the audience, authority-lifecycle narrative, flat teal visual language,
human and machine route parity, screenshot boundary, and release-gated
deployment before implementation begins.

- docs: make the tiered site design executable
- test: prove documentation subpath rendering
- feat: separate complete documentation captures
- feat: pin reviewed documentation assets
- feat: assemble the public documentation tiers
- feat: establish Docbank's authority-led site
- feat: preview every documentation tier together
- fix: make documentation deployment narrow and verifiable
- test: verify the public documentation boundary
- ci: gate documentation promotion on released sources
- test: keep browser specs out of the unit runner
- fix: enforce documentation publication boundaries
- feat: simplify the landing hero and link community surfaces
- fix: redraw the interface map with orthogonal routing
- feat: tell the AI intelligence and git-contrast story
- fix: serve every published screenshot from the site itself

Generated with Codex
Generated with Claude Code (claude-fable-5-1)
Co-authored-by: Codex <198982749+openai-codex[bot]@users.noreply.github.com>
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>

- fix: keep documentation previews self-contained
- fix: answer preview requests when a file vanishes after stat
@wesm
docs: make storage and audit contracts easier to follow
66b04eb 
Readers need to understand what an operation guarantees before tracing its
implementation. Explain the document model first, name the actors, and show
ordered flows for capture, restore, editing, and audit enrollment.

Keep the normative fields, limits, examples, and failure boundaries intact.
Separate earlier audit design context from the current contract so old
status notes do not mislead contributors.

Generated with Codex
Co-authored-by: Codex <198982749+openai-codex[bot]@users.noreply.github.com>
@wesm
docs: make vault operating guides easier to follow
94c575b 
Readers need to find the next action without first learning internal storage
and audit terminology. Lead the guides with outcomes, define the terms that
matter, and separate procedures from limits and failure handling.

Keep command examples, revision checks, permanent retention, and recovery
requirements explicit so shorter prose does not weaken the operating contract.

Generated with Codex
Co-authored-by: Codex <198982749+openai-codex[bot]@users.noreply.github.com>
@wesm
docs: explain agent and application contracts in plain language
5531bfd 
Integrators need to see what to send, what to verify, and how to handle a
failure without unpacking dense storage terminology. Separate those decisions
and keep exact commands, fields, limits, and receipt checks close to the task.

Link capability summaries to their owning guides and distinguish available
worker components from complete retrieval workflows. Correct stale scope and
web descriptions so readers do not infer limits the implementation no longer has.

Generated with Codex
Co-authored-by: Codex <198982749+openai-codex[bot]@users.noreply.github.com>
@wesm
docs: help readers use Docbank without decoding its architecture
c997109 
Readers need to know what they can do before they learn how the vault is
built. Lead the website and README with document tasks, turn the docs index
into a guide to those tasks, and keep the HTML and Markdown explanations in
agreement.

Record the writing rules for future changes. Separate current interfaces
from planned workflows, and retain historical design decisions with their
original dependency and publication conditions.

Generated with Codex
Co-authored-by: Codex <198982749+openai-codex[bot]@users.noreply.github.com>
@roborev-ci

roborev-ci Bot commented Sep 9, 2026

Copy link
Copy Markdown

roborev: Combined Review (c997109)

Verdict: Changes require fixes for 1 finding.

High

  • .github/workflows/deploy-docs.yml:50-71; scripts/validate-docs-release.sh:40-58: The deployment job checks out the requested documentation source and executes its source-controlled deployment script with Vercel credentials, while the validator allows deployment-sensitive files to change. A merged documentation-only change could alter deployment behavior, bypass validation, exfiltrate credentials, or misuse the production project. Run the deployment wrapper, validator, and credential-sensitive build/install code only from a trusted pinned ref or protected workflow checkout. Treat the selected source solely as inert documentation input and remove deployment-sensitive paths from its allowlist.

    Reported by: codex, codex (security)

Reviewers: 2 done | Synthesis: codex, 8s | Total: 13m22s

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@wesm wesm

Labels

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@wesm @salmonumbrella