qgraphflow 0.0.6 → 0.0.7

package/skills/q-flow/references/types/architecture.md

@@ -1,41 +1,61 @@
 # architecture
 
-Components and their dependencies: who calls, reads or depends on whom, inside which runtime or ownership boundary. Read with `graph-common.md`.
+Read with `graph-common.md`. Architecture offers three views:
+
+- `meta.architectureView: "relations"` (default): 组件关系架构图 — calls and dependencies.
+- `capabilities`: 平台能力架构图 — platform foundation, capabilities, business integration and rules.
+- `engineering`: 工程分层架构图 — project organization and one component's internal layers, with parallel support.
 
 | Node `kind` | Group `kind` | Edge `kind` |
 | --- | --- | --- |
-| `external`, `config`, `framework`, `security`, `service`, `business`, `data`, `failure`, `system`, `component`, `database` | `runtime`, `security`, `ownership`, `external` | `request`, `call`, `data`, `success`, `failure`, `framework`, `optional`, `depends` |
+| `external`, `config`, `framework`, `security`, `service`, `business`, `data`, `failure`, `system`, `component`, `database` | `runtime`, `security`, `ownership`, `external` | `request`, `call`, `data`, `success`, `failure`, `framework`, `optional`, `depends`, `aggregates`, `inherits`, `provides` |
+
+## Components and evidence
+
+Use `business` for one or two business centres, `service` for entry points, `component` for internal modules, `data` for repositories/caches/queues as code, `database` for stores, `external` for systems outside the repo (no `source`), `security` for filters/auth, `config` for configuration, `framework` for framework-owned pieces, `failure` for explicit failure handling and `system` for a subsystem shown as one box.
+
+`label` names the component at the chosen level; `subtitle` states its responsibility. Use exact class/route/table/package names when relevant; supporting detail goes in `facts` or overview body. Keep conceptual scope explicit; names/config do not prove status or runtime compatibility.
+
+Edges follow calls/data: `request` HTTP/RPC, `call` in-process/service calls, `data` reads/writes, `success`/`failure` outcome branches, `framework` wiring, `optional` conditional paths. Label with the operation, usually up to 3 words; put details in `facts`. `site` anchors the call, construction or config that establishes repository evidence.
+
+Direction is fixed: `aggregates` aggregator → member; `inherits` child → parent; `provides` provider → consumer; `depends` dependent → dependency. These are not runtime calls. Never reverse them to match the drawing's reading direction or delete them to simplify layout.
+
+`groupId` / `parentId` encode real ownership: `runtime` process/JVM/container, `ownership` module/team, `security` trust zone, `external` outside systems. Draw an area-wide filter as a security boundary, not edges to every component. Nodes may be ungrouped.
 
-## Rules
+## Overview structure
 
-- `business` is the business centre (one or two per view); `service` for services and entry points, `component` for internal modules, `data` for repositories / caches / queues as code, `database` for the store itself, `external` for systems outside the repository (clients, gateways, third parties — no `source`), `security` for auth / filters, `config` for configuration, `framework` for framework-owned runtime pieces, `failure` for an explicit failure handler or dead-letter path, `system` for a whole subsystem shown as one box.
-- Edges follow the direction of the call or data movement: `request` for HTTP / RPC into the system, `call` for in-process or service calls, `data` for reads / writes, `depends` for configuration or library dependency, `success` / `failure` for outcome branches, `framework` for wiring supplied by a framework, `optional` for conditional paths. Label with the operation (`createOrder`, `publish order.created`), not the kind.
-- `groupId` puts a node inside a real boundary (`runtime` = one process / JVM / container, `ownership` = team or module, `security` = trust zone, `external` = outside world). Nodes outside every group are fine.
-- Keep 6–12 nodes per view; a second view beats a crowded one. Every node needs a `source` anchor except externals and framework pieces.
+Either overview requires non-empty `layout.sections`. Each section has a unique `id`, non-empty `title`, and `mode`: `stack` (layers), `grid` (wrapping peers), `row` (parallel regions), or `note` (explanations). Non-notes have non-empty `items`: each exactly one `{ "nodeId": "..." }`, `{ "groupId": "..." }`, or nested section. Group references include real members and child groups. Every node is placed exactly once. IDs must not collide with nodes/groups. `detailOf` optionally names the overall component represented by a detail section. Sections describe presentation only; keep real ownership unchanged.
+
+Optional section `text` contains paragraph strings and `source` uses the common anchor. A note requires non-empty text and no items. Nodes accept `overviewText` paragraph strings and `badges`: `{ "label": "JDK 17", "role": "version", "evidence": "document", "source": { ... } }`. Roles: `status`, `version`, `requirement`; evidence kinds and optional anchors follow common rules. Empty arrays are valid on nodes. Reference-image status/version/rules are document claims, not verified source.
+
+Repeated architecture views require distinct `meta.viewId`; all identities must be unique, including legacy type IDs. Collections have 1–32 views; other types stay unique. Menus show capabilities/engineering/relations as independent architecture types, adding titles for repeated templates.
+
+Use reference bands/cards/badges. Section `tone` / node `overviewTone`: `white`, `subtle`, `blue`, `green`, `lavender`, `plain`; section `frame`: `solid`, `dashed`, `none`; grid `columns`: 1–16; row `weights`: positive numbers per item (detail/support `[2,1]`); node `overviewAccent`: boolean stripe. Use tones and grids to clarify each fictional or public model. Style is not evidence.
 
 ## Minimal valid skeleton
 
 ```json
 {
-  "meta": { "title": "Order service · components", "sourceRef": "repo@main", "diagramType": "architecture", "locale": "zh-CN" },
-  "groups": [{ "id": "process", "label": "order-service process", "kind": "runtime" }],
+  "meta": { "title": "Platform integration", "diagramType": "architecture", "architectureView": "capabilities", "viewId": "platform-overview", "sourceRef": "Conceptual example", "locale": "en" },
   "nodes": [
-    { "id": "client", "label": "Web client", "kind": "external", "subtitle": "calls POST /orders" },
-    { "id": "api", "label": "OrderController", "kind": "service", "groupId": "process", "module": "order", "source": { "kind": "source", "file": "src/api/orders.js", "lineStart": 1, "lineEnd": 40, "symbol": "OrderController" } },
-    { "id": "service", "label": "OrderService", "kind": "business", "groupId": "process", "module": "order", "subtitle": "createOrder · payOrder", "source": { "kind": "source", "file": "src/services/order-service.js", "lineStart": 6, "lineEnd": 49 } },
-    { "id": "db", "label": "orders DB", "kind": "database", "groupId": "process", "module": "order", "source": { "kind": "schema", "file": "db/schema.sql", "lineStart": 1, "lineEnd": 31 } }
+    { "id": "platform", "label": "Platform", "kind": "system", "module": "platform", "overviewText": ["Shared application capabilities"], "badges": [] },
+    { "id": "application", "label": "Application", "kind": "component", "module": "application", "overviewText": [], "badges": [] }
   ],
-  "edges": [
-    { "id": "e1", "source": "client", "target": "api", "kind": "request", "label": "HTTP", "evidence": "source" },
-    { "id": "e2", "source": "api", "target": "service", "kind": "call", "label": "createOrder", "evidence": "source" },
-    { "id": "e3", "source": "service", "target": "db", "kind": "data", "label": "save order", "evidence": "source" }
-  ]
+  "edges": [{ "id": "capabilities", "source": "platform", "target": "application", "kind": "provides", "label": "Shared capabilities", "evidence": "inference" }],
+  "layout": { "sections": [
+    { "id": "platform-layer", "title": "Platform", "mode": "stack", "tone": "blue", "items": [{ "nodeId": "platform" }] },
+    { "id": "application-layer", "title": "Applications", "mode": "grid", "tone": "green", "items": [{ "nodeId": "application" }] },
+    { "id": "scope-note", "title": "Evidence scope", "mode": "note", "text": ["Conceptual structure, without source implementation claims."] }
+  ] }
 }
 ```
 
+For relations, omit `architectureView` and `layout.sections`.
+
+Generation measures full text. Unlock to reorder peers within the same section/group. Details edit body/badges/sections; apply relayouts, failure keeps the draft/valid canvas, cancel discards. Save keeps order/style; switch keeps each view; reset affects only the current view.
+
 ## Frequent validation errors
 
-- `node X.kind is unsupported for architecture` — you used a kind from another type (`actor`, `process`, `entity`); pick from the table.
-- `node X.groupId does not name a group` — add the group to `groups` or remove `groupId`.
-- `edge e.evidence is unsupported` — one of `source code config schema test document framework inference`.
-- Layout diagnostics after generation (`group.member-inset`, `route.*`) mean the view is too dense: split into two views rather than removing facts.
+Reject unknown kinds/evidence, missing references/geometry and duplicate/missing placements. Report blockers; never drop facts or shrink text.
+
+`layout.overviewConnections`: `within-category` (default) or `all`; categories are deepest sections. Page/export hide cross-category edges by default, retaining JSON/details. To show required cross-category dependencies, use `all` or relations.

package/skills/q-flow/references/types/class.md

@@ -10,6 +10,7 @@ Types and their structural relationships: inheritance, implementation, compositi
 
 - `attributes` and `methods` are arrays of strings in UML form (`+cents: number`, `+charge(orderId, amount): Promise<Result>`); list the real members, keep declared types. `interface` and `abstract` render with their stereotype.
 - Edge direction: `inheritance` child → parent; `implementation` class → `interface` (the target must be an interface); `composition` / `aggregation` whole → part (diamond at the whole); `association` from the holder of the reference to the referenced type; `dependency` user → used (`new`, parameter, return type).
+- Edge `site`: the `extends` / `implements` clause or the field that holds the association.
 - `sourceMultiplicity` / `targetMultiplicity` (`1`, `*`, `0..1`, `1..*`, `2..4`) are allowed only on `association`, `aggregation` and `composition`.
 - Optional `layout.rank` puts parents / interfaces above their children; when given, a child must not rank above its parent.
 - Keep 5–10 classes per view; show the members that matter for the question, but never fabricate ones.
@@ -26,12 +27,18 @@ Types and their structural relationships: inheritance, implementation, compositi
     { "id": "item", "label": "OrderItem", "kind": "class", "attributes": ["+sku: string", "+quantity: number"], "source": { "kind": "source", "file": "src/domain/order.js", "lineStart": 5, "lineEnd": 15 } }
   ],
   "edges": [
-    { "id": "c1", "source": "gateway", "target": "provider", "kind": "inheritance", "evidence": "source" },
-    { "id": "c2", "source": "order", "target": "item", "kind": "composition", "label": "items", "sourceMultiplicity": "1", "targetMultiplicity": "1..*", "evidence": "source" }
+    { "id": "c1", "source": "gateway", "target": "provider", "kind": "inheritance", "evidence": "source", "site": { "file": "src/domain/payment-provider.js", "lineStart": 8, "symbol": "PaymentProvider" } },
+    { "id": "c2", "source": "order", "target": "item", "kind": "composition", "label": "items", "sourceMultiplicity": "1", "targetMultiplicity": "1..*", "evidence": "source", "site": { "file": "src/domain/order.js", "lineStart": 19, "symbol": "items" } }
   ]
 }
 ```
 
+## Layout
+
+Contract parents above implementations; complete member compartments and lateral dependencies. Geometry is derived from full content; never shorten facts to fit the template.
+
+Layout keeps attributes, methods, relation direction and endpoint markers; routes leave the nearest feasible class outline.
+
 ## Frequent validation errors
 
 - `edge c implementation target must be an interface` — use `inheritance` for an abstract base class, `implementation` only towards `kind: "interface"`.

package/skills/q-flow/references/types/dataflow.md

@@ -10,6 +10,7 @@ How data moves between external entities, processes and data stores (Gane–Sars
 
 - `external` is a source or sink outside the system (user, partner API — no `source`); `process` transforms data (a service method, a job); `dataStore` holds it (table group, file, cache, topic).
 - Every edge is `data` and its `label` names the data that flows (`customerId, items`, `paid orders`), not the operation. Direction is the direction the data moves; a request and its response are two edges when both carry data.
+- Edge `site`: the read or write call that moves the data.
 - Flows directly between stores, or from an external entity to a store, are kept when the source shows them; do not insert a process to make the notation "pure".
 - `groups` mark ownership (`ownership`) or the outside world (`external`) only when the boundary is real. Anchor processes to the function, stores to the schema / file writer.
 - Keep 6–10 nodes per view; one pipeline or one request path per view. `module` follows the evidenced domain of each process and store (the service, the cache layer, the topic); an external that belongs to a channel carries it too.
@@ -27,14 +28,20 @@ How data moves between external entities, processes and data stores (Gane–Sars
     { "id": "csv", "label": "settlement CSV", "kind": "dataStore" }
   ],
   "edges": [
-    { "id": "d1", "source": "buyer", "target": "create", "kind": "data", "label": "customerId, items", "evidence": "source" },
-    { "id": "d2", "source": "create", "target": "orders", "kind": "data", "label": "order", "evidence": "source" },
-    { "id": "d3", "source": "orders", "target": "export", "kind": "data", "label": "paid orders", "evidence": "source" },
-    { "id": "d4", "source": "export", "target": "csv", "kind": "data", "label": "settlement rows", "evidence": "source" }
+    { "id": "d1", "source": "buyer", "target": "create", "kind": "data", "label": "customerId, items", "evidence": "source", "site": { "file": "src/services/order-service.js", "lineStart": 15, "symbol": "createOrder" } },
+    { "id": "d2", "source": "create", "target": "orders", "kind": "data", "label": "order", "evidence": "source", "site": { "file": "src/services/order-service.js", "lineStart": 30, "symbol": "save" } },
+    { "id": "d3", "source": "orders", "target": "export", "kind": "data", "label": "paid orders", "evidence": "source", "site": { "file": "src/jobs/settlement-export.js", "lineStart": 8, "symbol": "findPaid" } },
+    { "id": "d4", "source": "export", "target": "csv", "kind": "data", "label": "settlement rows", "evidence": "source", "site": { "file": "src/jobs/settlement-export.js", "lineStart": 19, "symbol": "writeFile" } }
   ]
 }
 ```
 
+## Layout
+
+External inputs, processing stages and storage regions connected by the actual data relationships. Geometry is derived from full content; never shorten facts to fit the template.
+
+Layout keeps process, store and external symbols, data names and flow direction.
+
 ## Frequent validation errors
 
 - `edge d.kind is unsupported for dataflow` — only `data`; the operation belongs in the label.

package/skills/q-flow/references/types/deployment.md

@@ -11,7 +11,7 @@ Where runtime units run and how they connect: hosts, networks, containers, datab
 - `container` for a running container / process, `node` for a VM or machine, `device` for hardware or a client device, `artifact` for a deployable file (jar, image, bundle), `service` for a managed / logical service, `database` for stores, `external` for third-party endpoints (no `source`).
 - Groups model real boundaries from the manifests: `network` (compose networks, VPC subnets), `host`, `cluster`, `namespace`; nest with `parentId`. A node belongs to one group; when a unit sits on two networks, place it by its primary role and say so in `facts`.
 - Edges: `network` for traffic (label with port or protocol), `depends` for `depends_on` / environment-variable references, `deploy` from a unit to the artifact it runs. Direction follows the connection initiator.
-- Anchor each unit to its service block in the manifest (`source.kind: "config"`); evidence for edges is `config` or `document`.
+- Anchor each unit to its service block in the manifest (`source.kind: "config"`); evidence for edges is `config` or `document`; an edge `site` is the manifest line declaring the port, `depends_on` or variable.
 
 ## Minimal valid skeleton
 
@@ -25,13 +25,21 @@ Where runtime units run and how they connect: hosts, networks, containers, datab
     { "id": "postgres", "label": "postgres", "kind": "database", "groupId": "data", "source": { "kind": "config", "file": "deploy/docker-compose.yml", "lineStart": 30, "lineEnd": 33 } }
   ],
   "edges": [
-    { "id": "d1", "source": "browser", "target": "api", "kind": "network", "label": "443", "evidence": "config" },
-    { "id": "d2", "source": "api", "target": "postgres", "kind": "depends", "label": "DATABASE_URL", "evidence": "config" }
+    { "id": "d1", "source": "browser", "target": "api", "kind": "network", "label": "443", "evidence": "config", "site": { "file": "deploy/docker-compose.yml", "lineStart": 12, "symbol": "443" } },
+    { "id": "d2", "source": "api", "target": "postgres", "kind": "depends", "label": "DATABASE_URL", "evidence": "config", "site": { "file": "deploy/docker-compose.yml", "lineStart": 15, "symbol": "DATABASE_URL" } }
   ]
 }
 ```
 
+## Layout
+
+Runtime tiers packed inside the existing network/host ownership hierarchy. Geometry is derived from full content; never shorten facts to fit the template.
+
+Layout keeps nested runtime boundaries and cross-boundary relations; boundaries grow around real members, never reparent.
+
 ## Frequent validation errors
 
 - `group X.parentId does not name a group` — nested networks must list their parent first.
 - `node X.kind is unsupported for deployment` — `service` here is a deployment unit; application-code kinds (`component`, `business`) belong to architecture.
+
+Optional node `layout.tier` accepts `external`, `application`, `infrastructure`, or `data`, arranged top to bottom. Without a hint: external nodes use external, databases data, queues/caches infrastructure, and other nodes application. It is a display hint, never a new runtime fact.

package/skills/q-flow/references/types/er.md

@@ -11,6 +11,7 @@ Tables (entities), their columns and keys, and the relationships with cardinalit
 - Every entity has a non-empty `fields` array; each field `{ "name", "type", "key"?: "PK" | "FK" | "UK", "nullable"?: boolean }` copied from the DDL / mapping (types verbatim, `nullable: true` only when the column allows NULL). List every column of the table you show; do not invent columns, do not infer foreign keys that the schema does not declare.
 - A relationship needs both `sourceCardinality` and `targetCardinality`, each one of `1`, `0..1`, `*`, `1..*`, `0..*`. Source is the referenced (parent) side, target the referencing side: `customers (1) → orders (0..*)`. A UNIQUE foreign key gives `1 → 0..1`. Label with the verb in the locale's language (`places`, `contains`).
 - Anchor each entity to its `CREATE TABLE` (or ORM class) with `source.kind: "schema"`. Keep 4–8 entities per view; large schemas become several views by aggregate.
+- Edge `site`: the foreign-key constraint or mapping annotation; `symbol` is the referenced table.
 
 ## Minimal valid skeleton
 
@@ -24,11 +25,17 @@ Tables (entities), their columns and keys, and the relationships with cardinalit
       "fields": [{ "name": "id", "type": "VARCHAR(32)", "key": "PK", "nullable": false }, { "name": "customer_id", "type": "BIGINT", "key": "FK", "nullable": false }, { "name": "status", "type": "VARCHAR(16)", "nullable": false }] }
   ],
   "edges": [
-    { "id": "r1", "source": "customers", "target": "orders", "kind": "relationship", "label": "places", "sourceCardinality": "1", "targetCardinality": "0..*", "evidence": "schema" }
+    { "id": "r1", "source": "customers", "target": "orders", "kind": "relationship", "label": "places", "sourceCardinality": "1", "targetCardinality": "0..*", "evidence": "schema", "site": { "file": "db/schema.sql", "lineStart": 11, "symbol": "customers" } }
   ]
 }
 ```
 
+## Layout
+
+A related-entity matrix with full field columns and dedicated cardinality/label corridors. Geometry is derived from full content; never shorten facts to fit the template.
+
+Layout keeps fields, relation direction, cardinalities and endpoint symbols; routes leave the nearest feasible entity outline.
+
 ## Frequent validation errors
 
 - `node X.fields must be an array` / entity without fields — every entity lists at least one field.

package/skills/q-flow/references/types/flowchart.md

@@ -14,6 +14,7 @@ The steps and decisions of one function, use case or job, top to bottom. Read wi
 - The main path must read downward. When the happy path is not obvious from the edges, list it in `layout.primaryPath` (node ids in order, each pair joined by a directed edge). Feedback / retry edges are allowed and route around the outside.
 - `module` per step is the subsystem whose work the step performs: a call into inventory is inventory's work, a payment check is payment's, a pure control decision keeps the owning component, `start` / `end` take the caller. A flow that really lives inside one subsystem keeps one module; `module.single-tone` only asks you to check.
 - A `process`, `input`, `output` or `subprocess` has exactly one outgoing edge; only a `decision` branches (`flowchart.process-branch`).
+- Edge `site`: the call that runs a step, or the condition line of a `yes` / `no` branch.
 - Anchor each step to the lines that implement it. Keep 8–14 nodes; merge trivial assignments into the step that owns them.
 
 ## Minimal valid skeleton
@@ -31,15 +32,21 @@ The steps and decisions of one function, use case or job, top to bottom. Read wi
     { "id": "failed", "label": "throw 402", "kind": "end", "module": "orders" }
   ],
   "edges": [
-    { "id": "f1", "source": "start", "target": "reserve", "kind": "flow", "evidence": "source" },
-    { "id": "f2", "source": "reserve", "target": "ok", "kind": "flow", "evidence": "source" },
-    { "id": "f3", "source": "ok", "target": "persist", "kind": "yes", "label": "yes", "evidence": "source" },
-    { "id": "f4", "source": "ok", "target": "failed", "kind": "no", "label": "no", "evidence": "source" },
-    { "id": "f5", "source": "persist", "target": "done", "kind": "success", "evidence": "source" }
+    { "id": "f1", "source": "start", "target": "reserve", "kind": "flow", "evidence": "source", "site": { "file": "src/services/order-service.js", "lineStart": 17, "symbol": "reserve" } },
+    { "id": "f2", "source": "reserve", "target": "ok", "kind": "flow", "evidence": "source", "site": { "file": "src/services/order-service.js", "lineStart": 25, "symbol": "ok" } },
+    { "id": "f3", "source": "ok", "target": "persist", "kind": "yes", "label": "yes", "evidence": "source", "site": { "file": "src/services/order-service.js", "lineStart": 32, "symbol": "persist" } },
+    { "id": "f4", "source": "ok", "target": "failed", "kind": "no", "label": "no", "evidence": "source", "site": { "file": "src/services/order-service.js", "lineStart": 27, "symbol": "failed" } },
+    { "id": "f5", "source": "persist", "target": "done", "kind": "success", "evidence": "source", "site": { "file": "src/services/order-service.js", "lineStart": 34, "symbol": "done" } }
   ]
 }
 ```
 
+## Layout
+
+A vertical main spine with separate side branches and outer feedback corridors. Geometry is derived from full content; never shorten facts to fit the template.
+
+Layout keeps decision exits on distinct sides, the declared main path and full branch labels.
+
 ## Frequent validation errors
 
 - `layout.primaryPath has no directed edge from A to B` — the path must follow existing edges; fix the path or add the missing edge.

package/skills/q-flow/references/types/sequence.md

@@ -1,6 +1,6 @@
 # sequence
 
-Calls and returns along one flow, with activation bars and fragments. Read with `graph-common.md`; every sequence rule the validator checks is on this page.
+Calls and returns along one flow, with activation bars and fragments. Read with `graph-common.md`.
 
 | Node `kind` | Group `kind` | Edge `kind` |
 | --- | --- | --- |
@@ -8,14 +8,15 @@ Calls and returns along one flow, with activation bars and fragments. Read with
 
 ## Participants (nodes)
 
-- One node per lifeline: `actor` for the human or caller, `service` / `participant` for code you read, `external` for systems outside the repository, `database` for a store or repository. Participants never have `groupId`.
+- One node per lifeline: `actor` for the human or caller, `service` / `participant` for code you read, `external` for systems outside the repository, `database` for a store. Participants never have `groupId`.
 - Left-to-right order follows first appearance in the messages; `layout.participantOrder` (all ids, once) only reproduces an existing convention.
+- 8 participants / 20 messages is advisory; user detail wins. Follow common splitting rules.
 
 ## Messages (edges)
 
 - Every message has `order` (positive integer, unique, increasing in time; gaps allowed), a non-empty `label` (method or message with the important arguments), `evidence`, and `kind`: `sync` (caller waits), `async` (no wait: events, publish), `return` (reply, drawn dashed).
-- A `return` carries `"replyTo": "<call id>"`: the call is an earlier `sync` / `async` with reversed endpoints, has at most one return, and both sit in the same fragment operand. Unpaired returns are legal but drawn without pair colour and `C1` labels.
-- Self-messages are allowed. Alternative outcomes of one call are one return labelled `ok | declined`, not two.
+- A `return` carries `"replyTo": "<call id>"`: the call is an earlier `sync` / `async` with reversed endpoints, has at most one return, and both sit in the same fragment operand.
+- Self-messages are allowed. Alternative outcomes of one call are one return (`ok | declined`).
 
 ## Activation bars (`executions`)
 
@@ -31,8 +32,8 @@ Top-level array of `{ "id", "participantId", "start": { "edgeId", "at" }, "end":
 ```
 
 - `alt`: two or more guarded operands, optional `else` last. `opt`: one guarded operand. `loop`: one guarded operand plus `loop: { "min", "max" | "*" }`. `par`: two or more operands with `label` instead of `guard` (concurrent; vertical order is not time).
-- `edgeIds` lists the operand's messages; an operand may instead or also carry `body` text or a child fragment (`parentId` + `parentOperandId`). Operand ids are required except on `alt`; a message belongs to at most one operand; successive operands' `order` ranges must not interleave. A call and its return, and a bar's start and end, stay in one operand path.
-- Guards are display text — copy the real condition. Only fragments the source establishes (an `if`, a retry loop, concurrent handlers).
+- `edgeIds` lists the operand's messages; an operand may instead or also carry `body` text or a child fragment (`parentId` + `parentOperandId`). Operand ids are required except on `alt`; a message belongs to at most one operand; successive operands' `order` ranges must not interleave.
+- Guards are display text — copy the real condition. Only fragments the source establishes (`if`, retry loop, concurrent handlers).
 
 ## Minimal valid skeleton
 
@@ -41,9 +42,9 @@ Top-level array of `{ "id", "participantId", "start": { "edgeId", "at" }, "end":
   "meta": { "title": "POST /orders → createOrder", "sourceRef": "repo@main", "diagramType": "sequence", "locale": "zh-CN" },
   "nodes": [
     { "id": "client", "label": "caller", "kind": "actor" },
-    { "id": "service", "label": "OrderService", "kind": "service", "source": { "kind": "source", "file": "src/services/order-service.js", "lineStart": 15, "lineEnd": 37 } },
-    { "id": "payments", "label": "PaymentProvider", "kind": "external", "source": { "kind": "source", "file": "src/domain/payment-provider.js", "lineStart": 2, "lineEnd": 6 } },
-    { "id": "bus", "label": "EventBus", "kind": "participant", "source": { "kind": "source", "file": "src/events/bus.js", "lineStart": 13, "lineEnd": 17 } }
+    { "id": "service", "label": "OrderService", "kind": "service", "source": { "kind": "source", "file": "src/order-service.js", "lineStart": 15, "lineEnd": 37 } },
+    { "id": "payments", "label": "PaymentProvider", "kind": "external", "source": { "kind": "source", "file": "src/payment.js", "lineStart": 2, "lineEnd": 6 } },
+    { "id": "bus", "label": "EventBus", "kind": "participant", "source": { "kind": "source", "file": "src/bus.js", "lineStart": 13, "lineEnd": 17 } }
   ],
   "groups": [
     { "id": "outcome", "label": "payment result", "kind": "alt", "operands": [
@@ -51,10 +52,10 @@ Top-level array of `{ "id", "participantId", "start": { "edgeId", "at" }, "end":
       { "id": "declined", "guard": "else", "edgeIds": [], "body": "release inventory, throw 402" } ] }
   ],
   "edges": [
-    { "id": "m1", "source": "client", "target": "service", "kind": "sync", "label": "createOrder(items)", "order": 1, "evidence": "source" },
-    { "id": "m2", "source": "service", "target": "payments", "kind": "sync", "label": "charge(orderId, total)", "order": 2, "evidence": "source" },
+    { "id": "m1", "source": "client", "target": "service", "kind": "sync", "label": "createOrder(items)", "order": 1, "evidence": "source", "site": { "file": "src/order-service.js", "lineStart": 15 } },
+    { "id": "m2", "source": "service", "target": "payments", "kind": "sync", "label": "charge(orderId, total)", "order": 2, "evidence": "source", "site": { "file": "src/order-service.js", "lineStart": 28, "symbol": "charge" } },
     { "id": "m3", "source": "payments", "target": "service", "kind": "return", "label": "{ ok, transactionId }", "order": 3, "replyTo": "m2", "evidence": "source" },
-    { "id": "m4", "source": "service", "target": "bus", "kind": "async", "label": "publish(order.created)", "order": 4, "evidence": "source" },
+    { "id": "m4", "source": "service", "target": "bus", "kind": "async", "label": "publish(order.created)", "order": 4, "evidence": "source", "site": { "file": "src/order-service.js", "lineStart": 35, "symbol": "publish" } },
     { "id": "m5", "source": "service", "target": "client", "kind": "return", "label": "order | 402", "order": 5, "replyTo": "m1", "evidence": "source" }
   ],
   "executions": [
@@ -64,11 +65,14 @@ Top-level array of `{ "id", "participantId", "start": { "edgeId", "at" }, "end":
 }
 ```
 
+## Layout
+
+Layout widens participant gaps for full labels; message order, reply pairing, bars and fragments stay.
+
 ## Frequent validation errors
 
-- `edge m.order must be a positive integer for sequence` / `order duplicates N` — `--fix` renumbers in array order, or edit the number.
-- `edge r.replyTo m must reference a sync or async call from a return` / `endpoints must be reversed` / `must precede its return` — point at the right call; `--fix` fills it when exactly one candidate exists.
-- `group g.operands order ranges must be ordered and non-interleaving` — all messages of operand 1 come before operand 2; move a message or split the fragment.
-- `group g.operands[i].id is required` — `opt` / `loop` / `par` operands need ids (`--fix` adds `op1..`).
+- `edge m.order must be a positive integer for sequence` / `order duplicates N` — `--fix` renumbers in array order.
+- `edge r.replyTo m must reference a sync or async call from a return` / `endpoints must be reversed` / `must precede its return` — point at the right call; `--fix` fills a unique candidate.
+- `group g.operands order ranges must be ordered and non-interleaving` — all of operand 1 precedes operand 2: move a message or split the fragment.
 - `execution x.start endpoint m does not belong to participant p` — `send` ⇒ source, `receive` ⇒ target.
 - `Sequence group g needs explicit operands before automatic layout` — every fragment declares `operands`.

package/skills/q-flow/references/types/state.md

@@ -14,6 +14,7 @@ The lifecycle of one component or entity: states, the events that move between t
 - A guard is a condition the source checks, never a restatement of the source state (`state != RUNNING` on a transition out of `STARTING`). When an event leads every state to one target (shutdown, close), draw the transitions the source names per state and put "entered from any state on …" in the target's `facts`.
 - A `state` may carry `entry`, `do` and `exit`: one plain string each for what the source runs on entering the state, while it stays active and on leaving it (`"entry": "schedule the timeout, send the registration"`). Take an action out of a transition's `action` and into `entry` when the code runs it after the state is set; leave out the keys the source does not show, never invent a `do`.
 - Anchor each state to where it is declared (enum member, transition-table row, status constant). Tag the state the component exists to reach and stay in (`running`, `active`) with `tags: ["core"]`.
+- Edge `site`: the line that sets the target state; `symbol` is the target constant.
 - State colors are derived from the lifecycle and never written: the `core` state is green, a state with no way on (or only into a `final`) is slate, a state tagged `failure` is red, and the rest run warm to cool in the order the machine reaches them (orange, blue, teal, …). So always tag the goal state `core`: without one the states keep their module color. Use `tags: ["failure"]` only for an error or aborted state, not for every cancellation or timeout.
 - One machine per view; keep 5–10 states. States carry the component's `module`; a `choice` takes the module of the subsystem whose result it branches on; `initial` / `final` never carry a wash.
 
@@ -29,13 +30,19 @@ The lifecycle of one component or entity: states, the events that move between t
     { "id": "cancelled", "label": "cancelled", "kind": "state", "source": { "kind": "source", "file": "src/domain/order-state.js", "lineStart": 6, "lineEnd": 6 } }
   ],
   "edges": [
-    { "id": "s0", "source": "initial", "target": "created", "kind": "transition", "label": "new Order", "evidence": "source" },
-    { "id": "s1", "source": "created", "target": "paid", "kind": "transition", "label": "pay", "guard": "payment.ok", "evidence": "source" },
-    { "id": "s2", "source": "created", "target": "cancelled", "kind": "transition", "label": "cancel", "action": "release inventory", "evidence": "source" }
+    { "id": "s0", "source": "initial", "target": "created", "kind": "transition", "label": "new Order", "evidence": "source", "site": { "file": "src/domain/order.js", "lineStart": 22, "symbol": "CREATED" } },
+    { "id": "s1", "source": "created", "target": "paid", "kind": "transition", "label": "pay", "guard": "payment.ok", "evidence": "source", "site": { "file": "src/domain/order.js", "lineStart": 41, "symbol": "PAID" } },
+    { "id": "s2", "source": "created", "target": "cancelled", "kind": "transition", "label": "cancel", "action": "release inventory", "evidence": "source", "site": { "file": "src/domain/order.js", "lineStart": 47, "symbol": "CANCELLED" } }
   ]
 }
 ```
 
+## Layout
+
+Initial state, lifecycle bands, outcome branches and local self-transitions. Geometry is derived from full content; never shorten facts to fit the template.
+
+Layout keeps initial/final symbols, transition labels and the self-transition arc.
+
 ## Frequent validation errors
 
 - `edge s.guard must be a string` — guards and actions are plain text, not objects or booleans.

package/skills/q-flow/references/types/usecase.md

@@ -33,6 +33,12 @@ Actors and what they can do, with include / extend relationships between use cas
 }
 ```
 
+## Layout
+
+Actors outside the real system boundary and use cases in a compact internal matrix. Geometry is derived from full content; never shorten facts to fit the template.
+
+Layout keeps the system boundary, actor identity and include/extend direction.
+
 ## Frequent validation errors
 
 - `node X.groupId places an actor inside a system boundary` — remove `groupId` from actors.