Runbook: Regenerate STRIX Harness Documentation

docs / process / runbooks / regenerate-documentation

← all docs

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

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

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/