Process Document: Maintaining the STRIX Documentation Harness

docs / process / harness-maintenance-process

← all docs

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), see docs/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:

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

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

Step 2: Edit the generator, not the output

Step 3: Run the regeneration commands

Step 4: Verify the output

Step 5: Refresh the runnable samples snapshot

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