docs: establish Docbank's authority-led public site

.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' }}

.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

.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*

.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

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
 

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.