10 · Troubleshooting & Glossary

← Docs home · Common failure modes, fixes, and the project vocabulary.

Fuller pipeline troubleshooting is in docs/PIPELINE_GUIDE.md § Troubleshooting.

Troubleshooting

Pipeline

Symptom Likely cause / fix
“Subagent returned unexpected output” A chunked AI step returned malformed content. Re-run that step; for solutions, ensure the sub-agent returned only <details> blocks (see below).
Pipeline freezes on remaster Remaster is the highest-load step. Section likely >800 lines and should chunk via remaster_chunked.py. See PIPELINE_GUIDE.md § chunking / performance.
File not found: _pipeline_state.json No prior run for this section. It’s created on first run — not an error; just start the pipeline.
Math-check reports many false positives The AI review is conservative. Confirm against the deterministic pre-check (check_latex_delimiters); genuine issues are unbalanced $/{} or HTML tags inside math.
Orphan _Solutions.md (page renders short/broken) A sub-agent wrote a standalone solutions file instead of a splice. Always use splice_solutions.py; the sub-agent must return only <details> blocks, one per problem. (Regression: calc §2.3, 2026-05-19/20.)
A teaching section ends up unnumbered mid-flow It was titled ## Key Terms. number.py excludes “Key Terms” from numbering — reserve that title for the end-of-section glossary; give teaching sections a descriptive title.

Figures & media

Symptom Likely cause / fix
Figure renders but looks wrong (label collision, backwards sweep) Lint passed but the image is wrong. Read the PNG. Wrap labels in Group(); AnnularSector pies sweep CCW.
Batch render: many failures Usually slug too long (>4 hyphen-tokens → path truncation). Shorten slugs, re-render with --only <slug>.
--auto-render did nothing Docker missing — the hook logs a warning and skips rather than failing. Install/start Docker.
Stale figure/video shows after re-render Cache token not bumped. Bump cache_buster: in the manifest and the HTML ?v= together (bump-cache-version).

Publish & deploy

Symptom Likely cause / fix
Chapter-subdir pages render unstyled after a publish change Asset path-depth bug. publish.py rewrite depth must be sub.count('/') + 1, not +2 (memory project_publish_path_depth).
Pushed to git but the site didn’t change git push doesn’t deploy. Run wrangler pages deploy docs --project-name bookshelf --branch desktop --commit-dirty=true (desktop = production; --branch preview only updates the staging alias, not oerbookshelf.app).
raSHio callout links 404 raSHio wasn’t deployed before the book page. Deploy the linked tool site first.
AI tutor / decks 500 on the live site D1 migrations not applied or R2 bucket missing. wrangler d1 migrations apply bookshelf-ai; wrangler r2 bucket create bookshelf-decks.

Editing existing rendered HTML

Glossary

Term Meaning
ALL_STEPS The 15-step ordered pipeline list the book-pipeline skill walks.
Remaster The AI step that rewrites raw source into textbook-density prose.
Numbered MD / _Solutions.md The number.py output, and its clone with <details> solutions spliced in.
Splice Inserting <details> solution blocks into a copy of the numbered MD (splice_solutions.py) — not a standalone file.
Philosophy-reorg Step 7.5: enforce Def → TIN → Example order within each H2.
Try-It-Now (TIN) Inline practice block with a reveal-on-click solution.
Context Pause / Insight Note Editorial callouts (the “why”). Use callout-inline when adjacent to a TIN/Example to avoid sidebar float.
Fixup (Phase A / B) Step 11: 18 deterministic HTML cleanups (fixup_phase_a.py) + targeted AI fixes.
Survival guard A publish.py post-copy transform (figure swaps, navbar sync, slides injection) reapplied on every publish.
Figure-anim-wrap / figure-static-wrap The <img>-replacement wrapper for animated MP4 / static PNG figure pairs.
Cache-buster (?v=YYYYMMDD) Asset version token; bump on any CSS/JS/figure change.
kami + Wedgwood The active editorial theme — print-grade structure, Wedgwood-Blue accent. Lives in style-bookshelf.css.
raSHio The author’s free web calculator tools that replace TI-calculator instructions.
Preflight The validate-everything-before-running gate (preflight.py / book-pipeline-preflight).
Stitch (disabled) Former step 12 — assembled chapter pages. Retired 2026-06-06; do not run.
D1 / R2 Cloudflare’s SQLite database / object storage, backing the AI tutor and slide decks.
Pages Function A serverless route under functions/ (file-based routing) adding dynamic behavior to the static site.
graphify The repo knowledge-graph tool; report in graphify-out/GRAPH_REPORT.md.
Handoff A single-slot resume note (HANDOFF.md) for picking up work across sessions.

When these docs and a SKILL.md disagree

The SKILL.md wins — it’s the live spec and changes with the code. These docs are a navigational layer over the skills; if you find drift, fix the skill first, then update the matching docs page.