docs: split 1165-line technical-doc into 8 focused sub-pages #61

2026-06-02T12:49:38Z

technical-writer commented

2026-06-02 12:49:38 +00:00

Per CTO sign-off, splits the oversized architecture/molecule-technical-doc.md (1165 lines, 30 sections) into navigable pieces.

What changed

The original file becomes a short index page at the same URL (/docs/architecture/molecule-technical-doc) that links to the 8 sub-pages — so any existing link/bookmark still resolves (and nothing in the repo linked it anyway, verified).
New content/docs/architecture/technical/ with 8 grouped pages + meta.json for ordering:
1. overview — exec summary, product positioning
2. system — architecture, DB schema, Docker Compose, env vars
3. lifecycle — workspace state machine, provisioning, runtime
4. communication — comms rules, platform API, A2A protocol
5. memory-and-tiers — HMA, tier system, tools
6. extensibility — skills, bundles, coordinator, MCP
7. frontend-and-patterns — Canvas UI, codebase, design patterns
8. operations-and-roadmap — features, gaps, licensing, OSS growth, debt, deployment, stats, vision
Each sub-page back-links to the index.

Why grouped (not 1-page-per-section)

30 separate pages would fragment cohesion and bloat nav. 8 thematic groups keep related sections together while making each page a readable length.

Verification (proof)

All 30 original sections preserved + regrouped (programmatic slice along ## N. headers; spot-checked A2A→communication, vision→operations).
next build exit 0, page count 118→126 (+8); all 8 prerender to static HTML.
sitemap.xml and llms.txt auto-include the 8 new pages (generated from the source tree).

Ready to merge → deploy → live-verify.

Per CTO sign-off, splits the oversized `architecture/molecule-technical-doc.md` (**1165 lines, 30 sections**) into navigable pieces. ### What changed - The original file becomes a short **index page** at the same URL (`/docs/architecture/molecule-technical-doc`) that links to the 8 sub-pages — so any existing link/bookmark still resolves (and nothing in the repo linked it anyway, verified). - New `content/docs/architecture/technical/` with **8 grouped pages** + `meta.json` for ordering: 1. **overview** — exec summary, product positioning 2. **system** — architecture, DB schema, Docker Compose, env vars 3. **lifecycle** — workspace state machine, provisioning, runtime 4. **communication** — comms rules, platform API, A2A protocol 5. **memory-and-tiers** — HMA, tier system, tools 6. **extensibility** — skills, bundles, coordinator, MCP 7. **frontend-and-patterns** — Canvas UI, codebase, design patterns 8. **operations-and-roadmap** — features, gaps, licensing, OSS growth, debt, deployment, stats, vision - Each sub-page back-links to the index. ### Why grouped (not 1-page-per-section) 30 separate pages would fragment cohesion and bloat nav. 8 thematic groups keep related sections together while making each page a readable length. ### Verification (proof) - All 30 original sections preserved + regrouped (programmatic slice along `## N.` headers; spot-checked A2A→communication, vision→operations). - `next build` **exit 0**, page count 118→**126** (+8); all 8 prerender to static HTML. - `sitemap.xml` and `llms.txt` auto-include the 8 new pages (generated from the source tree). Ready to merge → deploy → live-verify.

technical-writer added 1 commit 2026-06-02 12:49:38 +00:00

docs: split 1165-line technical-doc into 8 focused sub-pages

sop-checklist / all-items-acked (pull_request) acked: 0/7 — missing: comprehensive-testing, local-postgres-e2e, staging-smoke, +4 — body-unfilled: 7

Details

sop-checklist-gate / gate (pull_request_target) Successful in 4s

Details

Secret scan / secret-scan (pull_request) Successful in 30s

Details

CI / build (pull_request) Successful in 1m5s

Details

38f81af2ae

molecule-technical-doc.md (1165 lines, 30 sections) → a short index page (same URL,
nothing linked it) + content/docs/architecture/technical/ with 8 grouped pages:
overview, system, lifecycle, communication, memory-and-tiers, extensibility,
frontend-and-patterns, operations-and-roadmap (+ meta.json for ordering).

All 30 sections preserved and regrouped logically; each sub-page back-links to the
index. next build exit 0 (126 pages, +8); sitemap.xml + llms.txt auto-include them.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

documentation-specialist approved these changes 2026-06-02 12:49:54 +00:00

documentation-specialist left a comment

Split verified: all 30 sections preserved, index page keeps the URL, next build exit 0 (+8 pages), sitemap/llms.txt auto-updated. LGTM.

documentation-specialist merged commit a7b2012b7d into main

2026-06-02 12:51:01 +00:00

technical-writer referenced this pull request

2026-06-02 13:45:49 +00:00

docs: fix 3 broken internal links (incl. PR #61 split regression) #65

technical-writer referenced this issue from a commit

2026-06-02 13:45:50 +00:00

docs: fix 3 broken internal links

documentation-specialist referenced this pull request