Runbook: Regenerate STRIX Harness Documentation
Owner: Doc harness maintainer | Frequency: As needed (whenever a generator or its source data changes) Last Updated: 2026-08-14 | Last Run: 2026-08-14 (full regeneration pass during initial harness build)
Purpose
Step-by-step commands to regenerate this project's own generated documentation
— architecture.html, diagrams/module-graph.html, the HTML'd design/module
docs, and the module-docs index table — after editing a generator script. Pairs
with docs/process/harness-maintenance-process.md, which explains when and
why to run each of these.
All commands assume the current working directory is the STRIX project
root (the folder containing tools/, docs/, diagrams/, samples/).
Prerequisites
- [ ] Python 3.10+ available (
python3 --version) - [ ] Python
markdownpackage installed forgen_design_html.py(pip3 install markdown --break-system-packagesif missing) - [ ] The generator you're about to run has already been edited per Step 2 of
docs/process/harness-maintenance-process.md - [ ]
scratchpad/py_structure.jsonexists and is current, if runninggen_modules.py(it is the real AST dumpgen_modules.pyreads from)
Procedure
Step 1: Regenerate the architecture hub page and module-graph page
cd STRIX
python3 tools/gen_html.py
Expected result: architecture.html and diagrams/module-graph.html are
rewritten in place. No console output on success beyond a normal exit (script
does not print progress messages).
If it fails:
- ModuleNotFoundError — you're not running from the STRIX project root, or a
stray edit introduced a bad import. Re-check cwd.
- SyntaxError: unterminated string literal inside an f-string — a template
edit introduced brace/quote nesting the f-string can't parse. Rewrite the
affected block using .format()-style templating instead of nested
f-strings (this happened once during the original build, in
gen_design_html.py's render function).
Step 2: Regenerate HTML versions of design/module docs
cd STRIX
python3 tools/gen_design_html.py
Expected result: Six HTML files are rewritten from their Markdown
sources: docs/design/HLD.html, docs/design/LLD.html,
docs/design/agentic-framework.html, docs/modules/runtime.html,
docs/modules/report.html, docs/modules/agents.html. Mermaid code fences in
the source Markdown are converted to <div class="mermaid"> blocks and
rendered via Mermaid-from-CDN in the output HTML.
If it fails:
- ModuleNotFoundError: No module named 'markdown' — install it:
pip3 install markdown --break-system-packages
- A doc you edited isn't showing up in HTML at all — it's not yet in the
PAGES list inside gen_design_html.py. Add a
(md_path, html_path, title, breadcrumb) tuple for it, then re-run.
Step 3: Regenerate the module-docs index table
cd STRIX
python3 tools/gen_modules.py
Expected result: Prints a Markdown table (package, doc file, description,
file count, LOC) to stdout, sourced from scratchpad/py_structure.json and
the MODULE_DOCS dict in the script. This output is the source for the index
table in docs/modules/README.md — paste/merge it in if the table changed.
If it fails:
- FileNotFoundError: scratchpad/py_structure.json — the AST dump is
missing or was deleted. Regenerating it requires re-running the AST
extraction pass against samples/strix/ (out of scope for this runbook —
see the process document's "re-clone Strix" edge case).
- Table shows 0 files for a package — check MODULE_DOCS maps that package's
key correctly to its folder name in strix/.
Step 4 (optional): Regenerate codeviz drill-down / stage explorer / cluster labels
Only needed if the underlying Graphify output or Strix source changed.
cd STRIX
python3 tools/codeviz/codeviz.py \
--root samples/strix --name "Strix" --top-package strix \
--exclude tests --exclude .venv --exclude interface/tui \
--out tool-outputs/codeviz/strix-codeviz.html
python3 tools/codeviz/gen_cluster_labels.py \
--in tool-outputs/graphify/graph.json \
--out-dir tool-outputs/graphify --project "Strix (STRIX)"
python3 tools/codeviz/gen_stage_explorer.py
Expected result: tool-outputs/codeviz/strix-codeviz.html,
tool-outputs/graphify/graph.labeled.json +
tool-outputs/graphify/labeled-clusters.html, and
tool-outputs/codeviz/strix-stage-explorer.html are rewritten.
If it fails:
- codeviz.py errors on a package it can't resolve — check --exclude flags
match the current samples/strix/ layout (it may drift if Strix is
re-cloned at a newer commit)
- gen_cluster_labels.py mis-labels or under-labels clusters — check its
pkg_of() function and MODULE_THEME dict are still correct for the
current strix/<package> layout
Step 5: Refresh the runnable samples snapshot (only if tools/ changed)
cd STRIX
rsync -a --exclude='__pycache__' tools/ samples/harness-tools/
Expected result: samples/harness-tools/ matches tools/ again.
If it fails:
- rsync: command not found — fall back to
cp -r tools/*.py samples/harness-tools/ && cp -r tools/codeviz/*.py tools/codeviz/README.md samples/harness-tools/codeviz/
Verification
- [ ] Open
architecture.htmland click through the Simple/Technical.switchtoggle — both states render correctly - [ ] In the "Explore the full documentation" section of
architecture.html, spot-check 3–5 links resolve to real files - [ ] Any Markdown doc you edited has matching content in its
.htmlcounterpart (if it's in thePAGESlist) - [ ]
docs/modules/README.md's index table file/LOC counts matchgen_modules.py's latest stdout output - [ ]
diff -rq tools/ samples/harness-tools/(ignoring__pycache__) returns no differences, iftools/was edited this run
Troubleshooting
| Symptom | Likely Cause | Fix |
|---|---|---|
Operation not permitted deleting tools/__pycache__/*.pyc |
Cowork blocks deletes inside the primary connected project folder | Ignore — cache files, not deliverables; excluded from samples sync via rsync --exclude |
Graphviz dot errors with syntax error near 'Graph' |
A node literally named Graph collides with the Graphviz keyword |
Rename the node (e.g. AgentsGraph) in the .dot source |
Graphviz warns #fff is "not a known color" |
dot wants full 6-hex color codes |
Use #ffffff instead of #fff throughout .dot files |
npm install -g fails with EACCES |
Default npm prefix isn't user-writable in this sandbox | npm config set prefix ~/.npm-global and add ~/.npm-global/bin to PATH |
graphify command not found after pip install |
pip installs scripts to ~/.local/bin, not on PATH by default |
export PATH="$PATH:$HOME/.local/bin" (or the sandbox's equivalent path) before running |
| Graphify skips HTML viz: "too large for HTML viz" | Node count exceeds the default viz limit | Set GRAPHIFY_VIZ_NODE_LIMIT env var higher (e.g. 6000) before re-running |
Write/Read/Edit tool errors on a /sessions/... path |
Those tools operate on the host filesystem, not the sandbox VM path | Use mcp__workspace__bash heredocs (cat > "path" << 'EOF') for files inside mounted project/vault folders instead |
Rollback
Generated files are deterministic outputs of the scripts in tools/ — there
is no separate rollback mechanism beyond version control. If a regeneration
run produces bad output:
1. Revert the generator script edit in tools/ (e.g. git checkout -- tools/gen_html.py, or restore from samples/harness-tools/ if it still has the last-known-good version)
2. Re-run the relevant command from this runbook to regenerate correct output
Escalation
| Situation | Contact | Method |
|---|---|---|
A generated doc's factual claim about Strix looks wrong and you can't verify it against samples/strix/ |
Whoever originally verified the claim (see the doc's own commit history / the vault's Project Log) | Check STRIX — Project Log.md in the vault for context, then re-verify against source directly |
| A design-token change is needed project-wide | Owner of templates/design-system/tokens.css |
Update the tokens file, then manually sync the hard-coded CSS strings in gen_html.py and gen_design_html.py to match |
History
| Date | Run By | Notes |
|---|---|---|
| 2026-08-14 | Doc harness maintainer | Full regeneration pass during initial harness build; also created this runbook and samples/harness-tools/ |