[codex] validate GitHub Pages docs payload in CI (#96)

* fix(ci): validate pages docs payload

* feat(docs): wire mdbook-admonish preprocessor for mdbook 0.5 compatibility

- Add [preprocessor.admonish] to book/book.toml via mdbook-admonish install
- Refresh mdbook-admonish.css to v1.20.0 assets
- Install mdbook-admonish from padamson/mdbook-admonish@feat/mdbook-0.5-compat
  (tommilligan/mdbook-admonish#235) in CI and docs workflows — released v1.20.0
  was built against mdbook 0.4.x and fails on 0.5's null config fields
- Add admonish presence check and install instructions to Justfile docgen recipe
- Add smoke-test admonish blocks (note/warning/tip) to book/src/intro.md

TODO: pin to a released version once #235 merges upstream

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(ci): rename MDBOOK_* env vars to TOOL_ prefix to avoid mdbook config injection

mdbook 0.5 reads MDBOOK_* env vars as config key overrides (strips prefix,
lowercases, replaces _ with -). MDBOOK_MERMAID_VERSION was being injected as
the unknown config key `mermaid-version`, causing `ERROR invalid key` on every
docs build. MDBOOK_VERSION had the same risk with `version`.

Renaming to TOOL_MDBOOK_VERSION / TOOL_MDBOOK_MERMAID_VERSION avoids the prefix
match entirely.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(docker): add kani-proofs to planner and builder COPY stages

cargo chef prepare failed because kani-proofs was a workspace member
but was not copied into the Docker context before the planner stage ran.
Adds COPY to both planner (before cargo chef prepare) and builder.

Adds wrkflw-ci-build.yml workflow and `just build` recipe to prove the
fix locally without Docker: runs cargo chef prepare + ledgerr-mcp build
via wrkflw emulation mode, asserting kani-proofs appears in the recipe.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(release): remove unknown cog field ignore_fixup_commits

Field was rejected by cocogitto at runtime, blocking cog bump.
Removed; merge-commit skipping is handled by ignore_merge_commits.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(ci): resolve workflow validation failures on every push

Two workflows were failing GitHub's parse-time validation on every push:

- publish.yml: secrets context is not available during job-level `if:`
  evaluation. Moved CRATES_IO_TOKEN/PYPI_API_TOKEN to job-level env vars
  and gated each step with `if: ${{ env.TOKEN != '' }}` instead.

- wrkflw-docgen.yml: `runner.temp` is a job-execution context, not
  available in workflow-level `env:` blocks. Replaced with `/tmp/sccache`
  (always correct in emulation mode where wrkflw runs on the host).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet (coordinator) <coordinator@promptexecution.com.au>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 3 people

.github/workflows/ci.yml

@@ -9,6 +9,10 @@ permissions:
   contents: write
   security-events: write
 
+env:
+  TOOL_MDBOOK_VERSION: "0.5.0"
+  TOOL_MDBOOK_MERMAID_VERSION: "0.17.0"
+
 jobs:
   test-and-build:
     runs-on: ubuntu-latest
@@ -116,8 +120,7 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
   docs-check:
-    needs: test-and-build
-    if: github.event_name == 'pull_request'
+    name: Validate GitHub Pages docs build
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -132,20 +135,17 @@ jobs:
       - name: Install just
         run: cargo install just --locked
 
-      - name: Setup mdBook
-        uses: jontze/action-mdbook@v3
-        with:
-          token: ${{ secrets.GITHUB_TOKEN }}
-          use-mermaid: true
-
-      - name: Install mdbook binaries
-        run: cargo install mdbook mdbook-mermaid --locked
+      - name: Install mdBook toolchain
+        run: |
+          cargo install mdbook --version "$TOOL_MDBOOK_VERSION" --locked
+          cargo install mdbook-mermaid --version "$TOOL_MDBOOK_MERMAID_VERSION" --locked
 
       - name: Install mdbook-admonish
-        run: cargo install mdbook-admonish --locked
+        # TODO: pin to a released version once tommilligan/mdbook-admonish#235 merges
+        run: cargo install --git https://github.com/padamson/mdbook-admonish.git --branch feat/mdbook-0.5-compat mdbook-admonish
 
       - name: Install mdbook-rhai-mermaid
         run: cargo install --path crates/mdbook-rhai-mermaid
 
-      - name: Validate docs
-        run: just docgen-check
+      - name: Validate GitHub Pages docs payload
+        run: just docgen-pages-check

.github/workflows/docs.yml

@@ -9,6 +9,10 @@ on:
 permissions:
   contents: write
 
+env:
+  TOOL_MDBOOK_VERSION: "0.5.0"
+  TOOL_MDBOOK_MERMAID_VERSION: "0.17.0"
+
 jobs:
   deploy:
     runs-on: ubuntu-latest
@@ -19,26 +23,26 @@ jobs:
       - name: Install Rust
         uses: dtolnay/rust-toolchain@stable
 
+      - name: Setup Node
+        uses: actions/setup-node@v4
+
       - name: Install just
         run: cargo install just --locked
 
-      - name: Setup mdBook
-        uses: jontze/action-mdbook@v3
-        with:
-          token: ${{ secrets.GITHUB_TOKEN }}
-          use-mermaid: true
-
-      - name: Install mdbook binaries
-        run: cargo install mdbook mdbook-mermaid --locked
+      - name: Install mdBook toolchain
+        run: |
+          cargo install mdbook --version "$TOOL_MDBOOK_VERSION" --locked
+          cargo install mdbook-mermaid --version "$TOOL_MDBOOK_MERMAID_VERSION" --locked
 
       - name: Install mdbook-admonish
-        run: cargo install mdbook-admonish --locked
+        # TODO: pin to a released version once tommilligan/mdbook-admonish#235 merges
+        run: cargo install --git https://github.com/padamson/mdbook-admonish.git --branch feat/mdbook-0.5-compat mdbook-admonish
 
       - name: Install mdbook-rhai-mermaid
         run: cargo install --path crates/mdbook-rhai-mermaid
 
-      - name: Build docs
-        run: just docgen
+      - name: Validate GitHub Pages docs payload
+        run: just docgen-pages-check
 
       - name: Deploy to GitHub Pages
         uses: peaceiris/actions-gh-pages@v3

.github/workflows/publish.yml

@@ -53,47 +53,54 @@ jobs:
   publish-crates:
     runs-on: ubuntu-latest
     needs: publish-ghcr
-    if: ${{ secrets.CRATES_IO_TOKEN != '' }}
+    env:
+      CRATES_IO_TOKEN: ${{ secrets.CRATES_IO_TOKEN }}
     steps:
       - name: Checkout
+        if: ${{ env.CRATES_IO_TOKEN != '' }}
         uses: actions/checkout@v4
 
       - name: Install Rust
+        if: ${{ env.CRATES_IO_TOKEN != '' }}
         uses: dtolnay/rust-toolchain@stable
 
       - name: Publish ledger-core
+        if: ${{ env.CRATES_IO_TOKEN != '' }}
         run: cargo publish -p ledger-core --token "${CRATES_IO_TOKEN}"
-        env:
-          CRATES_IO_TOKEN: ${{ secrets.CRATES_IO_TOKEN }}
 
       - name: Wait for crates.io index propagation
+        if: ${{ env.CRATES_IO_TOKEN != '' }}
         run: sleep 20
 
       - name: Publish ledgerr-mcp
+        if: ${{ env.CRATES_IO_TOKEN != '' }}
         run: cargo publish -p ledgerr-mcp --token "${CRATES_IO_TOKEN}"
-        env:
-          CRATES_IO_TOKEN: ${{ secrets.CRATES_IO_TOKEN }}
 
   publish-pypi:
     runs-on: ubuntu-latest
     needs: publish-ghcr
-    if: ${{ secrets.PYPI_API_TOKEN != '' }}
+    env:
+      PYPI_API_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
     steps:
       - name: Checkout
+        if: ${{ env.PYPI_API_TOKEN != '' }}
         uses: actions/checkout@v4
 
       - name: Set up Python
+        if: ${{ env.PYPI_API_TOKEN != '' }}
         uses: actions/setup-python@v5
         with:
           python-version: "3.11"
 
       - name: Build Python package
+        if: ${{ env.PYPI_API_TOKEN != '' }}
         working-directory: plugins/l3dg3rr-plugin-create/python
         run: |
           python -m pip install --upgrade pip build
           python -m build
 
       - name: Publish to PyPI
+        if: ${{ env.PYPI_API_TOKEN != '' }}
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
           packages-dir: plugins/l3dg3rr-plugin-create/python/dist/

.github/workflows/wrkflw-ci-build.yml

@@ -0,0 +1,59 @@
+# wrkflw-ci-build: local CI build verification (emulation mode, no Docker required)
+# Run with: wrkflw run .github/workflows/wrkflw-ci-build.yml
+# Or via:   just build
+#
+# Proves that:
+#   1. cargo chef prepare succeeds (the planner step that failed without kani-proofs)
+#   2. cargo build -p ledgerr-mcp compiles cleanly
+#
+# Requires: Rust toolchain on host (cargo-chef installed automatically if missing)
+name: wrkflw-ci-build
+
+on:
+  workflow_dispatch:
+
+env:
+  CARGO_TERM_COLOR: always
+  RUST_BACKTRACE: "1"
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  planner-smoke:
+    name: "Planner smoke (cargo chef prepare)"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install cargo-chef
+        run: |
+          if ! command -v cargo-chef >/dev/null 2>&1; then
+            cargo install cargo-chef --locked
+          fi
+
+      - name: Run cargo chef prepare
+        run: |
+          cargo chef prepare --recipe-path /tmp/recipe.json
+          echo "=== recipe.json written ($(wc -c < /tmp/recipe.json) bytes) ==="
+          python3 -c "
+          import json, sys
+          d = json.load(open('/tmp/recipe.json'))
+          members = [m['relative_path'] for m in d['skeleton']['manifests']]
+          print('workspace members in recipe:', len(members))
+          for m in members:
+              print(' ', m)
+          assert any('kani-proofs' in m for m in members), 'kani-proofs missing from recipe!'
+          print('PASS: kani-proofs present in cargo chef recipe')
+          "
+
+  build-mcp:
+    name: "Build ledgerr-mcp"
+    needs: [planner-smoke]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build ledgerr-mcp
+        run: cargo build -p ledgerr-mcp --bin ledgerr-mcp-server

.github/workflows/wrkflw-docgen.yml

@@ -23,7 +23,7 @@ env:
   # (wrkflw secure-emulation runs as host processes — no sandboxing of the daemon).
   # If sccache is not installed, RUSTC_WRAPPER is silently ignored by cargo.
   RUSTC_WRAPPER: sccache
-  SCCACHE_DIR: ${{ runner.temp || '/tmp' }}/sccache
+  SCCACHE_DIR: /tmp/sccache
   CARGO_TERM_COLOR: always
   RUST_BACKTRACE: "1"
 

Dockerfile

@@ -18,6 +18,7 @@ FROM chef AS planner
 COPY Cargo.toml Cargo.lock ./
 COPY crates ./crates
 COPY xtask ./xtask
+COPY kani-proofs ./kani-proofs
 RUN cargo chef prepare --recipe-path recipe.json
 
 # ── build ─────────────────────────────────────────────────────────────────────
@@ -28,6 +29,7 @@ RUN cargo chef cook --release --recipe-path recipe.json
 COPY Cargo.toml Cargo.lock ./
 COPY crates ./crates
 COPY xtask ./xtask
+COPY kani-proofs ./kani-proofs
 COPY docs ./docs
 COPY rules ./rules
 COPY scripts ./scripts

Justfile

@@ -433,9 +433,12 @@ stats:
 
 # Build mdbook documentation locally
 # Requires: cargo install mdbook mdbook-mermaid && cargo install --path crates/mdbook-rhai-mermaid
+# mdbook-admonish: cargo install --git https://github.com/padamson/mdbook-admonish.git --branch feat/mdbook-0.5-compat mdbook-admonish
+# TODO: switch to a released version once tommilligan/mdbook-admonish#235 merges
 docgen:
     @if [ ! -x ~/.cargo/bin/mdbook ]; then echo "error: mdbook not found — run: cargo install mdbook mdbook-mermaid"; exit 1; fi
     @if [ ! -x ~/.cargo/bin/mdbook-mermaid ]; then echo "error: mdbook-mermaid not found — run: cargo install mdbook-mermaid"; exit 1; fi
+    @if [ ! -x ~/.cargo/bin/mdbook-admonish ]; then echo "error: mdbook-admonish not found — see comment above docgen recipe in Justfile"; exit 1; fi
     @if [ ! -x ~/.cargo/bin/mdbook-rhai-mermaid ]; then cargo install --path crates/mdbook-rhai-mermaid --quiet; fi
     PATH="$HOME/.cargo/bin:$PATH" ~/.cargo/bin/mdbook build book
     @echo "Docs built in book/book/ — serve with: npx serve book/book"
@@ -475,9 +478,19 @@ docgen-check:
     @echo "Running live-editor unit tests..."
     @node --test book/theme/rhai-live-core.test.js
     @echo "Checking iso-pipeline-objects.html has at least 5 mermaid blocks..."
-    @count=$$(grep -c 'class="mermaid"' book/book/iso-pipeline-objects.html); echo "Found $$count mermaid blocks in iso-pipeline-objects.html"; if [ "$$count" -lt 5 ]; then echo "error: expected at least 5 mermaid blocks, found $$count"; exit 1; fi; echo "✓ iso-pipeline-objects.html has $$count mermaid blocks (>= 5)"
+    @count=$(grep -c 'class="mermaid"' book/book/iso-pipeline-objects.html || true); echo "Found $count mermaid blocks in iso-pipeline-objects.html"; if [ "$count" -lt 5 ]; then echo "error: expected at least 5 mermaid blocks, found $count"; exit 1; fi; echo "✓ iso-pipeline-objects.html has $count mermaid blocks, expected at least 5"
     @echo "All documentation diagrams validated!"
 
+# Verify the exact mdBook output directory published to GitHub Pages.
+docgen-pages-check:
+    just docgen-check
+    @test -f book/book/index.html || { echo "error: GitHub Pages publish payload missing book/book/index.html"; exit 1; }
+    @compgen -G 'book/book/theme/rhai-live-core*.js' >/dev/null || { echo "error: GitHub Pages publish payload missing live editor core asset"; exit 1; }
+    @compgen -G 'book/book/theme/rhai-live-*.js' >/dev/null || { echo "error: GitHub Pages publish payload missing live editor asset"; exit 1; }
+    @compgen -G 'book/book/mdbook-admonish*.css' >/dev/null || { echo "error: GitHub Pages publish payload missing admonish CSS"; exit 1; }
+    @grep -q 'l3dg3rr Ledger Documentation' book/book/index.html || { echo "error: GitHub Pages index does not look like the hosted docs"; exit 1; }
+    @echo "✓ GitHub Pages docs payload validated at book/book/"
+
 # Negative test: verify broken cross-references are present in output (mdBook
 # does not fail on broken links at build time — this confirms the behavior)
 docgen-check-negative:
@@ -505,6 +518,16 @@ docgen-check-negative:
 test-mcp-providers:
     cargo test -p ledgerr-mcp --test mcp_provider_smoke 2>&1 | tail -20
 
+# ─── build: local CI build via wrkflw ──────────────────────────────────────
+
+# Prove the Dockerfile planner fix: runs cargo chef prepare + ledgerr-mcp build
+# via wrkflw emulation mode (no Docker required).
+build emulation="emulation":
+    @if ! command -v wrkflw >/dev/null 2>&1; then echo "error: wrkflw not found — run: cargo install wrkflw"; exit 1; fi
+    @echo "=== wrkflw: CI build verification ==="
+    wrkflw run --runtime {{emulation}} .github/workflows/wrkflw-ci-build.yml
+    @echo "=== build complete ==="
+
 # ─── wrkflw: local CI pipeline runner ──────────────────────────────────────
 
 # Run the wrkflw-local-docgen workflow locally using emulation mode (no Docker).

book/book.toml

@@ -4,17 +4,17 @@ language = "en"
 src = "src"
 title = "l3dg3rr Ledger Documentation"
 
-[preprocessor.admonish]
-command = "mdbook-admonish"
-assets_version = "3.1.0" # do not edit: managed by `mdbook-admonish install`
-
 [preprocessor.rhai-mermaid]
 command = "mdbook-rhai-mermaid"
 before = ["mermaid"]
 
 [preprocessor.mermaid]
 optional = true
-after = ["rhai-mermaid", "admonish"]
+after = ["rhai-mermaid"]
+
+[preprocessor.admonish]
+command = "mdbook-admonish"
+assets_version = "3.1.0" # do not edit: managed by `mdbook-admonish install`
 
 [output.html]
 edit-url-template = "https://github.com/PromptExecution/l3dg3rr/edit/main/book/src/{path}#L{line}"

book/src/intro.md

@@ -1,8 +1,9 @@
 # Introduction
 
-```admonish info
-**l3dg3rr** is designed for US expats who need to reconcile complex financial histories across multiple jurisdictions (US, AU, UK) without compromising privacy.
-```
+<div class="admonition info">
+<div class="admonition-title">Info</div>
+<p><strong>l3dg3rr</strong> is designed for US expats who need to reconcile complex financial histories across multiple jurisdictions (US, AU, UK) without compromising privacy.</p>
+</div>
 
 `l3dg3rr` is a local-first financial document intelligence system
  for retroactive U.S. expat tax preparation. It ingests raw statements, classifies transactions with editable rules, verifies hard constraints, and exports an accountant-usable Excel workbook with audit history.
@@ -53,3 +54,16 @@ The visualization chapters document the live mdBook diagram system. They are imp
 - [Workbook & Audit](./workbook-audit.md)
 - [Theory of Operation](./theory.md)
 - [Graph Data Model](./graph.md)
+
+<!-- mdbook-admonish smoke-test: remove once verified rendering works -->
+```admonish note title="Local-first by design"
+All processing runs on your machine — no private financial data leaves the host.
+```
+
+```admonish warning
+PDF ingestion rewrites the workbook in-place. Back up `tax-ledger.xlsx` before running a full re-ingest.
+```
+
+```admonish tip title="CPA handoff"
+Export the workbook after every classification pass so your accountant always has the latest reconciled state.
+```