docs: bring the book to parity with the skill; PR-gate the book build

The cross-harness skill shipped (PR #17/#19) with README/CLAUDE.md/AGENTS.md
coverage, but the mdBook — the public disclosure surface — had zero mention
of it. By this project's own standard that is a parity defect: the flagship
consumable feature was undocumented where it is disclosed.

- New chapter "Consume it: the peltier skill" (docs/src/skill.md): install
  paths and the harness matrix, the ZeroClaw script-blocking variant, the
  gate order verify mode enforces, the refusal doctrine, and exactly which
  of these claims CI asserts. Numbers carry their CI and workload.
- SUMMARY.md, architecture.md (layout now lists the skill + mirror),
  reproduce.md, introduction.md: cross-links to the chapter.
- docs.yml: pull requests now BUILD the book (never deploy) — a broken
  chapter or dangling include is a red PR check, not a post-merge surprise.
  Also closes an audit finding: the book rebuilds when results/** changes,
  since case-study chapters {{#include}} evidence files from there.

Book build verified locally with mdbook 0.4.x (skill.html renders).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
2026-07-15 12:19:49 -04:00
co-authored by Claude Fable 5
parent c2d80f95d8
commit 6e169ab819
6 changed files with 122 additions and 3 deletions
+16 -2
View File
@@ -2,12 +2,23 @@ name: docs
# Builds the mdBook site in docs/ and deploys it to GitHub Pages.
# One-time setup: repo Settings → Pages → Source = "GitHub Actions".
#
# Pull requests build the book but never deploy — so a broken book (or a
# chapter that {{#include}}s a file that moved) is a red PR check, not a
# post-merge surprise. results/** is a trigger because case-study chapters
# include evidence files from there.
on:
push:
branches: [main]
paths:
- "docs/**"
- "results/**"
- ".github/workflows/docs.yml"
pull_request:
paths:
- "docs/**"
- "results/**"
- ".github/workflows/docs.yml"
workflow_dispatch:
@@ -18,8 +29,8 @@ permissions:
# Allow one concurrent deployment; don't cancel an in-progress prod deploy.
concurrency:
group: pages
cancel-in-progress: false
group: pages-${{ github.event_name == 'pull_request' && github.ref || 'prod' }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
jobs:
build:
@@ -29,6 +40,7 @@ jobs:
steps:
- uses: actions/checkout@v4
- name: Configure Pages
if: github.event_name != 'pull_request'
uses: actions/configure-pages@v5
- name: Install mdBook
run: |
@@ -39,11 +51,13 @@ jobs:
- name: Build
run: mdbook build docs
- name: Upload artifact
if: github.event_name != 'pull_request'
uses: actions/upload-pages-artifact@v3
with:
path: docs/book
deploy:
if: github.event_name != 'pull_request'
needs: build
runs-on: ubuntu-latest
environment: