Process Document: Maintaining the STRIX Documentation Harness
Owner: STRIX documentation harness maintainer (whoever last regenerated the docs) | Last Updated: 2026-08-14 | Review Cadence: Quarterly, or whenever tools/ changes
Scope note: this document is about operating this project's own documentation-generation tooling (
tools/gen_html.py,tools/gen_design_html.py,tools/gen_modules.py,tools/codeviz/*) — it is not about running Strix itself. For operating Strix (the pentesting agent), seedocs/process/process-operate-strix.md.
Purpose
The STRIX project folder documents the usestrix/strix codebase for a mixed
audience (analysts, junior developers, architects). Most of that documentation
is not hand-written Markdown/HTML — it is generated from source-verified
data (an AST dump of the Strix repo, Graphify/CodeGraph graph output, and a
MODULES config table) by five Python scripts under tools/. This process
exists so that:
- Documentation never silently drifts from the real Strix source, because it is regenerated from source data rather than hand-maintained prose.
- Anyone who updates the underlying data (re-clones a newer Strix commit, re-runs Graphify/CodeGraph) knows exactly which command to run to make the visible docs reflect that update.
- The project's standing rule — never hand-edit a generated file; edit the generator and regenerate — is actually enforceable, because the mapping from generator to output is written down here.
Scope
In scope: regenerating architecture.html, diagrams/module-graph.html,
the six HTML pages under docs/design/ and docs/modules/ that have Markdown
sources, and the module-docs index table (docs/modules/README.md).
Out of scope: re-running Graphify/CodeGraph/codeviz against a new Strix
source checkout (that is a separate, heavier activity — re-cloning Strix,
re-extracting graphs, and updating tool-outputs/), and hand-written docs that
have no generator (e.g. docs/00_START_HERE.md, the vault notes, this
document itself). Those are edited directly.
RACI Matrix
| Step | Responsible | Accountable | Consulted | Informed |
|---|---|---|---|---|
Edit a generator script in tools/ |
Doc harness maintainer | Doc harness maintainer | Whoever owns the MODULES schema / design tokens |
Team reading the docs |
| Run the regeneration commands | Doc harness maintainer | Doc harness maintainer | — | — |
| Verify generated output (links, layout, design-language parity) | Doc harness maintainer | Doc harness maintainer | — | — |
Refresh samples/harness-tools/ snapshot |
Doc harness maintainer | Doc harness maintainer | — | — |
Approve a change to the MODULES table (new package, changed deterministic/LLM classification) |
Doc harness maintainer | Whoever verified the underlying Strix source claim | Person who read the Strix source | Team |
Process Flow
Strix source or graph-tool output changes
│
▼
Edit the relevant generator in tools/ (never the .html/.md output directly)
│
▼
Run the generator (python3 tools/<script>.py)
│
▼
Spot-check the regenerated file(s): links resolve, design language matches,
content is source-accurate
│
▼
Refresh samples/harness-tools/ if tools/ changed
│
▼
Commit / hand off — no separate "publish" step, output is already in-place
Detailed Steps
Step 1: Identify what changed and which generator owns it
- Who: Doc harness maintainer
- When: Whenever the underlying Strix source, graph-tool output, or design tokens change, or a documentation bug is reported (broken link, stale content, wrong module count)
- How: Match the symptom to a generator using this table:
| Symptom / change | Generator to edit |
|---|---|
architecture.html content, layout, or the "Explore" hub links are wrong |
tools/gen_html.py |
diagrams/module-graph.html is wrong |
tools/gen_html.py (writes both files) |
HLD / LLD / agentic-framework HTML, or the 3 HTML'd module docs, look wrong or are out of date with their .md source |
tools/gen_design_html.py |
Module-docs index table (docs/modules/README.md) has wrong file/LOC counts |
tools/gen_modules.py (reads scratchpad/py_structure.json) |
| Module→file→function drill-down page is stale | tools/codeviz/codeviz.py |
| Graphify cluster labels are ungrouped or mis-themed | tools/codeviz/gen_cluster_labels.py |
| Pipeline stage explorer (S0–S15) is stale | tools/codeviz/gen_stage_explorer.py |
A .md file with no generator (e.g. 00_START_HERE.md, a vault note) |
Edit directly — no regeneration step |
- Output: The correct generator script identified before any edit is made
Step 2: Edit the generator, not the output
- Who: Doc harness maintainer
- When: Immediately after Step 1
- How: Open the identified script in
tools/. Common edit points: gen_html.py→ theMODULESlist (per-module id/name/layer/color/pkg/ in/out/role/detail/model/deterministic fields) or the "Explore" section's link tablesgen_design_html.py→ thePAGESlist of(md_path, html_path, title, breadcrumb)tuples — add a tuple here to HTML-ify a new Markdown docgen_modules.py→ theMODULE_DOCSdict mapping package to (doc filename, description) Do not openarchitecture.html, any file underdocs/design/*.html,docs/modules/*.html, ordocs/modules/README.mdand edit them by hand — the next regeneration run will silently overwrite hand edits.- Output: An updated generator script, not yet reflected in output files
Step 3: Run the regeneration commands
- Who: Doc harness maintainer
- When: Immediately after Step 2
- How: See
docs/process/runbooks/regenerate-documentation.mdfor the exact, copy-paste commands and expected results for each generator. - Output: Updated
.html/.mdfiles in place
Step 4: Verify the output
- Who: Doc harness maintainer
- When: Immediately after Step 3
- How:
- Open the regenerated HTML and confirm the Simple/Technical
.switchtoggle still works and the VVAH design tokens (navy/blue header gradient, white.mboxcards,--accent:#1a56db) are intact - If
architecture.htmlwas regenerated, re-run the link check: extract all relativehrefs and confirm every target file exists - Confirm any new or changed claim (module role, deterministic-vs-LLM
classification, file/LOC count) is still source-accurate — re-check
against
samples/strix/if in doubt, per this project's "verify every claim against real source" rule - Output: Confirmed-correct documentation, ready to hand off
Step 5: Refresh the runnable samples snapshot
- Who: Doc harness maintainer
- When: Only if
tools/itself changed in Step 2 (not needed for content-only changes like editingdocs/00_START_HERE.mddirectly) - How:
rsync -a --exclude='__pycache__' tools/ samples/harness-tools/ - Output:
samples/harness-tools/matches the livetools/again
Exceptions and Edge Cases
| Scenario | What to Do |
|---|---|
A doc needs an HTML version but isn't in gen_design_html.py's PAGES list yet |
Add a (md_path, html_path, title, breadcrumb) tuple to PAGES, then run python3 tools/gen_design_html.py — do not hand-write the HTML |
| You need to regenerate everything after a Strix re-clone (new commit, new source) | This is out of scope for this document — treat it as a new pass through this project's original build sequence (re-run Graphify/CodeGraph, re-verify claims against the new source, then update generator config tables before regenerating) |
__pycache__/*.pyc files won't delete (Operation not permitted) |
This is expected — the primary connected project folder blocks deletes of any file, including harmless bytecode cache. Leave them; they are not deliverables and are excluded from the samples/harness-tools/ sync via rsync --exclude |
| A generator run produces a Python syntax/traceback error after an edit | Most likely cause historically: nested {...} braces inside an f-string colliding with literal JS/CSS braces (hit while editing gen_design_html.py). Prefer .format()-style templating or escape braces ({{/}}) over deeply nested f-strings in the HTML template portions |
| Generated file's design language looks off (wrong colors, missing toggle) | Compare against templates/design-system/tokens.css (the canonical VVAH token source) and the CSS string in gen_html.py — the generators currently hard-copy the token values rather than importing the file, so a token drift has to be fixed in both places |
Metrics
| Metric | Target | How to Measure |
|---|---|---|
Broken relative links in architecture.html |
0 | Regex-extract all href="..." values, confirm each target file exists |
Docs with a .md source but no .html counterpart, where HTML was requested |
0 gaps against the agreed file list | Diff find docs -name '*.md' against gen_design_html.py's PAGES list |
samples/harness-tools/ drift from tools/ |
0 (in sync after any tools/ edit) |
diff -rq tools/ samples/harness-tools/ (ignoring __pycache__) |
| Time from "generator edited" to "verified output" | Same session | Track manually; this is a fast, single-person loop by design |
Related Documents
docs/process/runbooks/regenerate-documentation.md— exact commands for this processdocs/process/harness-process-optimization.md— current-state waste analysis and improvement plan for this workflowdocs/process/process-operate-strix.md— the sibling process document for operating Strix itself (not this harness)templates/design-system/tokens.css— canonical design-token sourcesamples/harness-tools/README.md— the runnable reference snapshot this process points to