Propose documentation updates after code merges to main

.github/workflows/deploy-docs.yml

@@ -32,12 +32,12 @@ jobs:
         id: node-version
         run: echo "node-version=$(grep '^nodejs ' .tool-versions | awk '{print $2}')" >> $GITHUB_OUTPUT
 
+      # No dependency cache: the docs-proposal workflow runs generated content
+      # on the main ref, where it could save a poisoned entry under this key.
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
           node-version: ${{ steps.node-version.outputs.node-version }}
-          cache: "npm"
-          cache-dependency-path: docs/package-lock.json
 
       - name: Setup Pages
         uses: actions/configure-pages@v4

.github/workflows/docs-proposal.yml

@@ -0,0 +1,187 @@
+name: Documentation proposal
+
+# Proposes documentation edits with Copilot CLI after code merges to main and
+# opens one reviewable pull request per merge. See
+# docs/superpowers/specs/2026-10-01-docs-proposal-automation-design.md.
+on:
+  push:
+    branches: [main]
+    paths:
+      - "crates/**"
+      - "trusted-server.example.toml"
+      - "edgezero.toml"
+      - "fastly.toml"
+      - ".cargo/config.toml"
+      - "scripts/**"
+      - "!scripts/docs-proposal/**"
+  workflow_dispatch:
+    inputs:
+      sha:
+        description: Full SHA of a commit on main to propose documentation for
+        required: true
+        type: string
+      base:
+        description: >-
+          Full SHA of main before the push that added the commit, when that
+          push added several commits; defaults to the commit's first parent
+        required: false
+        type: string
+
+permissions: {}
+
+# Sequential merges are proposed one at a time, in order. The default queue
+# keeps only one pending run and cancels older ones, so keep them all. Every
+# job has a timeout so a hung run cannot hold the queue for hours.
+concurrency:
+  group: docs-proposal
+  cancel-in-progress: false
+  queue: max
+
+# Each job runs the proposal scripts from the workflow's own revision in
+# `tools/` against a checkout of the merge commit in `source/`, so retrying a
+# merge that predates this tooling, or a later fix to it, still works. A push
+# that adds several commits is inspected from the previous main head; a manual
+# retry of such a push needs that head as its `base` input.
+env:
+  MERGE_SHA: ${{ inputs.sha || github.sha }}
+  BASE_SHA: ${{ github.event_name == 'push' && github.event.before || inputs.base }}
+
+jobs:
+  # Copilot runs here with a read-only token; it cannot push or open PRs.
+  # Copilot can write files that later steps execute, so treat this job as
+  # untrusted: it uses no dependency cache that later runs would restore.
+  propose:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: read
+      copilot-requests: write
+    steps:
+      - name: Checkout tools
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.workflow_sha }}
+          path: tools
+          persist-credentials: false
+
+      - name: Checkout merge commit
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ env.MERGE_SHA }}
+          path: source
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Retrieve Node.js version
+        id: node-version
+        run: echo "node-version=$(grep '^nodejs ' tools/.tool-versions | awk '{print $2}')" >> "$GITHUB_OUTPUT"
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ steps.node-version.outputs.node-version }}
+
+      - name: Install Copilot CLI
+        run: npm install -g @github/copilot@1.0.90
+
+      - name: Propose documentation edits
+        working-directory: source
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: ../tools/scripts/docs-proposal/propose.sh "$MERGE_SHA" .docs-proposal "$BASE_SHA"
+
+      - name: Upload proposal
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-proposal
+          path: source/.docs-proposal/
+          include-hidden-files: true
+          if-no-files-found: error
+
+  # VitePress executes Vue in Markdown during the build, so the docs gates run
+  # here with no write token, persisted credentials, or dependency cache.
+  validate:
+    needs: propose
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout tools
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.workflow_sha }}
+          path: tools
+          persist-credentials: false
+
+      - name: Checkout merge commit
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ env.MERGE_SHA }}
+          path: source
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Retrieve Node.js version
+        id: node-version
+        run: echo "node-version=$(grep '^nodejs ' tools/.tool-versions | awk '{print $2}')" >> "$GITHUB_OUTPUT"
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ steps.node-version.outputs.node-version }}
+
+      - name: Download proposal
+        uses: actions/download-artifact@v4
+        with:
+          name: docs-proposal
+          path: source/.docs-proposal
+
+      - name: Validate proposal
+        working-directory: source
+        run: ../tools/scripts/docs-proposal/validate.sh "$MERGE_SHA" .docs-proposal
+
+  # Copilot does not run here, and neither does any proposal content: this job
+  # re-checks the path allowlist on a fresh checkout and publishes the patch.
+  publish:
+    needs: validate
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - name: Checkout tools
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.workflow_sha }}
+          path: tools
+          persist-credentials: false
+
+      - name: Checkout merge commit
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ env.MERGE_SHA }}
+          path: source
+          fetch-depth: 0
+
+      - name: Retrieve Node.js version
+        id: node-version
+        run: echo "node-version=$(grep '^nodejs ' tools/.tool-versions | awk '{print $2}')" >> "$GITHUB_OUTPUT"
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ steps.node-version.outputs.node-version }}
+
+      - name: Download proposal
+        uses: actions/download-artifact@v4
+        with:
+          name: docs-proposal
+          path: source/.docs-proposal
+
+      - name: Publish proposal pull request
+        working-directory: source
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: ../tools/scripts/docs-proposal/publish.sh "$MERGE_SHA" .docs-proposal

.github/workflows/format.yml

@@ -162,3 +162,28 @@ jobs:
 
       - name: Build with VitePress (fails on dead links)
         run: npm run build
+
+  docs-proposal-scripts:
+    name: docs-proposal scripts
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Retrieve Node.js version
+        id: node-version
+        run: echo "node-version=$(grep '^nodejs ' .tool-versions | awk '{print $2}')" >> $GITHUB_OUTPUT
+        shell: bash
+
+      - name: Use Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ steps.node-version.outputs.node-version }}
+
+      - name: Run shellcheck
+        run: shellcheck scripts/docs-proposal/*.sh
+
+      - name: Test hunk review builder
+        run: node --test scripts/docs-proposal/hunks.test.mjs
+
+      - name: Test proposal scripts
+        run: scripts/docs-proposal/test.sh

.gitignore

@@ -63,3 +63,6 @@ src/*.html
 # leftover local build artifacts (node_modules, target, dist) that remain on disk.
 /crates/js/
 /crates/integration-tests/
+
+# Documentation proposal workflow scratch space
+/.docs-proposal/

AGENTS.md

@@ -362,6 +362,7 @@ Every PR must pass:
 7. Docs format (`cd docs && npm run format`)
 8. Markdown format outside `docs/` (requires `cd docs && npm ci` first): `docs/node_modules/.bin/prettier --config docs/.prettierrc --check "*.md" ".claude/**/*.md" ".github/**/*.md" "crates/**/*.md" "scripts/**/*.md" "tinybird/**/*.md"`; fix with `--write` in place of `--check`
 9. Native core build-digest test and lint (`cargo test -p trusted-server-core --test template_build_digest` and `cargo clippy -p trusted-server-core --test template_build_digest -- -D warnings`)
+10. Documentation proposal scripts: `shellcheck scripts/docs-proposal/*.sh && node --test scripts/docs-proposal/hunks.test.mjs && scripts/docs-proposal/test.sh`
 
 ---