ci(docs): check linked terms, procedure format, and UI verification

.github/workflows/test.yml

@@ -72,6 +72,35 @@ jobs:
       - name: Check docs freshness
         run: node scripts/check-docs-freshness.mjs
 
+  docs-conventions:
+    name: Docs / Conventions
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    steps:
+      - name: Checkout
+        # Full history so the script can diff the branch against its base.
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Fetch base branch
+        run: git fetch --quiet origin "${{ github.base_ref || 'dev' }}"
+
+      # Checks the classes of review comment the prose style pass misses:
+      # concepts that have a canonical page but are never linked, procedure
+      # and troubleshooting formatting that disagrees with sibling pages, and
+      # click-through UI changes that nobody states they ran.
+      - name: Check docs conventions
+        env:
+          BASE_REF: origin/${{ github.base_ref || 'dev' }}
+        run: node scripts/check-docs-conventions.mjs
+
   mcp-tests:
     name: MCP / Integration (login handoff)
     runs-on: ubuntu-latest

docs/contributing/docs-workflow.md

@@ -50,4 +50,15 @@ The docs source of truth is the markdown content under `docs/` in this repositor
 
 - run `pnpm dev:docs`
 - run `pnpm build:docs`
+- run `pnpm check:docs`
 - click through nav and sidebar links
+
+## Conventions check
+
+`pnpm check:docs` runs `scripts/check-docs-conventions.mjs` over the pages your branch changed. The same script runs in CI on every pull request. It enforces three things that reviewers otherwise have to catch by hand:
+
+1. **Linked terms.** `scripts/docs-conventions.json` lists concepts that have a canonical page or spec. A page that mentions one has to link it at least once. Add an entry to that file when a new canonical page lands. The script checks every internal target against `docs/docs.json` on each run, so a renamed route fails the check before a reader finds the broken link.
+2. **Consistent procedures.** A page that uses `<Steps>` cannot also write a procedure as a bolded numbered list, and a `## Troubleshooting` section has to match the format the sibling pages in its directory already use.
+3. **UI verification.** When a change touches a click-through procedure, the pull request body needs a `UI verification:` line naming who ran the flow and against which environment. "Nobody has run it yet" is a valid answer. The point is that a reviewer reads it in the description instead of asking.
+
+Run the script on specific pages with `node scripts/check-docs-conventions.mjs docs/mcp/overview.md`, or across the whole site with `--all`.

package.json

@@ -16,6 +16,7 @@
     "preview:docs": "pnpm --filter memwal-docs serve",
     "verify:memwal": "tsx scripts/verify-memwal-credentials.ts",
     "check:compatibility": "node scripts/check-compatibility-contract.mjs",
+    "check:docs": "node scripts/check-docs-conventions.mjs",
     "tx:publish": "tsx scripts/build-publish-tx.ts",
     "tx:create-caps": "tsx scripts/build-migration-caps-tx.ts",
     "tx:finalize": "tsx scripts/build-finalize-tx.ts",