docs: add "keep in sync" maintenance instructions

- New docs/maintaining.md (build/deploy, custom domain, figures, the
  spreadsheet snippet) + nav entry
- PLAYBOOK: "Documentation site — keep it in sync" section + Quick-start
  step 12, so a future agent updates docs/ when changing the toolkit

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: jackgallant

PLAYBOOK.md

@@ -47,6 +47,21 @@ boundary is "today minus ~5 years"; advance it as the calendar moves.
 
 ---
 
+## Documentation site — keep it in sync
+
+There is a public documentation website built from `docs/` (MkDocs + Material),
+live at **https://gallantlab.org/literature-review-toolkit/**. It is a *superset*
+of this PLAYBOOK and the README, not a fork. **When you change the toolkit — a
+tool, a phase, a command/flag, a guardrail or lesson — update the matching page
+under `docs/` in the same change** (fastest to drift: `docs/phases.md`,
+`docs/tools.md`, `docs/pipeline.md`). It auto-deploys via
+`.github/workflows/docs.yml` on push to `main` (build runs `mkdocs build
+--strict`). Full editing/figure/snippet details live in `docs/maintaining.md`.
+The repo is **public** (that's what enables free Pages); `site_url` uses the org's
+`gallantlab.org` custom domain, not `github.io`.
+
+---
+
 ## Phase 0 — choose the mode (do this first)
 
 One tool, two front-ends. Everything after the front-end — verify, citation
@@ -853,6 +868,8 @@ not a framework — they're scaffolding to keep the LLM judgment work fast.
 10. Phase 8: report to user.
 11. Phase 4 (PDF download) is OPTIONAL. Only run if the user explicitly
     asks for PDFs.
+12. If you changed any tool/phase/command, update the matching docs/ page
+    (see "Documentation site — keep it in sync" above).
 ```
 
 For a topic with ~40 search-added + ~30 xref-added papers, the default

docs/maintaining.md

@@ -0,0 +1,60 @@
+# Maintaining this site
+
+Notes for whoever edits the docs next — human or agent.
+
+!!! warning "Keep the docs in sync with the toolkit"
+    This site is a **superset of `README.md` + `PLAYBOOK.md`**, not a fork. When
+    you change the toolkit — add/rename a tool, change a phase, alter a command or
+    flag, add a guardrail/lesson — **update the affected page under `docs/` in the
+    same change.** The pages that drift fastest:
+
+    - `docs/phases.md` — phase commands and guardrails
+    - `docs/tools.md` — the tool tables (one row per script in `tools/`)
+    - `docs/pipeline.md` — the Mermaid flow and the phases-at-a-glance line
+
+## How it's built and deployed
+
+- **Engine:** MkDocs + Material. Config: [`mkdocs.yml`](https://github.com/gallantlab/literature-review-toolkit/blob/main/mkdocs.yml). Content: `docs/`.
+- **Deploy:** [`.github/workflows/docs.yml`](https://github.com/gallantlab/literature-review-toolkit/blob/main/.github/workflows/docs.yml)
+  runs on every push to `main` that touches `docs/**`, `mkdocs.yml`, or the
+  workflow. It runs `mkdocs build --strict` (a broken link or missing file
+  **fails the build**) and publishes to GitHub Pages.
+- **Live URL:** <https://gallantlab.org/literature-review-toolkit/> — the
+  `gallantlab` org serves project Pages under its **custom domain**, so
+  `site_url` in `mkdocs.yml` is `gallantlab.org`, **not** `github.io`. Don't
+  "correct" it back.
+- **Repo is public** — that's what lets free GitHub Pages serve it.
+
+## Preview locally
+
+```bash
+pip install -r docs/requirements.txt
+mkdocs serve            # http://127.0.0.1:8000, live-reload
+mkdocs build --strict   # what CI runs; fix anything it flags before pushing
+```
+
+## Where the figures come from
+
+All example figures are **real outputs from actual reviews**, copied into
+`docs/assets/`:
+
+- `assets/figures/lineage_*.png` — families figures (`families_figure.py` output)
+  from various review subdirectories.
+- `assets/figures/lab_*.png` — the `gallant_lab` lab-mode trajectory + in-context
+  figures.
+- `assets/examples/example_review_*.png` — pages of a review `.docx`, rendered via
+  LibreOffice → PDF → `pdftoppm`, then trimmed with ImageMagick.
+
+To refresh them, re-copy the source PNG (or re-render the `.docx`/`.xlsx`) and
+overwrite the file in `docs/assets/` — the filenames are referenced from the
+Markdown, so keep them stable.
+
+## The spreadsheet preview table
+
+The colour-coded bibliography table on the [Phases](phases.md#phase-5-build-the-spreadsheet)
+page is **not** a screenshot — it's HTML generated from a real `rows.json` and
+pulled in as a snippet (`--8<-- "docs/_includes/bib_table.html"`). To regenerate
+it from a different review, build an HTML `<table class="bib-preview">` with rows
+classed `row-search` / `row-xref` / `row-source` (the colour classes live in
+`docs/stylesheets/extra.css`) and overwrite `docs/_includes/bib_table.html`. That
+partial is excluded from the published site via `exclude_docs` in `mkdocs.yml`.

mkdocs.yml

@@ -93,3 +93,4 @@ nav:
   - Topic mode vs lab mode: modes.md
   - Tools reference: tools.md
   - Examples: examples.md
+  - Maintaining this site: maintaining.md