Refresh the demo vault
scripts/refresh_demo.py is the one command that takes changed product documentation, summarises it into the example vault, and rebuilds the demo site.
It is a local maintainer tool. It never runs in CI, is not a CLI subcommand, and is not part of a packaged install.
What it does
- Reads the last-refreshed git revision from
demo/.demo-source-rev. - Asks git which files under
docs/changed since that revision (git diff --name-status) and which still have uncommitted working-tree edits (git status --porcelain), so a maintainer can preview before committing. - Builds a plan: added pages are added, deleted pages are removed, modified or renamed pages are removed and then re-added (llmwiki cannot update an already-ingested document in place).
- Drives the existing CLI against
demo/:add/remove, thensynth --docs-onlyscoped with--pathto each raw doc this plan just added (not every pending document in the vault), thenbuild --out demo/site, andlint. After synth it checks that every plan-added raw doc has a matchingwiki/sources/page and refuses to write.demo-source-revwhen coverage is incomplete (lint alone is not enough). Remove-only plans skip synth and do not require a reachable backend. - Writes
HEADintodemo/.demo-source-revonly after that coverage check passes. - Prints the full lint report. Warnings do not fail the run; they are the maintainer's sight of warning-severity defects under the errors-only CI gate.
Maintainer docs under docs/maintainers/ are not part of the product corpus and never enter the plan.
Prerequisites
- A git working copy of this repository. Change detection is git history, not file timestamps. The command cannot run from a release archive (a downloaded tarball or an installed wheel has no
.gitand no recorded revision to diff against). - A working synthesis backend (
synthesis.backendinconfig.jsonset toclaudeorollama, and that backend reachable). The script probes withllmwiki synth --checkand stops with an actionable error before it touches the vault if nothing is reachable.
Usage
From the repository root:
python3 scripts/refresh_demo.py --dry-run
python3 scripts/refresh_demo.py
python3 scripts/refresh_demo.py --force
python3 scripts/refresh_demo.py --base HEAD~5
python3 scripts/refresh_demo.py --verify-slugs reference-cli,upgrading
| Flag | Effect |
|---|---|
--dry-run |
Print the plan and write nothing. Does not need a synthesis backend. |
--force |
Treat every product doc under docs/ as changed (remove-then-add each). Use this for a first refresh when demo/.demo-source-rev does not exist yet. |
--base <rev> |
Diff against this revision instead of the SHA in demo/.demo-source-rev. |
--verify-slugs <a,b> |
Local coverage gate only: exit 1 if any listed raw/docs/<slug>/ file lacks a matching wiki/sources/ page. Used by the /release skill after a manual path-scoped synth; does not run a refresh. |
The command reports the plan before it does any work. --dry-run is the preview that changes nothing.
What this does not do
- It does not commit. After a real run, review
demo/raw/,demo/wiki/, anddemo/.demo-source-revyourself. - It does not run in GitHub Actions. CI builds and lints the committed demo; it never regenerates it. Wiki-checks also triggers on
docs/**. Ifdemo/.demo-source-revis committed, that job printspython3 scripts/refresh_demo.py --dry-runso a docs change without a local refresh is visible — still no model, still no vault write. - The committed pre-push hook reminds you when a push includes product markdown under
docs/(notdocs/maintainers/). The reminder does not fail the push; applying the plan is still a localrefresh_demo.pyrun. - It does not change how user vaults ingest documents. The remove-then-add workaround is demo-only.
- It does not refresh authored demo sessions. On a release cut the default is to run
scripts/generate_demo_sessions.pywith a release-day--today(and re-synth when filenames change) unless the human explicitly opts out — see RELEASE_PROCESS.md and #225.