@caddis/cli 0.4.44 → 0.4.46

package/bundles/codex/.codex/skills/frontend/flow-studio/references/patterns.md

@@ -0,0 +1,415 @@
+# Scenario recipes
+
+Each recipe shows how to express a domain scenario in a flow-studio model.
+All recipes listed below are **proven** and match an example file in `examples/`.
+
+## Common states
+
+You can start from these base states and adjust words to match your domain:
+
+| State id | Word | Tone | Border | Edge | Motion | Bucket |
+|---|---|---|---|---|---|---|
+| `ok` | OK | ok | solid | flow | flow | good |
+| `planned` | PLANNED | muted | dashed | dash | flow-slow | neutral |
+| `late` | LATE | warn | solid | flow | flow | neutral |
+| `breached` | BREACHED | crit | solid | flow | flow | gap |
+| `unknown` | NOT RECORDED | warn | dotted | dot | breathe | gap |
+
+---
+
+## 1. Data lineage and dependency impact
+
+- **Example file:** `examples/lineage.json`
+- **Scenario:** Trace data assets from ingestion sources through storage, pipelines, transformations, to consuming dashboards and applications.
+- **Typical columns:** Source, Host, Database, Pipeline, Tables, Refresher, Views, App, Dashboard.
+- **Typical lanes:** Customer Portal, Order Service, Data Warehouse, Reporting Platform. A lane without documentation uses `gap: true`.
+- **Node count guideline:** 15 to 30 nodes.
+- **Recommended inspector relations:**
+  - Upstream (`dir: "up"`, label: "Upstream sources")
+  - Downstream (`dir: "down"`, label: "Downstream consumers")
+  - Pages (`dir: "down"`, label: "Affected pages", filter: `{ "kind": "card" }`)
+- **Copy-paste skeleton:**
+
+```json
+{
+  "version": 1,
+  "meta": {
+    "title": "Customer Data Lineage",
+    "help": "Tracks customer record movement from OLTP to analytical reports.",
+    "asOf": "2026-10-06",
+    "source": "Data Governance Catalog"
+  },
+  "layout": "columns-lanes",
+  "columns": [
+    { "id": "src", "title": "Sources", "width": 180 },
+    { "id": "ingest", "title": "Ingestion", "width": 180 },
+    { "id": "wh", "title": "Warehouse", "width": 200 },
+    { "id": "bi", "title": "Reporting", "width": 180 }
+  ],
+  "lanes": [
+    { "id": "crm", "title": "CRM Core", "badge": "PROD", "badgeTone": "ok" },
+    { "id": "analytics", "title": "Analytics Engine", "badge": "PROD", "badgeTone": "ok" }
+  ],
+  "states": {
+    "ok": { "word": "LIVE", "tone": "ok", "border": "solid", "edge": "flow", "motion": "flow", "bucket": "good" },
+    "planned": { "word": "PLANNED", "tone": "muted", "border": "dashed", "edge": "dash", "motion": "flow-slow", "bucket": "neutral" }
+  },
+  "nodes": [
+    { "id": "crm-db", "kind": "card", "lane": "crm", "col": 0, "row": 0, "state": "ok", "title": "CRM Postgres" },
+    { "id": "cdc-pipe", "kind": "card", "lane": "crm", "col": 1, "row": 0, "state": "ok", "title": "CDC Stream" },
+    { "id": "dim-cust", "kind": "card", "lane": "analytics", "col": 2, "row": 0, "state": "ok", "title": "dim_customer" },
+    { "id": "dash-sales", "kind": "card", "lane": "analytics", "col": 3, "row": 0, "state": "ok", "title": "Sales Dashboard" }
+  ],
+  "links": [
+    { "id": "l1", "from": "crm-db", "to": "cdc-pipe", "state": "ok" },
+    { "id": "l2", "from": "cdc-pipe", "to": "dim-cust", "state": "ok" },
+    { "id": "l3", "from": "dim-cust", "to": "dash-sales", "state": "ok" }
+  ]
+}
+```
+
+---
+
+## 2. Ticket, case, or order lifecycle
+
+- **Example file:** `examples/ticket-lifecycle.json`
+- **Scenario:** Track service requests, customer tickets, or incident cases from creation to triage, engineering resolution, verification, and closure.
+- **Typical columns:** New, Triage, In Progress, Review, Waiting, Resolved, Closed.
+- **Typical lanes:** Tier 1 Support, Platform Engineering, Quality Assurance, Customer.
+- **Node count guideline:** 8 to 20 nodes.
+- **Recommended inspector relations:**
+  - Previous step (`dir: "up"`, label: "Came from")
+  - Next step (`dir: "down"`, label: "Goes to")
+  - Escalations (`dir: "down"`, label: "Escalated to")
+- **Copy-paste skeleton:**
+
+```json
+{
+  "version": 1,
+  "meta": {
+    "title": "Support Ticket Journey",
+    "help": "End-to-end support ticket triage and escalation workflow.",
+    "asOf": "2026-10-06",
+    "source": "HelpDesk Service API"
+  },
+  "layout": "columns-lanes",
+  "columns": [
+    { "id": "triage", "title": "Triage", "width": 160 },
+    { "id": "dev", "title": "Engineering", "width": 180 },
+    { "id": "qa", "title": "Verification", "width": 160 },
+    { "id": "done", "title": "Resolved", "width": 160 }
+  ],
+  "lanes": [
+    { "id": "support", "title": "Support Desk", "badge": "T1", "badgeTone": "ok" },
+    { "id": "eng", "title": "Platform Team", "badge": "T2", "badgeTone": "ok" }
+  ],
+  "states": {
+    "ontime": { "word": "ON TIME", "tone": "ok", "border": "solid", "edge": "flow", "motion": "flow", "bucket": "good" },
+    "risk": { "word": "AT RISK", "tone": "warn", "border": "dashed", "edge": "dash", "motion": "breathe", "bucket": "neutral" },
+    "breach": { "word": "BREACHED", "tone": "crit", "border": "solid", "edge": "flow", "motion": "flow", "bucket": "gap" }
+  },
+  "nodes": [
+    { "id": "inbound", "kind": "card", "lane": "support", "col": 0, "row": 0, "state": "ontime", "title": "Inbound Case" },
+    { "id": "diag", "kind": "card", "lane": "support", "col": 0, "row": 1, "state": "ontime", "title": "Initial Assessment" },
+    { "id": "bugfix", "kind": "card", "lane": "eng", "col": 1, "row": 0, "state": "risk", "title": "Patch Defect", "sla": 3600 },
+    { "id": "verify", "kind": "card", "lane": "support", "col": 2, "row": 0, "state": "ontime", "title": "Customer Verify" },
+    { "id": "closed", "kind": "card", "lane": "support", "col": 3, "row": 0, "state": "ontime", "title": "Case Closed" }
+  ],
+  "links": [
+    { "id": "l-triage", "from": "inbound", "to": "diag", "state": "ontime" },
+    { "id": "l-escalate", "from": "diag", "to": "bugfix", "state": "risk" },
+    { "id": "l-test", "from": "bugfix", "to": "verify", "state": "ontime" },
+    { "id": "l-reopen", "from": "verify", "to": "bugfix", "state": "risk", "kind": "loop-back", "label": "Failed test" },
+    { "id": "l-resolve", "from": "verify", "to": "closed", "state": "ontime" }
+  ]
+}
+```
+
+---
+
+## 3. Agent and customer journey
+
+- **Example file:** `examples/agent-journey.json`
+- **Scenario:** Trace user prompts into an autonomous agent loop (receive, analyze, plan, tool execution, critique, response).
+- **Typical columns:** Receive, Classify, Plan, Act, Validate, Respond.
+- **Typical lanes:** User, Agent Core, Tool Worker, Human Reviewer.
+- **Node count guideline:** 8 to 20 nodes.
+- **Recommended inspector relations:**
+  - Inputs (`dir: "up"`, label: "Context inputs")
+  - Outputs (`dir: "down"`, label: "Generated steps")
+  - Tool calls (`dir: "down"`, label: "External tools")
+- **Copy-paste skeleton:**
+
+```json
+{
+  "version": 1,
+  "meta": {
+    "title": "Autonomous Agent Loop",
+    "help": "Execution loop of an LLM agent with tool calls and human verification.",
+    "asOf": "2026-10-06",
+    "source": "Agent Orchestrator"
+  },
+  "layout": "columns-lanes",
+  "columns": [
+    { "id": "input", "title": "Input", "width": 160 },
+    { "id": "think", "title": "Reasoning", "width": 180 },
+    { "id": "exec", "title": "Tool Execution", "width": 180 },
+    { "id": "out", "title": "Response", "width": 160 }
+  ],
+  "lanes": [
+    { "id": "client", "title": "User Session", "badge": "USER", "badgeTone": "muted" },
+    { "id": "orchestrator", "title": "Agent Planner", "badge": "AI", "badgeTone": "ok" },
+    { "id": "mcp", "title": "Tool Worker", "badge": "MCP", "badgeTone": "accent" }
+  ],
+  "states": {
+    "ready": { "word": "READY", "tone": "ok", "border": "solid", "edge": "flow", "motion": "flow", "bucket": "good" },
+    "thinking": { "word": "ACTIVE", "tone": "accent", "border": "solid", "edge": "flow", "motion": "flow", "bucket": "neutral" },
+    "retry": { "word": "RETRY", "tone": "warn", "border": "dashed", "edge": "dash", "motion": "breathe", "bucket": "neutral" }
+  },
+  "nodes": [
+    { "id": "prompt", "kind": "card", "lane": "client", "col": 0, "row": 0, "state": "ready", "title": "User Prompt" },
+    { "id": "plan", "kind": "card", "lane": "orchestrator", "col": 1, "row": 0, "state": "thinking", "title": "Create Plan" },
+    { "id": "call-api", "kind": "card", "lane": "mcp", "col": 2, "row": 0, "state": "ready", "title": "Execute Tool Call" },
+    { "id": "answer", "kind": "card", "lane": "client", "col": 3, "row": 0, "state": "ready", "title": "Final Reply" }
+  ],
+  "links": [
+    { "id": "l-in", "from": "prompt", "to": "plan", "state": "ready" },
+    { "id": "l-call", "from": "plan", "to": "call-api", "state": "ready" },
+    { "id": "l-back", "from": "call-api", "to": "plan", "state": "retry", "kind": "loop-back", "label": "Tool result" },
+    { "id": "l-reply", "from": "plan", "to": "answer", "state": "ready" }
+  ]
+}
+```
+
+---
+
+## 4. CI/CD pipeline and release train
+
+- **Example file:** `examples/ci-cd-pipeline.json`
+- **Scenario:** Trace code commit through automated build, testing, container scanning, staging validation, and canary production deployment.
+- **Typical columns:** Commit, Build, Test, Security, Staging, Production.
+- **Typical lanes:** Web Frontend, Core Service, Infrastructure as Code.
+- **Node count guideline:** 10 to 25 nodes.
+- **Recommended inspector relations:**
+  - Upstream stages (`dir: "up"`, label: "Required steps")
+  - Downstream gates (`dir: "down"`, label: "Dependent gates")
+  - Artifacts (`dir: "down"`, label: "Published packages")
+- **Copy-paste skeleton:**
+
+```json
+{
+  "version": 1,
+  "meta": {
+    "title": "Release Train Pipeline",
+    "help": "Continuous delivery pipeline with automated test gates and approval checks.",
+    "asOf": "2026-10-06",
+    "source": "GitHub Actions"
+  },
+  "layout": "columns-lanes",
+  "columns": [
+    { "id": "src", "title": "Source", "width": 150 },
+    { "id": "ci", "title": "Build & Test", "width": 180 },
+    { "id": "gate", "title": "Approval", "width": 160 },
+    { "id": "deploy", "title": "Deployment", "width": 180 }
+  ],
+  "lanes": [
+    { "id": "app", "title": "App Service", "badge": "CI/CD", "badgeTone": "ok" },
+    { "id": "ops", "title": "Infrastructure", "badge": "PROD", "badgeTone": "warn" }
+  ],
+  "states": {
+    "pass": { "word": "PASSED", "tone": "ok", "border": "solid", "edge": "flow", "motion": "flow", "bucket": "good" },
+    "running": { "word": "RUNNING", "tone": "accent", "border": "solid", "edge": "flow", "motion": "flow", "bucket": "neutral" },
+    "failed": { "word": "FAILED", "tone": "crit", "border": "solid", "edge": "flow", "motion": "flow", "bucket": "gap" }
+  },
+  "nodes": [
+    { "id": "push", "kind": "card", "lane": "app", "col": 0, "row": 0, "state": "pass", "title": "Git Commit" },
+    { "id": "lint-test", "kind": "card", "lane": "app", "col": 1, "row": 0, "state": "pass", "title": "Unit & Integration" },
+    { "id": "gate-check", "kind": "gateway", "lane": "ops", "col": 2, "row": 0, "state": "running", "title": "Sign-off OK?" },
+    { "id": "prod-deploy", "kind": "card", "lane": "ops", "col": 3, "row": 0, "state": "pass", "title": "Canary Rollout" }
+  ],
+  "links": [
+    { "id": "l-ci", "from": "push", "to": "lint-test", "state": "pass" },
+    { "id": "l-gate", "from": "lint-test", "to": "gate-check", "state": "pass" },
+    { "id": "l-ok", "from": "gate-check", "to": "prod-deploy", "state": "pass", "label": "Approved" },
+    { "id": "l-fail", "from": "gate-check", "to": "push", "state": "failed", "kind": "loop-back", "label": "Rejected" }
+  ]
+}
+```
+
+---
+
+## 5. Approval or business process
+
+- **Example file:** `examples/approval-flow.json`
+- **Scenario:** Multi-tiered approval workflow for expense requests, contract reviews, or capital expenditure.
+- **Typical columns:** Submission, Initial Review, Dept Approval, Executive Signoff, Fulfillment.
+- **Typical lanes:** Employee, Line Manager, Finance Officer, VP / Executive.
+- **Node count guideline:** 8 to 22 nodes.
+- **Recommended inspector relations:**
+  - Prior reviews (`dir: "up"`, label: "Previous decisions")
+  - Next approvals (`dir: "down"`, label: "Next reviews")
+  - Audit trail (`dir: "down"`, label: "Audit records")
+- **Copy-paste skeleton:**
+
+```json
+{
+  "version": 1,
+  "meta": {
+    "title": "Expense Approval Flow",
+    "help": "Multi-tier corporate expense authorization workflow.",
+    "asOf": "2026-10-06",
+    "source": "ERP Workflow Engine"
+  },
+  "layout": "auto",
+  "columns": [
+    { "id": "start", "title": "Request", "width": 160 },
+    { "id": "review", "title": "Review", "width": 180 },
+    { "id": "finance", "title": "Finance", "width": 180 },
+    { "id": "done", "title": "Pmt", "width": 160 }
+  ],
+  "lanes": [
+    { "id": "staff", "title": "Requester", "badge": "STAFF", "badgeTone": "muted" },
+    { "id": "mgr", "title": "Line Manager", "badge": "MGR", "badgeTone": "ok" },
+    { "id": "acct", "title": "Finance Dept", "badge": "ACCT", "badgeTone": "warn" }
+  ],
+  "states": {
+    "approved": { "word": "APPROVED", "tone": "ok", "border": "solid", "edge": "flow", "motion": "flow", "bucket": "good" },
+    "pending": { "word": "PENDING", "tone": "warn", "border": "dashed", "edge": "dash", "motion": "breathe", "bucket": "neutral" },
+    "rejected": { "word": "REJECTED", "tone": "crit", "border": "solid", "edge": "flow", "motion": "flow", "bucket": "gap" }
+  },
+  "nodes": [
+    { "id": "submit", "kind": "card", "lane": "staff", "state": "approved", "title": "Submit Invoice" },
+    { "id": "mgr-gate", "kind": "gateway", "lane": "mgr", "state": "pending", "title": "Within Budget?" },
+    { "id": "finance-audit", "kind": "card", "lane": "acct", "state": "pending", "title": "Tax Compliance" },
+    { "id": "payout", "kind": "card", "lane": "acct", "state": "approved", "title": "Disburse Funds" }
+  ],
+  "links": [
+    { "id": "l-sub", "from": "submit", "to": "mgr-gate", "state": "approved" },
+    { "id": "l-app", "from": "mgr-gate", "to": "finance-audit", "state": "approved", "label": "Yes" },
+    { "id": "l-rej", "from": "mgr-gate", "to": "submit", "state": "rejected", "kind": "loop-back", "label": "Revise" },
+    { "id": "l-pay", "from": "finance-audit", "to": "payout", "state": "approved" }
+  ]
+}
+```
+
+---
+
+## 6. Incident timeline and root cause
+
+- **Example file:** `examples/incident-timeline.json`
+- **Scenario:** Trace outage timeline from initial alert to blast radius detection, containment action, patch rollout, and post-incident review.
+- **Typical columns:** Detection, Triage, Containment, Patch, Verification, Recovered.
+- **Typical lanes:** API Gateway, Orders Service, Database, On-Call Operations.
+- **Node count guideline:** 10 to 24 nodes.
+- **Recommended inspector relations:**
+  - Root causes (`dir: "up"`, label: "Root causes")
+  - Impacted components (`dir: "down"`, label: "Blast radius")
+  - Incident actions (`dir: "down"`, label: "Remediation tasks")
+- **Copy-paste skeleton:**
+
+```json
+{
+  "version": 1,
+  "meta": {
+    "title": "Production Outage Timeline",
+    "help": "Post-incident analysis of connection pool exhaustion.",
+    "asOf": "2026-10-06",
+    "source": "Incident Response Log"
+  },
+  "layout": "columns-lanes",
+  "columns": [
+    { "id": "t0", "title": "10:00 Alert", "width": 160 },
+    { "id": "t1", "title": "10:15 Triage", "width": 180 },
+    { "id": "t2", "title": "10:30 Mitigation", "width": 180 },
+    { "id": "t3", "title": "11:00 Recovered", "width": 160 }
+  ],
+  "lanes": [
+    { "id": "gw", "title": "API Gateway", "badge": "EDGE", "badgeTone": "warn" },
+    { "id": "db", "title": "Database Cluster", "badge": "STORAGE", "badgeTone": "crit" }
+  ],
+  "states": {
+    "healthy": { "word": "HEALTHY", "tone": "ok", "border": "solid", "edge": "flow", "motion": "flow", "bucket": "good" },
+    "failing": { "word": "FAILED", "tone": "crit", "border": "solid", "edge": "flow", "motion": "flow", "bucket": "gap" },
+    "fixed": { "word": "RESTORED", "tone": "ok", "border": "solid", "edge": "flow", "motion": "flow", "bucket": "good" }
+  },
+  "nodes": [
+    { "id": "alert", "kind": "card", "lane": "gw", "col": 0, "row": 0, "state": "failing", "title": "504 Gateway Timeout" },
+    { "id": "pool-exhaust", "kind": "card", "lane": "db", "col": 1, "row": 0, "state": "failing", "title": "Pool Depleted" },
+    { "id": "restart-nodes", "kind": "card", "lane": "db", "col": 2, "row": 0, "state": "healthy", "title": "Scale Connections" },
+    { "id": "traffic-restored", "kind": "card", "lane": "gw", "col": 3, "row": 0, "state": "fixed", "title": "Normal Latency" }
+  ],
+  "links": [
+    { "id": "l-root", "from": "alert", "to": "pool-exhaust", "state": "failing" },
+    { "id": "l-fix", "from": "pool-exhaust", "to": "restart-nodes", "state": "healthy" },
+    { "id": "l-back-online", "from": "restart-nodes", "to": "traffic-restored", "state": "fixed" }
+  ],
+  "inspector": {
+    "actions": [
+      { "id": "sim-fail", "label": "Simulate: DB Failure", "dir": "down", "staleText": "Cascade to edge clients" }
+    ]
+  }
+}
+```
+
+---
+
+## 7. Service or architecture dependency map
+
+- **Example file:** `examples/service-map.json`
+- **Scenario:** Map microservices, API gateways, cache layers, message brokers, and persistent datastores across functional domains.
+- **Typical columns:** Edge Gateway, Auth, Commerce API, Background Workers, Persistence.
+- **Typical lanes:** Public Domain, Core Domain, Data Infrastructure.
+- **Node count guideline:** 12 to 28 nodes.
+- **Recommended inspector relations:**
+  - Upstream callers (`dir: "up"`, label: "Direct clients")
+  - Downstream services (`dir: "down"`, label: "Downstream dependencies")
+  - Shared storage (`dir: "down"`, label: "Datastores used")
+- **Copy-paste skeleton:**
+
+```json
+{
+  "version": 1,
+  "meta": {
+    "title": "Microservice Architecture Map",
+    "help": "Service dependency topology with traffic volume and latency metrics.",
+    "asOf": "2026-10-06",
+    "source": "Service Mesh Telemetry"
+  },
+  "layout": "auto",
+  "columns": [
+    { "id": "edge", "title": "Edge", "width": 160 },
+    { "id": "svc", "title": "Services", "width": 200 },
+    { "id": "data", "title": "Datastores", "width": 180 }
+  ],
+  "lanes": [
+    { "id": "ingress", "title": "Ingress Tier", "badge": "NET", "badgeTone": "ok" },
+    { "id": "app", "title": "Application Tier", "badge": "SVC", "badgeTone": "ok" },
+    { "id": "storage", "title": "Persistence Tier", "badge": "DB", "badgeTone": "ok" }
+  ],
+  "states": {
+    "nominal": { "word": "HEALTHY", "tone": "ok", "border": "solid", "edge": "flow", "motion": "flow", "bucket": "good" },
+    "warn": { "word": "DEGRADED", "tone": "warn", "border": "dashed", "edge": "dash", "motion": "breathe", "bucket": "neutral" }
+  },
+  "nodes": [
+    { "id": "api-gw", "kind": "card", "lane": "ingress", "state": "nominal", "title": "Kong Gateway" },
+    { "id": "order-svc", "kind": "card", "lane": "app", "state": "nominal", "title": "Order Service", "metrics": { "value": 420, "unit": "rps", "label": "Throughput" } },
+    { "id": "db-cluster", "kind": "group", "lane": "storage", "state": "nominal", "title": "Postgres Cluster", "contains": ["pg-primary", "pg-replica"], "collapsed": true },
+    { "id": "pg-primary", "kind": "card", "lane": "storage", "state": "nominal", "title": "PG Primary" },
+    { "id": "pg-replica", "kind": "card", "lane": "storage", "state": "nominal", "title": "PG Read Replica" }
+  ],
+  "links": [
+    { "id": "l-edge-order", "from": "api-gw", "to": "order-svc", "state": "nominal" },
+    { "id": "l-order-pg", "from": "order-svc", "to": "pg-primary", "state": "nominal" }
+  ]
+}
+```
+
+---
+
+## Lane structure guidance
+
+A lane answers: "who or what owns this row?".
+- Group lanes by owning team, service domain, or architecture tier.
+- Avoid placing all nodes into a single lane; that destroys visual structure.
+- Avoid using more than 10 lanes; group related sub-services instead.
+- If a system has no verifiable document or owner, mark the lane `gap: true` with an explanatory note.

package/bundles/codex/.codex/skills/frontend/flow-studio/references/ux-rules.md

@@ -0,0 +1,91 @@
+# UX and design rules
+
+The 10 rules ensure flow-studio pages remain readable, informative, accessible, and fast.
+
+## The 10 rules
+
+### 1. One screen
+- **Rule statement:** The full flow fits on one screen without requiring panning in the initial default view.
+- **Rationale:** A user must comprehend the entire topology before diving into specific components.
+- **Pre-flight checklist question:** Did you check that the initial canvas fit scale is between 0.35 and 1.0 at standard desktop viewports (1600x900 and 1280x720)?
+- **Common mistake & fix:** Authoring 80 expanded nodes in 15 lanes so text is unreadable at fit. *Fix:* Group sub-systems into collapsible groups with `contains` and `collapsed: true` to keep initial visible nodes under 30.
+
+### 2. Left to right
+- **Rule statement:** Primary flow and time progress left to right, never right to left.
+- **Rationale:** Readers process sequential workflows and dependencies left to right; backward links create cognitive dissonance unless explicitly marked.
+- **Pre-flight checklist question:** Did you check that all forward links connect earlier columns to later columns?
+- **Common mistake & fix:** Drawing a return cycle with a standard forward arrow. *Fix:* Mark backward transitions as `kind: "loop-back"` so the router draws them under or over the main lane bands.
+
+### 3. Named states
+- **Rule statement:** States use plain domain words instead of raw enum strings or database codes.
+- **Rationale:** Stakeholders and domain experts should understand node statuses without a translation glossary.
+- **Pre-flight checklist question:** Did you check that state `word` fields display human-readable phrases like `READY`, `ON TIME`, or `DEGRADED` instead of `STATUS_200` or `ERR_412`?
+- **Common mistake & fix:** Exporting raw database enums directly into the model. *Fix:* Map internal enums to friendly words in `states.<id>.word`.
+
+### 4. Color carries meaning
+- **Rule statement:** Semantic colors communicate health: green is healthy, amber is warning, red is critical, blue is accent.
+- **Rationale:** Consistent visual coding allows immediate recognition of anomalies across diverse systems.
+- **Pre-flight checklist question:** Did you check that green tones indicate operational health and red tones indicate SLA breaches or defects?
+- **Common mistake & fix:** Styling informational cards with red or critical cards with blue. *Fix:* Use `tone: "ok"` for good, `tone: "warn"` for warning, `tone: "crit"` for critical, and `tone: "accent"` for active selection.
+
+### 5. No orphans
+- **Rule statement:** Every node connects to at least one other node unless explicitly marked.
+- **Rationale:** Isolated nodes look like layout bugs or forgotten elements.
+- **Pre-flight checklist question:** Did you check that every card has at least one incoming or outgoing link?
+- **Common mistake & fix:** Forgetting to link an auxiliary service. *Fix:* Connect the service to its callers, or set `allowIsolated: true` if isolation is an intentional design choice.
+
+### 6. Honest gaps
+- **Rule statement:** If an architecture layer or data source is unverified, draw a visible gap band rather than guessing.
+- **Rationale:** A diagram that fabricates missing systems causes dangerous production assumptions.
+- **Pre-flight checklist question:** Did you check that undocumented lanes have `gap: true` and an explanatory note?
+- **Common mistake & fix:** Omitting a legacy undocumented system or assuming its structure. *Fix:* Add the lane with `gap: true` and an amber dashed border to prompt clarification.
+
+### 7. Inspector on demand
+- **Rule statement:** The inspector side panel slides in on click and is never permanently open.
+- **Rationale:** A permanent side panel robs the canvas of 340px of width and compromises the one-screen overview.
+- **Pre-flight checklist question:** Did you check that the page loads with the inspector closed (`#inspector` hidden)?
+- **Common mistake & fix:** Hardcoding the inspector to be permanently expanded on desktop. *Fix:* Leave `#inspector` closed until a user selects a node or card.
+
+### 8. Two clicks to detail
+- **Rule statement:** Any node reveals its upstream dependencies, downstream impact, and telemetry in at most two clicks.
+- **Rationale:** Deep navigation trees frustrate operators during incident investigations.
+- **Pre-flight checklist question:** Did you check that clicking a node opens the inspector, and clicking a relation tab highlights the full related subgraph?
+- **Common mistake & fix:** Burying downstream connections behind nested menus or modal dialogs. *Fix:* Configure `inspector.relations` with `up` and `down` counts right at the top of the inspector.
+
+### 9. Motion explains
+- **Rule statement:** Animation represents data transit or status change, never mere cosmetic decoration.
+- **Rationale:** Unnecessary movement distracts users and triggers motion sickness.
+- **Pre-flight checklist question:** Did you check that running animations (`flow`, `breathe`, `failflash`) reflect active scenarios, degradation, or SLA breaches?
+- **Common mistake & fix:** Adding infinite spinning rings to inactive cards. *Fix:* Reserve `animation: flow` for active links, `breathe` for warning cards, and respect `prefers-reduced-motion`.
+
+### 10. Dark mode first-class
+- **Rule statement:** Every color token has a manually tuned dark value, not an automatic browser filter inversion.
+- **Rationale:** Inverted canvases distort data colors, destroy contrast, and wash out delicate edge lines.
+- **Pre-flight checklist question:** Did you check that all text and badge contrasts meet WCAG AA (>= 4.5:1) in both light and dark themes?
+- **Common mistake & fix:** Relying on `filter: invert(1)` which turns warning amber into unusable purple. *Fix:* Define distinct semantic variables in `:root[data-theme="dark"]`.
+
+---
+
+## Pre-flight checklist for agents
+
+Before presenting a generated flow page, verify:
+1. **Fit:** Open the page in a browser at 1600x900. Does the full diagram fit within the viewport without horizontal scrollbars?
+2. **Zero overlaps:** Ensure zero node-to-node box intersections and zero node-over-lane-title collisions.
+3. **No text truncation:** Do titles fit within card bounds? Are long labels handled with word-break or ellipsis?
+4. **Lane ownership:** Does every row correspond to an identifiable owner, service, or system?
+5. **No dead links:** Does every link id point to existing, valid node ids?
+6. **Accessible names:** Does every button, input, tab, and control have an `aria-label` or visible text?
+7. **Keyboard navigation:** Can a user Tab through controls and press Escape to close the inspector?
+8. **Responsive breakdown:** Does the layout degrade cleanly down to 820x900?
+
+---
+
+## Common mistakes and fixes
+
+- **Orphan nodes:** A node sits with no connecting edges. *Fix:* Add the missing connection or set `allowIsolated: true`.
+- **Unreadable first view:** Diagram has 70 nodes rendered simultaneously. *Fix:* Collapse secondary clusters into groups with `contains: [...]` and `collapsed: true`.
+- **Overlapping lanes:** Free-form node coordinates push nodes into neighboring lane regions. *Fix:* Ensure node Y coordinates plus heights stay within lane boundaries.
+- **Text spill:** Node labels exceed card width. *Fix:* Use short titles (under 24 characters) and set `subtitle` for auxiliary metadata.
+- **Permanent side panel:** The inspector remains open on load. *Fix:* The inspector must start closed and open only on selection.
+- **Flat visual hierarchy:** Every card looks identical. *Fix:* Vary card kinds (`card`, `group`, `gateway`, `chip`) and state tones (`ok`, `warn`, `crit`, `accent`).
+- **Unlabelled controls:** Icon buttons without text lack screen reader descriptions. *Fix:* Provide descriptive `aria-label` attributes on all buttons.

package/bundles/codex/.codex/skills/frontend/flow-studio/references/verify.md

@@ -0,0 +1,124 @@
+# Verification harness reference
+
+`scripts/check.mjs` is the automated headless browser testing harness for flow-studio pages. It drives Chromium via Playwright, interrogates page geometry and accessibility trees, tests user interactions, and asserts visual and behavioral invariants.
+
+## 1. CLI usage and options
+
+```bash
+# Run against a local build
+node scripts/check.mjs out/lineage.html
+
+# Run with custom output directory and viewports
+node scripts/check.mjs out/lineage.html --out check-out --viewports 1600x900,1280x720,820x900
+
+# Specify browser channel and skip optional groups
+node scripts/check.mjs out/lineage.html --channel msedge --skip notes,playback,update,hostile
+
+# Test hostile payload safety
+node scripts/check.mjs out/lineage.html --hostile out/hostile.html --json report.json
+
+# Skip performance benchmarking
+node scripts/check.mjs out/lineage.html --skip-perf
+```
+
+### CLI options
+- `<page.html | URL>`: File path or HTTP URL to the target page.
+- `--out <dir>`: Directory where screenshots and failure captures are saved (default: `check-out`).
+- `--viewports <WxH,...>`: Comma-separated list of test viewports (default: `1600x900,1280x720,820x900`).
+- `--channel <name>`: Browser executable channel (e.g. `msedge`, `chrome`).
+- `--skip <groups>`: Comma-separated list of test groups to skip (`notes`, `playback`, `update`, `hostile`). A skipped group is not a pass: skip one only when the page intentionally omits that feature, and record every skip in your verification notes.
+- `--hostile <file.html>`: Path to hostile test page to assert XSS and injection resistance.
+- `--json <file.json>`: Output machine-readable test results to a JSON report.
+- `--skip-perf`: Omit render and zoom frame timing performance assertions.
+
+---
+
+## 2. Check groups and assertions
+
+`scripts/check.mjs` organizes assertions into distinct groups:
+
+### 1. `structural`
+Validates that layout geometry satisfies visual clarity:
+- **Zero node-box intersections:** No two node bounding boxes overlap or intersect.
+- **Node inside lane:** Every node sits completely within its designated swimlane boundaries.
+- **No lane overlap:** Swimlanes do not collide vertically.
+- **Links touch node boxes:** Link start points and end points connect cleanly to their endpoint boxes without gaps or overshoots.
+- **Fit shows every node:** Canvas auto-fit places all nodes fully within the visible viewport bounds.
+- **Hidden nodes not painted:** Collapsed or view-filtered nodes have `visibility: hidden` and `opacity: 0`.
+
+### 2. `interaction`
+Validates user input, navigation, and state machines:
+- **Wheel zoom & pan:** Canvas zooms centered on the mouse position; zoom is clamped between 0.25x and 2.5x.
+- **Key navigation:** `0` fits canvas, arrow keys pan the viewport, `Escape` clears selection and closes the inspector.
+- **Group expansion / collapse:** Clicking expand/collapse buttons toggles child visibility and updates visible node counts.
+- **Node selection:** Clicking a node selects it, highlights connected edges, and slides open `#inspector`.
+- **N-hop search:** Searching terms highlights matches and dims non-matching nodes; increasing hops expands the lit radius.
+- **What-if simulation:** Clicking what-if buttons cascades simulated failure states through downstream dependents.
+- **View switcher:** Toggling views displays only elements specified in `visibleIn`.
+
+### 3. `a11y` (Accessibility)
+Validates compliance with WCAG 2.2 AA standards:
+- **Accessible names:** Every button, input, tab, and control has a non-empty `aria-label` or accessible text name.
+- **Keyboard navigation:** Visible nodes receive focus via Tab; hidden nodes are not reachable via Tab. No keyboard traps.
+- **Focus visibility:** Focused nodes display an active outline.
+- **Contrast ratios:** Normal text has at least 4.5:1 contrast against surface backgrounds in both light and dark themes.
+- **Table view:** An accessible `<table class="sources" id="tbl">` lists all visible graph nodes for screen reader users.
+- **Reduced motion:** `prefers-reduced-motion` disables all transitions and animations, setting edge dashes static.
+
+### 4. `safety`
+Validates security against hostile content and network isolation:
+- **No unhandled page errors:** Zero unhandled JavaScript exceptions in the console.
+- **No external network requests:** Zero external HTTP/HTTPS requests (local and standalone execution).
+- **Hostile string escaping:** Malicious HTML (`</script>`, `<img onerror=...>`, Unicode separators) is rendered as plain text without script execution or DOM injection.
+
+### 5. `performance`
+Validates responsiveness and frame timing:
+- **First render time:** Initial canvas render of all nodes must complete in under 500 ms.
+- **Frame budget:** 95th percentile wheel event handling time must be under 16 ms (60 fps threshold).
+- **Self-contained bundle size:** Generated single-file HTML pages must stay under 300 KB.
+
+### 6. `notes`
+Validates the implementation notes drawer:
+- In notes mode, numbered markers appear for every valid anchor.
+- Hovering and clicking markers coordinates with drawer cards.
+
+### 7. `playback`
+Validates scenario animation:
+- Stepping moves the active token along specified links in sequence.
+- Decision gateways show branch choice buttons in step mode.
+- SLA breaches trigger red counter highlighting and failure flash styling.
+
+### 8. `update`
+Validates live graph data updates:
+- Calling `FlowStudio.update(newModel)` updates topology while preserving pan, zoom, and active selection.
+- Invalid model updates preserve the previous valid DOM state and render `#banner` error notice.
+
+### 9. `hostile`
+Validates adversarial resistance:
+- Ingests `examples/hostile.json` to prove the parser and inspector remain inert against script injection.
+
+---
+
+## 3. Thresholds and limits
+
+| Metric / Check | Threshold | Rationale |
+|---|---|---|
+| First render duration | `< 500 ms` | Fast initial load experience |
+| Wheel event latency (p95) | `< 16 ms` | Smooth 60fps pan and zoom interaction |
+| Zoom range | `0.25` to `2.5` | Prevents disorientation from extreme zoom levels |
+| Contrast ratio | `>= 4.5:1` | WCAG AA readability in light and dark modes |
+| Node count guideline | `8` to `30` initial visible | Avoids visual clutter in default fit |
+| HTML bundle size | `< 300 KB` | Portable, zero-dependency self-contained distribution |
+
+---
+
+## 4. Reading failures and fixing issues
+
+When a check fails, the harness logs:
+```text
+FAIL  [structural] 1600x900 zero node-box intersections  crm-db/cdc-pipe
+```
+1. **Identify the group and viewport:** Here, `structural` at `1600x900`.
+2. **Read the detail payload:** The detail string lists the offending nodes (`crm-db` and `cdc-pipe`).
+3. **Inspect the screenshot:** Open `check-out/01-fit-1600x900.png` to inspect the visual collision.
+4. **Apply the fix:** Adjust the column width or node row/slot positions in `model.json`, then re-run `node scripts/check.mjs`.