schematex 0.8.2 → 0.9.0

package/dist/{chunk-HWNVSNDJ.cjs → chunk-HKOPXQYU.cjs}

@@ -349,7 +349,18 @@ var DIAGRAM_REGISTRY = [
     useWhen: "Use to propagate the consequences of an initiating event through a chain of barriers/safety functions and quantify each outcome's frequency \u2014 the inductive complement to a fault tree and the right wing of a bowtie. Header `eventtree`/`eta`; declare the initiating event with a frequency, the ordered functions with success/failure branch probabilities, and outcome rows with `s`/`f`/`*` patterns. The engine computes path frequency = f_initiating \xD7 \u03A0 branch-probabilities and flags the dominant sequence.",
     cluster: "risk-reliability",
     standard: "IEC 62502:2010 \xB7 NUREG/CR-2300 (PRA) \xB7 ISO 31010 Annex B; see 39-EVENT-TREE-STANDARD.md",
-    syntaxKey: "eventtree"
+    syntaxKey: "eventtree",
+    aliases: ["Event Tree Analysis", "ETA diagram", "event tree", "\u4E8B\u4EF6\u6811\u5206\u6790"],
+    keywords: [
+      "probabilistic risk assessment",
+      "PRA",
+      "safety function",
+      "accident sequence",
+      "barrier analysis",
+      "consequence analysis",
+      "nuclear safety",
+      "IEC 62502"
+    ]
   },
   {
     type: "fmea",
@@ -358,7 +369,25 @@ var DIAGRAM_REGISTRY = [
     useWhen: "Use to score and prioritise how each component/process step can fail \u2014 severity, occurrence, detection \u2014 and decide what to fix first. Header `fmea`; declare item/function \u2192 failure mode \u2192 effect (with `sev`) \u2192 cause (with `occ`) \u2192 controls (with `det`). The engine computes RPN = S\xD7O\xD7D and the AIAG-VDA Action Priority (High/Medium/Low), sorts the sheet, and colour-fills the RPN/AP cells by risk. Schematex's first table-shaped diagram.",
     cluster: "risk-reliability",
     standard: "AIAG-VDA FMEA Handbook (2019) \xB7 IEC 60812:2018 \xB7 SAE J1739 \xB7 MIL-STD-1629A; see 40-FMEA-STANDARD.md",
-    syntaxKey: "fmea"
+    syntaxKey: "fmea",
+    aliases: [
+      "FMEA",
+      "Failure Mode and Effects Analysis",
+      "FMECA",
+      "failure mode analysis",
+      "\u6545\u969C\u6A21\u5F0F\u4E0E\u5F71\u54CD\u5206\u6790"
+    ],
+    keywords: [
+      "RPN",
+      "risk priority number",
+      "Action Priority",
+      "AIAG-VDA",
+      "DFMEA",
+      "PFMEA",
+      "severity occurrence detection",
+      "reliability engineering",
+      "IEC 60812"
+    ]
   },
   // ── Systems thinking / stochastic ────────────────────────────
   {
@@ -368,7 +397,23 @@ var DIAGRAM_REGISTRY = [
     useWhen: 'Use for systems thinking / system dynamics: variables connected by `+`/`\u2212` causal links, where the engine detects feedback loops and labels each R (even number of negative links) or B (odd). Header `causalloop`/`cld`; write `A -> B : +` links and optional `loop R1 "name"` annotations and `delay` marks. Distinct from `sociogram` (social ties, no polarity) and `flowchart` (process steps).',
     cluster: "causality-analysis",
     standard: "Sterman, Business Dynamics (2000) \xB7 Meadows, Thinking in Systems; see 41-CAUSAL-LOOP-STANDARD.md",
-    syntaxKey: "causalloop"
+    syntaxKey: "causalloop",
+    aliases: [
+      "Causal Loop Diagram",
+      "CLD",
+      "feedback loop diagram",
+      "systems thinking diagram",
+      "\u56E0\u679C\u56DE\u8DEF\u56FE"
+    ],
+    keywords: [
+      "system dynamics",
+      "reinforcing loop",
+      "balancing loop",
+      "feedback loop",
+      "stock and flow",
+      "Sterman",
+      "Meadows"
+    ]
   },
   {
     type: "markov",
@@ -377,7 +422,22 @@ var DIAGRAM_REGISTRY = [
     useWhen: "Use to model a probabilistic state process (reliability/availability, queueing, regime models) where you want the long-run distribution or absorption answer, not just the picture. Header `markov`/`markovchain`; write `S1 -> S2 : 0.3` transitions (each state's out-edges sum to 1). The engine computes the stationary distribution, classifies states, and for absorbing chains the fundamental matrix. Sibling of `state` and `petri`.",
     cluster: "behavior-modeling",
     standard: "Norris, Markov Chains (1997) \xB7 Kemeny & Snell, Finite Markov Chains; see 42-MARKOV-CHAIN-STANDARD.md",
-    syntaxKey: "markov"
+    syntaxKey: "markov",
+    aliases: [
+      "Markov chain",
+      "Markov chain diagram",
+      "stochastic state transition diagram",
+      "\u9A6C\u5C14\u53EF\u592B\u94FE"
+    ],
+    keywords: [
+      "stationary distribution",
+      "stochastic process",
+      "transition matrix",
+      "transition probability",
+      "absorbing state",
+      "steady state",
+      "discrete-time"
+    ]
   },
   // ── Software / process engineering ───────────────────────────
   {
@@ -387,7 +447,23 @@ var DIAGRAM_REGISTRY = [
     useWhen: 'Use to visualise a git branching/merging history. Header `gitGraph`; ordered `commit`, `branch <name>`, `checkout <name>`, `merge <name>`, `cherry-pick id: "\u2026"`, with `commit id:/tag:/type: HIGHLIGHT|REVERSE`. Mermaid `gitGraph` syntax parity so LLM output is drop-in compatible. Commits sit on per-branch lanes ordered chronologically; merges join lanes.',
     cluster: "software-uml",
     standard: "Mermaid gitGraph syntax \xB7 git DAG model; see 43-GIT-GRAPH-STANDARD.md",
-    syntaxKey: "gitgraph"
+    syntaxKey: "gitgraph",
+    aliases: [
+      "Git commit graph",
+      "git graph",
+      "git branch diagram",
+      "branching diagram",
+      "Git \u63D0\u4EA4\u56FE"
+    ],
+    keywords: [
+      "branching strategy",
+      "git history",
+      "merge",
+      "cherry-pick",
+      "GitFlow",
+      "Mermaid gitGraph",
+      "commit history"
+    ]
   },
   {
     type: "epc",
@@ -396,7 +472,22 @@ var DIAGRAM_REGISTRY = [
     useWhen: "Use for ARIS-style business process modelling (SAP / enterprise BPM). Header `epc`; declare `event`, `function`, connectors `and`/`or`/`xor`, and the control flow between them. The engine validates strict event\u2194function alternation and connector legality (an event cannot be the source of an OR/XOR split). Distinct from `bpmn` and `flowchart` \u2014 a separate published standard with stricter rules.",
     cluster: "corporate-legal",
     standard: "ARIS / Keller, N\xFCttgens & Scheer (1992); see 44-EPC-STANDARD.md",
-    syntaxKey: "epc"
+    syntaxKey: "epc",
+    aliases: [
+      "Event-driven Process Chain",
+      "EPC diagram",
+      "ARIS EPC",
+      "\u4E8B\u4EF6\u9A71\u52A8\u8FC7\u7A0B\u94FE"
+    ],
+    keywords: [
+      "ARIS",
+      "business process modeling",
+      "SAP",
+      "BPM",
+      "process chain",
+      "enterprise architecture",
+      "Scheer"
+    ]
   },
   {
     type: "idef0",
@@ -405,7 +496,23 @@ var DIAGRAM_REGISTRY = [
     useWhen: "Use to model what a system/process does and its inputs/controls/outputs/mechanisms \u2014 systems engineering, defence/government process docs, enterprise architecture. Header `idef0`; declare `function` boxes and ICOM arrows (`input`/`control`/`output`/`mechanism`) plus box\u2192box flows that name the target ICOM side. The engine enforces ICOM placement and assigns node numbers, in a diagonal box staircase.",
     cluster: "project-management",
     standard: "FIPS PUB 183 (1993) \xB7 SADT (Ross); see 45-IDEF0-STANDARD.md",
-    syntaxKey: "idef0"
+    syntaxKey: "idef0",
+    aliases: [
+      "IDEF0",
+      "IDEF0 function model",
+      "SADT diagram",
+      "function model",
+      "ICOM diagram"
+    ],
+    keywords: [
+      "functional modeling",
+      "FIPS 183",
+      "systems engineering",
+      "activity model",
+      "ICOM",
+      "process model",
+      "enterprise architecture"
+    ]
   },
   {
     type: "threatmodel",
@@ -414,7 +521,25 @@ var DIAGRAM_REGISTRY = [
     useWhen: "Use for security threat modelling (Microsoft SDL / OWASP Threat Dragon workflow): DFD shapes (external entity, process, data store), labelled data flows, and `boundary` trust zones. Header `threatmodel`/`stride`. The engine maps each element type to its STRIDE categories (external = S,R; process = all six; store = T,I,D + conditional R for logs; flow = T,I,D) and accents flows crossing a trust boundary. Includes the DFD base notation (no separate `dfd` engine).",
     cluster: "network-infrastructure",
     standard: "Shostack, Threat Modeling (2014) STRIDE-per-element \xB7 Microsoft SDL \xB7 base DFD DeMarco/Yourdon; see 46-THREAT-MODEL-STRIDE-STANDARD.md + 31-DFD-STANDARD.md",
-    syntaxKey: "threatmodel"
+    syntaxKey: "threatmodel",
+    aliases: [
+      "Threat model",
+      "STRIDE diagram",
+      "DFD threat model",
+      "data flow diagram",
+      "DFD",
+      "\u5A01\u80C1\u5EFA\u6A21"
+    ],
+    keywords: [
+      "STRIDE",
+      "security threat modeling",
+      "Microsoft SDL",
+      "OWASP Threat Dragon",
+      "trust boundary",
+      "attack surface",
+      "application security",
+      "Shostack"
+    ]
   },
   {
     type: "welding",
@@ -423,7 +548,24 @@ var DIAGRAM_REGISTRY = [
     useWhen: 'Use to annotate a welded joint on an engineering drawing: a horizontal reference line, a leader arrow to the joint, and a weld-symbol glyph above (other side) / below (arrow side) with size, length-pitch, groove angle, root opening, contour + finish. Header `welding [standard: aws|iso-a|iso-b]`; one `joint "label" { arrow: \u2026 other: \u2026 around field tail: \u2026 }` block per joint. Full glyph catalog (fillet, all groove types, plug/slot, spot/seam, back/backing, surfacing, edge) + weld-all-around, field flag, and tail process note. Validates illegal type/side/dimension combinations.',
     cluster: "electrical-industrial",
     standard: "AWS A2.4:2020 \xB7 ISO 2553:2019; see 47-WELDING-SYMBOL-STANDARD.md",
-    syntaxKey: "welding"
+    syntaxKey: "welding",
+    aliases: [
+      "Welding symbols",
+      "weld symbol",
+      "welding callout",
+      "weld joint symbol",
+      "\u710A\u63A5\u7B26\u53F7"
+    ],
+    keywords: [
+      "AWS A2.4",
+      "ISO 2553",
+      "fillet weld",
+      "groove weld",
+      "weld notation",
+      "engineering drawing",
+      "fabrication",
+      "weld dimensions"
+    ]
   }
 ];
 var DIAGRAM_SINCE = {
@@ -546,7 +688,7 @@ var EXAMPLES = [
       "signal-flow"
     ],
     "complexity": 2,
-    "featured": false,
+    "featured": true,
     "dsl": 'blockdiagram "PID control loop"\nC = block("PID C(s)") [role: controller]\nG = block("Plant G(s)") [role: plant]\nerr = sum(+r, -y)\nr = signal("r (setpoint)")\ny = signal("y (output)")\nin -> r\nr -> err\nerr -> C\nC -> G\nG -> y\nG -> err',
     "notes": '## Scenario\n\nThe standard closed-loop PID block diagram appears in every control systems textbook (Ogata, Franklin, \xC5str\xF6m) and every control system design spec sheet. Schematex renders it from a signal-flow description \u2014 not a generic flowchart \u2014 using proper summing junction symbols and automatic feedback routing.\n\n## Annotation key\n\n- `block("label") [role: ...]` \u2014 transfer function block; `role: controller` and `role: plant` affect visual styling\n- `sum(+r, -y)` \u2014 summing junction: adds the `+r` (reference) signal and subtracts the `-y` (output feedback)\n- `signal("label")` \u2014 named signal node\n- `G -> err` \u2014 the feedback path: plant output `y` routes back to the summing junction\n\n## How to read\n\nThe setpoint `r` enters the summing junction `err`, which subtracts the plant output `y` to compute the error signal. The PID controller `C(s)` processes the error and drives the plant `G(s)`. The plant output `y` is both the system output and the feedback signal. The loop is closed when `G -> err` feeds `y` back to the summing junction.'
   },
@@ -782,7 +924,7 @@ If the LED doesn't light up, three things to check, in order: LED polarity (the
       "balancing"
     ],
     "complexity": 3,
-    "featured": false,
+    "featured": true,
     "dsl": 'causalloop "Startup growth engine"\n  "Active users" -> "Word of mouth" : +\n  "Word of mouth" -> "New signups" : +\n  "New signups" -> "Active users" : +\n  "Active users" -> "Server load" : +\n  "Server load" -> "App performance" : -\n  "App performance" -> "Active users" : + delay\n  "Active users" -> Revenue : +\n  Revenue -> "Infra investment" : +\n  "Infra investment" -> "App performance" : + delay\n  loop R1 "Viral flywheel"\n  loop B1 "Scaling strain"',
     "notes": '## What this shows\n\nThe two-sided story of every viral product. One reinforcing loop drives growth: more active users produce more word of mouth, which drives signups, which adds users \u2014 an amplifying cycle. A second, balancing loop pushes back: more users raise server load, which degrades app performance, which (after a delay) loses users. The `delay` markers put the system-dynamics hash mark on the slow legs, where the lag between cause and effect is what makes the system overshoot.\n\nThe engine finds and labels the loops for you, which a drawing tool cannot. It enumerates every elementary cycle in the signed graph with Johnson\'s algorithm, then applies Sterman\'s rule \u2014 count the negative links, even means reinforcing (R), odd means balancing (B) \u2014 and numbers them R1, B1\u2026 The growth cycle comes back R (zero negatives), the load cycle B (one negative). The named `loop` declarations attach the human phrasing \u2014 "Viral flywheel", "Scaling strain" \u2014 onto the loops the engine detects.'
   },
@@ -819,7 +961,7 @@ If the LED doesn't light up, three things to check, in order: LED polarity (the
       "netlist"
     ],
     "complexity": 2,
-    "featured": false,
+    "featured": true,
     "dsl": 'circuit "Bridge Rectifier Supply" netlist\nV1 ac1 ac2 12Vac\nD1 ac1 vout 1N4007\nD2 ac2 vout 1N4007\nD3 0 ac1 1N4007\nD4 0 ac2 1N4007\nC1 vout 0 470u\nRload vout 0 1k',
     "notes": "## Scenario\n\nA technician needs a quick schematic for the textbook AC-to-DC rectifier: a transformer secondary, four rectifier diodes, a reservoir capacitor, and a load. The netlist form keeps the topology precise while the renderer chooses the schematic placement.\n\n## Annotation key\n\n- `D1` to `D4` are ordinary diode components inferred from the `D` prefix.\n- `0` is the canonical ground net.\n- `C1` smooths the rectified output across `vout` and ground.\n\n## How to read\n\nDuring each half-cycle, two diodes conduct and steer current into `vout` with the same polarity. The capacitor charges near the peak and supplies the load between peaks, reducing ripple at `Rload`."
   },
@@ -1109,7 +1251,7 @@ If the LED doesn't light up, three things to check, in order: LED polarity (the
       "control-flow"
     ],
     "complexity": 3,
-    "featured": false,
+    "featured": true,
     "dsl": 'epc "Purchase requisition"\n  layout: tb\n  event E1 "Material need identified"\n  function F1 "Create requisition"\n  function F2 "Determine source of supply"\n  xor X1\n  event E2 "Stock supplier exists"\n  event E3 "New supplier needed"\n  function F3 "Issue purchase order"\n  function F4 "Run tender process"\n  and A1\n  event E4 "Order dispatched"\n  event E5 "Supplier qualified"\n  E1 -> F1 -> F2 -> X1\n  X1 -> E2\n  X1 -> E3\n  E2 -> F3 -> A1\n  E3 -> F4 -> A1\n  A1 -> E4\n  A1 -> E5',
     "notes": '## What this shows\n\nA SAP-style procurement process modelled as an ARIS event-driven process chain (EPC), the notation that strictly alternates passive **events** ("Material need identified") and active **functions** ("Create requisition"). After sourcing, an **XOR** connector splits the flow on a real decision \u2014 an existing stock supplier versus a new supplier needing a tender \u2014 and the two paths re-converge on an **AND** connector that fans back out to the dispatched order and the qualified-supplier outcome.\n\nEPC\'s value here is structural validation, not a computed number. The engine checks the well-formedness rules and flags violations rather than silently drawing a broken model: event/function alternation along every path, single-in/single-out multiplicity carried by the connectors, reachability from start to end, and the **event-cannot-decide signature rule** \u2014 a passive event may not be the source of an XOR/OR split. That\'s why the decision routes *through* function `F2` before reaching the XOR, which is the correct ARIS form.'
   },
@@ -1221,7 +1363,7 @@ If the LED doesn't light up, three things to check, in order: LED polarity (the
       "core-damage"
     ],
     "complexity": 3,
-    "featured": false,
+    "featured": true,
     "dsl": 'eventtree "Large LOCA"\n  initiating LOCA "Large-break LOCA" freq: 1e-4\n  function RT "Reactor trips" p: 0.001\n  function ECCS "ECCS injection" p: 0.01\n  function CHR "Containment heat removal" p: 0.02\n  function CI "Containment integrity" p: 0.005\n  outcome s s s s -> "OK"\n  outcome s s s f -> "Late release"\n  outcome s s f * -> "Late release"\n  outcome s f * * -> "Early release"\n  outcome f * * * -> "Core damage"',
     "notes": '## What this shows\n\nThe textbook nuclear probabilistic-risk-assessment (PRA) tree. One initiating event \u2014 a large pipe break draining the coolant at a frequency of `1e-4` per year \u2014 is asked, left to right, whether each safety function holds: reactor trip, emergency core cooling (ECCS), containment heat removal, then containment integrity. Each `*` prunes a path that has already terminated, so the tree stays compact instead of ballooning to a full 2\u2074 ladder.\n\nThe engine does the arithmetic an event tree exists to give. It multiplies the initiating frequency by the success leg (`1 \u2212 p`) or failure leg (`p`) at each branch to get every sequence frequency, sums the two `"Late release"` leaves into one rolled-up outcome, and paints the largest-frequency path \u2014 the dominant accident sequence \u2014 in red. That computed answer, not the forking picture, is the deliverable a drawing tool can\'t produce.'
   },
@@ -1465,7 +1607,7 @@ If the LED doesn't light up, three things to check, in order: LED polarity (the
       "automotive"
     ],
     "complexity": 3,
-    "featured": false,
+    "featured": true,
     "dsl": 'fmea "EV battery pack DFMEA"\n  type: design\n  rank: ap\n  flag: ap >= High\n  number: DFMEA-2026-014\n  item "Cell module" fn "Store and deliver energy"\n    mode "Thermal runaway"\n      effect "Pack fire / occupant injury" sev: 10\n      cause "Internal short from dendrite growth" occ: 3\n        controls prevention: "Cell qualification", detection: "In-line CT scan" det: 4\n      cause "Overcharge past cutoff" occ: 2\n        controls prevention: "BMS voltage clamp", detection: "Redundant voltage sense" det: 3\n    mode "Capacity fade"\n      effect "Reduced range" sev: 6\n      cause "Electrolyte depletion" occ: 5\n        controls detection: "Periodic SOH estimate" det: 6\n  item "Busbar joint" fn "Conduct current between modules"\n    mode "High-resistance connection"\n      effect "Local overheating" sev: 8\n      cause "Loose torque on weld" occ: 4\n        controls detection: "End-of-line resistance test" det: 4',
     "notes": "## What this shows\n\nA design FMEA (DFMEA) on the highest-stakes subsystem in an electric vehicle. The nested chain reads item \u2192 mode \u2192 effect/cause/controls: a cell module that can suffer thermal runaway or capacity fade, and a busbar joint that can go high-resistance. Each effect carries a Severity, each cause an Occurrence, each control the Detection it earns \u2014 the three AIAG-VDA 1\u201310 scales.\n\nThe engine computes the priority rather than just tabling it. It flattens to one worksheet row per (item, mode, cause), multiplies RPN = S \xD7 O \xD7 D, and \u2014 the part that matters \u2014 derives the AIAG-VDA Action Priority, which is severity-primary. The thermal-runaway row sits at S10\xB7O3\xB7D4 with an RPN of 120; a naive RPN sort would rank it below a noisier low-severity defect, but Action Priority keeps every safety failure (S = 9\u201310) at **High** regardless. The `flag: ap >= High` directive highlights exactly those rows so the safety-critical work rises to the top."
   },
@@ -1592,7 +1734,7 @@ If the LED doesn't light up, three things to check, in order: LED polarity (the
       "hotfix"
     ],
     "complexity": 3,
-    "featured": false,
+    "featured": true,
     "dsl": 'gitGraph\n  commit id: "init"\n  commit id: "scaffold"\n  branch develop\n  checkout develop\n  commit id: "feature scaffold"\n  branch feature/login\n  checkout feature/login\n  commit id: "login UI"\n  commit id: "login API"\n  checkout develop\n  merge feature/login\n  commit id: "polish"\n  checkout main\n  merge develop tag: "v1.0"\n  branch hotfix\n  checkout hotfix\n  commit id: "patch CVE" type: HIGHLIGHT\n  checkout main\n  merge hotfix tag: "v1.0.1"\n  checkout develop\n  merge main',
     "notes": "## What this shows\n\nA full Git Flow release cycle, the branching strategy teams adopt to keep a clean trunk. Work forks off `main` into a long-lived `develop`, then into a short-lived `feature/login` branch; the feature merges back to develop, develop merges to `main` as the tagged `v1.0` release. Then a security `hotfix` branches straight off `main`, lands a HIGHLIGHT commit, ships as `v1.0.1`, and is merged back down into develop so the fix isn't lost \u2014 the discipline that keeps the two lines from diverging.\n\nThe DSL is the Mermaid `gitGraph` dialect verbatim, so existing Mermaid sources port directly. The engine replays the operation list in order to assign each commit to a lane, routes the merge connectors from each branch tip without crossings, renders the patch commit emphasised as a HIGHLIGHT, and draws the version tags as flags \u2014 all from a KB-scale, dependency-free bundle."
   },
@@ -1611,7 +1753,7 @@ If the LED doesn't light up, three things to check, in order: LED polarity (the
       "structured-analysis"
     ],
     "complexity": 3,
-    "featured": false,
+    "featured": true,
     "dsl": 'idef0 "Fulfil customer order"\nnode A0\nfunction A1 "Validate order"\nfunction A2 "Pick and pack"\nfunction A3 "Ship and invoice"\ninput     A1 "Customer order"\ncontrol   A1 "Credit policy"\nmechanism A1 "Order management system"\nA1 -> A2 "Validated order"\ninput     A2 "Inventory"\ncontrol   A2 "Picking rules"\nmechanism A2 "Warehouse staff"\nA2 -> A3 "Packed shipment"\ncontrol   A3 "Carrier contract"\nmechanism A3 "Shipping carrier"\noutput    A3 "Delivered order"\noutput    A3 "Invoice"',
     "notes": '## What this shows\n\nAn IDEF0 A0 diagram \u2014 the top-level functional decomposition of an order-fulfilment system \u2014 showing all four ICOM arrow roles. Reading the box edges by convention: **I**nputs enter on the left (the customer order, inventory), **C**ontrols govern from the top (credit policy, picking rules, carrier contract), **M**echanisms supply resources from the bottom (the order system, warehouse staff, carrier), and **O**utputs leave on the right (delivered order, invoice). The box-to-box flows (`A1 -> A2 "Validated order"`) chain the three activities.\n\nThe differentiator is that the model is correct by construction, not just drawn. Because the arrow keyword *is* the box edge it attaches to, the engine enforces ICOM placement \u2014 you cannot accidentally draw a control as an input. It resolves every box reference, assigns decomposition numbers (A0 \u2192 A1..A3), codes the boundary arrows down each edge (I1/C1/O1/M1\u2026), and applies the FIPS 3-to-6-box guideline. A flow that tried to *enter* a box via its `.output` edge would be rejected, because an output leaves a box \u2014 the standard is enforced, not suggested.'
   },
@@ -1740,7 +1882,7 @@ If the LED doesn't light up, three things to check, in order: LED polarity (the
       "steady-state"
     ],
     "complexity": 2,
-    "featured": false,
+    "featured": true,
     "dsl": 'markov "Customer lifecycle"\n  analysis: classify, stationary\n  Trial -> Trial : 0.4\n  Trial -> Active : 0.5\n  Trial -> Churned : 0.1\n  Active -> Active : 0.8\n  Active -> Trial : 0.05\n  Active -> Churned : 0.15\n  Churned -> Churned : 0.7\n  Churned -> Trial : 0.3',
     "notes": "## What this shows\n\nA SaaS customer modelled as a memoryless hop between three states \u2014 Trial, Active, Churned \u2014 each month. Every row of probabilities leaving a state sums to 1 (the row-stochastic rule), and because churned customers can re-enter via Trial (`Churned -> Trial : 0.3`), no state is a dead end: the chain is **ergodic**, every state reachable from every other.\n\nThe engine does the linear algebra. It validates the matrix, runs SCC analysis to confirm a single recurrent class with no absorbing sink, then computes the **stationary distribution \u03C0** \u2014 the long-run share of your customer base sitting in each state once the system settles, independent of where it started. That steady-state answer (and the per-state classification) is carried in `data-*`, and it is the number a churn model exists to produce, not the circles-and-arrows."
   },
@@ -2496,7 +2638,7 @@ If the LED doesn't light up, three things to check, in order: LED polarity (the
       "color-coding"
     ],
     "complexity": 3,
-    "featured": false,
+    "featured": true,
     "dsl": 'phylo "Bacterial Diversity"\n  newick: "((((Ecoli:0.1,Salmonella:0.12):0.05[&&NHX:B=98],Vibrio:0.2):0.08[&&NHX:B=85],((Bacillus:0.15,Staph:0.18):0.06[&&NHX:B=92],Listeria:0.22):0.1):0.15,((Myco_tb:0.3,Myco_leprae:0.28):0.12[&&NHX:B=100],(Strepto:0.25,Lactobacillus:0.2):0.08[&&NHX:B=78]):0.2);"\n  clade Gamma = (Ecoli, Salmonella, Vibrio) [color: "#1E88E5", label: "\u03B3-Proteobacteria"]\n  clade Firmi = (Bacillus, Staph, Listeria, Strepto, Lactobacillus) [color: "#E53935", label: "Firmicutes"]\n  clade Actino = (Myco_tb, Myco_leprae) [color: "#43A047", label: "Actinobacteria"]\n  scale "substitutions/site"',
     "notes": '## Scenario\n\nA microbiologist or bioinformatician pastes a Newick tree string exported from RAxML, IQ-TREE, or MEGA and immediately gets a publication-ready SVG with clade highlights and a branch-length scale bar \u2014 no manual layout required.\n\n## Annotation key\n\n- `newick: "..."` \u2014 standard Newick format tree string; branch lengths follow `:` after each taxon name\n- `[&&NHX:B=98]` \u2014 NHX annotation; `B=` is the bootstrap support value (0\u2013100), rendered on internal nodes\n- `clade id = (taxon, ...)` \u2014 defines a named clade by listing its leaf members\n- `[color: "#hex", label: "..."]` \u2014 colors the clade\'s subtree and adds a labeled arc\n- `scale "..."` \u2014 draws a calibrated scale bar with the given unit label\n\n## How to read\n\nThe tree shows three major bacterial clades. Blue (\u03B3-Proteobacteria): *E. coli*, *Salmonella*, and *Vibrio* cluster with 98% bootstrap support. Red (Firmicutes): *Bacillus*, *Staph*, *Listeria*, *Streptococcus*, and *Lactobacillus*. Green (Actinobacteria): the two *Mycobacterium* species form a highly supported clade (bootstrap 100). Branch lengths represent substitutions per site \u2014 longer branches indicate faster evolutionary rates.'
   },
@@ -3101,7 +3243,7 @@ If the LED doesn't light up, three things to check, in order: LED polarity (the
       "data-flow"
     ],
     "complexity": 3,
-    "featured": false,
+    "featured": true,
     "dsl": 'threatmodel "E-commerce checkout"\nexternal: Customer\nexternal: Payment Gateway\nprocess 1.0: Web App\nprocess 2.0: Order Service\ndatastore D1: Orders DB\ndatastore D2: Audit Log\nCustomer -> 1.0 : "HTTPS Checkout"\n1.0 -> 2.0 : "Place order"\n2.0 -> D1 : "Write order"\n2.0 -> Payment Gateway : "Charge card"\n2.0 -> D2 : "Order event"\nboundary "Internet" { Customer, Payment_Gateway }\nboundary "DMZ" { 1.0 }\nboundary "Internal" { 2.0, D1, D2 }',
     "notes": "## What this shows\n\nA STRIDE threat model of an e-commerce checkout drawn as a data-flow diagram (DFD): two external entities (the customer and a third-party payment gateway), two processes (the web app in the DMZ, the order service internally), and two data stores (the orders database and an audit log). Three trust boundaries partition the system \u2014 Internet, DMZ, Internal \u2014 and the labelled flows carry the data crossing between them.\n\nThe engine does the STRIDE-per-element analysis, not just the boxes. It applies the canonical mapping \u2014 externals get Spoofing/Repudiation, processes get the full S-T-R-I-D-E, stores get Tampering/Information-disclosure/DoS, and the **audit log additionally gets Repudiation** because it matches the log/journal pattern. Most usefully, it **flags every flow that crosses a trust boundary** \u2014 the customer\u2192web-app HTTPS request (Internet\u2192DMZ), the order-service\u2192payment-gateway charge (Internal\u2192Internet) \u2014 because boundary crossings are where spoofing, tampering, and information disclosure concentrate. Each element and flow carries its applicable STRIDE categories in `data-*`."
   },
@@ -3174,7 +3316,7 @@ If the LED doesn't light up, three things to check, in order: LED polarity (the
       "bus-read"
     ],
     "complexity": 1,
-    "featured": false,
+    "featured": true,
     "dsl": 'timing "Synchronous Bus Read"\nCLK:  clock 8\nRST:  rle 1*2 0*6\nEN:   rle 0*2 1*4 0*2\nDATA: zz====zz  data: ["D0","D1","D2","D3"]',
     "notes": "## Scenario\n\nA digital designer documents an 8-cycle synchronous read. Rather than typing\n`pppppppp` for the clock and counting `0`/`1` runs by hand for reset and enable \u2014\nthe most common source of misaligned waveforms \u2014 the diagram uses the two\nlength-explicit shorthands.\n\n## Annotation key\n\n- **`clock N`** \u2014 a clock generator with `N` periods. `CLK: clock 8` expands to\n  `pppppppp`; add `neg` for a negedge clock. No character-counting.\n- **`rle <state>*<count> \u2026`** \u2014 run-length segments. `RST: rle 1*2 0*6` expands to\n  `11000000`; `EN: rle 0*2 1*4 0*2` expands to `00111100`. Every signal's total\n  cell count is explicit, so the waves line up.\n- **raw wave string** \u2014 `DATA: zz====zz` keeps per-cell control where it matters;\n  `data: [...]` labels the four `=` bus segments.\n\n## How to read\n\nThe clock runs 8 cycles. Reset is asserted for the first 2 cycles, then drops.\nEnable rises for the middle 4 cycles. The data bus is high-impedance until enable,\nthen presents four stable bytes `D0\u2026D3`, returning to high-Z after. Because\n`clock` and `rle` make each signal exactly 8 cells, the edges align without manual\ncounting."
   },
@@ -3402,7 +3544,7 @@ If the LED doesn't light up, three things to check, in order: LED polarity (the
       "fabrication"
     ],
     "complexity": 3,
-    "featured": false,
+    "featured": true,
     "dsl": 'welding "Bracket assembly"\njoint "gusset to column" {\n  arrow: fillet size=8 len=50 pitch=150\n  other: fillet size=6\n  around\n  field\n  tail: "GMAW"\n}\njoint "splice plate (butt)" {\n  arrow: vgroove angle=60 root=3 throat=12 contour=flush finish=G\n  other: backing\n  tail: "SMAW; E7018"\n}',
     "notes": "## What this shows\n\nA **welding symbol** is the standard way a drawing tells a fabricator how to weld a joint \u2014 codified by **AWS A2.4** (US) and **ISO 2553** (international). It is a *reference-line skeleton*: a horizontal line, a leader arrow to the joint, and a weld glyph snapped above (other side) or below (arrow side) the line, with dimensions in fixed slots.\n\nThe first joint is an **intermittent double fillet** \u2014 a `size=8` arrow-side fillet welded `50` long on a `150` pitch, a `size=6` fillet on the other side \u2014 carried **all around** the gusset (the open circle at the leader junction) as a **field weld** (the flag), with the **GMAW** process noted in the tail. The second joint is a full-penetration **V-groove butt weld**: a `60\xB0` included angle with a `3 mm` root opening and a `12 mm` effective throat, a **backing** weld on the far side, ground **flush**, welded **SMAW** with **E7018** electrode. Each callout is placed correct-by-construction \u2014 the engine owns the skeleton, you describe the weld."
   }
@@ -3630,280 +3772,696 @@ var PROFILES = {
   genogram: {
     type: "genogram",
     header: 'genogram "Title"',
-    mode: "family declarations + indented children",
+    mode: "individual declarations + couple lines + indented children",
+    keywords: 'sex: male female unknown other \xB7 status: deceased stillborn miscarriage abortion \xB7 couple ops: -- (married) ~/~ (cohabiting-ended) ~x~ (divorced) -/- (separated) -o- (engaged) == (consanguineous) ~ (cohabiting) \xB7 child props: adopted foster guardian twin-identical twin-fraternal \xB7 individual attrs: age:N dob:"\u2026" dod:"\u2026" death:YYYY note:"\u2026" birth:out-of-wedlock|adopted|legitimate label:"\u2026" sibling-of:ID index \xB7 conditions: name(fill[,#color]) + \u2026 \xB7 fills: full half-left half-right half-top half-bottom quad-tl quad-tr quad-bl quad-br quarter striped dotted \xB7 emotional ops: -TYPE- or -TYPE-> where TYPE \u2208 harmony close love hostile conflict cutoff fused distant nevermet abuse neglect controlling jealous focused distrust',
     forms: [
-      "personId [sex, birthYear, optionalAttrs]",
-      'parentA -- parentB "optional relationship label"',
-      "indent children under the couple line"
+      'genogram "Smith Family"',
+      "  john [male, 1975]",
+      "  mary [female, 1977]",
+      '  john -- mary "m. 2002"',
+      "    alice [female, 2005, index]",
+      "  john -conflict- mary"
+    ],
+    prefer: [
+      "Declare every individual (`id [sex, year, attrs]`) before any couple or emotional line that references them.",
+      "Use couple operators `--` (married), `~/~` (cohabiting-ended), `~x~` (divorced), `-/-` (separated), `==` (consanguineous), `~` (cohabiting) on their own line; indent children beneath.",
+      "Annotate conditions as `conditions: name(fill, #color) + name2(fill2)`, e.g. `conditions: diabetes(half-left, #ff9800) + cancer(quad-tr, #9c27b0)`.",
+      "Mark the identified patient with the `index` attribute so the concentric double-border is drawn."
     ],
-    prefer: ["Declare people before emotional relationships.", 'Use `[label: "..."]` only where the syntax reference shows a label attribute.'],
-    avoid: ["Avoid inline comments and speculative relationship operators."],
-    repair: ["Unknown individuals usually need a declaration before the relationship line."]
+    avoid: [
+      "Don't use pedigree genetic-status tokens (`affected`, `carrier`, `proband`) in a genogram \u2014 use `conditions:` fill patterns instead.",
+      'Don\'t attach emotional-operator labels with `[label:]`; place the optional quoted label after the right-hand id: `john -conflict- mary "ongoing"`.',
+      "Don't invent fill patterns \u2014 use only `full`, `half-left/right/top/bottom`, `quad-tl/tr/bl/br`, `quarter`, `striped`, `dotted`."
+    ],
+    repair: [
+      "'Unknown individual' -> declare `id [sex]` before any couple or emotional line that references that id.",
+      "'Invalid fill pattern' -> use one of: full, half-left, half-right, half-top, half-bottom, quad-tl, quad-tr, quad-bl, quad-br, quarter, striped, dotted.",
+      "'Conflicting sex for' -> an individual was declared with two different sexes \u2014 keep sex in the first declaration only.",
+      "'Invalid birth status' -> `birth:` accepts only `legitimate`, `out-of-wedlock`, or `adopted`."
+    ]
   },
   ecomap: {
     type: "ecomap",
     header: 'ecomap "Title"',
-    mode: "center + external systems",
+    mode: "center declaration + external systems + connection operators",
+    keywords: 'center: ID [label:"\u2026"] \xB7 system: ID [label:"\u2026" category:family|friends|work|education|health|mental-health|religion|recreation|legal|community|substance|financial|cultural|technology|pet size:large|medium|small importance:major|moderate|minor] \xB7 connection ops (strength): === (strong) == (moderate) --- (normal) "- -" (weak) ~~~ (stressful) ~x~ (conflictual) -/- (broken) \xB7 directional variants: ===> <=== ==> <== --> <-- <-> <=> \xB7 [label:"\u2026"] on a connection',
     forms: [
-      'center: client [label: "Client"]',
-      'systemId [label: "System", category: family]',
-      'systemId === client [label: "support"]'
+      'ecomap "Marcus, age 15"',
+      '  center: client [label: "Marcus"]',
+      '  mom [label: "Mother", category: family]',
+      '  school [label: "East High School", category: education]',
+      '  therapist [label: "Ms. Chen", category: mental-health]',
+      '  mom === client [label: "primary caregiver"]',
+      "  school === client",
+      '  therapist <-> client [label: "weekly"]'
+    ],
+    prefer: [
+      "Declare exactly one `center: ID [props]` first; this is the central individual or family unit.",
+      'Declare all external systems (`ID [label: "\u2026", category: \u2026]`) before their connection lines.',
+      "Choose connection strength from `===` (strong), `==` (moderate), `---` (normal), `~~~` (stressful), `-/-` (broken); add a directional arrow variant (`-->`, `<->`, `==>`) when energy-flow direction matters."
+    ],
+    avoid: [
+      "Don't use genogram couple operators (`--`, `~/~`) inside an ecomap \u2014 they are not connection operators here.",
+      "Don't omit the `center:` line; a diagram with no center is structurally invalid even if it renders.",
+      "Don't nest family members under `center:` like a genogram; the ecomap center is a single node (use `sociogram` for network structure)."
     ],
-    prefer: ["Declare exactly one center.", "Declare outside systems before their connection lines."],
-    avoid: ["Avoid borrowing genogram operators such as `--`."],
-    repair: ["A valid render with a missing center is semantically wrong; add `center:` first."]
+    repair: [
+      "'Unexpected:' -> the line is not a center declaration, a system declaration, or a valid connection \u2014 check operator spelling (`~x~` has the letter x).",
+      "'Expected ecomap header' -> the first non-blank line must start with `ecomap`; add or fix the header.",
+      'A connection to an undeclared id silently creates a stray node \u2014 declare `systemId [label: "\u2026"]` before the connection line.'
+    ]
   },
   pedigree: {
     type: "pedigree",
     header: 'pedigree "Title"',
-    mode: "clinical pedigree",
+    mode: "individual declarations + couple lines + indented offspring (NSGC notation)",
+    keywords: 'sex: male female unknown amab afab uaab \xB7 genetic status: affected carrier carrier-x obligate-carrier presymptomatic unaffected \xB7 life status: deceased stillborn pregnancy sab tab ectopic \xB7 markers: proband consultand evaluated \xB7 couple ops: -- (mated) -/- (separated) == (consanguineous) ~ (cohabiting, no offspring) \xB7 multi-trait legend: id = "Label" (fill: quad-tl|quad-tr|quad-bl|quad-br) + affected:trait1+trait2 \xB7 header mode suffix: pedigree:autosomal-dominant|autosomal-recessive|x-linked',
     forms: [
-      "personId [sex, generationAttrs]",
-      "parentA -- parentB",
-      "indent offspring under the couple line"
+      'pedigree "Hemophilia A"',
+      "  I-1 [male, unaffected]",
+      "  I-2 [female, carrier-x]",
+      "  I-1 -- I-2",
+      "    II-1 [male, affected]",
+      "    II-2 [female, carrier-x]",
+      "    II-3 [male, unaffected]"
+    ],
+    prefer: [
+      "Use Roman-numeral generation labels (`I-1`, `II-3`) for individual ids \u2014 the NSGC clinical convention.",
+      "Declare genetic status on each individual: `affected`, `carrier`, `carrier-x` (X-linked dot), `obligate-carrier`, `presymptomatic`, or `unaffected`.",
+      "Mark the index case with `proband`; mark a family member seeking advice with `consultand`."
     ],
-    prefer: ["Use pedigree status/trait attributes from the syntax reference.", "Keep generation structure explicit."],
-    avoid: ["Avoid genogram emotional-relationship lines in pedigree output."],
-    repair: ["Declare every referenced individual before relationships."]
+    avoid: [
+      "Don't use genogram emotional-relationship operators (`-conflict-`, `-abuse->`) in a pedigree \u2014 only couple and parent-child lines are valid.",
+      "Don't mix pedigree status with genogram `conditions:` fill syntax; pedigree uses `affected`/`carrier` tokens, not `conditions:name(fill)`.",
+      "Don't invent sex tokens; valid values are `male`, `female`, `unknown`, `amab`, `afab`, `uaab`."
+    ],
+    repair: [
+      "'Unknown individual' -> declare `id [sex, geneticStatus]` before any couple line that references that id.",
+      "'Expected pedigree header' -> the first non-blank line must start with `pedigree`; the optional `:mode` suffix and title follow.",
+      "'Conflicting' -> keep one canonical declaration per individual; redeclarations should add only the missing couple reference."
+    ]
   },
   phylo: {
     type: "phylo",
     header: 'phylo "Title"',
-    mode: "quoted Newick",
-    forms: ['newick: "((A:0.1,B:0.2),C:0.3);"', 'clade Group = (A, B) [label: "Group"]'],
-    prefer: ["Use Newick for first-shot generation.", "Quote the Newick string."],
-    avoid: ["Avoid indent-tree mode unless the user wants a hand-authored tree."],
-    repair: ["A phylo document needs exactly one tree definition: Newick or indent tree."]
+    mode: "Newick string (newick:) or indented-tree DSL, with optional clade highlights",
+    keywords: 'newick: "\u2026" (NHX supported) \xB7 indent tree: root: then indented Name:branchLength \xB7 header opts [layout: rectangular|slanted|circular|unrooted, mode: phylogram|cladogram|chronogram|dendrogram, mrsd:"YYYY", branch-width:N] \xB7 clade ID = (leaf1, leaf2) [color: "#hex", label: "\u2026", highlight: branch|background|both] \xB7 outgroup: ID \xB7 scale "unit label" \xB7 cut N (dendrogram threshold)',
+    forms: [
+      'phylo "Bacterial Diversity"',
+      '  newick: "((Ecoli:0.1,Salmonella:0.12):0.05,Vibrio:0.2);"',
+      '  clade Gamma = (Ecoli, Salmonella, Vibrio) [color: "#1E88E5", label: "Gammaproteobacteria"]',
+      '  scale "substitutions/site"'
+    ],
+    prefer: [
+      'Use `newick: "\u2026"` for first-shot generation \u2014 a Newick string with branch lengths (`Name:length`); NHX annotations `[&&NHX:B=98]` carry bootstrap values.',
+      'Add `clade ID = (leaf1, leaf2, \u2026) [color: "#hex", label: "\u2026"]` after the newick line to highlight named clades.',
+      'Use `[mode: chronogram, mrsd: "YYYY"]` for time-calibrated trees and `[mode: cladogram]` when branch lengths are absent.'
+    ],
+    avoid: [
+      "Don't use the indent-tree mode (`root:` + indented names) for first-shot generation \u2014 Newick is more compact.",
+      "Don't omit branch lengths in phylogram mode; without them the layout collapses (use `[mode: cladogram]` explicitly instead).",
+      "Don't reference clade member names that don't match the Newick leaf labels exactly \u2014 highlighting silently does nothing on a mismatch."
+    ],
+    repair: [
+      "'No tree definition found (newick: or indent tree)' -> add a `newick: \"\u2026;\"` line or an indent tree starting with `root:` after the header.",
+      "'Empty indent tree definition' -> the `root:` block has no indented content \u2014 add at least one child line.",
+      "If clade colors don't appear, check every member id in `clade X = (\u2026)` exactly matches a leaf label in the Newick string."
+    ]
   },
   sociogram: {
     type: "sociogram",
     header: 'sociogram "Title"',
-    mode: "declared nodes + social ties",
-    forms: ['nodeId [label: "Person"]', 'nodeA -> nodeB [label: "choice"]', "config: layout = circular"],
-    prefer: ["Declare actors first.", "Use one supported layout/config value at a time."],
-    avoid: ["Avoid unknown config values; some adapters keep defaults."],
-    repair: ["Unknown edge endpoints need matching node declarations."]
+    mode: "declared nodes + edge operators + config",
+    keywords: 'nodeId [label:"\u2026" group:id role:star|isolate|bridge|neglectee|rejected size:small|medium|large] \xB7 group id [label:"\u2026" color:"#hex"] + indented members \xB7 edge ops positive: -> <-> -- ==> <==> === \xB7 negative: -x> <x-> -x- \xB7 neutral: -.> <.-> -.- \xB7 [weight:N label:"\u2026"] on edge \xB7 config: layout = circular|force-directed|concentric \xB7 config: sizing = uniform|in-degree|betweenness \xB7 config: coloring = default|group|role',
+    forms: [
+      'alice [label: "Alice"] [role: star]',
+      'bob [label: "Bob"] [group: teamA]',
+      'group teamA [label: "Team A", color: "#1976D2"]',
+      "  alice; bob",
+      'alice <-> bob [label: "study partners"]',
+      'carol -x> dave [label: "conflict"]',
+      "config: layout = force-directed"
+    ],
+    prefer: [
+      "Declare nodes explicitly before edge lines when you need `role:`, `group:`, or `size:` \u2014 the parser auto-registers undeclared ids, but only named declarations carry attributes.",
+      "Use `group id [label:\u2026]` + indented members to cluster nodes; coloring follows when `config: coloring = group` is set.",
+      "Pick the edge operator by valence: `->`/`<->`/`--` positive, `-x>`/`-x-` negative (rejection/conflict), `-.>`/`-.-` neutral; heavier `==>`/`===` encode strong-weight ties."
+    ],
+    avoid: [
+      "Don't borrow ecomap operators \u2014 in a sociogram `===` is an undirected strong tie, not an ecomap stress line; every operator encodes direction and valence.",
+      "Don't set `config: layout` to an unsupported value \u2014 only `circular`, `force-directed`, `concentric` are accepted; unknown values are silently ignored.",
+      "Don't omit the spaces around an edge operator: `alice->bob` is not parsed; it must be `alice -> bob`."
+    ],
+    repair: [
+      "'Sociogram must start with' -> the first non-blank line must be `sociogram` (optionally with a quoted title); fix a missing or misspelled header.",
+      'A node referenced only on edge lines auto-registers with no label \u2014 if the rendered label is the raw id, add an explicit `nodeId [label: "\u2026"]` declaration.',
+      "An unrecognised `config:` value (e.g. `layout = radial`) is silently dropped and defaults to `circular` \u2014 check spelling against the accepted enum."
+    ]
   },
   timing: {
     type: "timing",
     header: 'timing "Title"',
     mode: "WaveDrom signals, with clock/run-length shorthands",
+    keywords: 'timing "title" [hscale: N] \xB7 SIGNAME: wave_spec \xB7 wave chars 0 1 x z = . u d p P n N h H l L 2-9 \xB7 clock N [neg] \xB7 rle <state>*<count> \u2026 \xB7 data: ["a","b"] for = and digit segments \xB7 [GroupName] or group "name" { \u2026 } \xB7 --- spacer \xB7 phase: FLOAT (0.0\u20131.0)',
     forms: [
-      "CLK: clock 8                 (clock generator, 8 periods \u2014 no char-counting)",
-      "RST: rle 1*2 0*6             (run-length: two 1s then six 0s)",
-      'DATA: x====x data: ["A","B"] (raw WaveDrom wave + bus labels)'
+      'timing "Synchronous Bus Read"',
+      "CLK:  clock 8",
+      "RST:  rle 1*2 0*6",
+      "EN:   rle 0*2 1*4 0*2",
+      'DATA: zz====zz  data: ["D0","D1","D2","D3"]'
     ],
     prefer: [
-      "Use `clock N` for clocks instead of counting `p` characters.",
-      "Use `rle <state>*<count> ...` for level/data signals instead of counting characters \u2014 it auto-aligns length.",
-      "Drop to a raw wave string only for fine control; keep all signals the same total length so they align.",
-      "Use `data:` labels for bus segments (`=` or digit states)."
+      "Use `clock N` for clocks instead of counting `p` characters \u2014 `CLK: clock 8` is immune to count errors.",
+      "Use `rle <state>*<count> \u2026` for level/data signals \u2014 `RST: rle 1*2 0*6` makes length explicit and auto-aligns.",
+      'Drop to a raw wave string only for fine control (e.g. `DATA: zz====zz`); label bus segments (`=` or digit states) with `data: ["A","B",\u2026]`.',
+      "Keep all signals the same total cell count so they align; `clock N` and `rle` make this trivial to verify."
+    ],
+    avoid: [
+      "Avoid hand-counting long runs of identical characters \u2014 mismatched counts are the main source of misaligned waves.",
+      "Don't mix `clock`/`rle` and a raw wave string for the same signal; pick one form per signal.",
+      "Don't use a wave character outside `0 1 x z = . p P n N h H l L u d 2-9`."
     ],
-    avoid: ["Avoid hand-counting long runs of identical characters \u2014 that is the main source of misaligned waves."],
     repair: [
-      "Wave-state errors name the offending character and list the valid states.",
-      "If two signals don't line up, make their total cell counts equal (clock N and rle make this easy)."
+      "'clock needs a positive cycle count' -> provide an integer >= 1 after `clock`, e.g. `CLK: clock 8`.",
+      "'rle segment must be' -> each rle token must match `<char>*<N>` with a valid state char, e.g. `rle 1*3 0*5`.",
+      "'is not a valid state' -> valid states are `0 1 x z = . p P n N h H l L u d 2-9`; replace the offending character, or use `clock`/`rle`."
     ]
   },
   logic: {
     type: "logic",
     header: 'logic "Title"',
-    mode: "logic netlist",
-    forms: ["INPUT A, B", "G1 = AND(A, B)", "OUTPUT Y = G1"],
+    mode: "logic netlist \u2014 INPUT/OUTPUT declarations + gate assignments; optional module grouping",
+    keywords: 'logic ["Title"] [style: ansi|iec] \xB7 INPUT id, \u2026 \xB7 OUTPUT id, \u2026 \xB7 id = GATE(in1, in2, \u2026) \xB7 active-low prefix ~ on any signal \xB7 module "Label" { \u2026 } \xB7 combinational: AND OR NOT NAND NOR XOR XNOR BUF \xB7 output-buffer: TRISTATE_BUF TRISTATE_INV OPEN_DRAIN SCHMITT \xB7 flip-flops: DFF JKFF SRFF TFF \xB7 latches: LATCH_SR LATCH_D \xB7 complex: MUX DEMUX DECODER ENCODER COUNTER SHIFT_REG',
+    forms: [
+      'logic "1-bit Full Adder"',
+      "input A, B, Cin",
+      "output Sum, Cout",
+      "s1 = XOR(A, B)",
+      "Sum = XOR(s1, Cin)",
+      "c1 = AND(A, B)",
+      "c2 = AND(s1, Cin)",
+      "Cout = OR(c1, c2)"
+    ],
     prefer: [
-      "Gate form is `id = TYPE(in1, in2, \u2026)`; declare `INPUT`/`OUTPUT` ports explicitly. Prefix a signal with `~` for active-low.",
-      "Use only these canonical gate TYPEs: combinational AND, OR, NOT, NAND, NOR, XOR, XNOR, BUF; output buffers TRISTATE_BUF, TRISTATE_INV, OPEN_DRAIN, SCHMITT; flip-flops DFF, JKFF, SRFF, TFF; latches LATCH_SR, LATCH_D; complex MUX, DEMUX, DECODER, ENCODER, COUNTER, SHIFT_REG."
+      "Gate form is `id = TYPE(in1, in2, \u2026)`; declare `INPUT`/`OUTPUT` ports explicitly. Prefix any signal with `~` for active-low.",
+      "Use only canonical gate types \u2014 combinational `AND` `OR` `NOT` `NAND` `NOR` `XOR` `XNOR` `BUF`; buffers `TRISTATE_BUF` `TRISTATE_INV` `OPEN_DRAIN` `SCHMITT`; flip-flops `DFF` `JKFF` `SRFF` `TFF`; latches `LATCH_SR` `LATCH_D`; complex `MUX` `DEMUX` `DECODER` `ENCODER` `COUNTER` `SHIFT_REG`.",
+      'Group related gates with `module "Label" { \u2026 }` to render a named bounding box.'
+    ],
+    avoid: [
+      "Avoid circuit component names (`R`, `C`, transistors) or FBD block names (`TON`, `CTU`) inside logic diagrams \u2014 they are not valid gate types.",
+      "Don't leave a `module { \u2026 }` unclosed \u2014 an unclosed module block throws `Unclosed module`.",
+      "Don't rely on auto-declaration of undeclared signals \u2014 the parser warns and adds them silently; explicit `INPUT` lines are cleaner."
     ],
-    avoid: ["Avoid circuit component names (R, C, transistors) inside logic diagrams."],
-    repair: ["An unrecognised gate renders as a flagged `?` placeholder; replace it with the closest canonical gate from the list above (e.g. LOAD/REG \u2192 DFF, INV \u2192 NOT)."]
+    repair: [
+      "'has unrecognised type' -> replace with the closest canonical gate (e.g. `LOAD`/`REG` -> `DFF`, `INV` -> `NOT`, `BUFFER` -> `BUF`); the lint hint names the nearest match.",
+      "'Unclosed module' -> add a closing `}` for every `module \"\u2026\" {` block.",
+      "'was not declared; auto-declared as input' -> add an explicit `input X` line to make the port intentional."
+    ]
   },
   circuit: {
     type: "circuit",
     header: 'circuit "Title" netlist',
     mode: "SPICE-style netlist (recommended for generation)",
+    keywords: 'header: circuit "name" netlist \xB7 ID net1 net2 [value] [key=value \u2026] \xB7 prefixes R(resistor) C(capacitor) L(inductor) D(diode) V(voltage_source) I(current_source) Q(BJT) M(MOSFET) J(jfet) S(switch) F(fuse) B(battery) K(relay) U/X(ic) W(wire) T(terminal) \xB7 ground nets 0/gnd/ground/earth/vss/agnd/dgnd \xB7 type= override \xB7 dir=(right|left|up|down) \xB7 pins="\u2026" \xB7 positional mode (no netlist): id: type dir [label= value= at=] \xB7 wire right|left|up|down \xB7 at: id.pin \xB7 net NAME \xB7 ground vcc no_connect',
     forms: [
-      "V1 in 0 5V        (component-id  node-A  node-B  value)",
-      "R1 in out 1k",
-      "C1 out 0 100n"
+      'circuit "Bridge Rectifier Supply" netlist',
+      "V1 ac1 ac2 12Vac",
+      "D1 ac1 vout 1N4007",
+      "D2 ac2 vout 1N4007",
+      "D3 0 ac1 1N4007",
+      "D4 0 ac2 1N4007",
+      "C1 vout 0 470u",
+      "Rload vout 0 1k"
     ],
     prefer: [
-      "Always use netlist mode (`... netlist` header). Each line is one component; no spatial state to track.",
-      "Two components that share a node name are wired together. `0`, `gnd`, or `GND` is the ground net.",
-      "The component-id prefix sets the type (R=resistor, C=capacitor, L=inductor, V=source, D=diode, Q=BJT). Add explicit `type=` only when the prefix is ambiguous.",
-      "Optional orientation hint `dir=` (right|left|up|down) nudges a single symbol's facing, e.g. `C1 out 0 100n dir=down` for a shunt cap. Connectivity is unaffected; omit it unless layout readability needs it."
+      'Always use netlist mode (`circuit "name" netlist`). Each line is one component; no cursor state to track.',
+      "Two components sharing a net name are wired together. Ground is `0`, `GND`, or an alias (`AGND`, `VSS`, `earth`); all normalise to one GND rail.",
+      "The id first letter sets the type (R=resistor, C=capacitor, L=inductor, D=diode, V=voltage_source, Q=BJT, M=MOSFET). Use `type=` only when the prefix is ambiguous.",
+      "Optional `dir=right|left|up|down` nudges a symbol's orientation (e.g. `C1 vout 0 100n dir=down` for a shunt cap); it does not set position."
     ],
     avoid: [
-      "Avoid positional cursor routing (`wire`, `at:`) \u2014 that mode is for hand-drawing, not generation.",
-      "Do not invent coordinates; the layout engine places components from the net connectivity. `dir=` only rotates a symbol, it does not set position."
+      "Avoid positional cursor mode (`wire`, `at:`) \u2014 it requires tracking mental cursor state and is not recommended for generation.",
+      "Do not invent coordinates; the auto-layout engine places components from net connectivity. `dir=` only rotates a symbol.",
+      "Don't give a multi-terminal part fewer nets than it has pins (a `transformer` needs 4: `T1 p1 p2 s1 s2 type=transformer`)."
     ],
-    repair: ["If a component type or pin count is ambiguous, make the symbol type explicit with `type=`."]
+    repair: [
+      "'Cannot infer type from id' -> rename to a SPICE-prefix id (R*, C*, L*, D*, V*, Q*, M*\u2026) or add `type=<name>` (e.g. `N1 in out type=nmos`).",
+      "'must be unique' -> a reference designator is declared more than once; rename the duplicates.",
+      "'no ground reference' -> tie a return node to ground by naming a net `0` or `GND` (e.g. `V1 vin 0 5V`).",
+      "'connects to only one pin' -> wire the net to a second pin, or mark the open pin with a `no_connect` symbol."
+    ]
   },
   blockdiagram: {
     type: "blockdiagram",
     header: 'blockdiagram "Title"',
-    mode: "blocks, sums, signals",
-    forms: ['ctrl = block("PID") [role: controller]', "err = sum(+r, -y)", "err -> ctrl -> plant"],
-    prefer: ["Use named blocks and directed `->` chains."],
-    avoid: ["Avoid unlabeled feedback intent; model the summing junction."],
-    repair: ["Connections must point at declared blocks, sums, signals, or boundary IDs."]
+    mode: "named block/sum/signal decls + directed -> chains",
+    keywords: 'ID = block("label") [role:\u2026][route:above|below] \xB7 ID = sum(+a, -b) \xB7 ID = signal("label") [discrete] \xB7 connect ids with -> (chainable a -> b -> c) \xB7 in / out boundary ports \xB7 edge label ["text"] | roles: controller plant sensor actuator reference disturbance generic',
+    forms: [
+      'C = block("PID C(s)") [role: controller]',
+      'G = block("Plant G(s)") [role: plant]',
+      "err = sum(+r, -y)",
+      "in -> err -> C -> G -> y",
+      "G -> err"
+    ],
+    prefer: [
+      'Declare blocks `ID = block("label") [role: \u2026]`, junctions `ID = sum(+a, -b)`, and signals `ID = signal("label")`, then wire ids with directed `->` (chainable: `a -> b -> c`).',
+      "Model feedback through an explicit `sum(+ref, -fb)` \u2014 the signs are visual (+ enters, \u2212 subtracts), not computed; send a long return path over the top with `[route: above]` on the sensor block.",
+      'Roles for styling: controller, plant, sensor, actuator, reference, disturbance, generic. Use the auto-provided `in`/`out` ports for the system boundary, and annotate an edge with `["label"]`.'
+    ],
+    avoid: [
+      "An unknown id on a `->` line does NOT error \u2014 it silently becomes a stray generic `block`, so a typo'd id creates a phantom box. Keep ids consistent.",
+      "Avoid drawing feedback as a bare reverse arrow with no junction; route it into a `sum(...)` so the loop reads correctly.",
+      'Don\'t quote ids; quotes belong only inside `block("\u2026")` / `signal("\u2026")` labels and edge `["\u2026"]` labels.'
+    ],
+    repair: [
+      "'Invalid connection: <line>' -> a `->` line needs an id on both sides (e.g. `err -> C`); `C ->` or `-> C` alone is rejected.",
+      "Most ids auto-declare, so few lines hard-fail \u2014 if a box is unexpectedly empty or duplicated, look for an id typo (see avoid)."
+    ]
   },
   ladder: {
     type: "ladder",
     header: 'ladder "Title"',
-    mode: "rungs + IEC/Rockwell elements",
-    forms: ['rung 1 "Run motor":', "  XIC(START_PB)", "  OTE(MOTOR_RUN)"],
-    prefer: ["Use uppercase element names.", "Use `parallel:` + `branch:` only for OR branches."],
-    avoid: ["Avoid variable declarations and ST syntax."],
-    repair: ["Element typos are repairable from parser suggestions; keep the tag in parentheses."]
+    mode: "rungs with IEC 61131-3 contacts / coils / function blocks; OR branches via parallel:/branch:",
+    keywords: 'rung N ["comment"]: \xB7 contacts XIC XIO ONS OSF \xB7 coils OTE OTL OTU OTN RES \xB7 function blocks TON TOFF TP CTU CTD CTUD ADD SUB MUL DIV MOV EQU NEQ GRT LES GEQ LEQ \xB7 parallel: branch: (OR branch block) \xB7 element syntax ELEM(tag [, address] [, name="\u2026"])',
+    forms: [
+      'ladder "Motor Start/Stop"',
+      'rung 1 "Seal-in circuit":',
+      "  parallel:",
+      "    branch:",
+      '      XIC(START_PB, "IN 1.0", name="Start Button")',
+      "    branch:",
+      '      XIC(MOTOR_AUX, "BIT 3.0", name="Aux Contact")',
+      '  XIO(STOP_PB, "IN 1.1", name="Stop Button")',
+      '  OTE(MOTOR_CMD, "OUT 2.0", name="Motor Command")'
+    ],
+    prefer: [
+      "Use uppercase element names: contacts `XIC` `XIO` `ONS` `OSF`; coils `OTE` `OTL` `OTU` `OTN` `RES`; function blocks `TON` `TOFF` `TP` `CTU` `CTD` `CTUD` `ADD` `SUB` `MUL` `DIV` `MOV` `EQU` `NEQ` `GRT` `LES` `GEQ` `LEQ`.",
+      'Keep the tag as the first argument in parentheses; optional address (second positional) and `name=` follow: `XIC(START_PB, "IN 1.0", name="Start Button")`.',
+      "Model parallel contacts (OR logic) with an indented `parallel:` block containing two or more `branch:` sub-blocks."
+    ],
+    avoid: [
+      "Don't invent element types \u2014 an unrecognised name throws `unknown element type` and halts the parse; use only the canonical list.",
+      "Don't write an empty rung; every rung must contain at least one element or the parser throws `empty rung`.",
+      "Don't use `branch:` outside a `parallel:` block \u2014 it throws `branch: without parallel:`."
+    ],
+    repair: [
+      "'unknown element type' -> replace with the closest canonical name (e.g. `LATCH` -> `OTL`, `UNLATCH` -> `OTU`, `OSR` -> `ONS`); the parser's did-you-mean hint names the nearest match.",
+      "'empty rung' -> add at least one contact or coil element inside the rung.",
+      "'branch: without parallel:' -> wrap the `branch:` block inside a `parallel:` block first.",
+      "'element outside of rung' -> every element line must appear after a `rung N:` header."
+    ]
   },
   sld: {
     type: "sld",
     header: 'sld "Title"',
-    mode: "equipment assignments + power-flow edges",
-    forms: ['util = utility [label: "Grid"]', 'xfmr = transformer [rating: "500 kVA"]', "util -> xfmr  (one edge per line, no chaining)"],
+    mode: "equipment declarations + directed power-flow edges",
+    keywords: 'sld "title" [standard: ansi|iec|abnt|as-nzs] \xB7 ID = nodeType [label:"\u2026" voltage:"\u2026" rating:"\u2026" device:"\u2026"] \xB7 ID -> ID [cable:"\u2026" label:"\u2026"] \xB7 sources: utility generator solar wind ups \xB7 transformers: transformer transformer_dy transformer_yd transformer_yy transformer_dd autotransformer transformer_3winding \xB7 buses: bus bus_tie hub \xB7 switching: breaker breaker_vacuum switch switch_load ground_switch ats recloser sectionalizer fuse fuse_cl \xB7 protection: ct pt relay surge_arrester ground_fault \xB7 loads: motor load capacitor_bank harmonic_filter vfd \xB7 metering: watthour_meter demand_meter \xB7 aliases: mcb/mccb->breaker rcd/rcbo/rccb->ground_fault isolator/disconnector->switch_load panel/consumer_unit/distribution_board->bus',
+    forms: [
+      'sld "Utility + Generator Backup"',
+      'UTIL = utility [voltage: "480V", label: "Utility"]',
+      'GEN = generator [rating: "500 kW", voltage: "480V"]',
+      'ATS1 = ats [rating: "800A"]',
+      'BUS1 = bus [voltage: "480V"]',
+      'CB1 = breaker [rating: "200A"]',
+      'L1 = load [label: "Critical Load"]',
+      "UTIL -> ATS1",
+      "GEN -> ATS1",
+      "ATS1 -> BUS1",
+      "BUS1 -> CB1",
+      "CB1 -> L1"
+    ],
     prefer: [
-      "Declare equipment as `id = nodeType [attrs]`, one `from -> to` connection per line.",
-      "Use only these canonical nodeTypes: sources utility, generator, solar, wind, ups; transformers transformer, transformer_dy, transformer_yd, transformer_yy, transformer_dd, autotransformer, transformer_3winding; buses bus, bus_tie, hub; switching breaker, breaker_vacuum, switch, switch_load, ground_switch, ats, recloser, sectionalizer, fuse, fuse_cl; protection ct, pt, relay, surge_arrester, ground_fault; loads motor, load, capacitor_bank, harmonic_filter, vfd; metering watthour_meter, demand_meter.",
-      "IEC/REBT residential aliases are also accepted: mcb/mccb\u2192breaker, rcd/rcbo/rccb\u2192ground_fault, isolator/disconnector\u2192switch_load, panel/consumer_unit/distribution_board\u2192bus."
+      "Declare every node as `id = nodeType [attrs]` before any `->` connection references it.",
+      "Use one `from -> to` edge per line \u2014 SLD does not support chained arrows like `a -> b -> c`.",
+      'Annotate nodes with `[label: "\u2026", rating: "\u2026", voltage: "\u2026"]`; annotate edges with `[cable: "\u2026", label: "\u2026"]`.'
+    ],
+    avoid: [
+      "Avoid nodeTypes not in the catalog \u2014 an unrecognised type renders as a flagged `?` placeholder; pick the closest canonical type or alias (meter->watthour_meter, inverter->vfd, isolator->switch_load).",
+      "Avoid chained arrow syntax (`a -> b -> c`) \u2014 each connection must be its own line.",
+      "Avoid using `[standard: iec]` with ANSI-only devices (`recloser`, `sectionalizer`, `watthour_meter`) \u2014 they have no IEC symbol and render with a warning."
     ],
-    avoid: ["Avoid generic flowchart node syntax."],
-    repair: ["An unrecognised nodeType renders as a flagged `?` placeholder; pick the closest canonical type or alias from the list above (e.g. meter\u2192watthour_meter, inverter\u2192vfd)."]
+    repair: [
+      "'Connection references unknown node' -> declare the node with `id = nodeType` before the `->` line that names it.",
+      "'Duplicate node id' -> each id must appear on exactly one `id = nodeType` line; rename the second occurrence.",
+      "'Cannot parse line' -> every non-blank line must be the `sld` header, a node declaration (`id = type [attrs]`), or a connection (`id -> id [attrs]`).",
+      "'unrecognised type' -> replace the unknown type with a catalog type or alias (e.g. `inverter` -> `vfd`)."
+    ]
   },
   entity: {
     type: "entity",
     header: 'entity-structure "Title"',
-    mode: "legal entities + ownership edges",
+    mode: "legal entity declarations + typed ownership edges",
+    keywords: 'entity ID "Name" TYPE[@JX] [status:new|eliminated|modified tax:ccorp|passthrough|scorp|trust|disregarded|foundation|individual role:"\u2026" note:"\u2026"] \xB7 types: corp llc lp trust individual/person foundation disregarded/branch placeholder/tbf pool \xB7 edges: -> (ownership) ==> (voting-only) -.-> (pool/option) -~-> (license/management) --> (distribution) \xB7 edge attrs [class:"\u2026" label:"\u2026"] \xB7 percentage: "100%" or "V 75% / E 50%" \xB7 jurisdiction CODE "Name" [color:"#hex"] \xB7 cluster "Name" [members: [id1, id2], color:"#hex"]',
     forms: [
-      'entity holdco "HoldCo" corp@US',
-      'entity opco "OpCo" llc@DE',
-      "holdco -> opco : 100%",
-      'cluster "Group Name" [members: [holdco, opco]]'
+      'entity parent "Acme Global, Inc." corp@US [note: "Ultimate Parent"]',
+      'entity ie-holdco "Acme Ireland Holdings" corp@IE',
+      'entity ie-ip "Acme IP Ltd" corp@KY',
+      "parent -> ie-holdco : 100%",
+      'ie-ip -~-> ie-holdco [label: "IP License \xB7 royalty"]',
+      'jurisdiction US "United States" [color: "#3b82f6"]',
+      'cluster "Ireland / Cayman IP" [members: [ie-holdco, ie-ip]]'
     ],
     prefer: [
-      "Use `entity` declarations before ownership edges.",
-      "Keep legal form and jurisdiction explicit when known.",
-      'Group entities with `cluster "Name" [members: [id1, id2]]` \u2014 the members value MUST be a bracketed list.'
+      "Declare all `entity` nodes before any edge lines; the entity type goes after the quoted name (`corp`, `llc`, `lp`, `trust`, `individual`, `foundation`, `disregarded`, `pool`).",
+      "Append `@JX` jurisdiction code directly to the type token (`corp@DE`, `trust@SD`) \u2014 no space; omit only when jurisdiction is unknown.",
+      "Use the right edge operator for semantics: `->` ownership, `==>` voting-only control, `-~->` contractual (license/management), `-->` distribution, `-.->` option pool."
+    ],
+    avoid: [
+      "Don't use `fund` as an entity type \u2014 only canonical types are accepted; use `lp` for funds/LPs.",
+      'Don\'t put edge properties outside brackets: `[class: "Series A Pref"]`, not `: Series A Pref class`.',
+      "Don't write `cluster` without a bracketed `[members: [...]]` list \u2014 the members value must be a bracket-enclosed comma list."
     ],
-    avoid: ["Avoid database schema terminology; use `erd` for tables and FKs."],
-    repair: ["Unknown ownership endpoints need entity declarations."]
+    repair: [
+      "'Unknown entity type' -> replace with a canonical type: corp llc lp trust individual foundation disregarded placeholder pool.",
+      "'Edge references unknown entity' -> add the `entity <id> \u2026` declaration before the edge line.",
+      "'has no entities' -> the document needs at least one `entity` line."
+    ]
   },
   fishbone: {
     type: "fishbone",
     header: 'fishbone "Title"',
-    mode: "effect + cause categories",
-    forms: ['effect "Late Delivery"', 'category process "Process"', 'process: "Handoff delay"'],
-    prefer: ["Use one effect and structured categories for generated DSL."],
-    avoid: ["Avoid mixing compact alien syntax when a structured category form works."],
-    repair: ["If a cause lands nowhere, add or reference its category explicitly."]
+    mode: "effect + structured category ribs + cause lines",
+    keywords: 'effect "\u2026" \xB7 category id "Label" [side:top|bottom order:N color:"#hex"] \xB7 catId : "cause text" \xB7 compact: category Label: cause1; cause2 \xB7 sub-cause: indent >=2 + "- text" \xB7 config direction = left|right \xB7 config sides = both|top|bottom \xB7 config density = compact|normal|spacious',
+    forms: [
+      'fishbone "Manufacturing defect spike"',
+      'effect "Solder joint defect > 3%"',
+      'category man "Man"',
+      'category machine "Machine"',
+      'category method "Method"',
+      'man : "Operator training gaps"',
+      'machine : "Reflow oven calibration"',
+      '  - "Temperature profile not updated"',
+      'method : "No incoming inspection"'
+    ],
+    prefer: [
+      'Declare each `category id "Label"` before referencing `id : "cause"` \u2014 the structured form keeps category ids unambiguous.',
+      "Use `[side: top]` / `[side: bottom]` and `[order: N]` on a category to pin important categories (e.g. the 6M) to a specific rib instead of auto-alternating.",
+      "For second-level sub-causes, indent >= 2 spaces and prefix with `- `; they attach to the last Level-1 cause above them."
+    ],
+    avoid: [
+      "Don't reference a `catId :` cause before declaring that category \u2014 the parser throws `Unknown category`.",
+      'Don\'t omit `effect` \u2014 without an `effect` line the fish head falls back to the title; an explicit `effect "\u2026"` is clearer.',
+      "Don't mix compact shorthand (`category Label: cause1; cause2`) and structured `catId :` lines for the same category \u2014 the compact id is a slug of the label, so a mismatch silently creates a duplicate."
+    ],
+    repair: [
+      '\'Unknown category\' -> add `category X "Label"` before any `X : "cause"` line.',
+      "'requires at least one' -> the document has no `category` lines; add at least one `category id \"Label\"`.",
+      "'Sub-cause has no preceding Level-1 cause' -> a `- sub text` line appeared before any `catId : \"cause\"` line in that category; add a Level-1 cause above it."
+    ]
   },
   venn: {
     type: "venn",
     header: 'venn "Title"',
-    mode: "declared-set region counts",
-    forms: ['set A "Group A"', 'set B "Group B"', "A & B : 120", "A only : 80"],
-    prefer: ["Use declared sets plus region counts for first-shot Venn output.", "Use Euler relations only when subset/disjoint structure is the request."],
-    avoid: ["Avoid mixing enumeration mode with explicit region counts."],
-    repair: ["Declare every set before region or Euler relation lines."]
+    mode: "declared sets + region counts (primary); enumeration or Euler relations as alternates",
+    keywords: 'set ID "Label" [color:"#hex"] \xB7 A & B : <integer|percent%|"text"|[list]> \xB7 A only : N \xB7 region A & B : N \xB7 enumeration: ID = { item, item, \u2026 } \xB7 Euler: ID subset|disjoint|overlap ID \xB7 layout venn|euler|auto \xB7 config: proportional=true|false \xB7 config: showCounts=true|false|auto \xB7 config: showPercent=true|false',
+    forms: [
+      'venn "Customer Segments"',
+      'set email "Email subscribers" [color: "#1E88E5"]',
+      'set paid "Paid users" [color: "#E53935"]',
+      'set mobile "Mobile app users" [color: "#43A047"]',
+      "email & paid : 1840",
+      "email & mobile : 920",
+      "email & paid & mobile : 650",
+      "email only : 12400",
+      "paid only : 3200"
+    ],
+    prefer: [
+      'Declare every `set ID "Label"` before any region line that references it.',
+      "Use integer counts for research overlap, `%` values for audience overlap, and `[list]` values when each region should show enumerated items.",
+      "Use the Euler relation form (`A subset B`, `A disjoint B`) only when the structural relationship matters more than counts \u2014 it triggers Euler layout mode."
+    ],
+    avoid: [
+      "Don't mix enumeration mode (`ID = { \u2026 }`) with explicit `A & B :` region counts in the same document \u2014 enumeration auto-derives regions, so adding counts duplicates them.",
+      "Don't use a set id in a region line that was never declared with `set ID \u2026` \u2014 the parser throws `unknown set id`.",
+      "Don't add 5+ sets expecting a readable Venn \u2014 it degrades to an UpSet plot automatically; prefer Euler `disjoint`/`subset` when structure is sparse."
+    ],
+    repair: [
+      "'unknown set id' -> declare `set X \"Label\"` before the region line that uses it.",
+      "'duplicate set id' -> each set id must appear in exactly one `set` declaration; rename or remove the second.",
+      "'could not parse line' -> every non-blank, non-header line must match `set`, `region`, `A & B :`, `A only :`, `ID = { }`, a Euler relation, `layout`, or `config:`."
+    ]
   },
   flowchart: {
     type: "flowchart",
-    header: 'flowchart TD "Title"',
-    mode: "Mermaid-compatible nodes + edges",
-    forms: ["start([Start]) --> check{Decision?}", "check -->|Yes| done([Done])"],
-    prefer: ["Choose one direction in the header.", "Declare shapes explicitly when shape matters."],
-    avoid: ["Avoid subgraph complexity unless grouping is part of the request."],
-    repair: ["A bad header direction fails early; use TD, TB, BT, LR, or RL."]
+    header: "flowchart TD",
+    mode: "Mermaid-compatible nodes + edges (Mermaid prior: prefer this syntax)",
+    keywords: 'flowchart TD|TB|BT|LR|RL \xB7 nodes: A[rect] A(round) A([stadium]) A{diamond} A[/parallelogram/] A[[subroutine]] A[(cylinder)] A((circle)) A{{hexagon}} A>asymmetric] \xB7 edges: --> --- -.-> ==> --x --o --|label| -- label --> \xB7 fan-out: A & B --> C & D \xB7 subgraph "Title" \u2026 end \xB7 class A,B name \xB7 classDef name fill:\u2026 \xB7 style A fill:\u2026',
+    forms: [
+      "flowchart LR",
+      "  start([New order received])",
+      "  start --> validate{Inventory available?}",
+      "  validate -->|Yes| reserve[Reserve items]",
+      "  validate -->|No| notify[Notify customer]",
+      "  reserve --> payment{Payment authorized?}",
+      "  payment -->|Yes| ship[Ship order]",
+      "  ship --> done([End])",
+      "  notify --> done"
+    ],
+    prefer: [
+      "Use Mermaid `flowchart TD` (or `LR`) as the header \u2014 matches the dominant training prior; `graph TD` is also accepted.",
+      "Label decision branches with `-->|Yes|` / `-->|No|` pipe syntax; use `--` inline for longer edge text: `A -- approved --> B`.",
+      "Use `([\u2026])` stadium for terminals, `{\u2026}` diamond for decisions, `[\u2026]` rect for steps, `[(\u2026)]` cylinder for datastores."
+    ],
+    avoid: [
+      "Don't omit the direction token \u2014 a bare `flowchart` defaults to TB; always declare direction explicitly.",
+      "Avoid `subgraph` nesting deeper than one level in generated output; deep nesting is valid but rarely needed.",
+      "Don't use inline `:::className` syntax in generated output \u2014 use separate `class A,B name` or `classDef` statements."
+    ],
+    repair: [
+      "'expected' header -> the first non-comment line must be `flowchart TD` (or another direction); a missing or misspelled header rejects the document.",
+      "'unknown direction' -> direction must be one of TD TB BT LR RL (case-insensitive).",
+      "'expected node identifier' -> every edge must start with a valid id token; a bare `-->` without a left-hand node id is rejected."
+    ]
   },
   mindmap: {
     type: "mindmap",
     header: "mindmap",
-    mode: "Markdown headings + bullets",
-    forms: ["# Root", "## Branch", "- Child item"],
-    prefer: ["Use exactly one `#` root heading.", "Use bullets/headings instead of graph edges."],
-    avoid: ["Avoid comments in the body."],
-    repair: ["An orphan branch means the root `#` heading is missing."]
+    mode: "Markdown headings + bullets; %% directives for style/theme",
+    keywords: "# root (exactly 1) \xB7 ## H2 branch \xB7 ### deeper headings \xB7 - / * / + bullet (2-space indent = 1 depth level) \xB7 %% style: map|logic-right|futureswheel|driver \xB7 %% theme: default|monochrome|dark \xB7 %% maxLabelWidth: N \xB7 inline: **bold** *italic* `code` [text](url) [x]/[ ] checkbox",
+    forms: [
+      "mindmap",
+      "",
+      "# Product Launch Plan",
+      "",
+      "## Market readiness",
+      "- Competitive analysis",
+      "- Pricing benchmarks",
+      "",
+      "## Engineering",
+      "### Feature freeze",
+      "- Core API complete",
+      "",
+      "## Go-to-market",
+      "- Landing page live"
+    ],
+    prefer: [
+      "Open with exactly one `# Root` heading \u2014 the parser recovers a placeholder when it is missing (with a warning), but an explicit `# Title` is correct.",
+      "Use `%% style: logic-right` for outlines, the default `map` for balanced radial brainstorms, `%% style: futureswheel` for consequence mapping, `%% style: driver` for IHI diagrams.",
+      "Use 2-space indented bullets (`  - child`) to add depth under a heading without an extra `###` level \u2014 each 2-space step is one level deeper."
+    ],
+    avoid: [
+      "Don't write more than one `#` root heading \u2014 the parser throws `multiple` center nodes not allowed on the second.",
+      "Don't use graph-edge syntax (`A -> B`) inside a mindmap; the format is heading/bullet hierarchy only.",
+      "Don't place `%%` directives mid-document; they are only processed before the first heading and are otherwise ignored."
+    ],
+    repair: [
+      "'missing central topic' -> add a `# Your Topic` line as the first content line.",
+      "'multiple' center nodes not allowed -> demote all but the first `#` heading to `##` or deeper.",
+      "'no `# Title` heading found' (warning) -> the parser adopted the first line as the topic; add an explicit `# Title` at the top."
+    ]
   },
   matrix: {
     type: "matrix",
     header: 'matrix "Title"',
-    mode: "quadrant scatter",
-    forms: ["x-axis: Low -> High", "y-axis: Low -> High", '"Item" at (0.25, 0.8)'],
-    prefer: ["Use quadrant scatter for first-shot prioritization/portfolio requests.", "Use built-in templates when the framework is named."],
-    avoid: ["Avoid heatmap, correlation, and table modes unless the user asks for that form."],
-    repair: ["Point coordinates are normalized fractions; keep them in `[0,1]`."]
+    mode: "quadrant scatter (default) | named templates | heatmap | sipoc | qfd | punnett",
+    keywords: 'header variants: matrix "Title" | matrix <template> "Title" | matrix heatmap NxM | matrix correlation | matrix sipoc | matrix qfd | matrix punnett \xB7 templates: eisenhower impact-effort rice bcg ansoff johari 9-box risk-matrix \xB7 quadrant: x-axis: Low -> High \xB7 y-axis: Low -> High \xB7 "Label" at (x,y) [size:N category:C shape:circle|square|triangle|diamond] \xB7 quadrant Q1..Q4 "name" \xB7 Q1:/"Q1: text" cell shortcuts \xB7 style: table \xB7 config: offChartPolicy=clamp-badge|drop bubbleScale=area|radius',
+    forms: [
+      'matrix eisenhower "This Week"',
+      "style: table",
+      'Q2: "Ship hotfix"',
+      'Q1: "Write Q3 OKRs"',
+      'Q3: "Reorganize Slack channels"',
+      "",
+      'matrix bcg "Product Portfolio"',
+      '"Platform SDK" at (0.8, 0.8) size: 5 category: star',
+      '"Legacy API" at (0.85, 0.15) size: 4 category: cashcow'
+    ],
+    prefer: [
+      "Use a named template (`eisenhower`, `impact-effort`, `bcg`, `ansoff`, `johari`, `9-box`, `risk-matrix`, `rice`) for first-shot generation \u2014 it pre-fills axes and quadrant labels.",
+      "Add `style: table` with `Q1:`/`Q2:`/`Q3:`/`Q4:` item lines for the four-cell list layout instead of a scatter.",
+      "Quadrant scatter coordinates are normalized `[0,1]` fractions; add `size: N` for a bubble chart and `category:` to drive legend color."
+    ],
+    avoid: [
+      "Don't mix `sipoc:`/`qfd:`/`punnett:` sub-keywords in plain quadrant mode \u2014 they activate only under the matching header mode (`matrix sipoc`).",
+      "Don't set point coordinates outside `[0,1]` expecting the canvas to expand \u2014 they are clamped and badged (use `offChartPolicy: drop` to hide).",
+      "Don't use percentages or raw data values in `at (x, y)` \u2014 coordinates are fractions."
+    ],
+    repair: [
+      "A point that doesn't appear usually has coordinates outside `[0,1]` with `offChartPolicy` defaulting to `clamp-badge` \u2014 check `at (x, y)` are fractions.",
+      'An empty `qfd`/`sipoc` chart means the header was `matrix "Title"` (quadrant mode) not `matrix qfd "Title"` \u2014 add the mode keyword after `matrix`.',
+      "In `punnett` mode, a missing grid means the `cross:` line was not parsed \u2014 use even-length letter pairs (e.g. `Bb`) separated by `x`."
+    ]
   },
   orgchart: {
     type: "orgchart",
     header: 'orgchart "Title"',
-    mode: "indented hierarchy",
-    forms: ['ceo: "Name" | CEO', '  cto: "Name" | CTO', '    eng: "Name" | Engineer'],
-    prefer: ["Use indentation for the reporting tree.", "Use dotted explicit edges only for matrix reporting."],
-    avoid: ["Avoid mixing explicit report edges with indentation unless needed."],
-    repair: ["Duplicate IDs and unknown explicit edge endpoints are parse failures."]
+    mode: "indented hierarchy with pipe-separated fields; explicit edges for matrix/dotted lines",
+    keywords: 'id : "Name" | Title | Dept [props] \xB7 node kinds: person role open draft tbh advisor external \xB7 props: role(ceo|cto|cfo|coo|engineer|designer|sales|hr|legal|ops|product|data|advisor|intern|vacant) status(new|leaving|on-leave) assistant-of \xB7 edge ops: -> (report) -.-> (matrix/dotted) === (co-leaders) \xB7 config: direction=TD|LR layout=tree|list',
+    forms: [
+      'ceo: "Jamie Torres" | CEO [role: ceo]',
+      '  cto: "Raj Patel" | CTO [role: cto]',
+      '    eng1: "Priya Nair" | Eng Lead | Engineering [role: engineer]',
+      '  cfo: "Ellen Wu" | CFO [role: cfo]',
+      'advisor adv1: "Dr. Alan Ford" | Board Advisor [role: advisor]',
+      "pm_core -.-> lead_core"
+    ],
+    prefer: [
+      'Use 2-space indentation per level for the reporting tree \u2014 this is the implicit `->` edge. Fields are `id : "Name" | Title | Department`, pipe-separated.',
+      "Use node-kind prefixes `role`/`open` for vacant positions (dashed yellow + HIRING pill), `draft`/`tbh` for planned roles, `advisor`/`external` for contractors.",
+      "Add `[role: ceo]` (cto/cfo/engineer/designer/sales/hr/legal/ops/product/data/advisor/intern/vacant, case-insensitive) for the built-in role icon; draw dotted matrix lines as explicit `a -.-> b` edges."
+    ],
+    avoid: [
+      "Don't mix indentation hierarchy with an explicit `->` edge on the same parent\u2013child pair \u2014 only one is needed; both duplicate the report edge.",
+      'Don\'t omit the colon in node lines (`id : "Name"`); a line without a colon is silently skipped with a warning.',
+      "Don't reuse an id \u2014 the duplicate is dropped silently, losing its name/title."
+    ],
+    repair: [
+      "'skipped a line that is neither a node nor an edge' -> the line is missing a colon; rewrite as `id : \"Name\" | Title`.",
+      "'kept the first declaration of duplicate node id' -> each person needs a unique id; rename the second declaration.",
+      "'created node(s) from edges that were never declared' -> declare `x : \"Name\" | Title` so the card renders a real label instead of the bare id."
+    ]
   },
   decisiontree: {
     type: "decisiontree",
     header: 'decisiontree "Title"',
-    mode: "taxonomy questions",
-    forms: ['question "Question?"', '  yes: answer "Outcome"', '  no: answer "Other outcome"'],
-    prefer: ["Use taxonomy mode for troubleshooting and triage.", "Select `decisiontree:decision` or `decisiontree:ml` only when expected value or ML is explicit."],
-    avoid: ["Avoid mixing mode-specific keywords."],
-    repair: ["Indent each child under its parent and use the branch prefix required by the selected mode."]
+    mode: "taxonomy (default) | decision | ml | influence \u2014 select via header suffix",
+    keywords: 'header: decisiontree[:decision|:ml|:influence] "Title" \xB7 config: direction=top-down|left-right \xB7 taxonomy: question/q "\u2026" \xB7 answer/a/leaf "\u2026" \xB7 branch prefixes yes: no: label "X": \xB7 decision mode: decision chance end/outcome \xB7 choice "label" prob N \xB7 payoff=N \xB7 ml mode: split "\u2026" feature=F threshold=V gini/entropy/mse=N value=[N,\u2026] class=C \xB7 influence mode: decision chance value nodes + directed arcs',
+    forms: [
+      'decisiontree "Customer Support Triage"',
+      "direction: top-down",
+      "",
+      'question "Is the service completely down?"',
+      '  yes: question "Outage confirmed on status page?"',
+      '    yes: answer "Follow incident protocol \u2014 page on-call"',
+      '    no: answer "Check monitoring \u2014 open severity-1 ticket"',
+      '  no: answer "Escalate to billing team"'
+    ],
+    prefer: [
+      "Default mode is `taxonomy` \u2014 use `question`/`answer` (or `q`/`a`) with `yes:`/`no:` branch prefixes and 2-space indentation.",
+      'For decision analysis use `decisiontree:decision`; nodes are `decision` (square), `chance` (circle), `end` (triangle); label choices with `choice "label"` and probabilities with `prob N` on chance children; `payoff=N` on `end` nodes.',
+      "For ML visualization use `decisiontree:ml`; split nodes carry `feature=`/`threshold=`/`gini=`; leaves carry `value=[N,\u2026]` plus optional `class=`."
+    ],
+    avoid: [
+      "Don't use `decision`/`chance`/`end` in taxonomy mode \u2014 they throw `Unknown taxonomy node kind`.",
+      "Don't use `question`/`answer` in `:ml` mode \u2014 they throw `Unknown ML node kind`.",
+      "Don't let a chance node's `prob` children sum to anything but 1 \u2014 the parser throws `probabilities do not sum to 1.0`."
+    ],
+    repair: [
+      "'Unknown node kind' -> valid decision-mode kinds are `decision`, `chance`, `end`, `outcome`; switch mode or fix the keyword.",
+      "'Unknown taxonomy node kind' -> valid taxonomy kinds are `question`/`q` and `answer`/`a`/`leaf`.",
+      "'probabilities do not sum to 1.0' -> the `prob N` values on a chance node's children must add to exactly 1.0.",
+      "'Orphan line (bad indent)' -> every non-root node must be indented at least 2 spaces under its parent."
+    ]
   },
   timeline: {
     type: "timeline",
     header: 'timeline "Title"',
-    mode: "dated events",
-    forms: ['2026-05-22: "Event"', '2026-06-01 - 2026-06-30: "Phase"', '2026-07-01: milestone "Launch"'],
-    prefer: ["Use dated events/ranges and `milestone` for important points."],
-    avoid: ["Avoid custom row keys when a date is known."],
-    repair: ["Quote labels and keep the colon after the date/range."]
+    mode: "dated events on a time axis \u2014 swimlane (default), gantt, or lollipop styles",
+    keywords: 'DATE: "label" \xB7 DATE - DATE: "label" (range) \xB7 DATE: milestone "label" \xB7 era DATE - DATE: "label" \xB7 track "Name": / section Name (lanes) \xB7 config: style=swimlane|gantt|lollipop orientation=horizontal|vertical scale=proportional|equidistant|log \xB7 point props [side:above|below shape:circle|square|diamond|star|flag color:#hex category:\u2026] \xB7 dates: YYYY YYYY-MM YYYY-MM-DD, BC years, ordinal keys (Phase 1, Q1 2024)',
+    forms: [
+      'timeline "Platform v2 Launch"',
+      "config: style = gantt",
+      "",
+      '2025-07-01 - 2025-08-15: "Engineering build" [category: "engineering"]',
+      '2025-08-20: milestone "Feature freeze" [color: #E53935]',
+      '2025-09-15: milestone "Public launch" [color: #2E7D32]'
+    ],
+    prefer: [
+      "Use ISO dates (`YYYY-MM-DD`/`YYYY-MM`/`YYYY`) for the row key for proportional layout; for non-date groupings (Phase 1, Q1 2024) use an ordinal key placed in declaration order.",
+      "Use `config: style = gantt` for roadmaps (overlapping bars), `lollipop` for milestone stories, default `swimlane` for multi-track streams.",
+      'Use `milestone` before the quoted label for diamond headline events; group events with `track "Name":` or Mermaid `section Name`; add era bands with `era START - END: "label"`.'
+    ],
+    avoid: [
+      "Don't omit the colon after the date/range \u2014 `Expected ':' after date` is thrown when no colon separator is found.",
+      "Don't use `config: style = X` with a value other than `swimlane`, `gantt`, `lollipop` \u2014 throws `Invalid style`.",
+      "Don't write `era` with a single date instead of a range \u2014 throws `era requires a date range`."
+    ],
+    repair: [
+      "'Unrecognized line' -> an event line must be a date/range, then `:`, then a quoted label (optionally preceded by `milestone`).",
+      "'Invalid style' -> valid `config: style` values are `swimlane`, `gantt`, `lollipop`.",
+      "'era requires a date range' -> write `era 2020 - 2025: \"label\"` (two dates separated by ` - `)."
+    ]
   },
   state: {
     type: "state",
     header: "stateDiagram-v2",
-    mode: "Mermaid stateDiagram-v2 (recommended for generation)",
+    mode: "Mermaid stateDiagram-v2 (recommended; native 'state' header also accepted)",
+    keywords: 'stateDiagram-v2 (or state "Title" [direction: LR]) \xB7 [*] --> S / S --> [*] \xB7 S --> T : trigger [guard] / action \xB7 state "Long name" as ID \xB7 state ID <<choice>> | <<fork>> | <<join>> | <<end>> \xB7 composite state ID { \u2026 } with -- for concurrent regions \xB7 note right_of X : text \xB7 direction TB|LR \xB7 native pseudo-states: initial final choice junction fork join history dhistory terminate entry_point exit_point',
     forms: [
-      "[*] --> Idle",
-      "Idle --> Running : start",
-      "Running --> Done : finish",
-      "Done --> [*]"
+      "stateDiagram-v2",
+      "  [*] --> Idle",
+      "  Idle --> Running : start",
+      "  Running --> Paused : pause",
+      "  Paused --> Running : resume",
+      "  Running --> Done : finish",
+      "  Done --> [*]"
     ],
     prefer: [
-      "Use Mermaid `stateDiagram-v2` syntax: `[*]` for the start/end pseudo-states, `-->` for transitions, `: label` for the event/guard.",
-      'This matches the most common training data, so prefer it over the native `state "Title"` + `initial`/`final` form (which is also accepted).'
+      'Use Mermaid `stateDiagram-v2` with `[*]` for initial/final pseudo-states and `-->` for transitions \u2014 matches the dominant training prior and is less error-prone than the native `state "Title"` + `initial`/`final` form.',
+      "Write transition labels as `: trigger [guard] / action` \u2014 all three segments optional, but the colon is required if any label follows the arrow.",
+      "For composite states use `state ID { \u2026 }` (Mermaid) or `composite ID { \u2026 }` (native); separate concurrent regions with `--` inside the block."
     ],
     avoid: [
-      "Avoid composite/concurrent-state syntax until the request needs it.",
-      "Do not mix the two styles in one file (e.g. `[*]` together with `initial X`); pick `[*]`."
+      "Don't mix the two header styles \u2014 `[*]` (Mermaid) and `initial X` (native) are both accepted but must not appear together.",
+      "Don't invent pseudo-state kinds \u2014 valid are `initial`/`final`/`choice`/`junction`/`fork`/`join`/`history`/`dhistory`/`terminate`/`entry_point`/`exit_point` and `<<choice>>`/`<<fork>>`/`<<join>>`/`<<end>>`.",
+      "Don't leave a composite `{` block unclosed \u2014 an unclosed brace is a hard parse error."
     ],
     repair: [
-      "Every transition uses `-->`; place at least one named state between a `[*]` start and a `[*]` end.",
-      'If the header is rejected, use exactly `stateDiagram-v2` (or `state "Title"`).'
+      "'Expected' header -> the first non-comment line must be `stateDiagram-v2`, `stateDiagram`, or `state`.",
+      "'Unparseable line' -> check for an unsupported pseudo-state keyword, a missing `-->` arrow, or a line that is neither a transition, declaration, nor directive.",
+      "'Unclosed composite block' -> every `state ID {` or `composite ID {` must be closed with a matching `}`."
     ]
   },
   pid: {
     type: "pid",
     header: 'pid "Title"',
-    mode: "equipment + process lines",
+    mode: "equipment + process/signal lines + instrument declarations",
+    keywords: 'pid "title" [direction: LR|TB] \xB7 equip ID : type [tag:"\u2026"] \xB7 line ID from A[.port] to B[.port] [type: process|process_minor|pneumatic|electric|hydraulic|capillary|software|mechanical, size:"\u2026", service:"\u2026"] \xB7 inst TAG : category + indented measures EQUIP_OR_LINE / controls EQUIP \xB7 equipment: tank_atm tank_cone_roof vessel_v vessel_h sphere column_tray column_packed hx_shell_tube hx_air_cooled reboiler condenser pump_centrifugal pump_pd compressor blower reactor_cstr reactor_pfr filter cyclone flare cooling_tower valve_gate valve_ball valve_globe valve_butterfly valve_check valve_control valve_psv \xB7 instrument categories: field_discrete field_shared field_computer field_plc cr_discrete cr_shared cr_computer cr_plc local_discrete local_shared',
     forms: [
-      "equip T-101 : tank_atm",
-      "equip P-101 : pump_centrifugal",
-      "line L1 from T-101.bottom to P-101.in",
-      "inst FIC-201 : cr_shared"
+      'pid "Water Pump Flow Control"',
+      'equip T-101 : tank_atm [tag: "Feed Tank"]',
+      'equip P-101 : pump_centrifugal [tag: "Feed Pump"]',
+      "equip V-101 : valve_control",
+      'line L1 from T-101.bottom to P-101.in [service: "water", type: "process"]',
+      'line L2 from P-101.out to V-101.in [type: "process"]',
+      "inst FT-101 : field_discrete",
+      "  measures L2",
+      "inst FIC-101 : cr_shared",
+      "  controls V-101",
+      'line s1 from FT-101 to FIC-101 [type: "electric"]',
+      'line s2 from FIC-101 to V-101 [type: "pneumatic"]'
     ],
     prefer: [
-      "Declare equipment first (`equip ID : type [attrs]`), then process/signal lines, then instruments (`inst TAG : category`).",
-      "Use only these canonical equipment types: tanks/vessels tank_atm, tank_cone_roof, vessel_v, vessel_h, sphere; columns column_tray, column_packed; heat transfer hx_shell_tube, hx_air_cooled, reboiler, condenser; rotating pump_centrifugal, pump_pd, compressor, blower; reactors reactor_cstr, reactor_pfr; misc filter, cyclone, flare, cooling_tower; valves valve_gate, valve_ball, valve_globe, valve_butterfly, valve_check, valve_control, valve_psv.",
-      "Instrument categories: field_discrete, field_shared, field_computer, field_plc, cr_discrete, cr_shared, cr_computer, cr_plc, local_discrete, local_shared. Line types (`[type: \u2026]`): process, process_minor, pneumatic, electric, hydraulic, capillary, software, mechanical."
+      "Declare `equip` first, then `line` connections, then `inst` bubbles. Use ISA tag conventions (`FT-101` flow transmitter, `FIC-101` flow indicating controller).",
+      "Use the indented `measures LINE_OR_EQUIP` and `controls EQUIP` continuations under an `inst` to declare loop membership.",
+      "Use canonical `[type: \u2026]` line types: `electric` for transmitter->controller, `pneumatic` for controller->control-valve, `software` for DCS/PLC bus."
+    ],
+    avoid: [
+      "Avoid SLD electrical nodes (`transformer`, `breaker`, `bus`) inside a P&ID \u2014 use `sld` for electrical single-lines.",
+      "Don't invent equipment types; an unrecognised type renders as a flagged placeholder (use `hx_shell_tube` not `heat_exchanger`, `vessel_h` not `vessel_horizontal`, `reactor_cstr` not `cstr`).",
+      "Don't omit `[type: electric]` on a transmitter->controller line or `[type: pneumatic]` on a controller->control-valve line \u2014 both default to `process` pipe with a warning."
     ],
-    avoid: ["Avoid SLD electrical nodes (transformer, breaker) in a P&ID."],
-    repair: ["An unrecognised equipment type renders as a flagged `?` placeholder; pick the closest canonical type from the list above (e.g. exchanger/heat_exchanger\u2192hx_shell_tube, vessel_horizontal\u2192vessel_h, cstr\u2192reactor_cstr)."]
+    repair: [
+      "'Unparseable line' -> every body line must start with `equip`, `line`, `inst`, `measures`, or `controls`.",
+      "'unrecognised type' -> replace the unknown equipment type with a catalog type (exchanger->hx_shell_tube, vessel_horizontal->vessel_h, cstr->reactor_cstr).",
+      "'no signal path to a controller' -> add a signal line from the transmitter to a controller (C in the tag, e.g. FIC), or add the `controls` continuation under the controller."
+    ]
   },
   erd: {
     type: "erd",
     header: "erDiagram",
     mode: "Mermaid erDiagram (recommended for generation)",
+    keywords: 'erDiagram (Mermaid) \xB7 ENTITY { type name PK|FK|UK } \xB7 A ||--o{ B : label \xB7 glyphs: || one-mandatory \xB7 |o/o| zero-or-one \xB7 }|/|{ one-many \xB7 }o/o{ zero-many \xB7 erd (native) \xB7 table NAME { name type PK|FK|UK|NN } \xB7 ref A <card> -- <card> B : "label" \xB7 named cards: one-mandatory one-optional many-mandatory many-optional \xB7 notation: crowsfoot (v0.1) \xB7 direction: LR|TB',
     forms: [
       "CUSTOMER ||--o{ ORDER : places",
       "ORDER {",
@@ -3912,83 +4470,284 @@ var PROFILES = {
       "}"
     ],
     prefer: [
-      "Use Mermaid `erDiagram` syntax: relationships `A <card>--<card> B : label` with crow's-foot glyphs (`||` one, `o{` zero-or-many, `|{` one-or-many, `|o` zero-or-one); entity blocks `NAME { type name KEY }` with attributes **type-first** and KEY \u2208 PK/FK/UK.",
-      "Entities are auto-created from relationships; you only need a `{ \u2026 }` block to list attributes.",
-      "This matches the dominant training-data prior. The native `erd` header with `table NAME { name type PK }` + `ref \u2026 many-mandatory -- one-mandatory \u2026` is also accepted."
+      "Use the Mermaid `erDiagram` header; entities auto-create from relationship lines and only need a `{ \u2026 }` block to list attributes.",
+      "Attributes are type-first under `erDiagram`: `int id PK`, `varchar email UK` \u2014 never name-first.",
+      "Relationship syntax is `A <left-glyph>--<right-glyph> B : label`; use `||--o{` for one-to-many-optional, `||--|{` for one-to-many-mandatory."
+    ],
+    avoid: [
+      "Do not mix header styles: under `erDiagram` attrs are type-first; under native `erd` they are name-first with `table` blocks and `ref` lines.",
+      "Do not write `notation: chen` or `notation: barker` \u2014 only `crowsfoot` is implemented in v0.1.",
+      "Do not invent glyph pairs; left glyphs are `||` `|o` `}o` `}|`, right glyphs are `||` `o|` `o{` `|{`."
     ],
-    avoid: ["Do not mix the two header styles; under `erDiagram`, attributes are type-first (`int id PK`), not name-first."],
     repair: [
-      "Crow's-foot glyph pairs must be valid (`||`, `|o`, `}o`, `}|` on the left; `||`, `o|`, `o{`, `|{` on the right).",
-      "If the header is rejected, use exactly `erDiagram` (or native `erd`)."
+      "'Invalid Mermaid cardinality glyph' -> the left glyph must be `||`/`|o`/`}o`/`}|` and the right `||`/`o|`/`o{`/`|{`; fix the pair.",
+      "'Unrecognized erDiagram line' -> only relationship lines, entity blocks (`NAME {`), and `}` are valid under `erDiagram`; remove native `table`/`ref` lines.",
+      "'not yet implemented in v0.1; use' -> drop the `notation:` line or set `notation: crowsfoot`."
     ]
   },
   breadboard: {
     type: "breadboard",
     header: "breadboard",
-    mode: "parts + wires blocks",
-    forms: ['title: "Prototype"', "parts", "wires"],
-    prefer: ["Use physical parts and addressable tie points.", "Keep schematic tasks on `circuit` instead."],
-    avoid: ["Avoid abstract netlist syntax in breadboard output."],
-    repair: ["Missing parts or invalid breadboard connection endpoints need the breadboard syntax reference."]
+    mode: "parts section + wires section; breadboard-native hole/rail coordinates",
+    keywords: 'breadboard \xB7 board: mini|half|full \xB7 title: "\u2026" \xB7 parts section: id: KIND [args] @placement \xB7 wire kinds: resistor led cap-elec cap-ceramic diode button dip header \xB7 mcu uno|nano|esp32|pico \xB7 sensor hcsr04|dht11|dht22 \xB7 display oled-ssd1306|lcd-1602-i2c \xB7 actuator servo-sg90 \xB7 placement: @5e (hole) @5e..9e (span) @+t8 @-t8 @+b14 @-b14 (rails) @beside-left @beside-right @above @below \xB7 wires section: ep --color-- ep [via @coord] \xB7 colors: red black blue yellow orange green white purple brown grey \xB7 endpoints: @coord or partId:pin',
+    forms: [
+      "breadboard",
+      "board: half",
+      'title: "Blink LED \u2014 Arduino Uno"',
+      "parts",
+      "  uno: mcu uno @beside-left",
+      "  r1:  resistor 220 @5e..9e",
+      "  d1:  led red @10e..10f",
+      "wires",
+      "  uno:5V  --red--    @+t1",
+      "  uno:GND --black--  @-t1",
+      "  uno:D13 --yellow-- @9a"
+    ],
+    prefer: [
+      "Declare every part in the `parts` section before referencing it in `wires`; the part `id` is what you use as `partId:pin` in wire endpoints.",
+      "Use breadboard-native coordinates: `@5e` for hole column 5 row e, `@5e..9e` for a span, `@+t8`/`@-t8` for top positive/negative rail.",
+      "Wire color carries convention \u2014 `red` for +V, `black`/`blue` for GND, signal colors (`yellow`, `orange`, `green`) for data; all wire lines are `ep --color-- ep`."
+    ],
+    avoid: [
+      "Don't use rail coordinates (`@+t8`) on a `board: mini` \u2014 mini boards have no power rails and the parser throws `Mini boards have no power rails`.",
+      "Don't omit the `@` placement from a part \u2014 `missing placement` is thrown when the `@` token is absent.",
+      "Don't reference a part id in wires that was not declared in the parts section \u2014 `Wire references unknown part` fails validation."
+    ],
+    repair: [
+      "'Unknown board' -> set `board:` to `mini`, `half`, or `full`.",
+      "'Unknown part kind' -> use a supported kind (`resistor` `led` `cap-elec` `diode` `button` `dip` `header`) or a compound (`mcu uno`, `sensor hcsr04`, `display oled-ssd1306`).",
+      "'Wire references unknown part' -> add `X: KIND @placement` to the `parts` section before `wires`."
+    ]
   },
   bpmn: {
     type: "bpmn",
     header: "bpmn",
-    mode: "pool/lane objects + flows",
-    forms: ['pool "Service" {', '  lane "Worker" { A: start "Request" }', "flows", "A --> B"],
-    prefer: ["Use pools, lanes, and a `flows` block.", "Use `~~>` only for cross-pool message flow."],
-    avoid: ["Avoid generic flowchart syntax for BPMN semantics."],
-    repair: ["Sequence flows cannot cross pools; switch to message flow when needed."]
+    mode: "pool/lane declarations + flow objects + flows block",
+    keywords: 'bpmn [direction: LR|TB] [title: "\u2026"] \xB7 pool "Label" { \u2026 } \xB7 pool "Label" blackbox \xB7 lane "Label" { \u2026 } \xB7 id: start|intermediate|end [message|timer] ["label"] \xB7 id: task [user|service|send|receive|manual|script] "label" \xB7 id: subprocess "label" [collapsed] \xB7 id: gateway xor|or|and|event ["label"] \xB7 flows \xB7 A --> B (sequence) \xB7 G --? "cond" --> B (conditional) \xB7 G --* "default" --> B (default) \xB7 "Pool" ~~> id : "label" (message flow)',
+    forms: [
+      "bpmn",
+      "direction: LR",
+      'title: "Loan Application Approval"',
+      'pool "Bank" {',
+      '  lane "Clerk" {',
+      '    A: start "Application received"',
+      '    B: task user "Check completeness"',
+      '    G1: gateway xor "Complete?"',
+      "  }",
+      '  lane "Underwriter" {',
+      '    C: task service "Risk score"',
+      '    E: end "Approved"',
+      '    F: end "Rejected"',
+      "  }",
+      "}",
+      "flows",
+      "A --> B",
+      "B --> G1",
+      'G1 --? "yes" --> C',
+      'G1 --* "no" --> F',
+      "C --> E"
+    ],
+    prefer: [
+      'Declare flow objects inside `lane "Label" { id: kind \u2026 }` nested in `pool "Label" { \u2026 }`. The `id:` prefix before the keyword is required; labels must be quoted.',
+      "Event kinds `start`/`intermediate`/`end` with optional trigger `message`/`timer`; task markers `user`/`service`/`send`/`receive`/`manual`/`script`; gateway kinds `xor`/`or`/`and`/`event`.",
+      "Put all flows in a single `flows` block. Sequence flow `-->` stays inside one pool; use `~~>` only for cross-pool message flow; `--?` is a conditional branch with one `--*` default per gateway."
+    ],
+    avoid: [
+      "Don't use `-->` across pool boundaries \u2014 it is rejected with `crosses pool boundary \u2014 use message flow`.",
+      "Don't add lanes or tasks inside a `blackbox` pool \u2014 rejected with `black-box pool` cannot contain flow objects.",
+      "Don't give a `task` without a quoted label, and don't put more than one `--*` default flow on the same gateway."
+    ],
+    repair: [
+      "'crosses pool boundary \u2014 use message flow' -> replace `-->` with `~~>` and ensure source/target are in different pools.",
+      "'unknown flow-object kind' -> the word after `id:` must be `start`, `end`, `intermediate`, `task`, `subprocess`, or `gateway`.",
+      "'kind must be xor / or / and / event' -> a gateway declaration needs one of those four kinds after the `gateway` keyword."
+    ]
   },
   fbd: {
     type: "fbd",
     header: 'fbd "Title"',
-    mode: "networks + blocks",
-    forms: ["var Start: bool", 'network "Logic":', "Motor = AND(Start, Safe)"],
-    prefer: ["Use network/expression forms from the FBD syntax guide."],
-    avoid: ["Avoid ladder rung syntax in FBD output."],
-    repair: ["Invalid block calls need a supported block and valid arguments."]
+    mode: "variable declarations + numbered networks of indented assignment statements",
+    keywords: 'var NAME: TYPE [= init] \xB7 scopes: var var_input var_output var_in_out var_global var_external \xB7 types: bool int dint uint real lreal time string byte word dword timer counter \xB7 network [N] ["title"]: \xB7 Inst = BLOCK(args) \xB7 negation: ~varName \xB7 named args: PORT: value \xB7 nested: BLOCK(BLOCK(\u2026)) \xB7 port ref: Inst.PORT \xB7 boolean: AND OR NOT NAND NOR XOR XNOR BUF \xB7 edge: R_TRIG F_TRIG \xB7 bistable: SR RS \xB7 timers: TON TOF TP \xB7 counters: CTU CTD \xB7 math: ADD SUB MUL DIV MOD ABS NEG MOVE \xB7 compare: EQ NE GT GE LT LE \xB7 select: SEL MUX MAX MIN LIMIT',
+    forms: [
+      'fbd "Motor Control"',
+      "var Start: bool",
+      "var Stop: bool",
+      "var MotorOut: bool",
+      "var Latch: bool",
+      'network 0 "Start latch":',
+      "  Latch = OR(Start, AND(Latch, ~Stop))",
+      'network 1 "Drive output":',
+      "  MotorOut = MOVE(Latch)"
+    ],
+    prefer: [
+      "Declare variables with `var NAME: TYPE` before any `network` line; use `~varName` on an input to place a negation bubble inline instead of a `NOT` block.",
+      'Each `network [N] ["title"]:` header is followed by indented `Inst = BLOCK(args)` body lines until the next `network`.',
+      "Variadic blocks (`AND`, `OR`, `ADD`, `MUL`, `MAX`, `MIN`) accept any number of positional args and expand `IN1..INn` automatically."
+    ],
+    avoid: [
+      "Don't use ladder element names (`XIC`, `OTE`, ladder-style `TON`) inside FBD networks \u2014 they are not valid FBD blocks.",
+      "Don't reference an instance port (`Inst.PORT`) before that instance is assigned in the same network.",
+      "Don't use ladder comparison aliases \u2014 FBD uses `EQ NE GT GE LT LE`, not `EQU NEQ GRT LES GEQ LEQ`."
+    ],
+    repair: [
+      "'Unknown function block' -> replace with the closest IEC standard block (e.g. `EQUAL` -> `EQ`, `GREATER` -> `GT`, `TIMER_ON` -> `TON`).",
+      "'Duplicate instance name' -> each `Inst =` assignment in a program must use a unique left-hand name.",
+      "'Unrecognized network statement' -> the line must match `Inst = BLOCK(args)` or a bare `BLOCK(args)`; check for missing parentheses.",
+      "'Too many positional arguments' -> drop excess args or switch to named-port form `PORT: value`."
+    ]
   },
   sfc: {
     type: "sfc",
     header: 'sfc "Title"',
-    mode: "steps + transitions",
-    forms: ["step Idle [initial]", "transition Idle -> Run : Start", "step Run"],
-    prefer: ["Use explicit steps and transitions before alternative/simultaneous branches."],
-    avoid: ["Avoid UML state syntax in SFC output."],
-    repair: ["Every transition step reference must resolve to a declared step."]
+    mode: "steps with indented actions + from:/to: transitions",
+    keywords: 'step ID [initial|final|label:"\u2026"] \xB7 var NAME: TYPE \xB7 transition [id] from: A to: B: COND \xB7 jump from: A to: B \xB7 alt from: STEP: / sim from: STEP: COND with branch [priority:N]: + merge_to: STEP[: COND] \xB7 action line \xABQUAL Name [T#\u2026]\xBB | qualifiers: N S R L D P P0 P1 SD DS SL (L/D/SD/DS/SL need T#\u2026) | var types: bool int real time timer counter',
+    forms: [
+      "step S0 [initial]",
+      "  N FillValve_Closed",
+      'step S1 [label: "Filling"]',
+      "  N FillValve_Open",
+      "transition from: S0 to: S1: StartBtn",
+      "transition from: S1 to: S0: TankLevel >= 80.0"
+    ],
+    prefer: [
+      'Declare each `step ID [initial|final|label: "\u2026"]` first; put actions on indented lines under the step as `<QUAL> ActionName`.',
+      "Wire steps with `transition from: A to: B: CONDITION` \u2014 the condition is free text (e.g. `TankLevel >= 80.0`), stored verbatim, never evaluated.",
+      "Qualifiers are N S R L D P P0 P1 SD DS SL; the timed ones take a literal, e.g. `D Oven_Run T#15m`, `L Cooler_On T#5m`.",
+      "Concurrency: `sim from: STEP: COND` + `branch:` blocks + `merge_to: STEP: COND`. Choice: `alt from: STEP:` + `branch [priority: N]:` (each with `transition: COND`) + `merge_to: STEP`."
+    ],
+    avoid: [
+      "Don't use arrow transitions like `S0 -> S1 : cond` \u2014 SFC only accepts `transition from: S0 to: S1: cond` (a bare arrow line is rejected as 'Unrecognized SFC line').",
+      "Avoid a second `[initial]` step; if none is marked, the first declared step is promoted automatically.",
+      "Don't invent qualifiers \u2014 only N/S/R/L/D/P/P0/P1/SD/DS/SL are valid, and L/D/SD/DS/SL need a `T#\u2026` time literal."
+    ],
+    repair: [
+      "'Transition references unknown step: X' -> declare `step X` (or fix the id) before any transition that names it.",
+      "'Multiple [initial] steps: A and B' -> mark only one step `[initial]`.",
+      "'Unrecognized SFC line: \u2026' -> a transition must be `transition from: A to: B: cond`; an action line must start with a qualifier and sit indented under its step.",
+      "'sim block missing merge_to clause' -> end the branch block with `merge_to: STEP: CONDITION` (alt uses `merge_to: STEP`)."
+    ]
   },
   prisma: {
     type: "prisma",
     header: "prisma",
-    mode: "PRISMA 2020 single pipeline",
-    forms: ["identification:", "  databases:", "    n: 1000", "screening:", "included:"],
-    prefer: ["Use the required four stages and mandatory counts.", "Use single-pipeline 2020 mode unless other-methods data is present."],
-    avoid: ["Avoid generic flowchart boxes for PRISMA requests."],
-    repair: ["Missing stage blocks or mandatory `n` fields are intentional parser errors."]
+    mode: "indentation-structured PRISMA 2020 flow diagram (2-space indent)",
+    keywords: "prisma \xB7 mode: 2020-single|2020-dual|2009 \xB7 kind: systematic-review|scoping-review|ipd|nma \xB7 validate-counts: strict|warn|off \xB7 stages: previous-studies \xB7 identification: -> databases: (n: sources: duplicates-removed:) [other: (n:)] \xB7 screening: -> records-screened: excluded: (n: reasons: name=count,\u2026) \xB7 eligibility: -> full-text-assessed: excluded: (n: reasons:) \xB7 included: -> studies: [reports:]",
+    forms: [
+      "prisma",
+      "mode: 2020-single",
+      "title: Exercise for chronic low-back pain \u2014 SR",
+      "",
+      "identification:",
+      "  databases:",
+      "    n: 1418",
+      "    sources: PubMed=600, Embase=450, Cochrane=184, Web of Science=184",
+      "    duplicates-removed: 318",
+      "",
+      "screening:",
+      "  records-screened: 1100",
+      "  excluded:",
+      "    n: 870",
+      "    reasons: irrelevant title=750, non-English=120",
+      "",
+      "eligibility:",
+      "  full-text-assessed: 230",
+      "  excluded:",
+      "    n: 195",
+      "    reasons: wrong population=80, wrong intervention=60, wrong outcome=55",
+      "",
+      "included:",
+      "  studies: 35"
+    ],
+    prefer: [
+      "All four stages `identification:`, `screening:`, `eligibility:`, `included:` are required \u2014 the parser throws if any is missing.",
+      "Use 2-space indentation per level: stage keys at indent 0, sub-keys at indent 1, sub-sub-keys at indent 2.",
+      "Put reason breakdowns as `name=count` pairs on one `reasons:` line; for dual-pipeline add an `other:` block under `identification:` (auto-switches to 2020-dual)."
+    ],
+    avoid: [
+      "Don't write free-form stage keys \u2014 only `previous-studies`, `identification`, `screening`, `eligibility`, `included` are valid at the top level.",
+      "Don't omit `n:` inside any stage block \u2014 it is required.",
+      "Don't malform `reasons:` \u2014 pairs must be `name=count`; a missing `=` is an error."
+    ],
+    repair: [
+      "'required stage' is missing -> add the missing stage block (`identification:` needs a nested `databases:` with at least `n:`).",
+      "'is missing required' field -> add the required sub-key (e.g. `n:`, or an `excluded:` block under `screening:`).",
+      "'sources sum to' N but n = M -> make the `sources:` counts add up to the `n:` value, or remove `sources:`.",
+      "'unknown stage' -> valid top-level keys are `previous-studies`, `identification`, `screening`, `eligibility`, `included`."
+    ]
   },
   usecase: {
     type: "usecase",
     header: "usecase",
-    mode: "declarative UML use cases",
-    forms: ['system: "System"', "actor: Customer", 'usecase: "Checkout" as Checkout', "Customer -- Checkout"],
-    prefer: ["Use declarative actor/usecase lines for generated DSL."],
-    avoid: ["Avoid PlantUML inline form unless converting PlantUML-like input."],
-    repair: ["Include/extend relations must connect use cases, not actors."]
+    mode: "declarative actor/usecase declarations + typed relationship lines",
+    keywords: 'usecase \xB7 title: "\u2026" \xB7 system: "\u2026" \xB7 direction: LR|TB \xB7 actor: Name [as ID] [(external|business|system)] [(left|right)] \xB7 usecase: "Name" [as ID] [\xABstereotype\xBB] [{ extension point: name }] \xB7 relations: -- association \xB7 --> directed \xB7 ..> include \xB7 <.. extend \xB7 --|> generalization \xB7 multiplicity: "1" "0..*" \xB7 note "label" { id, id } \xB7 PlantUML inline: :Name: (Name)',
+    forms: [
+      "usecase",
+      'title: "ATM"',
+      'system: "ATM System"',
+      "actor: Customer",
+      "actor: Bank (external)",
+      'usecase: "Withdraw Cash" as Withdraw',
+      'usecase: "Check Balance" as Check',
+      "Customer -- Withdraw",
+      "Customer -- Check",
+      "Withdraw -- Bank"
+    ],
+    prefer: [
+      "Declare all `actor:` and `usecase:` lines before relationship lines \u2014 an unknown id on a relation is a hard error.",
+      "Use `actor: Name (external)` for system actors (rectangle), `(business)` for in-org actors, bare for stick figures; add `(left)`/`(right)` to pin placement.",
+      "Use `..>` for \xABinclude\xBB (arrow points to the included use case) and `<..` for \xABextend\xBB (arrow points to the base) \u2014 the directions are opposite and both enforced."
+    ],
+    avoid: [
+      "Don't use `--` between two actors, or `..>`/`<..` involving an actor \u2014 both are hard errors.",
+      "Don't use `--|>` between an actor and a use case \u2014 generalization must be actor\u2194actor or usecase\u2194usecase.",
+      "Don't skip the `as ID` alias when reusing a multi-word name in relationships \u2014 the auto-id replaces spaces with underscores."
+    ],
+    repair: [
+      "'unknown identifier' -> declare `actor: X` or `usecase: \"X\" as X` before the relation line that references it.",
+      "'must connect an actor and a use case' -> use `--|>` for actor generalization, not `--`.",
+      "'endpoints must be use cases' -> both sides of `..>`/`<..` must be use cases, not actors.",
+      "'first non-comment line must start with' -> the document must open with the bare keyword `usecase`."
+    ]
   },
   pert: {
     type: "pert",
     header: "pert",
-    mode: "AON tasks + dependencies",
-    forms: ['task A "Spec" duration: 3', 'task B "Build" duration: 8 after: A'],
-    prefer: ["Use AON network tasks first.", "Use time-scaled/AOA layouts only when requested."],
-    avoid: ["Avoid writing computed ES/EF/LS/LF fields yourself."],
-    repair: ["Task IDs must exist before they are used in `after:` lists."]
+    mode: "AON tasks with computed schedule (ES/EF/LS/LF/slack/critical path)",
+    keywords: 'pert \xB7 title: "\u2026" \xB7 unit: days|weeks|hours|abstract \xB7 direction: LR|TB \xB7 layout: network|timescaled|aoa \xB7 critical-tolerance: N \xB7 task ID "label" duration: N|O/M/P [after: ref,\u2026] [milestone] [lane: "Name"] \xB7 dependency refs: ID (FS) \xB7 ID FS|SS|FF|SF[+N|-N][d|w|h] \xB7 ID+N (FS lag sugar)',
+    forms: [
+      "pert",
+      'title: "Q3 Product Launch"',
+      "unit: days",
+      "",
+      'task A "Market research" duration: 5',
+      'task B "Design mockups" duration: 8 after: A',
+      'task C "Backend API" duration: 15 after: A',
+      'task D "Frontend build" duration: 10 after: B, C',
+      'task E "QA / testing" duration: 5 after: D',
+      'task G "Launch event" duration: 2 after: E'
+    ],
+    prefer: [
+      'Each `task ID "label" duration: N` is one activity; wire dependencies with `after: A, B` (comma-separated, forward references allowed). The engine computes ES/EF/LS/LF and the critical path \u2014 never write those yourself.',
+      "Use three-point estimation `duration: O/M/P` (e.g. `2/3/5`) for uncertainty \u2014 the engine computes `te = (O+4M+P)/6` and variance; add `critical-tolerance: 0.01` when mixing estimate kinds.",
+      'Declare dependency types when needed: `after: A FS`, `after: A SS+2`, `after: B FF-1` (default FS, zero lag); group activities with `lane: "Team"`.'
+    ],
+    avoid: [
+      "Don't write `ES:`, `EF:`, `LS:`, `LF:`, or `slack:` yourself \u2014 they are computed outputs.",
+      "Don't create a cycle in `after:` references, and don't reference an undeclared predecessor.",
+      "Don't mix lag unit suffixes that don't match `unit:` \u2014 e.g. `FS+2d` with `unit: weeks`."
+    ],
+    repair: [
+      "'is missing' duration -> add `duration: N` or append the bare word `milestone` to the task line.",
+      "'references undeclared predecessor' -> declare `task Y \u2026` anywhere (forward references are allowed).",
+      "'O <= M <= P' -> reorder a three-point estimate so optimistic <= most-likely <= pessimistic.",
+      "'duplicate task id' -> every task needs a unique id; rename the second occurrence."
+    ]
   },
   sequence: {
     type: "sequence",
     header: "sequenceDiagram",
     mode: "Mermaid sequenceDiagram (recommended for generation)",
+    keywords: 'sequenceDiagram (Mermaid) | sequence "Title" (native) \xB7 participant actor boundary control entity database collections queue \xB7 "as" alias \xB7 \xABstereotype\xBB \xB7 -> sync \xB7 ->> async \xB7 --> reply \xB7 -) async \xB7 -x lost \xB7 *Target create \xB7 +/- activation suffix \xB7 activate/deactivate \xB7 note over|left of|right of A[,B]: text \xB7 ref over A,B: text \xB7 == divider == \xB7 autonumber \xB7 fragments: alt else end / opt loop break critical neg ignore consider assert par seq strict and end',
     forms: [
       "participant Alice",
       "participant Bob",
@@ -3997,20 +4756,26 @@ var PROFILES = {
       "Note over Alice,Bob: handshake"
     ],
     prefer: [
-      "Use Mermaid `sequenceDiagram` syntax: `->>` is a sync call, `-->>` a reply/return, `-)` async; `participant`/`actor`, `Note over A,B:`, and `loop`/`alt`/`opt`/`par \u2026 end` all work.",
-      'This matches the dominant training-data prior; the native `sequence "Title"` header (where `->>` means async) is also accepted.',
-      "Add combined fragments only when control flow matters."
+      "Use the `sequenceDiagram` header (Mermaid mode): `->>` is a sync call and `-->>` is the reply/return \u2014 matches the dominant training prior.",
+      "Declare lifeline kinds with `participant`/`actor`/`boundary`/`control`/`entity`/`database`/`collections`/`queue` before use; undeclared ids auto-create as plain `participant`.",
+      "Use `->+` / `-->-` to open/close activation bars inline; use `alt \u2026 else \u2026 end`, `loop`, `opt`, `par \u2026 and \u2026 end` for fragments."
+    ],
+    avoid: [
+      "Do not mix `sequenceDiagram` and native `sequence` headers \u2014 in Mermaid mode `->>` is sync, in native mode it is async; pick one and keep arrows consistent.",
+      "Do not use `else` outside an `alt`, or `and` outside `par`/`seq`/`strict`.",
+      "Do not leave a combined fragment open \u2014 every `alt`/`opt`/`loop`/`par`/`break`/`critical` must close with `end`."
     ],
-    avoid: ["Do not mix the two header styles; pick `sequenceDiagram` and keep Mermaid arrow meanings throughout."],
     repair: [
-      "Every fragment (`loop`/`alt`/`opt`/`par`/`break`/`critical`) needs a matching `end`; `else` only inside `alt`.",
-      'If the header is rejected, use exactly `sequenceDiagram` (or `sequence "Title"`).'
+      "'must start with the keyword' -> fix the first line to exactly `sequenceDiagram` or `sequence \"Title\"`.",
+      "'is only valid inside an' -> move the `else` inside an `alt \u2026 end` block (or `and` inside `par`).",
+      "'without a matching combined fragment' -> add the missing `end`, or remove the dangling `else`/`and`."
     ]
   },
   petri: {
     type: "petri",
     header: 'petri "Title"',
     mode: "declared places + transitions + arcs",
+    keywords: 'place ID ["label"] *N|tokens:N [capacity:N] \xB7 transition ID ["label"] [immediate|timed] [rate:N] [priority:N] [guard: expr] \xB7 arc types: -> (standard) | -o (inhibitor, P\u2192T only) | -- (read) | => (reset, P\u2192T only) \xB7 weight: N or *N on arc \xB7 layout: lr|tb \xB7 marking: id=n,\u2026 \xB7 fire: T1, T2, \u2026 (simulate firing)',
     forms: [
       "place P1 *1",
       "transition T1",
@@ -4028,7 +4793,7 @@ var PROFILES = {
       "Avoid `-o`/`=>` arcs from a transition; inhibitor and reset arcs are place\u2192transition only."
     ],
     repair: [
-      "An 'unknown node' error means an arc references an undeclared place/transition \u2014 declare it first.",
+      "'arc references unknown node' -> an arc references an undeclared place/transition; declare it first.",
       "Set the initial marking so the transitions you intend to be enabled actually have enough input tokens."
     ]
   },
@@ -4036,27 +4801,28 @@ var PROFILES = {
     type: "network",
     header: 'network "Title"',
     mode: "device declarations + links (annotations are optional)",
+    keywords: "device kinds: router switch l3switch firewall loadbalancer ap wlc gateway modem ids proxy vpngw server serverfarm pc laptop mobile ipphone printer storage camera nvr dvr poeswitch encoder monitor internet wan cloud pstn lan \xB7 aliases: multilayer->l3switch wifi->ap workstation->pc nas/san->storage \xB7 device attrs: tier:edge|core|distribution|access ip: model: count: type:fixed|bullet|dome|ptz|turret at:x,y \xB7 link connectors: -- (undirected) | -> (directed) | == (LAG) \xB7 link annotations: copper|fiber|wireless|serial|poe|vpn|lag trunk|access speed(1G/10G/100M) vlan:N port:near>far \xB7 groups: site rack subnet vlan zone dmz { \u2026 } \xB7 layout: tiered|tree|star|ring|bus|mesh|spine-leaf|manual \xB7 spines: / leaves:",
     forms: [
-      'router r1 "Edge Router"      (kind  id  "label")',
-      'l3switch core1 "Core" tier: core      (optional structural hint)',
+      'router r1 "Edge Router"',
+      'l3switch core1 "Core" tier: core',
       'switch acc1 "Access" tier: access',
       'pc pc1 "Workstation"',
-      "r1 -- core1                  (link: id -- id)",
+      "r1 -- core1",
       "core1 -- acc1",
       "acc1 -- pc1"
     ],
     prefer: [
       'Start from the skeleton: `kind id "label"` device lines plus `a -- b` links. That alone renders a complete, valid diagram.',
       "Declare every device before any link references it.",
-      "Keep the cheap structural hints `layout:` (tiered/tree/star/ring/bus/mesh/spine-leaf) and `tier:` (edge/core/distribution/access) \u2014 they cost little and drive a readable hierarchy. They are recommended, not noise.",
+      "Keep the cheap structural hints `layout:` (tiered/tree/star/ring/bus/mesh/spine-leaf) and `tier:` (edge/core/distribution/access) \u2014 they drive a readable hierarchy.",
       "Common kinds: router, switch, l3switch, firewall, ap, server, pc, laptop, camera, nvr, poeswitch, internet, cloud."
     ],
     avoid: [
       "Avoid linking to an undeclared device id.",
-      'Add the verbose per-link annotations \u2014 `vlan:`, `port:`, speeds (1G/10G), `trunk`/`access` \u2014 and `subnet "cidr" { ... }` boundaries ONLY when the request explicitly needs them. These don\'t affect the layout and are where generation most often breaks.'
+      'Add verbose per-link annotations (`vlan:`, `port:`, speeds, `trunk`/`access`) and `subnet "cidr" { ... }` boundaries ONLY when the request needs them \u2014 they don\'t affect layout and are where generation most often breaks.'
     ],
     repair: [
-      "An 'undeclared device' error means a link references an id with no `kind id` declaration \u2014 declare it first.",
+      "'undeclared device' -> a link references an id with no `kind id` declaration; declare it first.",
       "If the layout looks flat/messy, add `layout: tiered` + `tier:` on infrastructure; if unsure about per-link annotations, drop them \u2014 the skeleton always renders."
     ]
   },
@@ -4064,40 +4830,42 @@ var PROFILES = {
     type: "umlclass",
     header: "umlclass",
     mode: "classifier declarations + relationship lines (PlantUML-flavoured, Mermaid aliases accepted)",
+    keywords: 'header: umlclass | class-diagram | classDiagram \xB7 classifiers: class | abstract class | interface | enum (or enumeration) | datatype | primitive \xB7 stereotype: \xABword\xBB or <<word>> \xB7 members in { }: visibility + - # ~ \xB7 modifiers {static} {abstract} \xB7 derived /name \xB7 multiplicity [1..*] \xB7 tilde-generics List~T~ -> List<T> \xB7 single-line: ClassName : +member \xB7 connectors: <|-- --|> generalization \xB7 <|.. ..|> realization \xB7 *-- --* composition \xB7 o-- --o aggregation \xB7 --> <-- directed assoc \xB7 ..> <.. dependency \xB7 -- association \xB7 multiplicity "1" "0..*" quoted next to endpoint \xB7 namespace A.B.C { } \xB7 direction: tb|lr',
     forms: [
-      "class Order { + id : String  + place() : void }     (visibility: + - # ~)",
-      "\xABinterface\xBB Shape { + area() : double }              (stereotype above name)",
+      "class Order { + id : String  + place() : void }",
+      "\xABinterface\xBB Shape { + area() : double }",
       "abstract class AbstractShape { + area() : double {abstract} }",
-      "\xABenumeration\xBB Suit { HEARTS DIAMONDS CLUBS SPADES } (literals in attr compartment)",
-      "Animal <|-- Dog                                     (generalization \u2014 hollow triangle to parent)",
-      "Shape <|.. Circle                                    (realization \u2014 dashed + hollow triangle)",
-      'Order *-- "1..*" LineItem : contains                (composition \u2014 filled diamond at whole)',
-      'Customer o-- "0..*" Address                          (aggregation \u2014 hollow diamond at whole)',
-      'A "1" --> "*" B : owns                               (directed association \u2014 open arrow to target)',
-      "X ..> Y                                              (dependency \u2014 dashed + open arrow)"
+      "\xABenumeration\xBB Suit { HEARTS DIAMONDS CLUBS SPADES }",
+      "Animal <|-- Dog",
+      "Shape <|.. Circle",
+      'Order *-- "1..*" LineItem : contains',
+      'Customer o-- "0..*" Address',
+      'A "1" --> "*" B : owns',
+      "X ..> Y"
     ],
     prefer: [
       "Single-word keyword is `umlclass` (also accepts `class-diagram` and Mermaid's `classDiagram`).",
       "Use `class`, `abstract class`, `\xABinterface\xBB`, `\xABenumeration\xBB`, or any custom `\xABstereotype\xBB` above the name.",
       "Members go in `{ \u2026 }`; visibility glyphs are `+ - # ~`; `{static}` underlines, `{abstract}` italicises, `/name` marks a derived attribute.",
-      'Multiplicity is the quoted token next to an endpoint: `"1"`, `"0..*"`, `"1..*"`. The line midpoint label after `:` is the association name.',
+      'Multiplicity is the quoted token next to an endpoint: `"1"`, `"0..*"`, `"1..*"`. The label after `:` is the association name.',
       "PlantUML connectors are primary; the Mermaid reversed forms `--|>`, `..|>`, `--*`, `--o` are accepted and normalised."
     ],
     avoid: [
-      "Don't use bare `class` as the diagram keyword \u2014 that's a reserved programming-language word, and the engine keyword is `umlclass`.",
-      "Don't put `-->` for dependency: `-->` is *directed association*; dependency is the dashed `..>` (this is a deliberate deviation from PlantUML, matching Mermaid and the usual UML reading).",
-      "Don't declare a classifier with an empty body and `{}` if you want a name-only sketch box \u2014 write `class Foo` on its own line."
+      "Don't use bare `class` as the diagram keyword \u2014 that's a reserved word; the engine keyword is `umlclass`.",
+      "Don't put `-->` for dependency: `-->` is directed association; dependency is the dashed `..>`.",
+      "Don't declare a classifier with an empty `{}` for a name-only box \u2014 write `class Foo` on its own line."
     ],
     repair: [
-      "A 'malformed relationship' error means no connector glyph was found between two ids \u2014 check the line uses one of `<|--` `<|..` `*--` `o--` `-->` `..>` `--` `..`.",
-      "A 'generalization cycle' error means inheritance edges form a loop \u2014 fix the parent/child direction of one of the edges named in the cycle.",
-      "If a class appears as a one-line empty box you didn't expect, the parser auto-created it from an arc reference \u2014 declare it explicitly or fix the typo in the relationship id."
+      "'malformed relationship' -> no connector glyph was found between two ids; use one of `<|--` `<|..` `*--` `o--` `-->` `..>` `--` `..`.",
+      "'generalization cycle' -> inheritance edges form a loop; fix the parent/child direction of one edge in the cycle.",
+      "If a class appears as an unexpected empty box, the parser auto-created it from an arc reference \u2014 declare it explicitly or fix the relationship id typo."
     ]
   },
   faulttree: {
     type: "faulttree",
     header: 'faulttree "Title"',
     mode: "flat event/gate declarations wired by id (top + gates + leaves)",
+    keywords: "header: faulttree | fta \xB7 event kinds: top | gate | basic | undeveloped | house | condition \xB7 gate exprs: AND(a,b,\u2026) | OR(\u2026) | XOR(\u2026) | VOTING(k/n; \u2026) | INHIBIT(x) if cond | PAND(a,b) [order: a,b] \xB7 leaf attr: p: N (or prob:, sci 1e-3) \xB7 house attr: state: 0|1 \xB7 analysis: cutsets | probability | pathsets \xB7 prob: rare|mcub|exact \xB7 layout: tb|bt \xB7 style: ansi|iec",
     forms: [
       "analysis: cutsets, probability",
       'top  T  "System fails" = OR(G1, G2)',
@@ -4121,9 +4889,9 @@ var PROFILES = {
       "Don't declare more than one `top`, and don't create cycles (a gate may not transitively reference itself)."
     ],
     repair: [
-      "'references undefined event' means a gate input id was never declared \u2014 add the `basic`/`gate`/\u2026 line.",
-      "'must have exactly one top' \u2014 keep a single `top`; downgrade the others to `gate`.",
-      "'VOTING k/n: n must equal the number of inputs' \u2014 make n match the listed inputs.",
+      "'references undefined event' -> a gate input id was never declared; add the `basic`/`gate`/\u2026 line.",
+      "'must have exactly one top' -> keep a single `top`; downgrade the others to `gate`.",
+      "'n must equal the number of inputs' -> in `VOTING(k/n; \u2026)` make n match the listed inputs.",
       "If P(top) shows 'n/a', a basic event in a cut set is missing its `p:`."
     ]
   },
@@ -4131,6 +4899,7 @@ var PROFILES = {
     type: "bowtie",
     header: 'bowtie "Title"',
     mode: "indentation-structured: hazard + topevent, then threat/consequence blocks with indented barrier chains",
+    keywords: 'hazard "\u2026" \xB7 topevent "\u2026" \xB7 threat "\u2026" \xB7 prevent "\u2026" \xB7 consequence "\u2026" \xB7 mitigate "\u2026" \xB7 escalation "\u2026" \xB7 barrier "\u2026" \xB7 layout: symmetric|compact \xB7 legend: on|off|bottom|bottom-right|top',
     forms: [
       'hazard "Working at height"',
       'topevent "Person falls from height"',
@@ -4144,7 +4913,7 @@ var PROFILES = {
     ],
     prefer: [
       "Single-word keyword is `bowtie`. Declare exactly one `topevent` (the knot) and an optional `hazard` header.",
-      "Each `threat` needs \u2265 1 indented `prevent` barrier; each `consequence` needs \u2265 1 indented `mitigate` barrier (the engine rejects a bare threat/consequence).",
+      "Each `threat` needs >= 1 indented `prevent` barrier; each `consequence` needs >= 1 indented `mitigate` barrier (the engine rejects a bare threat/consequence).",
       "Barrier order = declaration order (first = outermost, nearest the threat/consequence; last = innermost, nearest the knot).",
       "`escalation` nests (4 spaces) under the `prevent`/`mitigate` barrier it degrades; an escalation-factor `barrier` nests (6 spaces) under the escalation.",
       "Bowtie is qualitative \u2014 no probabilities. For Boolean gates + cut sets behind one threat, use a separate `faulttree`."
@@ -4156,16 +4925,17 @@ var PROFILES = {
       "Don't declare more than one `topevent` or more than one `hazard`."
     ],
     repair: [
-      "'has no preventative barrier' / 'no mitigative barrier' \u2014 add a `prevent`/`mitigate` line under the threat/consequence.",
-      "'not attached to a barrier' \u2014 move the `escalation` so it follows a `prevent`/`mitigate` line.",
-      "'needs at least one threat/consequence' \u2014 a one-wing diagram is a fault tree or event tree; add the missing wing.",
-      "'exactly one top event' \u2014 keep a single `topevent` line."
+      "'has no preventative barrier' / 'no mitigative barrier' -> add a `prevent`/`mitigate` line under the threat/consequence.",
+      "'not attached to a barrier' -> move the `escalation` so it follows a `prevent`/`mitigate` line.",
+      "'needs at least one threat/consequence' -> a one-wing diagram is a fault tree or event tree; add the missing wing.",
+      "'exactly one top event' -> keep a single `topevent` line."
     ]
   },
   eventtree: {
     type: "eventtree",
     header: 'eventtree "Title"',
     mode: "initiating event + ordered safety functions, then outcome rows with s/f/* branch patterns",
+    keywords: 'eventtree|eta "Title" \xB7 initiating ID "label" freq: <number|1e-4> \xB7 function ID "label" p: <0..1> \xB7 outcome <s|f|*>\u2026 -> "label" \xB7 layout: lr \xB7 # and // comments',
     forms: [
       'initiating LOCA "Large LOCA" freq: 1e-4',
       'function A "ECCS injects" p: 0.001',
@@ -4176,24 +4946,25 @@ var PROFILES = {
     ],
     prefer: [
       "Keyword `eventtree` (or `eta`). One `initiating` line with a `freq:`; then `function` lines in left-to-right order, each with its failure probability `p:` (success is auto-complemented to 1\u2212p).",
-      'Each `outcome` row gives a `s`/`f`/`*` pattern (one symbol per function) then `-> "label"`. `*` = path already terminated (pruned) \u2014 runs flat to its leaf, no further branching.',
+      'Each `outcome` row gives a `s`/`f`/`*` pattern (one symbol per function) then `-> "label"`. `*` = path already terminated (pruned).',
       "Let the engine compute path frequencies (f_initiating \xD7 \u03A0 branch-probs) \u2014 don't hand-write them."
     ],
     avoid: [
-      "Don't try to make a balanced 2\u207F tree \u2014 prune with `*` where a sequence ends early.",
+      "Don't try to make a balanced 2^n tree \u2014 prune with `*` where a sequence ends early.",
       "Don't put probabilities on outcome rows; `p:` belongs on `function` lines.",
       "Don't reverse the success/failure convention \u2014 success branches up, failure down."
     ],
     repair: [
-      "'outcome pattern length' \u2014 give exactly one s/f/* per declared function.",
-      "'no initiating event' \u2014 add one `initiating <id> \"\u2026\" freq: \u2026` line.",
-      "'once pruned stays pruned' \u2014 after a `*` in a pattern, the rest must also be `*`."
+      "'outcome pattern length' -> give exactly one s/f/* per declared function.",
+      "'no initiating event' -> add one `initiating <id> \"\u2026\" freq: \u2026` line.",
+      "'once pruned stays pruned' -> after a `*` in a pattern, the rest must also be `*`."
     ]
   },
   fmea: {
     type: "fmea",
     header: 'fmea "Title"',
     mode: "indentation-structured worksheet: item \u2192 failure mode \u2192 effect/cause/controls with S/O/D scores",
+    keywords: 'fmea "Title" \xB7 type: design|dfmea|process|pfmea|msr \xB7 rank: ap|rpn \xB7 flag: ap>=High|rpn>100 \xB7 item "\u2026" fn "\u2026" \xB7 mode "\u2026" \xB7 effect "\u2026" sev: 1..10 \xB7 cause "\u2026" occ: 1..10 \xB7 controls prevention: "\u2026" detection: "\u2026" det: 1..10 \xB7 action "mode" do: "\u2026" owner: "\u2026" target: DATE \xB7 revised sev:/occ:/det:',
     forms: [
       'fmea "Brake System DFMEA"',
       '  item "Master cylinder" fn "Generate pressure"',
@@ -4213,40 +4984,47 @@ var PROFILES = {
       "Don't put `occ:` on an effect or `sev:` on a cause \u2014 they bind to the wrong column."
     ],
     repair: [
-      "'score out of range' \u2014 keep S/O/D in 1\u201310.",
-      "'mode has no effect/cause' \u2014 every failure mode needs at least one effect and one cause."
+      "'score out of range' -> keep S/O/D in 1\u201310.",
+      "'has no effect/cause' -> every failure mode needs at least one effect and one cause."
     ]
   },
   causalloop: {
     type: "causalloop",
     header: 'causalloop "Title"',
     mode: "signed causal links between variables; engine detects R/B loops",
+    keywords: 'causalloop "Title" (alias: cld) \xB7 A -> B : + | - | s | o | same | opposite \xB7 "multi-word var" -> Target : + \xB7 A -> B : + delay \xB7 var "Variable name" \xB7 loop R1 "phrase" | loop B1 "phrase" \xB7 layout: auto | circle',
     forms: [
-      'causalloop "Adoption model"',
-      '"Adoption rate" -> Adopters : +',
-      'Adopters -> "Adoption rate" : +',
-      '"Adoption rate" -> "Potential adopters" : -',
-      'loop R1 "Word of mouth"',
-      'loop B1 "Market saturation"'
+      'causalloop "Startup growth engine"',
+      '"Active users" -> "Word of mouth" : +',
+      '"Word of mouth" -> "New signups" : +',
+      '"New signups" -> "Active users" : +',
+      '"Active users" -> "Server load" : +',
+      '"Server load" -> "App performance" : -',
+      '"App performance" -> "Active users" : + delay',
+      'loop R1 "Viral flywheel"',
+      'loop B1 "Scaling strain"'
     ],
     prefer: [
-      "Keyword `causalloop` (or `cld`). Write `A -> B : +` or `A -> B : -` (you may use `s`/`o` aliases). Multi-word variables go in quotes.",
-      'Let the engine classify loops R (reinforcing) / B (balancing) by counting negative links; optionally name them with `loop R1 "\u2026"`.',
-      "Put the `+`/`\u2212` polarity at the end of each link."
+      "Put every polarity after the `->` as `: +` or `: -` \u2014 every causal link must be signed.",
+      'Wrap multi-word variable names in double quotes: `"Active users"`. Single-token names (e.g. `Revenue`) need no quotes.',
+      'Let the engine classify loops R/B automatically \u2014 use `loop R1 "phrase"` only to name a loop it already detected.'
     ],
     avoid: [
-      "Don't draw boxes around variables \u2014 CLD variables are boxless text.",
-      "Don't omit polarity \u2014 every causal link is signed."
+      "Don't omit the polarity separator: `A -> B : +` is the canonical form.",
+      "Don't use `s`/`o`/`same`/`opposite` in generated output \u2014 they normalise to `+`/`-` but reduce readability.",
+      "Don't draw boxes around variables \u2014 CLD variables are boxless text labels; there is no shape syntax."
     ],
     repair: [
-      "'link needs a polarity' \u2014 append `: +` or `: -`.",
-      "'unknown variable' \u2014 variables are created on first use; check quoting/spelling."
+      "'is missing a polarity' -> append `: +` or `: -` after the target variable name.",
+      "'needs at least one causal link' -> add at least one signed link; a document with only `loop` declarations is rejected.",
+      "'malformed link (expected' -> each link line must contain `->` between the source and target variable names."
     ]
   },
   markov: {
     type: "markov",
     header: 'markov "Title"',
     mode: "probability-labelled state transitions; engine computes stationary distribution + classification",
+    keywords: 'markov | markovchain ["Title"] \xB7 state <id> ["Label"] [absorbing] \xB7 <from> -> <to> : <prob> (colon form) | <from> -> <to> <prob> (space form) \xB7 layout: ring|layered \xB7 normalize: true|false \xB7 analysis: stationary classify absorbing period all',
     forms: [
       'markov "Weather"',
       "Sunny -> Sunny : 0.9",
@@ -4255,23 +5033,26 @@ var PROFILES = {
       "Rainy -> Rainy : 0.5"
     ],
     prefer: [
-      "Keyword `markov` (or `markovchain`). Write `S1 -> S2 : 0.3` transitions; each state's outgoing probabilities must sum to 1.",
-      "Mark absorbing states by a 1.0 self-loop (or the `absorbing` keyword); the engine computes the stationary distribution and classifies states.",
-      "For an absorbing chain add `analysis: classify, absorbing` to get absorption probabilities + expected steps."
+      "Write `S1 -> S2 : 0.3` transitions (colon form is canonical); every state's outgoing probabilities must sum to 1 unless `normalize: true` is set.",
+      "Declare absorbing states with the `absorbing` keyword (`state Broke absorbing`); the engine validates it against the computed structure.",
+      "Use `analysis: classify, stationary` for ergodic chains; add `absorbing` for the fundamental matrix, absorption probabilities, and expected steps."
     ],
     avoid: [
-      "Don't let a state's out-probabilities sum to \u2260 1 (the engine errors); use `normalize: true` only if you intend rescaling.",
-      "Don't hand-compute the stationary distribution \u2014 it is derived."
+      "Don't let a state's outgoing probabilities sum to anything but 1 \u2014 this hard-errors unless `normalize: true`.",
+      "Don't declare a state `absorbing` unless it has a self-loop of probability 1 and no other out-edges.",
+      "Don't hand-compute the stationary distribution or absorption probabilities \u2014 they are derived."
     ],
     repair: [
-      "'row does not sum to 1' \u2014 fix the probabilities or add `normalize: true`.",
-      "'probability out of range' \u2014 keep each on (0,1]."
+      "'outgoing probabilities sum to' -> adjust that state's transitions to sum to exactly 1, or add `normalize: true`.",
+      "'is missing a probability' -> add `: <prob>` after the target state id.",
+      "'is declared absorbing but is' -> add `<id> -> <id> : 1` and remove other out-edges, or drop the `absorbing` keyword."
     ]
   },
   gitgraph: {
     type: "gitgraph",
     header: "gitGraph",
     mode: "Mermaid-compatible ordered git operations (commit/branch/checkout/merge)",
+    keywords: 'gitGraph [LR:|TB:|BT:] \xB7 commit [id:"\u2026"] [tag:"\u2026"] [type:NORMAL|REVERSE|HIGHLIGHT] \xB7 branch <name> [order:N] \xB7 checkout <name> | switch <name> \xB7 merge <name> [id:"\u2026"] [tag:"\u2026"] \xB7 cherry-pick id:"\u2026" [parent:"\u2026"] \xB7 %% comment \xB7 config: mainBranchName showBranches showCommitLabel',
     forms: [
       "gitGraph",
       '  commit id: "init"',
@@ -4282,136 +5063,168 @@ var PROFILES = {
       "  merge develop"
     ],
     prefer: [
-      'Header `gitGraph` (Mermaid syntax). Operations in order: `commit`, `branch <name>`, `checkout <name>`, `merge <name>`, `cherry-pick id: "\u2026"`.',
-      'Annotate commits with `id: "\u2026"`, `tag: "\u2026"`, `type: HIGHLIGHT|REVERSE|NORMAL`.',
-      "`checkout` (or `switch`) before committing onto a branch; `merge <name>` merges that branch into the current one."
+      "Operations must be in execution order: `branch <name>` opens a lane, `checkout <name>` (or `switch`) switches HEAD, `commit` adds a node on the current branch, `merge <name>` merges that branch into the current one.",
+      'Annotate commits with `id: "\u2026"`, `tag: "\u2026"`, and `type: HIGHLIGHT`/`REVERSE`/`NORMAL`; `cherry-pick id: "\u2026"` copies a commit by id.',
+      "Use `gitGraph LR:` (default) for left-to-right time; add `TB:`/`BT:` inline on the header to change orientation."
     ],
     avoid: [
-      "Don't `merge` or `checkout` a branch you never created with `branch`.",
-      "Don't merge a branch into itself."
+      "Don't `checkout` or `merge` a branch you have not created with `branch <name>` first.",
+      "Don't `merge` a branch into itself.",
+      "Don't use an option key other than `id`, `tag`, `type`, `order`, `parent`."
     ],
     repair: [
-      "'unknown branch' \u2014 add a `branch <name>` before `checkout`/`merge`.",
-      "'cannot merge current branch' \u2014 checkout the target lane first."
+      "'checkout of undeclared branch' -> add a `branch <name>` operation before the `checkout`.",
+      "'cannot merge branch' into itself -> `checkout` a different branch before the `merge`.",
+      "'cherry-pick of merge commit' requires parent -> add `parent: \"<id>\"` to the `cherry-pick` line."
     ]
   },
   epc: {
     type: "epc",
     header: 'epc "Title"',
-    mode: "alternating events/functions joined by AND/OR/XOR connectors; alternation validated",
+    mode: "alternating events/functions joined by and/or/xor connectors; alternation validated",
+    keywords: 'epc ["title"] [layout: tb|lr] \xB7 event ID ["label"] \xB7 function ID ["label"] (alias: func) \xB7 and ID \xB7 or ID \xB7 xor ID \xB7 A -> B (edge, chainable A -> B -> C) \xB7 A -> B : "label" \xB7 rules: strict event/function alternation; start/end are events; an event may not source an OR/XOR split',
     forms: [
       'epc "Order fulfilment"',
+      "  layout: tb",
       '  event E1 "Order received"',
       '  function F1 "Check credit"',
       "  xor X1",
       '  event E2 "Credit OK"',
       '  event E3 "Credit rejected"',
+      '  function F2 "Ship goods"',
+      '  function F3 "Notify customer"',
+      '  event E4 "Order shipped"',
+      '  event E5 "Order cancelled"',
       "  E1 -> F1 -> X1",
       "  X1 -> E2",
-      "  X1 -> E3"
+      "  X1 -> E3",
+      "  E2 -> F2 -> E4",
+      "  E3 -> F3 -> E5"
     ],
     prefer: [
-      "Keyword `epc`. Declare `event`, `function`, and connectors `and`/`or`/`xor` with ids; then the control flow `A -> B -> C`.",
-      "Strictly alternate events and functions (a connector may sit between them); start and end with events.",
-      "Use a connector node to split/join \u2014 e.g. a `xor` after a function fans out to alternative events."
+      "Declare `event`, `function`, and connector (`and`/`or`/`xor`) nodes with ids first; then wire them with `A -> B` edge lines (chainable: `A -> B -> C`).",
+      "Strictly alternate events and functions: every path follows event \u2192 function \u2192 event \u2192 \u2026 Connectors sit between them but the next typed node must be the opposite kind.",
+      "Use a connector node to split or join; place the connector after a function for any OR/XOR split."
     ],
     avoid: [
-      "Don't make an event the source of an OR/XOR split (only functions may decide) \u2014 the engine rejects it.",
-      "Don't connect event\u2192event or function\u2192function directly."
+      "Don't make an event the source of an `or`/`xor` split \u2014 only a function may precede an OR/XOR split.",
+      "Don't give an event or function more than one outgoing arc without a connector \u2014 the split belongs on a connector.",
+      "Don't connect two events or two functions in sequence without an intervening node."
     ],
     repair: [
-      "'event cannot be an OR/XOR split source' \u2014 put a function (decision) before the connector.",
-      "'alternation violated' \u2014 insert the missing event/function between two same-kind nodes."
+      "'is the source of a XOR split' -> insert a `function` between the event and the `xor`/`or` connector.",
+      "'must have a single output' -> add an `and`/`or`/`xor` node and route the multiple arcs from the connector.",
+      "'is used in an edge but never declared' -> add the missing `event`/`function`/connector declaration before the edge."
     ]
   },
   idef0: {
     type: "idef0",
     header: 'idef0 "Title"',
     mode: "function boxes + positional ICOM arrows (input-left, control-top, output-right, mechanism-bottom)",
+    keywords: 'idef0 ["title"] \xB7 node <id> \xB7 purpose "\u2026" \xB7 viewpoint "\u2026" \xB7 function ID "name" [n:N] \xB7 input ID "label" (left) \xB7 control ID "label" (top) \xB7 output ID "label" (right) \xB7 mechanism ID "label" (bottom) \xB7 call ID "label" \xB7 A1 -> A2 "label" (bare target = .input) \xB7 A1 -> A2.input|.control|.mechanism "label" \xB7 (tunnel) flag \xB7 ICOM codes I1/C1/O1/M1 auto-assigned',
     forms: [
-      'idef0 "Manufacture product"',
-      '  function A1 "Plan production"',
-      '  function A2 "Make parts"',
-      '  input A1 "Sales orders"',
-      '  control A1 "Production schedule"',
-      '  A1 -> A2 "Work plan"',
-      '  mechanism A2 "CNC machines"',
-      '  output A2 "Product"'
+      'idef0 "Fulfil customer order"',
+      "node A0",
+      'function A1 "Validate order"',
+      'function A2 "Pick and pack"',
+      'function A3 "Ship and invoice"',
+      'input     A1 "Customer order"',
+      'control   A1 "Credit policy"',
+      'mechanism A1 "Order management system"',
+      'A1 -> A2 "Validated order"',
+      'mechanism A2 "Warehouse staff"',
+      'A2 -> A3 "Packed shipment"',
+      'output    A3 "Delivered order"'
     ],
     prefer: [
-      "Keyword `idef0`. Declare `function` boxes; attach boundary arrows with `input`/`control`/`output`/`mechanism`.",
-      'Box\u2192box flow `A1 -> A2 "label"` lands on A2\'s input by default; use `A1 -> A2.control "\u2026"` to land on another ICOM side.',
-      "Remember the ICOM rule: Inputs enter left, Controls enter top, Outputs exit right, Mechanisms enter bottom \u2014 the engine enforces it."
+      'Declare `function ID "name"` boxes first; attach boundary arrows with `input`/`control`/`output`/`mechanism` + box id + quoted label. Box numbers and ICOM codes are assigned automatically.',
+      'Box-to-box flow `A1 -> A2 "label"` lands on A2\'s left (`input`) by default; use `A1 -> A2.control "\u2026"` or `A1 -> A2.mechanism "\u2026"` for the top or bottom edge.',
+      "Remember ICOM: Inputs enter left, Controls enter top, Outputs exit right, Mechanisms enter bottom. Use 3\u20136 boxes per diagram (FIPS 183)."
     ],
     avoid: [
-      "Don't route an output anywhere but the right edge, or a control anywhere but the top \u2014 the engine rejects it.",
-      "Don't hand-number the boxes \u2014 node numbers are assigned."
+      "Don't land a flow on the target's `.output` edge \u2014 outputs exit a box; use `.input`/`.control`/`.mechanism`.",
+      "Don't hand-number boxes with `n:N` unless you number every box \u2014 mixing explicit and auto numbering is an error.",
+      "Don't reference a box id in an arrow before declaring it with `function`."
     ],
     repair: [
-      "'output must exit the right edge' \u2014 declare it with `output` / land flows on the correct side.",
-      "'unknown box' \u2014 declare the `function` before referencing it."
+      "'arrow references undefined function box' -> add a `function ID \"name\"` line before any arrow that references it.",
+      "'cannot land on the target's .output' -> change `.output` to `.input`, `.control`, or `.mechanism`.",
+      "'must declare at least one' function box -> add at least one `function ID \"name\"` line; a diagram cannot be only arrows."
     ]
   },
   threatmodel: {
     type: "threatmodel",
     header: 'threatmodel "Title"',
-    mode: "DFD elements + data flows + trust boundaries; engine maps STRIDE + flags boundary crossings",
+    mode: "DFD elements + data flows + trust boundaries; engine maps STRIDE-per-element + flags boundary crossings",
+    keywords: 'external: Label | external ID: Label \xB7 process ID: Label \xB7 datastore ID: Label [log|audit|journal -> R auto-enabled] \xB7 A -> B : "label" (label required) \xB7 A <-> B : "label" (bidirectional) \xB7 boundary "Name" { id, id } \xB7 title: "\u2026" \xB7 STRIDE-per-element: external S,R \xB7 process all six \xB7 store T,I,D (R conditional) \xB7 flow T,I,D',
     forms: [
-      'threatmodel "Web App \u2014 STRIDE"',
-      "external: User",
-      "process 1.1: Web Server",
-      "datastore D1: User DB",
-      "User -> 1.1 : HTTPS Request",
-      "1.1 -> D1 : Lookup",
-      'boundary "Internet" { User }',
-      'boundary "DMZ" { 1.1 }'
+      'threatmodel "E-commerce checkout"',
+      "external: Customer",
+      "external Payment_Gateway: Payment Gateway",
+      "process 1.0: Web App",
+      "process 2.0: Order Service",
+      "datastore D1: Orders DB",
+      "datastore D2: Audit Log",
+      'Customer -> 1.0 : "HTTPS Checkout"',
+      '1.0 -> 2.0 : "Place order"',
+      '2.0 -> D1 : "Write order"',
+      '2.0 -> Payment_Gateway : "Charge card"',
+      'boundary "Internet" { Customer, Payment_Gateway }',
+      'boundary "DMZ" { 1.0 }',
+      'boundary "Internal" { 2.0, D1, D2 }'
     ],
     prefer: [
-      'Keyword `threatmodel` (or `stride`). Declare `external:`, `process N:`, `datastore D:`; connect with `A -> B : "label"` flows; group ids into `boundary "name" { \u2026 }` trust zones.',
-      "Let the engine annotate each element's STRIDE letters and flag flows that cross a trust boundary \u2014 don't list threats by hand.",
-      "Name audit/log stores with `log`/`audit`/`journal` so they pick up the conditional Repudiation threat."
+      "Keyword `threatmodel` (alias `stride`). Declare all `external:`, `process ID:`, `datastore ID:` elements first, then flows, then `boundary` groups.",
+      'Every flow `A -> B : "label"` requires a label \u2014 the colon and label are mandatory; use `<->` for a bidirectional shorthand.',
+      "Name audit/log stores with `log`/`audit`/`journal` to auto-enable the conditional Repudiation threat; let the engine annotate STRIDE and flag boundary-crossing flows."
     ],
     avoid: [
-      "Don't connect store\u2192store or external\u2192external (not valid DFD edges).",
-      "Don't leave data flows unlabelled."
+      "Don't connect `datastore \u2192 datastore` or `external \u2192 external` directly \u2014 both are hard DFD violations.",
+      "Don't omit the `: label` on a flow; a bare `A -> B` line is rejected.",
+      "Don't put an element id in two different `boundary` blocks \u2014 each element belongs to at most one boundary."
     ],
     repair: [
-      "'unknown element' \u2014 declare the external/process/datastore before referencing it.",
-      "'flow needs a label' \u2014 add `: \"\u2026\"` to the flow."
+      '\'has no label\' -> add `: "label"` after the target id (e.g. `1.0 -> D1 : "Lookup"`).',
+      "'references unknown element' -> declare the `external:`/`process`/`datastore` before the flow that references it.",
+      "'directly to data store' -> route the flow through a `process` node in between.",
+      "'lists unknown element' -> declare the element before the `boundary { \u2026 }` block that references it."
     ]
   },
   welding: {
     type: "welding",
     header: "welding [standard: aws|iso-a|iso-b]",
     mode: "reference-line callouts; one joint block per joint, weld glyphs above/below the line",
+    keywords: 'joint "label" { arrow: <weldspec> \xB7 other: <weldspec> \xB7 both: <weldspec> \xB7 around \xB7 field \xB7 tail: "\u2026" } \xB7 weldspec = <type> [size=n] [len=n] [pitch=n] [angle=deg] [root=n] [throat=n] [contour=flush|convex|concave] [finish=G|M|C|R|H|U] \xB7 types: fillet square vgroove bevel ugroove jgroove flarev flarebevel plug slot spot seam back backing surfacing edge \xB7 standard: aws (default) iso-a iso-b',
     forms: [
-      'welding "Bracket welds"',
-      'joint "bracket to plate" {',
+      'welding "Bracket assembly"',
+      'joint "gusset to column" {',
       "  arrow: fillet size=8 len=50 pitch=150",
       "  other: fillet size=6",
       "  around",
       "  field",
-      '  tail: "GTAW"',
+      '  tail: "GMAW"',
       "}",
-      'joint "butt weld" {',
-      "  arrow: vgroove angle=60 root=3 throat=12",
+      'joint "splice plate (butt)" {',
+      "  arrow: vgroove angle=60 root=3 throat=12 contour=flush finish=G",
       "  other: backing",
+      '  tail: "SMAW; E7018"',
       "}"
     ],
     prefer: [
-      'Keyword `welding`; one `joint "label" { \u2026 }` block per joint. Put a weld on `arrow:` (arrow side) and/or `other:` (other side); `both:` is shorthand for the same weld on both sides.',
-      "A weldspec is `<type> key=value \u2026`: `size=` (left of symbol), `len=`/`pitch=` (length-pitch, right), `angle=`/`root=` (groove only), `throat=`, `contour=flush|convex|concave`, `finish=G|M|C|R|H|U`.",
-      'Flags on their own line: `around` (weld-all-around), `field` (site weld). Process/spec/NDE goes in `tail: "GTAW; WPS-12"`.',
-      "Types: fillet \xB7 square \xB7 vgroove \xB7 bevel \xB7 ugroove \xB7 jgroove \xB7 flarev \xB7 flarebevel \xB7 plug \xB7 slot \xB7 spot \xB7 seam \xB7 back \xB7 backing \xB7 surfacing \xB7 edge."
+      'One `joint "label" { \u2026 }` block per joint. Weld sides are `arrow:` (arrow side), `other:` (other side), or `both:` (same spec both sides).',
+      "A weldspec is `<type> key=value \u2026`: `size=` (leg size / plug diameter), `len=`/`pitch=` (intermittent), `angle=`/`root=` (groove only), `throat=`, `contour=flush|convex|concave`, `finish=G|M|C|R|H|U`.",
+      'Supplementary symbols on their own line inside the joint: `around` (weld-all-around), `field` (site weld). Process/spec/NDE goes in `tail: "GTAW; WPS-12"`.',
+      "Choose `standard: iso-a` for the dual solid+dashed reference line; default `aws` uses a single line."
     ],
     avoid: [
-      "Don't put `angle=` on a fillet/plug/spot \u2014 angle is groove-only (the engine warns).",
-      "Don't use `both:` for plug/slot/surfacing \u2014 they are single-side; surfacing is arrow-side only.",
-      "Don't give a fillet without `size=`, or a `pitch=` without `len=`."
+      "Don't put `angle=` on a `fillet`, `plug`, `spot`, or `seam` \u2014 angle is groove-only (the engine warns).",
+      "Don't use `both:` for `plug`, `slot`, or `surfacing` \u2014 those are single-side; `surfacing` is arrow-side only.",
+      "Don't give a `fillet` without `size=`, or a `pitch=` without `len=` (an intermittent weld is length-pitch)."
     ],
     repair: [
-      "'a fillet weld needs a leg size' \u2014 add `size=\u2026` to the fillet spec.",
-      "'angle= only applies to groove welds' \u2014 drop `angle=`, or change the type to a groove."
+      "'a fillet weld needs a leg size' -> add `size=N` to the fillet weldspec (e.g. `arrow: fillet size=8`).",
+      "'angle= only applies to groove welds' -> drop `angle=`, or change the type to a groove such as `vgroove`.",
+      "'pitch= needs a length=' -> add `len=N` alongside `pitch=N` on the same weldspec."
     ]
   }
 };
@@ -4441,6 +5254,7 @@ function buildCanonicalSyntax(profile) {
     `- Canonical type: \`${profile.type}\``,
     `- Canonical header: \`${profile.header}\``,
     `- Preferred mode: ${profile.mode}`,
+    profile.keywords ? `- Keywords: ${profile.keywords}` : "",
     bulletSection("Core forms", profile.forms),
     bulletSection("Prefer", profile.prefer),
     bulletSection("Avoid by default", profile.avoid),
@@ -4462,7 +5276,9 @@ function listDiagrams() {
     tagline: d.tagline,
     useWhen: d.useWhen,
     cluster: d.cluster,
-    standard: d.standard
+    standard: d.standard,
+    ...d.aliases ? { aliases: d.aliases } : {},
+    ...d.keywords ? { keywords: d.keywords } : {}
   }));
 }
 function getSyntax(type, opts = {}) {
@@ -4551,18 +5367,27 @@ function toValidationError(diagnostic, type) {
     column: diagnostic.column,
     source: diagnostic.source,
     message: diagnostic.message,
-    hint: diagnostic.hint ?? repairHint(type)
+    hint: diagnostic.hint ?? repairHint(type, diagnostic.message)
   };
 }
-function repairHint(type) {
+function repairHint(type, message) {
   const resolved = type ? resolveDiagramType(type) : void 0;
   const profile = resolved ? getGenerationProfile(resolved) : void 0;
-  const typeHint = profile?.repair[0];
+  const typeHint = message ? profile ? matchRepair(profile.repair, message) : void 0 : profile?.repair[0];
   return [
     typeHint,
     "Fix the reported DSL error, then call validateDsl again before rendering or returning DSL."
   ].filter(Boolean).join(" ");
 }
+function matchRepair(repairs, message) {
+  for (const r of repairs) {
+    const quoted = r.match(/^['"]([^'"]+)['"]/);
+    if (!quoted) continue;
+    const fragment = quoted[1].split(":")[0].trim();
+    if (fragment.length >= 6 && message.includes(fragment)) return r;
+  }
+  return void 0;
+}
 
 exports.DIAGRAM_REGISTRY = DIAGRAM_REGISTRY;
 exports.DIAGRAM_SINCE = DIAGRAM_SINCE;
@@ -4575,5 +5400,5 @@ exports.listDiagrams = listDiagrams;
 exports.renderDsl = renderDsl;
 exports.resolveDiagramType = resolveDiagramType;
 exports.validateDsl = validateDsl;
-//# sourceMappingURL=chunk-HWNVSNDJ.cjs.map
-//# sourceMappingURL=chunk-HWNVSNDJ.cjs.map
+//# sourceMappingURL=chunk-HKOPXQYU.cjs.map
+//# sourceMappingURL=chunk-HKOPXQYU.cjs.map