qgraphflow 0.0.6 → 0.0.7

package/skills/q-flow/references/evidence-sources.md

@@ -6,10 +6,12 @@ CodeGraph is the preferred call-graph accelerator, not a hard dependency.
 
 The intended implementation is [`colbymchenry/codegraph`](https://github.com/colbymchenry/codegraph), exposed through its local CLI or MCP server.
 
-1. Check whether `codegraph` is on `PATH` and whether the target repository contains `.codegraph/`.
-2. When both are present, run `codegraph status` and use one bounded `codegraph explore "<question or symbols>"` query before direct repository tracing.
-3. An already configured CodeGraph MCP tool can serve the same bounded query. Use the tools actually available in this client; do not assume a client-specific tool name.
-4. If the CLI, MCP tool or current index is unavailable, continue directly with the fallback below. Ordinary drawing does not require installing or initializing CodeGraph, resolving npm versions, or changing client configuration.
+1. For repository-backed work, check the available CLI/MCP tool and target index. A `.codegraph/` directory is only a candidate index, not proof of availability or freshness.
+2. With the CLI and index present, run `codegraph status`. Only if it confirms a current index, use one bounded `codegraph explore "<question or symbols>"` query before direct tracing. Report CodeGraph as selected after successful preflight, and as used only after the query succeeds.
+3. A configured MCP tool can supply equivalent status and query results. Use the client's actual capabilities; do not invent a tool name or assume an index is current when freshness cannot be established.
+4. If the tool, current index or query is unavailable/fails, continue with direct tracing and accurately report the fallback. Before checking, say preflight is pending. Do not install, initialize, refresh an index or change client configuration merely to draw.
+
+Document-only requests use the supplied requirements as `document` evidence without CodeGraph preflight or invented source anchors. If implementation is unavailable, state that boundary; conceptual diagrams omit `--repo-root`. Mixed requests keep document and implementation claims distinct.
 
 ## Optional setup when requested
 
@@ -21,7 +23,7 @@ The intended implementation is [`colbymchenry/codegraph`](https://github.com/col
 ## Fallback order
 
 1. Use `rg --files`, then narrow `rg` searches to declarations, entry points, callers, implementations, configuration keys, and tests.
-2. Read the complete relevant source path and preserve file, line, and symbol anchors.
+2. Read the complete relevant source path and preserve file, line, and symbol anchors, including the line behind each call, write or key that links two components.
 3. Check build models, packaged artifacts, focused tests, and runtime configuration when they change the conclusion.
 4. Use framework documentation only for behavior owned by the framework; label it `framework` rather than repository source.
 5. Mark non-critical unresolved links as `inference`. Omit unresolved links on the claimed main path.

package/skills/q-flow/references/graph-common.md

@@ -1,54 +1,54 @@
 # Graph JSON: rules shared by every diagram type
 
-Read this file plus `types/<diagramType>.md`. Together they are the complete authoring contract; do not read scripts, the bundled HTML, Viewer source or tests to learn rules. `graph-schema.md` is the maintainers' full reference.
+Read this and `types/<diagramType>.md` for authoring; `graph-schema.md` is for maintainers.
+
+## Granularity
+
+Before Evidence, honor the user's scope, depth, required facts, node budget and view count. Minimal styling does not reduce content; "minimal styling, every call" keeps every requested call.
+
+- **Default system overview:** for system/repository architecture, use business modules (monolith) or services (distributed), one level below the system, plus relevant callers, external systems and shared infrastructure. Aim for **8–12 visible nodes**; **over 15** prompts review of real domain boundaries or a proposed split. Soft targets only: never pad small systems or drop necessary nodes.
+- **Minimal:** use the fewest elements that answer the question. Aggregate real modules/responsibilities only; retain required dependencies, boundaries, decisions and outcomes. Put supporting explanation in `facts`. State aggregation/exclusions in `meta.scope`; never turn an indirect path into a direct-call claim. An explicit success-path-only request may exclude failure paths.
+- **Detailed:** follow the requested depth; if unspecified, expand relevant units one level beyond the default. Include in-scope branches, errors, retries, guards, calls, fields or members as the type requires. Overview/type size suggestions do not cap detail. Requested topology must be visible, not only in `facts` or notes.
+
+Other defaults: module → components/classes; flow → steps/functions; entity set → tables. Preserve type semantics: sequence nodes are lifelines, calls are messages. Keep peers at comparable levels; show broader context as boundaries/external participants. Record level, coverage and exclusions in `meta.scope`. If a strict user limit conflicts with required coverage, explain the tradeoff; never silently omit facts or invent aggregation.
+
+Default to one graph; overview plus detail requests multiple views. Propose splits at real boundaries; honor explicit single-view requests. Repeated architecture needs unique `meta.viewId`; repeated other types need separate outputs. Together, views cover all requested facts with stable IDs and boundary handoffs.
+
+Before layout, map every explicit requirement to visible elements and evidence. Minimal: every element serves the question. Detailed: audit coverage at the requested depth. Report evidence gaps. Simplify during scoped authoring; never remove chosen facts to pass layout/validation.
 
 ## Shape
 
-```json
-{
-  "meta": { "title": "…", "subtitle": "…", "sourceRef": "<repo>@<rev> or a document name", "scope": "…", "diagramType": "architecture", "locale": "zh-CN" },
-  "groups": [{ "id": "g1", "label": "…", "kind": "<group kind>" }],
-  "nodes": [{ "id": "n1", "label": "…", "kind": "<node kind>", "subtitle": "…", "groupId": "g1", "module": "order", "tags": ["core"], "facts": ["…"], "source": { "kind": "source", "file": "src/a.js", "lineStart": 10, "lineEnd": 24, "symbol": "createOrder" } }],
-  "edges": [{ "id": "e1", "source": "n1", "target": "n2", "kind": "<edge kind>", "label": "…", "evidence": "source" }]
-}
-```
-
-- Required: `meta.title`, `meta.sourceRef`, `meta.diagramType`, non-empty `nodes`, and `edges` (an array; it may be empty). `meta.locale` is the user's language: `zh-CN` (default), `en`, `ru`, `pt`, `ja`, `de`, `es`.
-- `meta.locale` only translates the Viewer's interface. Write every readable text yourself in that language — title, subtitle, scope, `facts`, edge labels (relationship verbs, branch words), guards; the type pages' English sample text is a placeholder. Identifiers (class, table, field, method, route, config key, literal value) and standard notation (cardinalities, `«include»`, `alt` / `loop`) stay verbatim.
-- Write facts only: **no `position`, `size` or `route`** — layout is computed. Optional hints (`layout.rank` / `layout.order` on nodes, `layout.primaryPath` / `layout.participantOrder` on the graph) express an order that already exists in the source.
-- IDs are unique non-empty strings; every edge endpoint names a node. Keep ids short and stable (`order-service`, `m3`).
-- One graph per file by default. Only when the user asks for several views, wrap them as `{ "diagrams": [graph, graph] }`, each with a distinct `diagramType`.
+- Required: `meta.title`, `meta.sourceRef`, `meta.diagramType`, non-empty `nodes`, and an `edges` array (may be empty). Optional `groups` hold boundaries. Collections: `{ "diagrams": [graph, graph] }`, 1–32 views.
+- `meta.locale`: user's language, `zh-CN` (default), `en`, `ru`, `pt`, `ja`, `de`, `es`. It translates only the UI: author all prose, labels and guards in that language. Keep identifiers, literal values and standard notation verbatim; samples are placeholders.
+- Facts only: **no `position`, `size` or `route`**. Node `layout.rank` / `layout.order`, graph `layout.primaryPath` / `layout.participantOrder` express existing source order only.
+- IDs are unique, stable and non-empty; edge `source` / `target` name nodes.
 
 ## Nodes
 
-- `kind` must be one of the type's node kinds (see the type file). No invented kinds, no colour fields.
-- `label` is the real name from the source (class, route, table, service). `subtitle` is one line of responsibility. `facts` are short atomic statements; put uncertainty into the wording.
-- `module`: the subsystem whose work the node performs (order, inventory, payment …). Reuse the exact same non-empty string for that subsystem across nodes and views; it drives card identity colours (chip, frame, faint wash, outgoing lines). It is not containment (`groupId` is). A node without `module` renders on the plain surface, so give every ordinary node one — steps, decisions, choices, start / end, and an external hub or broker that belongs to an evidenced channel; only `initial` / `final` and true outsiders (a caller, a debugger, an ops role) stay plain. Eight colour slots are hashed from the name, so two modules can share a colour: that is expected, the module label stays authoritative, and a module is never renamed for colour.
-- `groupId` declares real containment in a `groups` entry; groups nest with `parentId`. Group `kind` must be one of the type's group kinds.
-- The business centre: use the `business` kind where the type has one (architecture), otherwise add `"core"` to `tags`. Never invent a `core` kind.
-- `fields` (ER, optional elsewhere): `[{ "name", "type", "key": "PK|FK|UK", "nullable": true|false }]`. `attributes` / `methods` (class): arrays of strings.
+- `kind`: from the type page; no invented kinds or colour fields. `label`: real source name; `subtitle`: responsibility; `facts`: short atomic statements with uncertainty explicit.
+- `module`: subsystem doing the work, consistently named across views. Assign every ordinary node, including steps/start/end and evidenced hubs/brokers; only `initial` / `final` and true outsiders may stay plain. Colours hash into five slots; modules are never renamed for colour. A node without `module` renders on the plain surface. Module is not ownership.
+- `groupId` names a real containing group; groups nest via `parentId` and use the type's group kinds. One node per component at the chosen level; split responsibilities only when source does.
+- Business centre: `business` kind where supported, otherwise `"core"` in `tags`, never a `core` kind.
 
 ## Edges
 
-- `kind` from the type's edge kinds. `label` names the action, message or data, not the kind.
-- `evidence` (required): `source` (code you read), `code`, `config`, `schema`, `test`, `document`, `framework` (behaviour supplied by a framework, not visible in project code), `inference` (your deduction — label it, do not hide it).
-- Omit relationships you cannot support. Do not add intermediate nodes to make notation look conventional.
+- `kind`: from the type page. `label`: action, message or data.
+- Required `evidence`: `source` (read code), `code`, `config`, `schema`, `test`, `document`, `framework` (framework-owned behaviour), `inference` (explicitly labelled deduction).
+- Omit unsupported relationships; add no intermediate nodes just for conventional notation.
 
 ## Source anchors
 
-- `source.file` is repository-relative (no `..`, no absolute paths); `lineStart` / `lineEnd` are 1-based and inclusive; `symbol` is optional. The generator checks that the file exists and the range fits when `--repo-root` is passed.
-- `symbol` is the name exactly as written at the definition (`OrderService.createOrder`, `orders`), never a description. With `--repo-root`, its last segment must appear as a whole word inside the range, so a moved, renamed or deleted definition fails validation; `--fix` re-anchors a name found once in its file.
-- Anchor the node to where it is **defined** (class, function, table, service block), not to a call site. Edges carry no anchor of their own; their endpoint nodes do.
-- Omit `source` for external actors, third-party systems and framework-owned runtime components. Never reuse an anchor from an example.
-- Prefer one node per real component. Split by responsibility only when the source does.
+- Node `source` / edge `site`: `{ "file": "src/a.js", "lineStart": 10, "lineEnd": 24, "symbol": "createOrder" }`. Node source also has `kind` (`source`, `config`, etc.). Files are repository-relative, without `..`; lines are 1-based, inclusive. With `--repo-root`, files must exist and ranges fit.
+- Optional `symbol` is an exact identifier, not prose; its last segment must occur as a whole word in the range. `--fix` re-anchors it only if unique in the file.
+- Anchor nodes at definitions, edges at the call/write/key/inheritance/state assignment establishing the relation; edge symbol names the target. `source`, `code`, `config`, `schema`, `test` edges require `site`; sequence returns follow their calls. `framework`, `document`, `inference` need none. Missing sites produce `edge.site-missing` once any site exists.
+- External actors, third-party systems and framework runtime nodes need no `source`. Never copy example anchors.
 
 ## Composition
 
-- The diagram must answer the question asked from the first reading view: one clear path, real component names, action / message / data names on edges. Choose the smallest set of nodes that still tells the truth; a large system is several views, not one huge graph.
-- Groups are for real boundaries only. `module` is not decoration either: it states which business subsystem a node's work belongs to, and the same subsystem keeps the same name in every view.
-- Full labels, never abbreviated to fit: the layout expands for text and wraps long labels.
-- For a collection, reuse node ids and `module` values across views so the same component is recognisable everywhere.
+- First view answers the question with real names and labelled relationships.
+- `meta.notes`: at most 6 strings of 120 characters, for risks, doc/code contradictions, unverified claims or exclusions the reader must see first. Name identifiers; avoid repeating drawn edges. Shown in "Key points" and below SVG.
+- Templates measure full text and use compact structure, outline ports, orthogonal routes and independent labels. Preserve order, alternatives, hierarchy, cardinalities and ownership. Bounded search cannot prove crossings unavoidable.
 
 ## Delivery
 
-Validate with `node scripts/validate-graph.mjs <graph.json> --input-only --repo-root <repo>` before generating; `SKILL.md` says how to repair errors and what the composition warnings mean. Errors name the element (`edge m7.order duplicates 7`, `node api unknown kind …`): fix that field with an edit; do not rewrite the whole file, do not delete facts to pass, do not bypass with `--force`.
+Validate with `node scripts/validate-graph.mjs <graph.json> --input-only --repo-root <repo>` before generating; `SKILL.md` covers repair and warnings.

package/skills/q-flow/references/graph-schema.md

@@ -4,7 +4,7 @@
 
 
 `scripts/generate-viewer.mjs` accepts either one `Graph` or a graph collection. Older graphs without `meta.diagramType` remain valid and render as `architecture`.
-`adaptive-v2`: generation defaults to `--layout auto` and accepts semantic inputs without positions or sizes. Declare real ownership with node `groupId` and group `parentId`; color `module` is not ownership. Optional node `layout.rank` / `layout.order`, graph `layout.primaryPath` / `layout.participantOrder` express existing order only. `--layout preserve` checks existing geometry without rearranging it. Ambiguous old containment requires an explicit author decision. `--input-only` checks semantics; source, geometry and browser rendering have separate statuses. `--force` only permits replacing outputs and never bypasses quality checks. A layered result whose width/height ratio leaves the accepted band 1/1.6–1.6 by more than 10% is folded (2–5 segments): a top-down layout that is too tall cuts its layer sequence into columns with aligned tops, a left-to-right layout that is too wide cuts it into rows with aligned starts, so every segment keeps its reading direction and continues at the start of the next one. Geometry and routes inside a segment are kept; cuts prefer boundary changes and avoid a decision's branches; an edge across a cut runs through the channel between its segments, or through the corridor before or after them when a neighbour or heading is in the way. A boundary spread over several segments is rebuilt around its members and must not cover foreign nodes. Among the folds that pass the quality gate within 10% of the band, the one with the fewest crossings wins, then the fewest segments, so a balanced fold is not passed over for a ragged one; a fold the gate rejects is skipped for the next one, and otherwise the nearest valid shape competes with the unfolded result. Candidates whose ratio is within 1.3× of the band rank equal on shape, so fewer point crossings come before compactness and a crossing is never traded for a slightly better ratio; only a strip beyond that outranks them. The type budget only breaks ties towards its preferred orientation. Declared `layout.rank` layouts and state charts with branches or loops never fold.
+`adaptive-v3`: generation defaults to `--layout auto` and accepts semantic inputs without positions or sizes. Declare real ownership with node `groupId` and group `parentId`; color `module` is not ownership. Optional node `layout.rank` / `layout.order`, graph `layout.primaryPath` / `layout.participantOrder` express existing order only. `--layout preserve` checks existing geometry without rearranging it. Ambiguous old containment requires an explicit author decision. `--input-only` checks semantics; source, geometry and browser rendering have separate statuses. `--force` only permits replacing outputs and never bypasses quality checks. A layered result whose width/height ratio leaves the accepted band 1/1.6–1.6 by more than 10% is folded (2–5 segments): a top-down layout that is too tall cuts its layer sequence into columns with aligned tops, a left-to-right layout that is too wide cuts it into rows with aligned starts, so every segment keeps its reading direction and continues at the start of the next one. Geometry and routes inside a segment are kept; cuts prefer boundary changes and avoid a decision's branches; an edge across a cut runs through the channel between its segments, or through the corridor before or after them when a neighbour or heading is in the way. A boundary spread over several segments is rebuilt around its members and must not cover foreign nodes. Among the folds that pass the quality gate within 10% of the band, the one with the fewest crossings wins, then the fewest segments, so a balanced fold is not passed over for a ragged one; a fold the gate rejects is skipped for the next one, and otherwise the nearest valid shape competes with the unfolded result. Candidates whose ratio is within 1.3× of the band rank equal on shape, so fewer point crossings come before compactness and a crossing is never traded for a slightly better ratio; only a strip beyond that outranks them. The type budget only breaks ties towards its preferred orientation. Declared `layout.rank` layouts and state charts with branches or loops never fold. Architecture views are laid out both top-down and left-to-right; after crossings, the direction whose whole view fits one 1392×688 screen at the larger zoom wins, and the compiler records it in `layout.direction` (`down` / `right`), which a later compilation keeps.
 
 Flowchart main paths must run top-to-bottom, with left/right branches and outside feedback routes; a column fold continues the main path at the top of the next column, which is the only step that may run upwards. Auto, strict preservation and image exports apply the same rule. Optional `primaryPath` declares the main order; an unambiguous simple chain is checked even without it. Horizontal main paths are rejected regardless of node count; side branches and feedback edges may still run sideways or upwards.
 
@@ -17,6 +17,7 @@ Flowchart main paths must run top-to-bottom, with left/right branches and outsid
     "subtitle": "Optional supporting line",
     "sourceRef": "Branch, commit, document version, or evidence scope",
     "scope": "Verified evidence scope",
+    "notes": ["A finding the reader must see before opening any node"],
     "generatedAt": "ISO-8601 timestamp"
   },
   "groups": [
@@ -66,7 +67,7 @@ Flowchart main paths must run top-to-bottom, with left/right branches and outsid
 }
 ```
 
-Use one graph by default; a standalone page has no diagram-type menu. For a requested multi-diagram viewer, wrap 1–9 graphs in `diagrams`. Each graph must use a unique `meta.diagramType`; the toolbar view menu follows the fixed order `architecture`, `flowchart`, `sequence`, `er`, `deployment`, `class`, `state`, `usecase`, `dataflow` regardless of input order. The view menu lists the requested types vertically.
+Use one graph by default; a standalone page has no diagram-type menu. For a requested multi-diagram viewer, wrap 1–32 graphs in `diagrams`. Other types keep a unique `meta.diagramType`; repeated architecture views require unique `meta.viewId` values. The toolbar menu follows the fixed presentation order `capabilities`, `engineering`, `relations`, `flowchart`, `sequence`, `er`, `deployment`, `class`, `state`, `usecase`, `dataflow` regardless of input order. The three architecture entries retain the `architecture` semantic type. The view menu lists the requested types vertically.
 
 ```json
 {
@@ -85,6 +86,7 @@ The abbreviated graphs above show only the wrapper; every graph still follows th
 - `meta`, nodes, edges, groups and source anchors are objects; `nodes`, `edges`, and optional `groups` are arrays of objects. Invalid containers are rejected before layout or output generation.
 - Optional `meta.subtitle`, `meta.scope`, node `subtitle`, `source.symbol`, and edge `label` are strings. Optional node and edge `module` values are non-empty strings: reuse the exact same value for the same business module across every graph in a collection; do not store literal colors. Node `facts`, `tags`, `attributes`, and `methods` are arrays of non-empty strings. These rules apply to every diagram type.
 - Optional node `fields` is an array of objects with non-empty string `name` and `type`, optional `key` (`PK`, `FK`, `UK`) and boolean `nullable`; ER requires at least one field. Other types can expose these fields in search and details.
+- Optional `meta.notes` is an array of at most 6 non-empty strings of at most 120 characters (counted as characters, not UTF-16 units); an empty array means none. Each view of a collection has its own. It states what a reader must see before opening a node and the drawing cannot show: a defect or risk found, code that contradicts its documentation or UI, an unverified claim, scope left out. The Viewer shows it as a "Key points" card and `diagram.svg`, exported SVG and PNG draw it under the board; a graph without notes renders and exports byte-for-byte as before. The text is authored in the graph's language; saving from the page keeps it.
 - `meta.diagramType`: `architecture`, `flowchart`, `sequence`, `er`, `deployment`, `class`, `state`, `usecase`, or `dataflow`.
 - `meta.locale`: optional Viewer language: `en`, `zh-CN` (default), `ru`, `pt`, `ja`, `de`, or `es`; `ko` and `fr` remain supported for existing graphs. Interface strings are authored in English in the Viewer source (`i18n.js`, `i18n-messages.json` holds every other language including `zh-CN`); a graph without `meta.locale` still renders its interface in Chinese. This controls built-in interface and export labels; author titles, node labels, facts and relationship text in the desired language separately. Code identifiers and standard notation remain unchanged. In a collection, each diagram uses its own locale.
 - IDs are unique non-empty strings. Every edge endpoint names a node.
@@ -94,9 +96,10 @@ The abbreviated graphs above show only the wrapper; every graph still follows th
 - Edge `route` is optional. `via` contains graph-space waypoints and `labelAt` fixes the graph-space label center; omit both when automatic orthogonal routing is clear.
 - Every `route.via` and `route.labelAt` coordinate must be a finite non-negative number. The router inserts orthogonal elbows between waypoints and keeps the first and last connection anchored to the current node positions.
 - Optional node `source.kind` uses the same evidence values. `source.file` and `source.lineStart` identify the exact anchor.
-- With `--repo-root <directory>`, validation and generation read every node's `source.file` as repository-relative UTF-8 text and check the inclusive line range. Absolute paths, parent traversal, directories, binary files and symlinks escaping the root are rejected. Repeated references share one file read. When `source.symbol` is present, its last segment (split on every character other than a letter, digit, `_` or `$`) must occur as a whole word within the range; write the name as it appears at the definition, not a description. A failure names the lines where the word does occur in the file, and the receipt counts symbol checks in `sourceEvidence.symbols`. `--fix --repo-root` moves `lineStart` to the only such line in the file and shifts `lineEnd` with it, clamped to the last line; anchors with several or no matches stay for the author. Without the root, receipts explicitly mark existing source anchors `skipped`; without anchors they report `not-applicable`. These checks cover the local working tree, not `sourceRef` revision identity, definition parsing or claim correctness: a mention of the name left inside the range still passes.
+- Optional edge `site` (`file`, `lineStart`, optional `lineEnd` and `symbol`) records the line that makes the relationship hold: the call, write, foreign key, `extends` clause or state assignment. It has the same shape and checks as a node `source` but no `kind`: the edge's own `evidence` names the kind. An edge needs one when its `evidence` is `source`, `code`, `config`, `schema` or `test` and it is not a sequence `return` (`needsSite()`); the field is optional everywhere, so graphs written without it stay valid.
+- With `--repo-root <directory>`, validation and generation read every node's `source.file` and every edge's `site.file` as repository-relative UTF-8 text and check the inclusive line range. Absolute paths, parent traversal, directories, binary files and symlinks escaping the root are rejected. Repeated references share one file read. When `source.symbol` is present, its last segment (split on every character other than a letter, digit, `_` or `$`) must occur as a whole word within the range; write the name as it appears at the definition, not a description. A failure names the lines where the word does occur in the file, and the receipt counts symbol checks in `sourceEvidence.symbols` and relationship coverage in `sourceEvidence.relations` (`sited` of `eligible`, computed with or without the root). A site failure is named `diagrams[i].edges[j].site`. `--fix --repo-root` moves a node `source` or edge `site` `lineStart` to the only such line in the file and shifts `lineEnd` with it, clamped to the last line; anchors with several or no matches stay for the author (`edge <id>.site` in the messages). Without the root, receipts explicitly mark existing source anchors `skipped`; without anchors they report `not-applicable`. These checks cover the local working tree, not `sourceRef` revision identity, definition parsing or claim correctness: a mention of the name left inside the range still passes.
 - To emphasize the business center, use the existing `business` kind where supported, or include `core` or `business` in `tags` (matched case-insensitively). Keep the diagram's legal node kind; `core` is not a new kind or schema field. In a state diagram the `core` state is the goal and a `failure` tag marks a failed state; both only feed the Viewer's derived state colors.
-- Composition review (`reviewComposition()` in `graph-validation.js`, printed in full by `validate-graph.mjs --input-only` as `Composition warning (<type>) <rule>: …`, counted as `warnings: n` in every receipt) is advisory: warnings never fail validation or generation, and a collection with no `module` anywhere gets none. Rules: `module.missing` (an ordinary node without `module` once the collection uses modules; `initial` / `final` and the outsider kinds `external`, `actor`, `device` are exempt), `module.inconsistent` (the same node label carries a module in one view and none or another in a second view), `module.single-tone` (a flowchart or data flow of ≥ 6 washed nodes all in one module — a prompt to check, legitimate when the flow lives in one subsystem), `flowchart.process-branch` (a non-decision with more than one outgoing edge). The receipt carries `warnings: <count>` only when there are any.
+- Composition review (`reviewComposition()` in `graph-validation.js`, printed in full by `validate-graph.mjs --input-only` as `Composition warning (<type>) <rule>: …`, counted as `warnings: n` in every receipt) is advisory: warnings never fail validation or generation, and a collection with no `module` anywhere gets none. Rules: `module.missing` (an ordinary node without `module` once the collection uses modules; `initial` / `final` and the outsider kinds `external`, `actor`, `device` are exempt), `module.inconsistent` (the same node label carries a module in one view and none or another in a second view), `module.single-tone` (a flowchart or data flow of ≥ 6 washed nodes all in one module — a prompt to check, legitimate when the flow lives in one subsystem), `flowchart.process-branch` (a non-decision with more than one outgoing edge), `edge.site-missing` (an edge that needs a `site` while at least one other edge of the same graph records one; a graph with no site anywhere stays quiet). One rule needs the laid-out graph: `view.oversized` (`overviewWarnings()`, printed by `generate-viewer.mjs` once and only counted by output validation) fires when a view's bounds need more than `MAX_SCREENS` (4) reading rectangles of `OVERVIEW_AREA` (1392×688, a 1440×900 window with both panels closed) at `READABLE_ZOOM` (.75); a graph without positions reports nothing. The receipt carries `warnings: <count>` only when there are any.
 - The cool-neutral visual system is a Viewer presentation rule. Color, typography, and core styling require no new graph fields. The order-fulfillment preview model is example content, not a default dataset or evidence source.
 
 Legacy `playback` metadata is ignored. The Viewer has no automatic or stepped playback; directed-edge motion is a separate visual cue and does not imply execution order.
@@ -143,7 +146,7 @@ Sequence `order` retains semantic order; generated `route.messageY` supplies the
 
 Sequence `alt` optionally accepts `operands`: `[{"guard":"SignalR","edgeIds":["m10"]},{"guard":"HTTP","edgeIds":["m11","m12"]}]`. If supplied, at least two branches are required, with nonempty guards and valid, unique message IDs in ordered, non-interleaving order ranges. No visually enclosed message may be omitted. Guards are escaped text, never code. Page/export share guard and separator geometry; insufficient space is an error, not an implicit frame expansion. Legacy alt without operands remains loadable/saveable and visibly reports unspecified branch conditions with a validation warning. Text/position edits preserve operands.
 
-Sync has a filled arrow, async an open V, return an open V plus dashes; Sync stays solid; framework/inference evidence can still dash async messages, while returns remain dashed. Participant subtitles are drawn directly, in full; legacy drafts may retain ellipsis but cannot pass strict export. Actor heads are 130px with a subtitle, otherwise108px; ordinary heads stay72px. Authored lifeline ends and message order remain unchanged. Desktop defaults show overview; directory/search/keyboard locate and mobile (≤700px) defaults use local views at zoom≥.75. Explicit fit always shows the whole diagram.
+Sync has a filled arrow, async an open V, return an open V plus dashes; Sync stays solid; framework/inference evidence can still dash async messages, while returns remain dashed. Participant subtitles are drawn directly, in full; legacy drafts may retain ellipsis but cannot pass strict export. Actor heads are 130px with a subtitle, otherwise108px; ordinary heads stay72px. Authored lifeline ends and message order remain unchanged. Desktop defaults show the overview while it reads at zoom≥.75, else the start of the flow at .75; directory/search/keyboard locate use local views at zoom≥.75. Explicit fit always shows the whole diagram.
 
 ### ER
 
@@ -181,13 +184,13 @@ State nodes (`kind: "state"`) may contain `entry`, `do` and `exit`, each a non-e
 
 ### Source anchors
 
-Use `source` only when the node maps to a precise repository or supplied-document location. Omit it for external actors and framework-owned runtime components. Keep `facts` short and atomic, and put uncertainty in the wording as well as the evidence kind.
+Use `source` only when the node maps to a precise repository or supplied-document location. Omit it for external actors and framework-owned runtime components. Give an edge `site` when a line of code, configuration or schema makes that relationship hold; omit it for `framework`, `document` and `inference` edges. Keep `facts` short and atomic, and put uncertainty in the wording as well as the evidence kind.
 
 For an explicitly requested conceptual example, describe the relevant business model in `facts`, label inferred relationships as `inference`, and name that scope in metadata. Do not fabricate source paths or reuse preview-document anchors for another graph. Normal generation still writes `index.html`, `graph.json` and one SVG per view.
 
 ### Execution, pairing and nested fragments
 
-See `examples/sequence-execution.graph.json` in the repository (not shipped in the package) for the complete conceptual example (five participants, six call/return pairs, six executions, `loop → alt` and `opt → par`). The Viewer keeps these fields optional, so legacy graphs still render; the CLI validator requires a bar on the callee of every `sync` call answered by a `return`, from the call's `receive` to the return's `send` (legacy graphs without `replyTo` are never asked). `--fix` adds the missing bars, each nested in the innermost bar of that participant around it. Two answered calls to one callee that interleave (the second opens inside the first and closes after it) are not asked for bars, since bars on one participant cannot cross. New source-grounded sequences must explicitly author known executions, nesting and call/return references; the renderer does not infer bars from paired messages. Include only fragment behavior established by the source. These fields require a Viewer built with sequence execution support.
+See `examples/jeepay/sequence.graph.json` in the repository and package for source-backed unified-order calls, explicit returns, executions and the success callback fragment. The Viewer keeps these fields optional, so legacy graphs still render; the CLI validator requires a bar on the callee of every `sync` call answered by a `return`, from the call's `receive` to the return's `send` (legacy graphs without `replyTo` are never asked). `--fix` adds the missing bars, each nested in the innermost bar of that participant around it. Two answered calls to one callee that interleave (the second opens inside the first and closes after it) are not asked for bars, since bars on one participant cannot cross. New source-grounded sequences must explicitly author known executions, nesting and call/return references; the renderer does not infer bars from paired messages. Include only fragment behavior established by the source. These fields require a Viewer built with sequence execution support.
 
 A return declares `"replyTo": "call-id"`. It must reference an earlier sync/async call with reversed endpoints, in the same operand path, with at most one explicit return per call. Merge alternative outcomes before that return. Unpaired legacy messages stay legal. Paired labels display `C1` / `↩ C1` independently of editable text. Call and return share a color; nested calls form separate groups. Eight group colors are reused deterministically per theme; larger graphs retain unique pair IDs even when colors repeat. Node module colors are independent.
 
@@ -212,3 +215,21 @@ Structured fragments use `operands: [{id, edgeIds, guard?, label?, body?}]`:
 A child group specifies `parentId` and `parentOperandId`. For example, a loop operand `{id:"attempt", guard:"attempt < 3", edgeIds:["call","reply"]}` owns an alt group via `{parentId:"retry", parentOperandId:"attempt"}`. An opt operand `{id:"reserved", guard:"reserved", edgeIds:[]}` can own a par group in the same way. List a message directly in only one operand; parents inherit child membership. An empty `edgeIds` array requires non-empty plain-text `body` or a child fragment. Guards and body text are escaped, not executable. Reserve authored frame space for titles, guards, text-only branches, message labels and nested frames; validation rejects cycles, crossing frames, incorrect ownership and collisions.
 
 Legacy alt without operand IDs and old unstructured opt/loop remain readable and save without forced migration. Missing conditions are never invented. Sync messages use a solid baseline even for conceptual/inference evidence; evidence remains in metadata and details. Return messages keep dashed open arrows. JSON editing/download, SVG and PNG preserve the same execution bounds, pairing, fragments and group colors; exports remain static.
+
+## Architecture overview extension
+
+The complete authoring shape for `meta.architectureView`, `meta.viewId`, `layout.sections`, node `overviewText` and `badges` is in [types/architecture.md](types/architecture.md#overview-structure). Section geometry is compiled and persisted alongside card geometry. Ownership remains independent. Per-view diagnostics and drafts use view identity; legacy views fall back to diagram type. SVG naming stays index-based for collections. Browser edits do not reverify source claims; badge label edits remove their old anchor and become document claims.
+
+## Dedicated layout templates
+
+The generator measures complete content before choosing positions. Eleven presentation templates share the same routing, geometry checks, browser editing and exports. Platform capabilities use section matrices; engineering uses layers with parallel support; component relations cluster related components within real ownership; flowcharts use a main spine and side branches; sequence uses participant spans and event rows; ER uses related-entity matrices; deployment uses runtime tiers inside actual boundaries; class uses contract hierarchies; state uses lifecycle branches; use cases place actors outside the system; data flow separates processing and storage.
+
+Template placement never creates ownership, relationships or evidence. Authored ranks and peer order remain authoritative; deployment auto layout uses vertical runtime tiers, while other types retain explicit direction. Dense inputs keep a quality-valid layered candidate when it has fewer crossings or no template can pass the routing gate; `--verbose` reports the template, attempts and fallback. No supported facts are removed. Small layouts use their content bounds rather than a fixed canvas. The fixed botanical palette supports light/dark themes and stable module colors across views; it introduces no authored color field.
+
+## Semantic presentation rules
+
+Architecture overviews default to `layout.overviewConnections: "within-category"`: edges only draw when their endpoints belong to the same deepest presentation section. Cross-category edges remain in JSON, source evidence and relationship details. Set `"all"` to draw all relations. Viewer and SVG/PNG export use the same projection.
+
+Deployment nodes may declare `layout.tier`: `external`, `application`, `infrastructure`, or `data`. Auto layout orders these tiers from top to bottom within real runtime boundaries. Without a hint, databases use data, external nodes use external, queues/caches use infrastructure and other runtime nodes use application. This hint never adds a host, service or dependency.
+
+Measured templates preserve the component dependency path, vertical workflow spine, contract hierarchy, lifecycle notation, actor/system boundary and processing stages with adjacent stores. These rules take precedence over aspect ratio and space cost. `--layout preserve` keeps valid user geometry unchanged; invalid geometry returns diagnostics.

package/skills/q-flow/references/guided-intake.md

@@ -1,100 +1,80 @@
 # Guided intake
 
-Used only when the invocation and the conversation together do not supply a ready request. A ready request names a **subject** and the **question** the diagram must answer. Everything else has a default and is never asked.
+Use only when the invocation, supplied material and conversation leave necessary information missing. A ready request gives each requested view a **subject** and **question**, with a usable output location. Honor supplied preferences; use defaults for the rest.
 
-## Readiness
+## Input and readiness
 
-| Item | Ready when | Never asked |
-| --- | --- | --- |
-| Subject | A repository, module, flow, entity set or document is named, at the level the question needs: behaviour questions need one flow (state: one component); structure questions accept a repository or module | — |
-| Question | The user says what the diagram must answer, or names a type that implies it | — |
-| Diagram type | — | Derived from the question by SKILL.md Author step 1; default `architecture` |
-| Granularity | — | Derived from the subject by the altitude rule below; never ask "detailed or simple" |
-| Output directory, language, graph count, CodeGraph setup | — | Existing defaults; the recap shows the directory so the user can override |
-
-Only the missing item is asked. A behaviour question with a repository- or module-level subject is missing its flow: run the entry-point scan from the second round below on that subject and ask only for the flow. A request that arrived through the conversation (the skill was triggered by its description) is a ready request when it names both items.
+Resolve intent before material: an audit is read-only. Inspect, validate without `--fix`, and report findings; do not generate or overwrite artifacts. Evidence drift does not authorize an update. Then identify all supplied material before building options:
 
-## First-round inventory
+- **Existing graph:** read `graph.json`, including every view's metadata; inherit scope, type, granularity and directory. Follow SKILL.md Refresh for refresh, simplification or expansion. Ask only about an unresolved change, not the original drawing purpose again. Resolve which collection views the user wants changed; inherit every other view unchanged. For simplification or expansion, repeat `--view <view-id>` for the affected views during generation, keeping the others in preserve mode.
+- **Requirements:** read the supplied file, attachment or pasted text; derive subjects and questions from it. Do not scan unrelated repository modules or ask for material already supplied. Documented behaviour is not verified implementation. For mixed source/document requests, retain both and distinguish their evidence.
+- **Repository:** use the named repository or current project. Inventory only when needed to offer subjects or questions. If none of these materials is available, ask for a target repository or requirements; the plugin installation directory is not the target.
 
-Run before asking so that options name real modules. Budget: directory listing to depth 2 plus manifest presence; do not read source, do not scan entry points, do not run `codegraph explore`.
-
-| Signal | Files or directories | Enables |
-| --- | --- | --- |
-| Build | `package.json`, `pom.xml`, `build.gradle*`, `go.mod`, `Cargo.toml`, `pyproject.toml`, `*.csproj` | Module candidates; language and framework |
-| Persistence | `migrations/`, `db/migration/`, `*.sql`, `entity/`, `model/`, ORM mapping files | `er` |
-| Deployment | `Dockerfile`, `docker-compose*.yml`, `k8s/`, `helm/`, `charts/` | `deployment` |
-| State | file names containing `State`, `Status`, `Phase`, `Lifecycle` | `state` |
-| Documents | `docs/`, `requirements/`, `*.md` requirement files | `flowchart`, `usecase` |
-| CodeGraph | `.codegraph/` present | Recap says "CodeGraph" instead of "direct tracing" |
+Structure questions accept a system, module or entity set. Behaviour questions need one flow (state: one component) per view, including a flow described in requirements. A named type can supply the question. An existing graph can supply the subject and question for a requested update.
 
-More than 8 top-level directories: list only subdirectories that contain a build manifest. If the working directory is empty, is not a code repository, or is this plugin's own installation directory, ask for the target repository path or requirements document instead and list no module candidates.
+Ask only for missing information. Never ask for type, language, granularity, graph count or CodeGraph setup merely to fill a default. Document-only output uses the current project's `docs/qgraphflow/<scope>-<type>/`; honor a supplied directory. If no suitable project or supplied directory exists, ask only for the output location when that is all that is missing. Never output into the plugin cache.
 
-## Intent options
+Explicit multiple-view requests retain **every view**: keep shared subject/preferences and resolve only each view's missing scope. "Architecture and sequence, both" is not indecision; "architecture or sequence, which helps?" invites a recommendation. Default to one graph otherwise. Repeated architecture needs unique `meta.viewId`; repeated other types use separate outputs, as specified by [graph-common.md](graph-common.md#granularity).
 
-Phrase options as the question the diagram answers. Each option carries the subject level it needs and a one-word cost tag. Offer at most four, only those the inventory supports, and mark exactly one as recommended (default: the whole repository's structural overview).
+## Repository inventory
 
-| Option text | `meta.diagramType` | Needs | Cost | Offer when |
-| --- | --- | --- | --- | --- |
-| What the system is made of and who depends on whom | `architecture` | repository or module | fast | always |
-| Where it runs and how the pieces are deployed | `deployment` | repository | fast | deployment signal |
-| What is stored and how it relates | `er` | repository or module | fast | persistence signal |
-| Which types exist and how they relate | `class` | module | fast | build signal |
-| Who can do what | `usecase` | repository or module | fast | documents signal or public entry points |
-| Who calls whom, in what order | `sequence` | one flow | traces calls | always |
-| What decisions a process makes | `flowchart` | one flow | traces calls | always |
-| How data moves and changes | `dataflow` | one flow | traces calls | always |
-| What states something goes through | `state` | one component | traces calls | state signal |
+Before offering repository options, list directories to depth 2 and check manifest presence; do not read function bodies, scan entry points or run `codegraph explore` during this inventory.
 
-Structure intents (`architecture`, `deployment`, `er`, `class`, `usecase`) read manifests and declarations. Behaviour intents (`sequence`, `flowchart`, `dataflow`, `state`) trace execution paths and cost more; the tag states this, it does not change the recommendation.
+| Signal | Files or directories | Enables |
+| --- | --- | --- |
+| Build | `package.json`, `pom.xml`, `build.gradle*`, `go.mod`, `Cargo.toml`, `pyproject.toml`, `*.csproj` | Real module candidates |
+| Persistence | `migrations/`, `db/migration/`, `*.sql`, `entity/`, `model/`, ORM mappings | ER |
+| Deployment | `Dockerfile`, `docker-compose*.yml`, `k8s/`, `helm/`, `charts/` | Deployment |
+| State | file names containing `State`, `Status`, `Phase`, `Lifecycle` | State |
+| Documents | `docs/`, `requirements/`, requirements files | Document-backed subjects and questions |
+| CodeGraph | `.codegraph/` present | Candidate index only; availability/freshness still require preflight |
 
-## Altitude rule and view budget
+For more than eight top-level directories, prefer candidates containing build manifests. Do not invent module candidates for an empty, unrelated or plugin directory.
 
-Node unit is one level below the subject:
+## Intent options
 
-| Subject | Node unit |
-| --- | --- |
-| Whole repository | Module or service |
-| Module | Component or class |
-| One flow | Step or function |
-| Entity set | Table |
+Phrase choices as questions the diagram answers. Offer at most four relevant options, with one recommendation; use the user's words and available material. Default a repository overview to component relationships. Derive type/view from intent without an extra selection round.
 
-No fixed node or edge cap applies. Keep all facts needed by the requested scope; use the type-specific canvas budget and strict readability checks. A separate detail view may supplement the original model, but must not silently remove its relationships.
+| Question | Type / architecture view | Subject |
+| --- | --- | --- |
+| What capabilities does the platform provide and how does business connect? | `architecture` / `capabilities` | system or module |
+| How are engineering layers and components organized? | `architecture` / `engineering` | system or module |
+| What is the system made of and who depends on whom? | `architecture` / `relations` | system or module |
+| Where does it run? | `deployment` | system |
+| What is stored and how does it relate? | `er` | entity set or module |
+| Which types exist and how do they relate? | `class` | module |
+| Who can do what? | `usecase` | system or module |
+| Who calls whom, in what order? | `sequence` | flow |
+| What decisions does the process make? | `flowchart` | flow |
+| How does data move and change? | `dataflow` | flow |
+| What states does something go through? | `state` | component |
 
-## Asking
+Select relevant alternatives from this table, not all eleven at once. A platform/integration question brings capability architecture forward; a layering question brings engineering architecture forward. Do not require the user to learn internal view names. Repository call/behaviour questions require execution tracing; do not promise that declarations alone prove dependencies or behaviour.
 
-One message asks subject and intent together. Use the client's structured question tool when one exists; otherwise number the options in plain text. Do not assume a client-specific tool name. Ask in the user's language.
+## Asking and follow-up
 
-Plain-text shape:
+Ask subject and question together only when both are missing. Use the client's structured question tool when available, otherwise numbered plain text; do not assume a tool name. Ask in the user's language. Each question offers at most four choices and one recommendation, for example:
 
 ```
 Which part? 1 order  2 payment  3 inventory  4 whole repository (recommended)
 What should the diagram answer?
-  a  what the system is made of and who depends on whom — repository or module · fast (recommended)
-  b  who calls whom, in what order — one flow · traces calls
-  c  what is stored and how it relates — repository or module · fast
-  d  where it runs — repository · fast
+  1 system components and dependencies (recommended)
+  2 platform capabilities and business integration
+  3 engineering layers and components
+  4 the call order of a particular flow
 ```
 
-After asking, **end the turn and wait for the reply**. Do not assume an answer. Do not write `index.html`, `graph.json` or any other output before the round completes.
-
-## Second round
-
-Structure intents finish in the first round. A second round happens only in these cases, and there is never a third:
+After asking, **end the turn and wait for the reply**. Do not assume an answer or create graph/output files while essential information is unresolved. Usually one or two rounds suffice; readiness, not a fixed round count, ends intake.
 
-- **No subject yet**: offer at most three modules from the inventory, one recommended.
-- **Two intents**: take the primary one, note that the other can be a second diagram.
-- **Behaviour intent with a repository- or module-level subject**: scan the chosen subject for entry points and offer at most four flows. Use `rg -l` on file names and annotations (`*Controller*`, `*Handler*`, `*Listener*`, `*Consumer*`, `main`, `@RestController`, `@KafkaListener`, route decorators); do not read function bodies. Prefer candidates matching words the user already used. If still too many, group by package and let the user pick a package; that pick is the second round.
+- **Subject still missing:** offer grounded subjects from the material, with one recommendation.
+- **Behaviour flow missing:** for a repository, use `rg --files` / `rg -l` to find entry-point files and annotations (`*Controller*`, `*Handler*`, `*Listener*`, `*Consumer*`, `main`, route decorators). Do not read function bodies yet. Offer up to four flows matching the user's words; if necessary, first group by package. Selecting a package is not selecting a flow: if several remain, ask for the specific flow next. For documents, offer the described flows instead.
+- **Several views:** retain the full list and ask only for unresolved subjects/questions; do not replace it with the primary intent. Once all are ready, proceed without another confirmation.
+- **Delegated choice:** "whatever" / "you decide" permits the grounded recommendation; state it and proceed. Do not invent an unavailable repository, document or output location.
 
-"Whatever", "you decide" or an equivalent takes the recommended option; state the assumption in the recap.
+## Granularity, recap and start
 
-## Recap, then start
-
-One line, then start evidence without a second confirmation. The user can correct it with a new message at any time.
-
-```
-<type> · <subject> · answers <question> · <node unit>, nodes required by the evidence · <type-specific layout> · <output directory> · <CodeGraph | direct tracing>. Say so to drill into a node later.
-```
+Apply [Granularity](graph-common.md#granularity), including when intake is skipped. Carry the user's level and coverage into the recap; visual minimalism does not remove requested facts.
 
-Example: `sequence · order module, OrderController.create flow · answers the call order of placing an order · step-level nodes, as required · participants across and time down · docs/qgraphflow/order-create-sequence/ · direct tracing. Say so to drill into a step later.`
+After scope is ready, determine the evidence path using [evidence-sources.md](evidence-sources.md#codegraph-preflight). A directory alone never proves CodeGraph availability. Use document evidence for document-only work; report CodeGraph only after checking the tool and current index, otherwise direct tracing. If not checked yet, say evidence preflight is pending rather than claiming either tool was used.
 
-If bounded layout fails, report the blocking nodes and relationships and propose separate views with explicit coverage of the original model; never silently reduce the requested detail.
+Give one compact recap covering all requested views, subject/question, granularity/coverage, output directory and the actual evidence status, then start without another confirmation. Do not present internal schema fields as questions for the user. If bounded layout fails, report the blockers and propose views covering the original facts; never silently reduce detail or change an explicit graph count.

package/skills/q-flow/references/layout-routing.md

@@ -0,0 +1,47 @@
+# Compact semantic layout and orthogonal routing
+
+Shared entry points: `orthogonal-routing.js` for outline ports, corridors and labels; `layout-refinement.js` for bounded geometry refinement. `compile-layout.mjs` supplies measured ELK/sequence candidates; `architecture-overview.js` supplies measured section grids. The browser runs the same solver in an inline offline Worker, keeps controls responsive, and cancels pending work on reset/view disposal. Local moves freeze unaffected paths and labels; a growing card may displace an adjacent ownership frame together with its members within the movement bound. Page, SVG and PNG consume the same saved `via` and `labelAt`.
+
+## Eight steps
+
+1. Measure full titles, body, badges, notes, labels and notation before placement.
+2. Keep categories, flow, explicit ranks/order, ownership, hierarchy and section membership.
+3. Measure shared column tracks and row baselines, preserve existing alignment during local refinement, and reserve local connector space without breaking the grid.
+4. Rank actual outline side pairs and separate incident ports. Use a next-nearest feasible pair when the nearest corridor or its label space is blocked.
+5. Use horizontal/vertical routes, short clear paths and fewer turns.
+6. Resolve obstacles jointly: ports, paths, labels, permitted local moves and section-local gaps. Reroute after movement.
+7. Compare canonical/reversed/rotated edge priorities; earlier lines are not permanently protected. Separate parallel relations; retain traceable crossings when bounded alternatives do not improve the result.
+8. Reclaim excess space and accept the whole candidate only after the quality gate passes. Its thresholds are unchanged; the endpoint-stub rule measures a straight route by its real length rather than by its authored guide point.
+
+## Seven constraints
+
+- Hard: complete facts, directed semantics, ownership, required notation, clear text, valid endpoints and orthogonal routing geometry. Soft: area, route length, bends, crossings and movement.
+- Nearest means actual outline distance; an obstacle-free straight route is Manhattan shortest. Multi-relation results are bounded heuristics, not proofs of global optimality.
+- Safety, reading and local corridor spacing are distinct. Overview grids retain the reference spacing; only identified sections/band corridors expand.
+- For the eight non-sequence relation views, labels stay centred on their own straight segment, with complete measured bounds. Slide along that segment, reserve a wider gap or reroute when space is insufficient; never move a label off its line. Sequence message labels retain their notation-specific placement.
+- Priority/rip-up passes are deterministic by explicit primary flow, constrained branch and stable edge ID, independent of raw edge-array order.
+- At most 60 local layout evaluations, 156 units of movement from the operation origin, and 60,000–240,000 visibility-state visits per priority pass, scaled by edge count; each corridor uses at most 4,000 visits. Node generation keeps the existing 30-second ELK hang guard. Exhaustion reports `provenImpossible: false`, attempted alternatives, reason and affected IDs; retain the best quality-valid candidate.
+- Self relations, cycles, reverse directions, multiple relations and disconnected peers remain complete and individually traceable.
+
+## Type boundaries and editing
+
+Architecture, deployment, ER, class, dataflow and usecase retain their actual outline anchors and relationship markers. Flowchart/state keep distinct decision-side corridors, declared main paths and lifecycle endpoints. New state self-transitions use orthogonal brackets with inline labels; preserved older layouts retain their stored arc notation. Sequence uses measured participant-span and event-row constraints: preserve message order, reply pairing, activation endpoints, fragment scopes and horizontal message notation; local moves are horizontal only. A widened participant header shifts every later participant, fragment frame and saved x-coordinate right (at most 156 units) and restores message spans with the same constraints the generator uses.
+
+Overview card drags reorder peers without reparenting. Other drags keep the user's positions, expand real ownership frames as needed and reroute; Arrange may compact selected/one-hop peers or the full view within bounds. Full text changes grow the measured element first. Apply installs a complete checked candidate atomically; failure retains the inspector draft and last valid canvas. Collections remain keyed by `viewId`. Cancel, reset and save failure preserve existing per-view behavior. Preserve-mode generation does not recompute authored routes.
+
+## Examples
+
+Chinese: “绘制订单支付流程图，保留成功与失败分支；组件间距适中，最近边正交连接，长关系说明完整显示。”
+English: “Draw the deployment diagram for checkout, payment and the database. Keep runtime boundaries, compact related nodes, and route from the nearest feasible outlines without clipping labels.”
+
+For architecture use the same evidenced system in all three views: calls/dependencies, reusable platform capabilities, and source-proven project/internal layers. Reference pictures supply styling only, never new runtime or Maven facts.
+
+## Validation
+
+Run all Node tests, rebuild the offline Viewer, regenerate all nine types plus both overview templates, and run the two-theme/three-viewport browser matrix by view ID. Exercise editing, movement, failure rollback, repeated views, persistence, real SVG/PNG downloads and an isolated packaged CLI. Record semantic, geometry, browser and package evidence separately. Browser composition events do not attest native OS input-method candidate UI.
+
+## Dedicated layout templates
+
+The generator measures complete content before choosing positions. Eleven presentation templates share the same routing, geometry checks, browser editing and exports. Platform capabilities use section matrices; engineering uses layers with parallel support; component relations cluster related components within real ownership; flowcharts use a main spine and side branches; sequence uses participant spans and event rows; ER uses related-entity matrices; deployment uses runtime tiers inside actual boundaries; class uses contract hierarchies; state uses lifecycle branches; use cases place actors outside the system; data flow separates processing and storage.
+
+Template placement never creates ownership, relationships or evidence. Authored ranks and direction remain authoritative. Dense inputs keep a quality-valid layered candidate when templates add crossings, worsen the aspect band, fail validation or cost more than 25% extra in normalized area/routing; `--verbose` reports the template, attempts and fallback. No supported facts are removed. Small layouts use their content bounds rather than a fixed canvas. The fixed botanical palette supports light/dark themes and stable module colors across views; it introduces no authored color field.