dsh-model-everything 0.5.0 → 0.5.1

package/package.json

@@ -1,148 +1,148 @@
-{
-  "name": "dsh-model-everything",
-  "version": "0.5.0",
-  "description": "Modeling abstraction, architecture visualisation and automated review for designs and code, including a refactoring harness: draw a Mermaid or PlantUML source and measure its structure, executable verification of machines and protocols with before/after regression, data-model and migration checks, concurrency claim routing, export to external checkers, dependency-graph review, and report diffing. Native plugin for DeepSeek Harness (dsh).",
-  "type": "module",
-  "main": "lib/index.js",
-  "types": "lib/types/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./lib/types/index.d.ts",
-      "default": "./lib/index.js"
-    },
-    "./gate": {
-      "types": "./lib/types/gate.d.ts",
-      "default": "./lib/gate.js"
-    },
-    "./gate/package.json": "./gate/package.json",
-    "./gate/locale/*.json": "./gate/locale/*.json",
-    "./cordis.patch.yml": "./cordis.patch.yml",
-    "./package.json": "./package.json",
-    "./locale/*.json": "./locale/*.json",
-    "./client": "./lib/client.js",
-    "./diagram": {
-      "types": "./lib/types/diagram.d.ts",
-      "default": "./lib/diagram.js"
-    },
-    "./diagram/package.json": "./diagram/package.json"
-  },
-  "files": [
-    "lib",
-    "src",
-    "skills",
-    "cordis.patch.yml",
-    "examples",
-    "gate",
-    "locale",
-    "diagram"
-  ],
-  "dsh": {
-    "engines": {
-      "dsh": "^0.1.7-alpha.2 || ^0.1.7-rc.1 || ^0.2.0-rc.1 || ^0.2.1-alpha.1 || ^0.2.1-rc.4"
-    },
-    "category": "tools/dev",
-    "displayName": "dsh-model-everything",
-    "bundle": {
-      "patch": "./cordis.patch.yml"
-    },
-    "compatibility": {
-      "dsh": "^0.1.7-alpha.2 || ^0.1.7-rc.1 || ^0.2.0-rc.1 || ^0.2.1-alpha.1 || ^0.2.1-rc.4",
-      "dshReleases": {
-        "0.1.7-alpha.2": "compatible",
-        "0.1.7-rc.1": "compatible",
-        "0.1.7-rc.2": "compatible",
-        "0.2.0-rc.1": "compatible",
-        "0.2.0-rc.2": "compatible",
-        "0.2.1-alpha.1": "compatible",
-        "0.2.1-alpha.2": "compatible",
-        "0.2.1-alpha.3": "compatible",
-        "0.2.1-alpha.4": "compatible",
-        "0.2.1-alpha.5": "compatible",
-        "0.2.1-rc.2": "compatible",
-        "0.2.1-rc.3": "compatible",
-        "0.2.1-rc.4": "compatible"
-      },
-      "profiles": [
-        "headless",
-        "web"
-      ]
-    },
-    "client": {
-      "platform": "web",
-      "immediately": true,
-      "inject": []
-    }
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.json && node scripts/build-client.mjs",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "lint:md": "markdownlint --dot --ignore \"**/node_modules/**\" .",
-    "bump": "node scripts/bump-version.mjs",
-    "test:cards": "node tests/presentation/run.mjs && node tests/automaton/run.mjs && node tests/routing/run.mjs",
-    "coverage": "c8 --reporter=text --exclude-after-remap=false npm run test:engine",
-    "test:engine": "npm run build && node tests/engine/run.mjs && node tests/design-engine/run.mjs && node tests/catalog/run.mjs && node tests/data-engine/run.mjs && node tests/concurrency/run.mjs && node tests/uml/run.mjs && node tests/apply-smoke.mjs && node tests/memory/run.mjs && node tests/skills/run.mjs && node tests/gate/run.mjs && node tests/skill-routing/run.mjs && node tests/toolset/run.mjs && node tests/principles/run.mjs && node tests/feature-checklist/run.mjs && node tests/usage/run.mjs && node tests/translation/run.mjs && node tests/documentation/run.mjs && node tests/contributing/run.mjs && node tests/routing-map/run.mjs && node tests/report-reading/run.mjs && node tests/structure/run.mjs && node tests/automaton/run.mjs && node tests/diagram/run.mjs && node tests/client/run.mjs && node tests/render/run.mjs && node tests/presentation/run.mjs && node tests/routing/run.mjs && node tests/tool-routing/run.mjs && node tests/tools/run.mjs && node tests/baseline/run.mjs && node tests/granularity/run.mjs && node tests/exporters/run.mjs && node tests/report-view/run.mjs && node tests/contracts/run.mjs && node tests/tool-boundary/run.mjs && node tests/negatives/run.mjs && node tests/external/run.mjs",
-    "test:full": "npm run build && node tests/full-suite.mjs",
-    "check": "npm run lint:md && npm run test:engine",
-    "build:client": "node scripts/build-client.mjs"
-  },
-  "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.5",
-    "@deepseek-ai/dsh-agent": "^0.1.7-alpha.2 || ^0.1.7-rc.1 || ^0.2.0-rc.1 || ^0.2.1-alpha.1 || ^0.2.1-rc.4",
-    "@deepseek-ai/dsh-llm": "^0.1.7-alpha.2 || ^0.1.7-rc.1 || ^0.2.0-rc.1 || ^0.2.1-alpha.1 || ^0.2.1-rc.4",
-    "@deepseek-ai/dsh-session": "^0.1.7-alpha.2 || ^0.1.7-rc.1 || ^0.2.0-rc.1 || ^0.2.1-alpha.1 || ^0.2.1-rc.4",
-    "@deepseek-ai/dsh-skill-filesystem": "^0.1.7-alpha.2 || ^0.1.7-rc.1 || ^0.2.0-rc.1 || ^0.2.1-alpha.1 || ^0.2.1-rc.4",
-    "@deepseek-ai/dsh-tools": "^0.1.7-alpha.2 || ^0.1.7-rc.1 || ^0.2.0-rc.1 || ^0.2.1-alpha.1 || ^0.2.1-rc.4",
-    "@deepseek-ai/schemastery": "^3.18.5",
-    "dsh": "^0.1.7-alpha.2 || ^0.1.7-rc.1 || ^0.2.0-rc.1 || ^0.2.1-alpha.1 || ^0.2.1-rc.4"
-  },
-  "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.5",
-    "@deepseek-ai/dsh-agent": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-cordis-host-runner": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-home-paths": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-invariants": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-llm": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-ptc-runtime": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-sandbox": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-sandbox-policy": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-scope": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-session": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-skill": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-skill-filesystem": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-system-prompt": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-tools": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-user-approval": "^0.2.0-rc.2",
-    "@deepseek-ai/schemastery": "^3.18.5",
-    "@types/node": "^26.6.5",
-    "esbuild": "^0.28.2",
-    "markdownlint-cli": "0.49.1",
-    "typescript": "^7.0.2"
-  },
-  "author": {
-    "name": "AmethystLuna",
-    "url": "https://github.com/AmethystLuna"
-  },
-  "license": "MIT",
-  "repository": "https://github.com/AmethystLuna/dsh-model-everything",
-  "funding": {
-    "type": "custom",
-    "url": "https://afdian.com/a/amethystluna"
-  },
-  "keywords": [
-    "verification",
-    "model-checking",
-    "uml",
-    "diagrams",
-    "state-machine",
-    "data-model",
-    "concurrency",
-    "mermaid",
-    "plantuml",
-    "dsh",
-    "dsh-plugin",
-    "plugin"
-  ],
-  "engines": {
-    "node": ">=20"
-  }
-}
+{
+  "name": "dsh-model-everything",
+  "version": "0.5.1",
+  "description": "Modeling abstraction, architecture visualisation and automated review for designs and code, including a refactoring harness: draw a Mermaid or PlantUML source and measure its structure, executable verification of machines and protocols with before/after regression, data-model and migration checks, concurrency claim routing, export to external checkers, dependency-graph review, and report diffing. Native plugin for DeepSeek Harness (dsh).",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./gate": {
+      "types": "./lib/types/gate.d.ts",
+      "default": "./lib/gate.js"
+    },
+    "./gate/package.json": "./gate/package.json",
+    "./gate/locale/*.json": "./gate/locale/*.json",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json",
+    "./locale/*.json": "./locale/*.json",
+    "./client": "./lib/client.js",
+    "./diagram": {
+      "types": "./lib/types/diagram.d.ts",
+      "default": "./lib/diagram.js"
+    },
+    "./diagram/package.json": "./diagram/package.json"
+  },
+  "files": [
+    "lib",
+    "src",
+    "skills",
+    "cordis.patch.yml",
+    "examples",
+    "gate",
+    "locale",
+    "diagram"
+  ],
+  "dsh": {
+    "engines": {
+      "dsh": "^0.1.7-alpha.2 || ^0.1.7-rc.1 || ^0.2.0-rc.1 || ^0.2.1-alpha.1 || ^0.2.1-rc.4"
+    },
+    "category": "tools/dev",
+    "displayName": "dsh-model-everything",
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "compatibility": {
+      "dsh": "^0.1.7-alpha.2 || ^0.1.7-rc.1 || ^0.2.0-rc.1 || ^0.2.1-alpha.1 || ^0.2.1-rc.4",
+      "dshReleases": {
+        "0.1.7-alpha.2": "compatible",
+        "0.1.7-rc.1": "compatible",
+        "0.1.7-rc.2": "compatible",
+        "0.2.0-rc.1": "compatible",
+        "0.2.0-rc.2": "compatible",
+        "0.2.1-alpha.1": "compatible",
+        "0.2.1-alpha.2": "compatible",
+        "0.2.1-alpha.3": "compatible",
+        "0.2.1-alpha.4": "compatible",
+        "0.2.1-alpha.5": "compatible",
+        "0.2.1-rc.2": "compatible",
+        "0.2.1-rc.3": "compatible",
+        "0.2.1-rc.4": "compatible"
+      },
+      "profiles": [
+        "headless",
+        "web"
+      ]
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": []
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/build-client.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint:md": "markdownlint --dot --ignore \"**/node_modules/**\" .",
+    "bump": "node scripts/bump-version.mjs",
+    "test:cards": "node tests/presentation/run.mjs && node tests/automaton/run.mjs && node tests/routing/run.mjs",
+    "coverage": "c8 --reporter=text --exclude-after-remap=false npm run test:engine",
+    "test:engine": "npm run build && node tests/engine/run.mjs && node tests/design-engine/run.mjs && node tests/catalog/run.mjs && node tests/data-engine/run.mjs && node tests/concurrency/run.mjs && node tests/uml/run.mjs && node tests/apply-smoke.mjs && node tests/memory/run.mjs && node tests/skills/run.mjs && node tests/gate/run.mjs && node tests/skill-routing/run.mjs && node tests/toolset/run.mjs && node tests/principles/run.mjs && node tests/feature-checklist/run.mjs && node tests/usage/run.mjs && node tests/translation/run.mjs && node tests/documentation/run.mjs && node tests/contributing/run.mjs && node tests/routing-map/run.mjs && node tests/report-reading/run.mjs && node tests/structure/run.mjs && node tests/automaton/run.mjs && node tests/diagram/run.mjs && node tests/client/run.mjs && node tests/render/run.mjs && node tests/cycle-break/run.mjs && node tests/layering/run.mjs && node tests/ordering/run.mjs && node tests/coords/run.mjs && node tests/channels/run.mjs && node tests/components/run.mjs && node tests/placement/run.mjs && node tests/presentation/run.mjs && node tests/routing/run.mjs && node tests/tool-routing/run.mjs && node tests/tools/run.mjs && node tests/baseline/run.mjs && node tests/granularity/run.mjs && node tests/exporters/run.mjs && node tests/report-view/run.mjs && node tests/contracts/run.mjs && node tests/tool-boundary/run.mjs && node tests/negatives/run.mjs && node tests/external/run.mjs",
+    "test:full": "npm run build && node tests/full-suite.mjs",
+    "check": "npm run lint:md && npm run test:engine",
+    "build:client": "node scripts/build-client.mjs"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.5",
+    "@deepseek-ai/dsh-agent": "^0.1.7-alpha.2 || ^0.1.7-rc.1 || ^0.2.0-rc.1 || ^0.2.1-alpha.1 || ^0.2.1-rc.4",
+    "@deepseek-ai/dsh-llm": "^0.1.7-alpha.2 || ^0.1.7-rc.1 || ^0.2.0-rc.1 || ^0.2.1-alpha.1 || ^0.2.1-rc.4",
+    "@deepseek-ai/dsh-session": "^0.1.7-alpha.2 || ^0.1.7-rc.1 || ^0.2.0-rc.1 || ^0.2.1-alpha.1 || ^0.2.1-rc.4",
+    "@deepseek-ai/dsh-skill-filesystem": "^0.1.7-alpha.2 || ^0.1.7-rc.1 || ^0.2.0-rc.1 || ^0.2.1-alpha.1 || ^0.2.1-rc.4",
+    "@deepseek-ai/dsh-tools": "^0.1.7-alpha.2 || ^0.1.7-rc.1 || ^0.2.0-rc.1 || ^0.2.1-alpha.1 || ^0.2.1-rc.4",
+    "@deepseek-ai/schemastery": "^3.18.5",
+    "dsh": "^0.1.7-alpha.2 || ^0.1.7-rc.1 || ^0.2.0-rc.1 || ^0.2.1-alpha.1 || ^0.2.1-rc.4"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.5",
+    "@deepseek-ai/dsh-agent": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-cordis-host-runner": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-home-paths": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-invariants": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-llm": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-ptc-runtime": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-sandbox": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-scope": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-session": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-skill": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-skill-filesystem": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-tools": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-user-approval": "^0.2.0-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.5",
+    "@types/node": "^26.6.5",
+    "esbuild": "^0.28.2",
+    "markdownlint-cli": "0.49.1",
+    "typescript": "^7.0.2"
+  },
+  "author": {
+    "name": "AmethystLuna",
+    "url": "https://github.com/AmethystLuna"
+  },
+  "license": "MIT",
+  "repository": "https://github.com/AmethystLuna/dsh-model-everything",
+  "funding": {
+    "type": "custom",
+    "url": "https://afdian.com/a/amethystluna"
+  },
+  "keywords": [
+    "verification",
+    "model-checking",
+    "uml",
+    "diagrams",
+    "state-machine",
+    "data-model",
+    "concurrency",
+    "mermaid",
+    "plantuml",
+    "dsh",
+    "dsh-plugin",
+    "plugin"
+  ],
+  "engines": {
+    "node": ">=20"
+  }
+}

package/skills/model-everything-diagram/SKILL.md

@@ -1,82 +1,84 @@
----
-name: model-everything-diagram
-description: "Use when drawing a diagram from its source text or checking its structure: Mermaid and PlantUML subsets, structure budgets, and containment diffs. Every line it cannot draw is refused by number. The drawing proves layout, not design. Doctrine: the model-everything skill.""
----
-
-# Model Everything — Drawing
-
-A drawing is how a design is read, and a drawing that quietly drops a lifeline is worse than no drawing, because
-it looks complete. This skill covers the drawing half: it renders the subset it can actually draw, refuses the rest
-**by line**, measures the structure against budgets, and compares two drawings by what contains what.
-
-The doctrine it inherits — say what a result does and does not prove, read `verdict` and never `ok` — lives in the
-`model-everything` skill. Load that one when the question is whether a design is *correct*; load this one when the
-question is what the picture shows.
-
-## When This Skill Applies
-
-| The task involves… | What it does |
-|---|---|
-| "draw this mermaid", "render this PlantUML", "make a diagram of this flow" | `diagram_render`: source text to SVG, laid out and painted here, with `out` to write a file and `scheme` for the palette |
-| "is this diagram too dense", "how deep do the packages nest" | `diagram_review`: group width, nesting depth and node count against budgets you set, plus **what it measured** |
-| "what changed between these two diagrams", "did this package move" | `diagram_diff`: boundaries added, removed, renamed or re-parented, and nodes that changed owner |
-| A source in a notation the plugin does not draw | Refused with the line number; `diagram_render` still draws everything else and reports what it skipped |
-| A diagram already in a file, to link from a document | `diagram_render` with `out`, then link the SVG |
-
-## The two notations, and where each one stops
-
-| Notation | Drawn | Refused by name |
-|---|---|---|
-| Mermaid | `graph`/`flowchart` (TD/TB/LR), node shapes `[..]`, `(..)`, `{..}`, `((..))`, `[(..)]`, `[[..]]`, `<<..>>`; edges `-->`, `---`, `-.->`, `==>`, labels `-->\|text\|` and `-- text -->`; `stateDiagram`/`-v2` with `[*]` start and end markers and `state "text" as id`; `subgraph … end` including nesting | `sequenceDiagram`, `classDiagram`, `erDiagram`, `gantt`, `pie`, `journey`, `mindmap`, `timeline`, `quadrantChart`, `gitGraph`, `C4Context`, and the `click`/`style`/`classDef` directives |
-| PlantUML | `component`, `package`, `node`, `folder`, `cloud`, `database`, `state`, `artifact`, `rectangle` blocks and `[bracketed]` components; `-->`, `--->`, `..>`, either direction, `: label`; `[*] -->` start markers; `skinparam`/`!theme` ignored | `actor`, `participant`, `usecase`, `class`, `object`, `note`, `legend`, and the `alt`/`opt`/`loop`/`par` fragments |
-
-A refusal is one line in `refused`, phrased `line N: …`. The drawing you get does not show the refused lines, and
-the tool says so rather than leaving you to notice.
-
-## What the structure review reports
-
-| Code | Severity | What it means |
-|---|---|---|
-| `B1_GROUP_TOO_WIDE` | error | A boundary holds more direct children than the budget. A package with twenty boxes has stopped reading as a package. |
-| `B2_TOO_DEEP` | error | Nesting past the budget. Beyond three levels a reader needs the source, not the picture. |
-| `B3_EMPTY_GROUP` | error | A boundary with nothing drawable inside it: it claims a containment the drawing cannot show. |
-| `B4_SINGLE_MEMBER` | warning | A boundary around one thing. Often a layer that was never split, sometimes exactly right. |
-| `B5_TOO_MANY_NODES` | error | The whole drawing past its node budget. |
-| `D0_NO_SOURCE` | error | Nothing to review. |
-
-`measured` is printed next to `findings` on purpose: an empty finding list from a source that never parsed would
-otherwise read as a clean bill of health.
-
-## What the diff reports
-
-| Code | Kind | What changed |
-|---|---|---|
-| `H1_GROUP_ADDED` | info | A boundary that did not exist, saying what contains it when it is nested |
-| `H2_GROUP_REMOVED` | info | A boundary that is gone |
-| `H3_GROUP_RENAMED` | info | Same id, different text |
-| `H4_GROUP_MOVED` | warning | A boundary that changed parent, both sides named |
-| `H5_NODE_ADDED` / `H6_NODE_REMOVED` | info | A node that appeared or disappeared |
-| `H7_NODE_REGROUPED` | warning | A node that changed which group holds it |
-| `D1_SIDE_UNREADABLE` | error | One side produced no drawing, so there was nothing to compare |
-
-A rename is only a rename when the id survived. A vanished id beside a new one is an unrelated removal and
-addition, because the ids are what a caller tracks across versions.
-
-**It judges movement, not merit.** Whether a component belongs in its new package is the reader's call; the diff
-reports that the move happened and nothing more.
-
-## The whiteboard
-
-The right sidebar has a **Diagram** tab: paste a source, get the drawing. It scales to the pane, switches colour
-scheme (`default`, `github`, `high-contrast`, `print`), follows the page's light or dark surface, and folds a group
-into a single box when you click it. It reads no tool result, so it keeps working whatever changes on the tool side.
-
-## What this does not do
-
-- **It does not verify behaviour.** A drawing of a machine says nothing about whether the machine is safe; that is
-  `model_verify` on the model the drawing came from.
-- **It does not read a diagram back into a model.** `uml_parse` does that for the families it owns.
-- **It does not audit dependencies.** `uml_structure_verify` reads a component diagram as a dependency graph and
-  judges the edges; `diagram_review` only measures the shape.
-- **It does not draw everything.** A notation outside the subset above is refused by line; a picture that looks
-  complete and quietly lost half its arrows is the failure this whole subset exists to avoid.
+---
+name: model-everything-diagram
+description: "Use when drawing a diagram from its source text or checking its structure: Mermaid and PlantUML subsets, structure budgets, and containment diffs. Every line it cannot draw is refused by number. The drawing proves layout, not design. Doctrine: the model-everything skill.""
+---
+
+# Model Everything — Drawing
+
+A drawing is how a design is read, and a drawing that quietly drops a lifeline is worse than no drawing, because
+it looks complete. This skill covers the drawing half: it renders the subset it can actually draw, refuses the rest
+**by line**, measures the structure against budgets, and compares two drawings by what contains what.
+
+The doctrine it inherits — say what a result does and does not prove, read `verdict` and never `ok` — lives in the
+`model-everything` skill. Load that one when the question is whether a design is *correct*; load this one when the
+question is what the picture shows.
+
+## When This Skill Applies
+
+| The task involves… | What it does |
+|---|---|
+| "draw this mermaid", "render this PlantUML", "make a diagram of this flow" | `diagram_render`: source text to SVG, laid out and painted here, with `out` to write a file and `scheme` for the palette |
+| "is this diagram too dense", "how deep do the packages nest" | `diagram_review`: group width, nesting depth and node count against budgets you set, plus **what it measured** |
+| "what changed between these two diagrams", "did this package move" | `diagram_diff`: boundaries added, removed, renamed or re-parented, and nodes that changed owner |
+| A source in a notation the plugin does not draw | Refused with the line number; `diagram_render` still draws everything else and reports what it skipped |
+| An edge whose straight line would cross a component | Routed around it on a sparse grid (candidate lines from each box edge, A* with a bend penalty), so a line never reads as a connection that is not there |
+| A label with a hard line break, or one too long for its box | `<br>`, `<br/>` and a real newline end a line; anything longer than the drawing's line width wraps. The box is sized from the lines it draws. An edge label is drawn on its edge - centred on the middle of the edge's longest straight run, over a mask in the page colour - and slides along that run to clear a box, another label or another edge's line |
+| A diagram already in a file, to link from a document | `diagram_render` with `out`, then link the SVG |
+
+## The two notations, and where each one stops
+
+| Notation | Drawn | Refused by name |
+|---|---|---|
+| Mermaid | `graph`/`flowchart` (TD/TB/LR), node shapes `[..]`, `(..)`, `{..}`, `((..))`, `[(..)]`, `[[..]]`, `<<..>>`; edges `-->`, `---`, `-.->`, `==>`, labels `-->\|text\|` and `-- text -->`; `stateDiagram`/`-v2` with `[*]` start and end markers and `state "text" as id`; `subgraph … end` including nesting | `sequenceDiagram`, `classDiagram`, `erDiagram`, `gantt`, `pie`, `journey`, `mindmap`, `timeline`, `quadrantChart`, `gitGraph`, `C4Context`, and the `click`/`style`/`classDef` directives |
+| PlantUML | `component`, `package`, `node`, `folder`, `cloud`, `database`, `state`, `artifact`, `rectangle` blocks and `[bracketed]` components; `-->`, `--->`, `..>`, either direction, `: label`; `[*] -->` start markers; `skinparam`/`!theme` ignored | `actor`, `participant`, `usecase`, `class`, `object`, `note`, `legend`, and the `alt`/`opt`/`loop`/`par` fragments |
+
+A refusal is one line in `refused`, phrased `line N: …`. The drawing you get does not show the refused lines, and
+the tool says so rather than leaving you to notice.
+
+## What the structure review reports
+
+| Code | Severity | What it means |
+|---|---|---|
+| `B1_GROUP_TOO_WIDE` | error | A boundary holds more direct children than the budget. A package with twenty boxes has stopped reading as a package. |
+| `B2_TOO_DEEP` | error | Nesting past the budget. Beyond three levels a reader needs the source, not the picture. |
+| `B3_EMPTY_GROUP` | error | A boundary with nothing drawable inside it: it claims a containment the drawing cannot show. |
+| `B4_SINGLE_MEMBER` | warning | A boundary around one thing. Often a layer that was never split, sometimes exactly right. |
+| `B5_TOO_MANY_NODES` | error | The whole drawing past its node budget. |
+| `D0_NO_SOURCE` | error | Nothing to review. |
+
+`measured` is printed next to `findings` on purpose: an empty finding list from a source that never parsed would
+otherwise read as a clean bill of health.
+
+## What the diff reports
+
+| Code | Kind | What changed |
+|---|---|---|
+| `H1_GROUP_ADDED` | info | A boundary that did not exist, saying what contains it when it is nested |
+| `H2_GROUP_REMOVED` | info | A boundary that is gone |
+| `H3_GROUP_RENAMED` | info | Same id, different text |
+| `H4_GROUP_MOVED` | warning | A boundary that changed parent, both sides named |
+| `H5_NODE_ADDED` / `H6_NODE_REMOVED` | info | A node that appeared or disappeared |
+| `H7_NODE_REGROUPED` | warning | A node that changed which group holds it |
+| `D1_SIDE_UNREADABLE` | error | One side produced no drawing, so there was nothing to compare |
+
+A rename is only a rename when the id survived. A vanished id beside a new one is an unrelated removal and
+addition, because the ids are what a caller tracks across versions.
+
+**It judges movement, not merit.** Whether a component belongs in its new package is the reader's call; the diff
+reports that the move happened and nothing more.
+
+## The whiteboard
+
+The right sidebar has a **Diagram** tab: paste a source, get the drawing. It scales to the pane, switches colour
+scheme (`default`, `github`, `high-contrast`, `print`), follows the page's light or dark surface, and folds a group
+into a single box when you click it. It reads no tool result, so it keeps working whatever changes on the tool side.
+
+## What this does not do
+
+- **It does not verify behaviour.** A drawing of a machine says nothing about whether the machine is safe; that is
+  `model_verify` on the model the drawing came from.
+- **It does not read a diagram back into a model.** `uml_parse` does that for the families it owns.
+- **It does not audit dependencies.** `uml_structure_verify` reads a component diagram as a dependency graph and
+  judges the edges; `diagram_review` only measures the shape.
+- **It does not draw everything.** A notation outside the subset above is refused by line; a picture that looks
+  complete and quietly lost half its arrows is the failure this whole subset exists to avoid.