Scaffold or maintain a system design report as a folder of section .md files plus a small hub index with llm_toc (file paths for LLM partial reads). MemNet-first when serve is up: pin_map(TSK_model_*) before prose, atomise @ART/@SEC/@CLM after sync. Triggers: system design report pack, split outputs sections, outputs folder system design, multi-file system design, hub index llm_toc file, memnet report sync.
Scaffold or maintain a system design report as a folder of section .md files plus a small hub index with llm_toc (file paths for LLM partial reads). MemNet-first when serve is up: pin_map(TSK_model_*) before prose, atomise @ART/@SEC/@CLM after sync. Triggers: system design report pack, split outputs sections, outputs folder system design, multi-file system design, hub index llm_toc file, memnet report sync.
- **Hub first:** agents read **`index.md`** (or `README.md`) only for full-file list — **low line count (LOC)** — then open **one** `file` from `llm_toc` per task; do not load every section `.md` into context by default.
- **MemNet before prose (when serve up):** `serve_status` → `pin_map(TSK_model_<short>)` → then hub → **one** section file. Do not grep-deploy from memory when warm rows exist.
- **Normative layout:** [references/SYSTEM_DESIGN_REPORT_LAYOUT.md](references/SYSTEM_DESIGN_REPORT_LAYOUT.md) — do not invent a second competing root under `docs/`.
- **MemNet pipeline:** [references/memnet-report-pipeline.md](references/memnet-report-pipeline.md) -- ART/SEC/claim atoms after sync; G/M step codes per [sysml-memnet-pipeline.md](../sysml-memnet-documentation/references/sysml-memnet-pipeline.md) (GQL / openCypher-shaped only).
- **Model wins:** deploy/connections/behaviour/requirements `.sysml` stay authoritative; **sysml-view-doc-sync** after edits. Keep `10-requirements-traceability` and `outputs/diagrams/` plant-setup flows aligned with refine/derive + behaviour.
- Report sections are **human-first**: write compact, precise prose. Prefer tables, bullets, and short notes; avoid long introductory filler and avoid restating the same fact in multiple sections.
- If a section can be understood from a table plus one short sentence, do that instead of a paragraph.
- **UTF-8 encoding:** All `.md` files **must** be UTF-8 encoded (no mixed encoding, no BOM). Merge using Python (see skill): read each file with explicit `encoding='utf-8'`, combine in order, write merged output as UTF-8. **No Unicode sanitization needed** — proper UTF-8 handles all special characters (–, →, ↔, ×, §) correctly.
- **Section files are merge inputs only:** Remove all inter-section cross-references ("See chapter X", "See section Y") before merging. Individual files are not meant to be read standalone.
- **Do not commit merged files to git** — keep only section `.md` files as authoritative source; generate exports (merged `.md`, HTML, LaTeX) on-demand using Python merge script.
System design report generator (multi-file pack)
When: A system design (or similar) narrative is large enough that one monolithic *-system-design.md is hard for agents to navigate, or the team wants sections as separate files with a machine-readable map (llm_toc with file entries).
These packs are for human readers too, so keep each section tight and purposeful. The hub should orient the reader; the section files should explain only what is needed.
Pairing
project-output-article — same section semantics and Mermaid rules; this skill adds folder + file split + hub llm_toc.
sysml-view-doc-sync — update every touched section file after deploy changes.
sysml-memnet-documentation — pin_map before generate/maintain; atomise@ART/@SEC/@CLM after sync (memnet-report-pipeline.md).
sysml-modeling-workflow — validate .sysml before report delta; report maintenance is step 5 follow-on, not a substitute for model snap.
md-to-tex — pass hub llm_toc order as Pandoc input list for multi-file → one .tex.
mdtohtml — export section files to HTML (Mermaid rendering, UTF-8 safe, handles encoding correctly).
Pipeline
A — Generate or refresh full pack
MemNet preflight — serve_status. If up: read AGENT-CONTEXT.md → pin_map(TSK_model_<short>, depth=2). Warm miss → initial model snap per sysml-memnet-documentation before writing prose.
Create or adopt folder — Under , use pack root (or legacy if the project already started — one pack per project, ).
sysml-v2-models/projects/<name>/outputs/
system-design-report/
system-design/
documented in hub
Hub file — From assets/hub-index-template.md: project title, source line (model paths), llm_toc with file, optional llm_keywords, optional memnet: block (anchor, art_id, session, cross-artifact manuals).
Section files — From assets/section-template.md: content from warm graph + deploy grep — exact link* names, requirement ids (parent/child via refine/derive), behaviour action names, de-facto part notes from model doc comments.
Sync — Run sysml-view-doc-sync; validate mermaid / mmdc only when rendering assets. Include outputs/diagrams/ commissioning / plant-setup flowcharts when behaviour defines them; keep 10-requirements-traceability in step with the requirements package.
MemNet report delta — references/memnet-report-pipeline.md: @ART + @SEC per hub section + key @CLM facts with mentions EDGs to @CON/@PRT/@REQ. Skip only if serve_status false.
✅ No character sanitization needed; proper encoding handles it all
Before merge (optional for individual section inspection):
Individual .md files should NOT contain cross-references (e.g., "See section X" or "See chapter 3") since they are inputs to merge, not standalone documents. Remove all inter-section links before merging.
Step 2: Validate Mermaid diagrams (MANDATORY)
# Validate merged markdown for Mermaid parse errors
mmdc -i leo-laser-comm-PAT-system-design-merged.md
# If errors occur, fix them in source section files, then re-merge and re-validate
Step 3: Convert to HTML
cd c:\Projects\SystemDesign
python tools/md_to_html.py sysml-v2-models/projects/leo-cubesat-laser-comm/outputs/system-design-report/leo-laser-comm-PAT-system-design-merged.md
