diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 6a027d36..f46bc000 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -12,6 +12,66 @@ concurrency:
cancel-in-progress: true
jobs:
+ docs:
+ name: Public documentation
+ runs-on: ${{ github.repository == 'kenn-io/docbank' && (github.event_name == 'push' && github.ref == 'refs/heads/main' || (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository && github.event.pull_request.base.repo.full_name == github.repository)) && 'kenn-linux-x64-public' || 'ubuntu-latest' }}
+ steps:
+ - name: Check out full repository history
+ uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+ with:
+ fetch-depth: 0
+ persist-credentials: false
+
+ - name: Set up Go
+ uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6.5.0
+ with:
+ go-version-file: go.mod
+ cache: ${{ github.repository == 'kenn-io/docbank' && (github.event_name == 'push' && github.ref == 'refs/heads/main' || (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository && github.event.pull_request.base.repo.full_name == github.repository)) && 'false' || 'true' }}
+
+ - name: Set up Node.js
+ uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+ with:
+ node-version: "24"
+ cache: npm
+ cache-dependency-path: frontend/package-lock.json
+
+ - name: Install pinned documentation tools
+ run: |
+ ./scripts/vercel-install-docs.sh
+ echo "$PWD/.vercel-tools/bin" >> "$GITHUB_PATH"
+
+ - name: Install browser test dependencies
+ run: |
+ npm ci --prefix frontend
+ node frontend/node_modules/@playwright/test/cli.js install --with-deps chromium webkit
+
+ - name: Verify documentation sources and assets
+ run: |
+ bash scripts/docs-assets-sync.test.sh
+ npm --prefix frontend run screenshots:check
+ make docs-subpath-test
+ node --test scripts/docs/*.test.mjs
+ make docs-build
+
+ - name: Verify Vercel upload boundary
+ if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+ env:
+ VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
+ run: |
+ if [ -z "$VERCEL_TOKEN" ]; then
+ echo "VERCEL_TOKEN must be configured for trusted main-branch documentation checks" >&2
+ exit 1
+ fi
+ npm install --global vercel@58.4.4
+ mkdir -p .superpowers
+ vercel deploy --dry --json --project docbank.ai --scope kenn-software --token "$VERCEL_TOKEN" > .superpowers/vercel-dry-run.json
+ node scripts/docs/assert-vercel-dry-run.mjs .superpowers/vercel-dry-run.json
+
+ - name: Verify documentation in Chromium and WebKit
+ run: |
+ npm --prefix frontend run docs-site:check
+ npm --prefix frontend run docs-site:test
+
frontend:
name: Web application
runs-on: ${{ github.repository == 'kenn-io/docbank' && (github.event_name == 'push' && github.ref == 'refs/heads/main' || (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository && github.event.pull_request.base.repo.full_name == github.repository)) && 'kenn-linux-x64-public' || 'ubuntu-latest' }}
diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
new file mode 100644
index 00000000..4e4e4489
--- /dev/null
+++ b/.github/workflows/deploy-docs.yml
@@ -0,0 +1,71 @@
+name: Deploy documentation
+
+on:
+ workflow_dispatch:
+ inputs:
+ source_sha:
+ description: Full eligible documentation source commit SHA
+ required: true
+ type: string
+
+permissions:
+ contents: read
+
+concurrency:
+ group: docbank-documentation-production
+ cancel-in-progress: false
+
+jobs:
+ validate:
+ name: Validate documentation source
+ runs-on: ubuntu-latest
+ outputs:
+ release_tag: ${{ steps.release.outputs.release_tag }}
+ source_sha: ${{ steps.release.outputs.source_sha }}
+ steps:
+ - name: Check out trusted release policy
+ uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+ with:
+ fetch-depth: 0
+ persist-credentials: false
+ ref: main
+
+ - name: Validate requested source against the release boundary
+ id: release
+ env:
+ SOURCE_SHA: ${{ inputs.source_sha }}
+ run: |
+ git fetch --quiet origin refs/heads/main:refs/remotes/origin/main --tags
+ release_tag=$(git describe --tags --abbrev=0 --match 'v[0-9]*.[0-9]*.[0-9]*' origin/main)
+ ./scripts/validate-docs-release.sh "$SOURCE_SHA" "$release_tag"
+ echo "source_sha=$SOURCE_SHA" >> "$GITHUB_OUTPUT"
+ echo "release_tag=$release_tag" >> "$GITHUB_OUTPUT"
+
+ deploy:
+ name: Build and promote documentation
+ needs: validate
+ runs-on: ubuntu-latest
+ environment: production
+ steps:
+ - name: Check out the validated source
+ uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+ with:
+ fetch-depth: 0
+ persist-credentials: false
+ ref: ${{ needs.validate.outputs.source_sha }}
+
+ - name: Set up Node.js
+ uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+ with:
+ node-version: "24"
+
+ - name: Install pinned Vercel CLI
+ run: npm install --global vercel@58.4.4
+
+ - name: Verify, build, inspect, and promote
+ env:
+ DOCS_SOURCE: ${{ needs.validate.outputs.source_sha }}
+ VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
+ VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
+ VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
+ run: ./scripts/deploy-docs.sh
diff --git a/.gitignore b/.gitignore
index 21ba218d..972248f8 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,8 +10,14 @@ internal/web/dist/*
!internal/web/dist/.keep
# docs build
+**/__pycache__/
+/.cache/docs-assets/
+/site/
+/.vercel/
+/.vercel-tools/
docs/.venv/
docs/site/
docs/zensical-public-docs.*
docs/.zensical-build.*
.kata.local.toml
+.env*
diff --git a/.vercelignore b/.vercelignore
new file mode 100644
index 00000000..817eb397
--- /dev/null
+++ b/.vercelignore
@@ -0,0 +1,50 @@
+# Vercel receives only the static documentation build inputs. Product source,
+# screenshots, tests, internal plans, generated output, and local state remain
+# outside the upload boundary.
+/*
+
+!/vercel.json
+
+!/LICENSES
+/LICENSES/*
+!/LICENSES/Inter-OFL-1.1.txt
+!/LICENSES/JetBrains-Mono-OFL-1.1.txt
+
+!/website
+
+!/docs
+/docs/*
+!/docs/*.md
+/docs/README.md
+!/docs/agents
+!/docs/architecture
+!/docs/usage
+!/docs/overrides
+/docs/overrides/*
+!/docs/overrides/main.html
+!/docs/stylesheets
+/docs/stylesheets/*
+!/docs/stylesheets/extra.css
+!/docs/scripts
+/docs/scripts/*
+!/docs/scripts/check_built_site.py
+!/docs/scripts/check_markdown_sources.py
+!/docs/llms.txt
+!/docs/pyproject.toml
+!/docs/uv.lock
+!/docs/zensical-docs.sh
+!/docs/zensical.toml
+
+!/scripts
+/scripts/*
+!/scripts/docs
+/scripts/docs/*
+!/scripts/docs/build.mjs
+!/scripts/docs/verify-site.mjs
+!/scripts/docs-assets.ref
+!/scripts/docs-assets.txt
+!/scripts/install.ps1
+!/scripts/install.sh
+!/scripts/sync-docs-assets.sh
+!/scripts/vercel-build-docs.sh
+!/scripts/vercel-install-docs.sh
diff --git a/AGENTS.md b/AGENTS.md
index 4aaa4003..b19d7481 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -21,11 +21,30 @@ Instructions for autonomous coding agents working in this repository.
`frontend/package-lock.json`. Run `make frontend-test` for type, kit-ui,
unit, and production-build checks. Release CI builds the frontend once and
embeds those exact assets in all six platform archives.
-- Real web screenshots use the repository-owned Playwright harness in
- `frontend/screenshots/`. Run `make frontend-screenshots`; captures must use
+- Real documentation screenshots use the repository-owned Playwright harness in
+ `frontend/screenshots/`. Run `make docs-screenshots`; captures must use
its temporary synthetic vault and real daemon, never a developer vault or
mocked API data. Generated images stay under `.superpowers/screenshots/`
- until they are visually inspected and attached to the relevant pull request.
+ until they are visually inspected and published as a complete reviewed set.
+ Publish the complete set as one orphan `docs-assets` commit, then pin that
+ exact commit in `scripts/docs-assets.ref`. Documentation builds consume the
+ pin and never generate screenshots or follow a mutable branch head.
+- Run `make docs-serve` from the repository root to build, watch, and preview
+ the product page, authority guide, and operating documentation on one origin.
+ Run `make docs-build` after the final source or asset-pin edit. The strict
+ build stages only the explicit public allowlist into `site/`; internal plans,
+ scripts, and agent instructions must not enter the output.
+- A software release makes a documentation source eligible; it does not publish
+ that source. The selected source is normally the post-tag documentation-only
+ follow-up. Deployment still requires maintainer authorization. From the
+ repository root, `make docs-deploy DOCS_SOURCE=$(git rev-parse HEAD)` uploads
+ an unpromoted production build, verifies it and the release boundary, and
+ then promotes it. The deploy path does not generate screenshots, build the
+ product, run Docker, or install frontend dependencies. Pull-request jobs
+ never receive Vercel credentials; the authenticated upload dry run is a
+ trusted `main`-push check, and the manual production workflow validates its
+ requested source without credentials before entering the protected
+ environment.
## Private Data Boundary
diff --git a/LICENSES/Inter-OFL-1.1.txt b/LICENSES/Inter-OFL-1.1.txt
new file mode 100644
index 00000000..9b2ca37b
--- /dev/null
+++ b/LICENSES/Inter-OFL-1.1.txt
@@ -0,0 +1,92 @@
+Copyright (c) 2016 The Inter Project Authors (https://github.com/rsms/inter)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION AND CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
diff --git a/LICENSES/JetBrains-Mono-OFL-1.1.txt b/LICENSES/JetBrains-Mono-OFL-1.1.txt
new file mode 100644
index 00000000..23a3dca4
--- /dev/null
+++ b/LICENSES/JetBrains-Mono-OFL-1.1.txt
@@ -0,0 +1,93 @@
+Copyright 2020 The JetBrains Mono Project Authors (https://github.com/JetBrains/JetBrainsMono)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
diff --git a/Makefile b/Makefile
index 2ed16392..9dc3ec76 100644
--- a/Makefile
+++ b/Makefile
@@ -21,7 +21,7 @@ DEFAULT_GOLANGCI_LINT_CACHE := $(shell git rev-parse --path-format=absolute --gi
GOLANGCI_LINT_CACHE ?= $(DEFAULT_GOLANGCI_LINT_CACHE)
export GOLANGCI_LINT_CACHE
-.PHONY: build install clean test test-v release-scripts-test frontend frontend-test frontend-dev frontend-screenshots fmt lint lint-ci tidy install-hooks docs-install docs-build docs-serve docs-link docs-deploy help
+.PHONY: build install clean test test-v release-scripts-test frontend frontend-test frontend-dev docs-screenshots fmt lint lint-ci tidy install-hooks docs-install docs-subpath-test docs-assets-test docs-assets-sync docs-build docs-serve docs-link docs-deploy help
build: frontend
CGO_ENABLED=1 go build -tags "$(BUILD_TAGS)" -ldflags="$(LDFLAGS)" -o docbank ./cmd/docbank
@@ -60,7 +60,7 @@ frontend-test:
frontend-dev:
cd frontend && npm run dev
-frontend-screenshots:
+docs-screenshots:
cd frontend && npm run screenshots
fmt:
@@ -93,14 +93,23 @@ install-hooks:
docs-install:
cd docs && uv sync --frozen
+docs-subpath-test:
+ cd docs && uv run --project . --frozen --no-dev python scripts/check_zensical_subpath.py
+
bridge-contract:
go test -tags fts5 ./document/bridge -run '^TestBridgeContractNormativeDocuments'
-docs-build: bridge-contract
- cd docs && ./zensical-docs.sh build
+docs-assets-test:
+ bash scripts/docs-assets-sync.test.sh
+
+docs-assets-sync:
+ ./scripts/sync-docs-assets.sh
+
+docs-build: bridge-contract docs-subpath-test
+ node scripts/docs/build.mjs
docs-serve:
- cd docs && ./zensical-docs.sh serve
+ node scripts/docs/serve.mjs
# Deploys use the operator's installed Vercel CLI; install it with
# `npm install -g vercel` or from https://vercel.com/docs/cli.
@@ -109,20 +118,19 @@ docs-link:
echo "vercel CLI not found. Install: https://vercel.com/docs/cli" >&2; \
exit 1; \
fi
- cd docs && vercel link
-
-docs-deploy: docs-build
- @if ! command -v vercel >/dev/null 2>&1; then \
- echo "vercel CLI not found. Install: https://vercel.com/docs/cli" >&2; \
+ vercel link
+ @test -f .vercel/project.json || { \
+ echo "Vercel did not create .vercel/project.json at the repository root." >&2; \
exit 1; \
- fi
- @if [ ! -f docs/.vercel/project.json ]; then \
- echo "docs are not linked to a Vercel project yet." >&2; \
- echo "Run: vercel login && make docs-link" >&2; \
+ }
+
+docs-deploy:
+ @if [ -z "$(DOCS_SOURCE)" ]; then \
+ echo "DOCS_SOURCE is required and must be a full source commit SHA." >&2; \
+ echo "Run: make docs-deploy DOCS_SOURCE=$$(git rev-parse HEAD)" >&2; \
exit 1; \
fi
- cp -R docs/.vercel docs/site/.vercel
- vercel deploy docs/site --prod --yes
+ DOCS_SOURCE="$(DOCS_SOURCE)" ./scripts/deploy-docs.sh
help:
- @echo "Targets: build install clean test test-v release-scripts-test frontend frontend-test frontend-dev frontend-screenshots fmt lint lint-ci tidy install-hooks docs-install docs-build docs-serve docs-link docs-deploy"
+ @echo "Targets: build install clean test test-v release-scripts-test frontend frontend-test frontend-dev docs-screenshots fmt lint lint-ci tidy install-hooks docs-install docs-subpath-test docs-assets-test docs-assets-sync docs-build docs-serve docs-link docs-deploy"
diff --git a/README.md b/README.md
index 0d5bf72d..72325490 100644
--- a/README.md
+++ b/README.md
@@ -16,7 +16,7 @@ recoverable deletion, verified backup, and optional permanent audited history.
The vault catalog stays under your control instead of inside a provider
account.
-
+
The standalone CLI, web application, TUI, scripts, and agents all use the same
authenticated daemon contract. Go applications can instead embed independently
diff --git a/docs/README.md b/docs/README.md
index df1d4229..d725c050 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -15,24 +15,76 @@ plus internal design material.
metadata, assets, and publishing boundary; all Python tools run through
the locked `uv` environment
-Every rendered directory route also publishes its exact Markdown source at
-the sibling `.md` path: `/setup/` has `/setup.md`, and
-`/usage/importing/` has `/usage/importing.md`. This gives agents and other
-text-first clients a stable representation without scraping rendered HTML.
-Section landing pages use a sibling source such as `usage.md`, not
-`usage/index.md`, so relative links keep the same base at `/usage.md`.
+Every rendered directory route also publishes its exact Markdown source at the
+sibling `.md` path. The operating page `/docs/setup/` has `/docs/setup.md`, and
+`/docs/usage/importing/` has `/docs/usage/importing.md`. The product page and
+authority guide follow the same rule at `/index.md` and `/guide.md`. Agents and
+other text-first clients can use these stable representations without scraping
+rendered HTML.
## Building
+Run documentation commands from the repository root:
+
+```bash
+make docs-install # one-time: install the locked Zensical environment
+make docs-serve # build and watch all three tiers on http://127.0.0.1:8000
+make docs-build # strict production build into site/
+```
+
+`make docs-serve` serves the product page, authority guide, and operating
+documentation from one origin. It rebuilds after changes beneath `website/` or
+`docs/`, or after the pinned screenshot commit or manifest changes. A failed
+rebuild leaves the last successful `site/` available for inspection.
+
+## Screenshots
+
+Screenshot generation is a separate reviewed workflow. It never runs during a
+documentation build or deployment.
+
+1. Run `make docs-screenshots`. The harness starts a real daemon with a
+ temporary synthetic vault and writes the complete capture set beneath
+ `.superpowers/screenshots/`.
+2. Inspect every generated image and its metadata.
+3. Publish the complete reviewed set as one orphan `docs-assets` commit.
+4. Put that exact commit in `scripts/docs-assets.ref` and run
+ `make docs-assets-sync`.
+5. Run `make docs-build` after the final source or asset-pin edit.
+
+Never capture a developer vault, publish a partial set, or point the build at a
+mutable branch head.
+
+## Deployment
+
+A software release makes a documentation source eligible; it does not publish
+that source. The selected source is normally the documentation-only follow-up
+after the tag and release notes exist. A maintainer must still authorize every
+deployment.
+
+Link the Vercel project once from the repository root with `make docs-link`.
+Deploy an exact eligible source from a clean checkout with:
+
```bash
-cd docs
-uv sync --frozen # one-time: installs zensical into docs/.venv
-./zensical-docs.sh serve # live-reload preview
-./zensical-docs.sh build # strict production build into docs/site/
+make docs-deploy DOCS_SOURCE=$(git rev-parse HEAD)
```
-Or from the repository root: `make docs-install`, `make docs-serve`,
-`make docs-build`.
+The command checks that the source is on `origin/main`, descends from the latest
+software release, and contains only approved documentation changes. It uploads
+an unpromoted production build, waits for Vercel to verify it, repeats the
+release check, and only then promotes the build. Deployment does not generate
+screenshots, build the product, run Docker, or install frontend dependencies.
+
+The protected `Deploy documentation` workflow provides the same path for an
+explicitly supplied source SHA. A credential-free job checks that SHA against
+the release policy from `main` before the protected production job receives
+the validated SHA. It has no automatic push, pull-request, tag, or release
+trigger.
+
+Pull-request documentation checks never receive Vercel credentials. The
+authenticated upload dry run runs only after a trusted push to `main` and
+requires the repository `VERCEL_TOKEN` secret. Production deployment requires
+the `VERCEL_TOKEN`, `VERCEL_ORG_ID`, and `VERCEL_PROJECT_ID` secrets on the
+protected `production` environment.
## Documentation boundary
diff --git a/docs/index.md b/docs/index.md
index bac0580f..420452e4 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -34,7 +34,7 @@ curl -fsSL https://docbank.ai/install.sh | sh
Build agent workflows
-
+
Docbank copies bytes into the vault without making the source path part of document identity. The virtual tree gives operators a familiar hierarchy while retained content stays addressable by checksum.
+
+
+
+
+ A generated vault in the real web interface.
+
+
+
+
+
+
+
Identify the record
+
A stable node identity survives moves and renames. Replacement creates an immutable content version, preserving checksums and history instead of silently changing what an identifier means.
Before processing, the operator chooses where document bytes may go and which outputs may be retained. Authorization governs a task; it does not transfer source authority to the processor.
OCR and rendition providers turn the source into normalized Markdown and text through an enforceable contract. A rendition is a governed derivative of one exact version; it can improve retrieval or be regenerated without becoming the original record.
Chunks, embedding generations, and vector indexes enter the same catalog as every other derivative: fingerprinted, bound to provider and model identity, and rebuildable from retained evidence. The catalog records what produced every vector.
Hybrid search fuses lexical and semantic signals, optionally expands and reranks, and explains each ranked result. The fence holds: every answer keeps the document, version, and evidence behind it. An index helps locate the record; it does not define it.
+
+
+
+
+ Search results in the generated documentation vault.
+
+
+
+
+
+
+
Replace intelligence, keep the record
+
Consent can be revoked and derived state is disposable. Purge renditions, embeddings, and indexes, re-derive them through a different provider, or restore them from backup with no provider in the loop. The originals are never touched.
The CLI, web application, TUI, HTTP API, embedded Go package, and agent tools operate over the same vault model. Each surface inherits the same identity, revision, and integrity boundaries.
Verification checks content and history before an operator needs them. Incremental snapshots restore exact bytes, metadata, and retained history without relying on a processing or search provider.
The system of record for documents your agents can use.
+
Docbank is a local-first, open-source document vault. Originals stay exact and authoritative while governed processing makes them searchable for people, systems, and agents.
+
+ curl -fsSL https://docbank.ai/install.sh | sh
+
+
Local-first · Apache-2.0 · CLI · Web · TUI · HTTP API · Go · MCP
+
+
+
+
+
+
01 / Authority
+
One record. Explicit states.
+
+
A document can be copied, indexed, transformed, and served through several interfaces. Its authority does not move implicitly with those operations.
+
+
+
SourceExact retained bytes and stable identity.
+
AuthorizationA reviewed processing boundary.
+
UnderstandingDerivatives bound to one source version.
+
RetrievalResults backed by evidence and source identity.
+
RecoveryVerified restore under operator control.
+
+
+
+
+
+
+
02 / Guarantees
+
Built around the record, not the index.
+
+
Docbank separates durable document authority from the systems that make documents useful. That boundary stays visible in routine operator work.
+
+
+
+
Source sovereign
+
Keep the original exact.
+
Content-addressed bytes, stable document identity, immutable versions, and checksums preserve what entered the system.
+
+
+
Govern understanding
+
Approve what may leave control.
+
Processing policy names the provider boundary and retained outputs. Derived text and embeddings remain tied to the source version that produced them.
+
+
+
Constrain answers
+
Retrieve with evidence.
+
Search and agent access operate over verified current content while preserving the document and version behind a result.
+
+
+
Restore the record
+
Recover without a provider.
+
Incremental snapshots retain content, metadata, and history so recovery does not depend on a search or processing service.
+
+
+
+
+
+
+
+
03 / Operation
+
A vault operators can inspect.
+
+
Browse a filesystem-shaped document tree, inspect document identity and storage state, and move through retained authority without leaving the vault interface.
+
+
+
+
+
+ The real web interface against a generated synthetic vault. Select the image to inspect it at full size.
+
+
+
+
+
+
+
04 / Processing
+
Choose the boundary per workload.
+
+
Understanding is governed work, not an invisible side effect of storage. Operators decide where it runs and which outputs become retained derivatives.
+
+
+
+
Local
+
Keep processing beside the vault.
+
Use local tooling when document bytes should remain on operator-controlled hardware.
+
+
+
Self-hosted
+
Run a controlled service boundary.
+
Point governed jobs at infrastructure your organization operates and audits.
+
+
+
Hosted
+
Use bounded external capability.
+
Authorize a provider for a defined task while keeping the original and resulting record in Docbank.
+
+
+
None
+
Store without processing.
+
A document remains a complete authoritative record even when no derivative is produced.
+
+
+
+
+
+
+
+
05 / Intelligence
+
AI understanding, on the record.
+
+
OCR output, renditions, chunks, embeddings, and vector indexes are records too: cataloged, fingerprinted, and bound to the exact source version that produced them.
+
+
+
+
+
+
+
Catalog derivatives
+
Bind understanding to its source.
+
Renditions, chunk sets, embedding generations, and vector indexes publish atomically into a durable catalog, each fingerprinted against one immutable source version.
+
+
+
Replace providers
+
Swap models without losing the record.
+
Local, self-hosted, and hosted OCR and embedding providers plug into standard bridges. Consent is durable and revocable, and uploads bind to the exact inspected bytes.
+
+
+
Rebuild intelligence
+
Treat derived state as disposable.
+
Purge, re-derive, and rebuild renditions, embeddings, and indexes deterministically. Derivatives back up and restore without any provider, and originals are never touched.
+
+
+
Explain retrieval
+
Rank with reasons, answer with evidence.
+
Hybrid lexical and semantic search, with optional expansion and reranking, explains each ranked result and keeps the document and version behind it.
+
+
+
+
+
+
+
+
06 / Interfaces
+
One authority across every surface.
+
People, applications, and agents work through interfaces suited to the task. They do not create separate copies of record.
Docbank is closer to a storage appliance with an evidence-aware intelligence layer: the operator owns the vault, its policy, and its recovery path.
+
+
+
+
Cloud drive
+
The service is the record.
+
Identity, search, processing, and recovery are coupled to one provider account and its lifecycle.
+
+
+
Git repository
+
The ledger expects rewriting.
+
Rebase and force-push rewrite history by design, identity follows paths, and large originals or AI derivatives overflow into bolt-on stores with no consent or provenance contract.
+
+
+
Docbank
+
The vault is the record.
+
Storage locations, processors, and interfaces are replaceable participants around operator-controlled authority, including every AI-derived record.
+
+
+
+
+
+
+
+
08 / Start
+
Follow one document through the system.
+
+
+
The guide makes each authority boundary concrete. The operating documentation carries installation, workflows, architecture, and exact command behavior.
',
+ ),
+ );
+ await write(output, "index.md", await readFile(path.join(repoRoot, "docs/index.md")));
+ await write(output, "setup.md", await readFile(path.join(repoRoot, "docs/setup.md")));
+ await write(output, "llms.txt", "redundant docs index\n");
+ await write(output, "install.sh", "redundant installer\n");
+}
+
+
+test("assembles all tiers and public assets into one site root", async (t) => {
+ const repoRoot = await repositoryFixture(t);
+ const output = path.join(repoRoot, "site");
+
+ await buildSite({ repoRoot, output, buildDocs: buildDocsFixture, syncAssets: syncAssetsFixture });
+
+ for (const relative of [
+ "index.html",
+ "index.md",
+ "guide/index.html",
+ "guide.md",
+ "docs/index.html",
+ "docs/index.md",
+ "docs/setup/index.html",
+ "docs/setup.md",
+ "assets/generated/capture.png",
+ "install.sh",
+ "install.ps1",
+ "llms.txt",
+ ]) {
+ await access(path.join(output, relative));
+ }
+ await assert.rejects(access(path.join(output, "docs/llms.txt")));
+ await assert.rejects(access(path.join(output, "docs/install.sh")));
+
+ const setup = await readFile(path.join(output, "docs/setup/index.html"), "utf8");
+ assert.match(setup, /src="\/assets\/generated\/capture\.png"/);
+ assert.doesNotMatch(setup, /docbank\.ai\/assets/);
+});
+
+
+test("fails before assembling when the pinned assets are not synced", async (t) => {
+ const repoRoot = await repositoryFixture(t);
+ const output = path.join(repoRoot, "site");
+
+ await assert.rejects(
+ () => buildSite({ repoRoot, output, buildDocs: buildDocsFixture, syncAssets: async () => {} }),
+ { code: "ENOENT" },
+ );
+ await assert.rejects(access(output));
+});
+
+
+test("keeps the previous marked output when verification fails", async (t) => {
+ const repoRoot = await repositoryFixture(t);
+ const output = path.join(repoRoot, "site");
+ await write(output, ".docbank-docs-output", "generated by docbank docs build\n");
+ await write(output, "sentinel.txt", "previous output\n");
+ await write(repoRoot, "website/index.html", html("https://docbank.ai/", 'Missing'));
+
+ await assert.rejects(
+ () => buildSite({ repoRoot, output, buildDocs: buildDocsFixture, syncAssets: syncAssetsFixture }),
+ /broken local URL/,
+ );
+ assert.equal(await readFile(path.join(output, "sentinel.txt"), "utf8"), "previous output\n");
+});
diff --git a/scripts/docs/serve.mjs b/scripts/docs/serve.mjs
new file mode 100644
index 00000000..f0924fbd
--- /dev/null
+++ b/scripts/docs/serve.mjs
@@ -0,0 +1,287 @@
+import { watch as watchPath } from "node:fs";
+import { lstat, open } from "node:fs/promises";
+import http from "node:http";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { buildSite } from "./build.mjs";
+
+
+const contentTypes = new Map([
+ [".css", "text/css; charset=utf-8"],
+ [".html", "text/html; charset=utf-8"],
+ [".js", "text/javascript; charset=utf-8"],
+ [".json", "application/json; charset=utf-8"],
+ [".md", "text/markdown; charset=utf-8"],
+ [".png", "image/png"],
+ [".ps1", "text/plain; charset=utf-8"],
+ [".sh", "text/x-shellscript; charset=utf-8"],
+ [".svg", "image/svg+xml"],
+ [".txt", "text/plain; charset=utf-8"],
+ [".woff2", "font/woff2"],
+ [".xml", "application/xml; charset=utf-8"],
+]);
+
+
+export function createRebuildQueue({ build, debounceMs = 100, onError = console.error }) {
+ let timer;
+ let running = false;
+ let pending = false;
+ let closed = false;
+ const waiters = new Set();
+
+ function notify() {
+ for (const waiter of waiters) waiter();
+ }
+
+ function schedule(delay = debounceMs) {
+ if (timer) clearTimeout(timer);
+ timer = setTimeout(run, delay);
+ }
+
+ async function run() {
+ timer = undefined;
+ if (closed) {
+ notify();
+ return;
+ }
+ running = true;
+ notify();
+ try {
+ await build();
+ } catch (error) {
+ onError(error);
+ } finally {
+ running = false;
+ if (pending && !closed) {
+ pending = false;
+ schedule(0);
+ }
+ notify();
+ }
+ }
+
+ return {
+ request() {
+ if (closed) return;
+ if (running) {
+ pending = true;
+ return;
+ }
+ schedule();
+ },
+
+ idle({ waitForRunning = true } = {}) {
+ return new Promise((resolve) => {
+ const check = () => {
+ const settled = waitForRunning
+ ? !timer && !running && !pending
+ : running || (!timer && !pending);
+ if (!settled) return;
+ waiters.delete(check);
+ resolve();
+ };
+ waiters.add(check);
+ check();
+ });
+ },
+
+ close() {
+ closed = true;
+ pending = false;
+ if (timer) clearTimeout(timer);
+ timer = undefined;
+ notify();
+ },
+ };
+}
+
+
+const generatedDocsEntry = /^(?:\.|site$|zensical-site\.|zensical-public-docs\.)/;
+
+
+export function isGeneratedDocsPath(filename) {
+ if (!filename) return false;
+ const [first] = String(filename).split(/[\\/]/, 1);
+ return generatedDocsEntry.test(first);
+}
+
+
+function resolveRequest(siteRoot, rawUrl) {
+ const rawPath = rawUrl.split(/[?#]/, 1)[0];
+ let decoded;
+ try {
+ decoded = decodeURIComponent(rawPath);
+ } catch {
+ return undefined;
+ }
+ if (!decoded.startsWith("/") || decoded.includes("\0") || decoded.includes("\\")) {
+ return undefined;
+ }
+ if (decoded.split("/").includes("..")) return undefined;
+
+ const route = decoded.endsWith("/") ? `${decoded}index.html` : decoded;
+ const target = path.resolve(siteRoot, `.${route}`);
+ const prefix = `${path.resolve(siteRoot)}${path.sep}`;
+ if (!target.startsWith(prefix)) return undefined;
+ return target;
+}
+
+
+async function serveFile(siteRoot, request, response, logger) {
+ if (request.method !== "GET" && request.method !== "HEAD") {
+ response.writeHead(405, { Allow: "GET, HEAD" });
+ response.end();
+ return;
+ }
+
+ const target = resolveRequest(siteRoot, request.url ?? "/");
+ if (!target) {
+ response.writeHead(404);
+ response.end("Not found\n");
+ return;
+ }
+
+ let metadata;
+ try {
+ metadata = await lstat(target);
+ } catch (error) {
+ if (error?.code === "ENOENT" || error?.code === "ENOTDIR") {
+ response.writeHead(404);
+ response.end("Not found\n");
+ return;
+ }
+ throw error;
+ }
+ if (!metadata.isFile() || metadata.isSymbolicLink()) {
+ response.writeHead(404);
+ response.end("Not found\n");
+ return;
+ }
+
+ let handle;
+ try {
+ handle = await open(target, "r");
+ } catch (error) {
+ if (error?.code === "ENOENT" || error?.code === "ENOTDIR") {
+ response.writeHead(404);
+ response.end("Not found\n");
+ return;
+ }
+ throw error;
+ }
+ try {
+ const { size } = await handle.stat();
+ response.writeHead(200, {
+ "Cache-Control": "no-store",
+ "Content-Length": size,
+ "Content-Type": contentTypes.get(path.extname(target)) ?? "application/octet-stream",
+ });
+ } catch (error) {
+ await handle.close();
+ throw error;
+ }
+ if (request.method === "HEAD") {
+ response.end();
+ await handle.close();
+ return;
+ }
+ const stream = handle.createReadStream();
+ stream.on("error", (error) => {
+ logger.error(error);
+ response.destroy(error);
+ });
+ stream.pipe(response);
+}
+
+
+function listen(server, host, port) {
+ return new Promise((resolve, reject) => {
+ server.once("error", reject);
+ server.listen(port, host, () => {
+ server.off("error", reject);
+ resolve();
+ });
+ });
+}
+
+
+export async function startDocsServer({
+ repoRoot,
+ host = "127.0.0.1",
+ port = 8000,
+ build = ({ output }) => buildSite({ repoRoot, output }),
+ watch = true,
+ watchFactory = watchPath,
+ logger = console,
+}) {
+ const siteRoot = path.join(repoRoot, "site");
+ await build({ output: siteRoot });
+
+ const queue = createRebuildQueue({
+ build: async () => {
+ try {
+ await build({ output: siteRoot });
+ logger.log("documentation rebuilt");
+ } catch (error) {
+ logger.error("documentation rebuild failed; serving the previous build");
+ throw error;
+ }
+ },
+ onError: (error) => logger.error(error),
+ });
+
+ const watchers = [];
+ if (watch) {
+ for (const [source, recursive, ignore] of [
+ [path.join(repoRoot, "website"), true, () => false],
+ [path.join(repoRoot, "docs"), true, isGeneratedDocsPath],
+ [path.join(repoRoot, "scripts", "docs-assets.ref"), false, () => false],
+ [path.join(repoRoot, "scripts", "docs-assets.txt"), false, () => false],
+ ]) {
+ const watcher = watchFactory(source, { recursive }, (_event, filename) => {
+ if (!ignore(filename)) queue.request();
+ });
+ watcher.on?.("error", (error) => logger.error(error));
+ watchers.push(watcher);
+ }
+ }
+
+ const server = http.createServer((request, response) => {
+ serveFile(siteRoot, request, response, logger).catch((error) => {
+ logger.error(error);
+ if (!response.headersSent) response.writeHead(500);
+ response.end("Internal server error\n");
+ });
+ });
+ await listen(server, host, port);
+ const address = server.address();
+ if (!address || typeof address === "string") throw new Error("documentation server has no TCP address");
+ const url = `http://${host}:${address.port}/`;
+
+ return {
+ url,
+ port: address.port,
+ close() {
+ queue.close();
+ for (const watcher of watchers) watcher.close();
+ return new Promise((resolve, reject) => {
+ server.close((error) => error ? reject(error) : resolve());
+ });
+ },
+ };
+}
+
+
+const invokedPath = process.argv[1] ? pathToFileURL(path.resolve(process.argv[1])).href : "";
+if (import.meta.url === invokedPath) {
+ const here = path.dirname(fileURLToPath(import.meta.url));
+ const repoRoot = path.resolve(here, "..", "..");
+ const configuredPort = process.env.DOCBANK_DOCS_PORT;
+ const port = configuredPort === undefined ? 8000 : Number(configuredPort);
+ if (!Number.isInteger(port) || port < 0 || port > 65_535) {
+ throw new Error("DOCBANK_DOCS_PORT must be an integer from 0 through 65535");
+ }
+ const server = await startDocsServer({ repoRoot, port });
+ process.stdout.write(`serving documentation at ${server.url}\n`);
+}
diff --git a/scripts/docs/serve.test.mjs b/scripts/docs/serve.test.mjs
new file mode 100644
index 00000000..361f1ac8
--- /dev/null
+++ b/scripts/docs/serve.test.mjs
@@ -0,0 +1,211 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import http from "node:http";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { createRebuildQueue, startDocsServer } from "./serve.mjs";
+
+
+async function write(root, relative, contents) {
+ const destination = path.join(root, relative);
+ await mkdir(path.dirname(destination), { recursive: true });
+ await writeFile(destination, contents);
+}
+
+
+async function fixture(t) {
+ const repoRoot = await mkdtemp(path.join(tmpdir(), "docbank-docs-server-"));
+ t.after(() => rm(repoRoot, { recursive: true, force: true }));
+ for (const [relative, contents] of Object.entries({
+ "site/index.html": "
',
+ }),
+ );
+ await write(
+ site,
+ "guide/index.html",
+ page({ canonical: "https://docbank.ai/guide/", body: 'Docs' }),
+ );
+ await write(
+ site,
+ "docs/index.html",
+ page({ canonical: "https://docbank.ai/docs/", body: 'Setup' }),
+ );
+ await write(
+ site,
+ "docs/setup/index.html",
+ page({ canonical: "https://docbank.ai/docs/setup/", body: 'Overview' }),
+ );
+ const markdown = {
+ "index.md": "# Product\n",
+ "guide.md": "# Guide\n",
+ "docs/index.md": "# Operating docs\n",
+ "docs/setup.md": "# Setup\n",
+ };
+ for (const [relative, contents] of Object.entries(markdown)) {
+ await write(site, relative, contents);
+ }
+ await write(website, "index.md", markdown["index.md"]);
+ await write(website, "guide.md", markdown["guide.md"]);
+ await write(docs, "index.md", markdown["docs/index.md"]);
+ await write(docs, "setup.md", markdown["docs/setup.md"]);
+ await write(site, "assets/generated/capture.png", "png fixture");
+ await write(
+ site,
+ "llms.txt",
+ [
+ "# Docbank",
+ "- [Product](https://docbank.ai/index.md)",
+ "- [Guide](https://docbank.ai/guide.md)",
+ "- [Docs](https://docbank.ai/docs/index.md)",
+ "- [Setup](https://docbank.ai/docs/setup.md)",
+ "",
+ ].join("\n"),
+ );
+ return {
+ site,
+ sources: {
+ website,
+ docs,
+ assets: ["capture.png"],
+ },
+ };
+}
+
+
+test("accepts complete routes, Markdown peers, links, and assets", async (t) => {
+ const input = await fixture(t);
+ await verifySite(input);
+});
+
+
+test("accepts the generated 404 page without a canonical peer", async (t) => {
+ const input = await fixture(t);
+ const notFound = page({
+ canonical: "https://docbank.ai/docs/",
+ body: 'Skip',
+ }).replace('', "");
+ await write(input.site, "docs/404.html", notFound);
+
+ await verifySite(input);
+});
+
+
+test("rejects a substantive HTML file that is not a directory route", async (t) => {
+ const input = await fixture(t);
+ await write(
+ input.site,
+ "docs/orphan.html",
+ page({ canonical: "https://docbank.ai/docs/orphan.html" }),
+ );
+
+ await assert.rejects(
+ () => verifySite(input),
+ /docs\/orphan\.html: unsupported substantive HTML route/,
+ );
+});
+
+
+test("rejects an HTML route without its Markdown peer", async (t) => {
+ const input = await fixture(t);
+ await rm(path.join(input.site, "guide.md"));
+ await assert.rejects(() => verifySite(input), /guide\/index\.html: missing Markdown peer guide\.md/);
+});
+
+
+test("rejects a stale llms index", async (t) => {
+ const input = await fixture(t);
+ await write(
+ input.site,
+ "llms.txt",
+ "- [Product](https://docbank.ai/index.md)\n- [Guide](https://docbank.ai/guide.md)\n- [Docs](https://docbank.ai/docs/index.md)\n",
+ );
+ await assert.rejects(() => verifySite(input), /llms\.txt: missing \/docs\/setup\.md/);
+});
+
+
+test("rejects a broken local link", async (t) => {
+ const input = await fixture(t);
+ await write(
+ input.site,
+ "index.html",
+ page({ canonical: "https://docbank.ai/", body: 'Missing' }),
+ );
+ await assert.rejects(() => verifySite(input), /index\.html: broken local URL \/missing\//);
+});
+
+
+test("rejects an image that is not site-relative", async (t) => {
+ for (const src of [
+ "https://raw.githubusercontent.com/example/capture.png",
+ "https://docbank.ai/assets/generated/capture.png",
+ "//docbank.ai/assets/generated/capture.png",
+ ]) {
+ const { site, sources } = await fixture(t);
+ await write(
+ site,
+ "docs/setup/index.html",
+ page({
+ canonical: "https://docbank.ai/docs/setup/",
+ body: `
+
+ 
+
+ 
+
+
+ 
+
+
+ 
+
+ 
+
+
+ 
+
+
+ 
+
+ 
+
+