@caddis/cli 0.4.45 → 0.4.47

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

@@ -1,13 +1,13 @@
 # Scenario recipes
 
-Each recipe says how to express a scenario in a flow-studio model. **Proven** means an example model passes the
-check harness. **Candidate** means the recipe is written but not built yet: say so when you use it.
-Version 0.1 draws left-to-right flows only (see `SKILL.md`); where a scenario needs a loop or a branch, the
-recipe says what to do today.
+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 to start from (change the words to fit the scenario):
+## Common states
 
-| State id | Word | tone | border | edge | motion | bucket |
+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 |
@@ -15,65 +15,401 @@ Common states to start from (change the words to fit the scenario):
 | `breached` | BREACHED | crit | solid | flow | flow | gap |
 | `unknown` | NOT RECORDED | warn | dotted | dot | breathe | gap |
 
-## 1. Data lineage and dependency impact (proven: `examples/lineage.json`)
+---
+
+## 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" }
+  ]
+}
+```
 
-- **Columns:** source, host, database, jobs, tables, refreshers, report tables, apps, pages.
-- **Lanes:** one per app or system; a lane with no document gets `gap: true` and a note saying what is missing.
-- **States:** measured, declared, inferred, not recorded. Views: Today (what is measured) and Complete (adds the
-  declared layer).
-- **Inspector:** Feeds this, Downstream, Pages (`filter: {col: <pages column>}`). **Action:** "Simulate: this stops
-  updating".
-- **Questions:** which layers matter, which sources are measured and which are declared, who owns each document.
-- **Traps:** guessing a link (use a placeholder), counting a declared snapshot as current (carry its date).
+---
 
-## 2. Ticket, case or order lifecycle (candidate)
+## 4. CI/CD pipeline and release train
 
-- **Columns:** the stages (New, Triage, In progress, Waiting, Resolved, Closed). **Lanes:** the owning team or
-  system. **States:** on time, at risk, breached. **Nodes:** one card per stage and team; `weight` = open count.
-- **Loops:** "reopened" and "back to triage" are loops: not drawn yet. Add a "Reopened" node in a later column.
-- **Inspector:** Came from, Goes to, Closed. **Action:** "Simulate: SLA breach".
-- **Traps:** drawing every status as a column when only some have owners.
+- **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:**
 
-## 3. Agent, user or customer journey (candidate)
+```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" }
+  ]
+}
+```
 
-- **Columns:** phases (Discover, Try, Buy, Use, Renew) or time steps. **Lanes:** actors (customer, agent, system).
-  **Nodes:** touchpoints. **States:** smooth, friction, failure. **Metrics:** put the figure in `subtitle`.
-- **Traps:** mixing actors in one lane; no states (a journey with no pain points hides the point).
+---
 
-## 4. Incident timeline and root cause (candidate)
+## 5. Approval or business process
 
-- **Columns:** time buckets (T-30m, T-10m, T0, T+10m, T+1h). **Lanes:** systems. **Nodes:** events.
-  **States:** normal, degraded, failed. **Action:** "Simulate: this failed" shows the blast radius.
+- **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:**
 
-## 5. CI/CD pipeline and release train (candidate)
+```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" }
+  ]
+}
+```
 
-- **Columns:** stages (commit, build, test, scan, deploy, verify). **Lanes:** environments or services.
-  **States:** passed, running, failed, skipped. **Inspector:** Upstream, Downstream, Environments.
+---
 
-## 6. Approval or business process (candidate)
+## 6. Incident timeline and root cause
 
-- **Columns:** steps; **lanes:** roles. Branches ("approved" and "rejected") are two nodes in the next column.
-  Gateway diamonds are not drawn yet: use a card titled "Decision: ...".
+- **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:**
 
-## 7. Service or architecture dependency map (candidate)
+```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" }
+    ]
+  }
+}
+```
 
-- **Columns:** tiers (client, edge, service, data store). **Lanes:** domains. **States:** healthy, degraded, down.
-  **Action:** "Simulate: this is down" ripples to the dependents.
+---
 
-## 8. State machine (candidate; needs loops)
+## 7. Service or architecture dependency map
 
-- Not a good fit until loop-back links exist. Draw the forward path only and list the returns in the inspector
-  (`members`).
+- **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:**
 
-## 9 to 16. Further candidates
+```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" }
+  ]
+}
+```
 
-Multi-agent or LLM orchestration trace, job schedule and batch dependency, decision tree or runbook, data model or
-entity explorer, access and permission graph, supply chain, learning path or roadmap, network topology. Start from
-recipe 1 or 5 and say they are unproven. When one passes the checks, add its model under `examples/` and change
-"candidate" to "proven" here.
+---
 
-## Choosing the lanes (the usual mistake)
+## Lane structure guidance
 
-If every node sits in one lane, the page has no structure: a lane answers "who or what owns this row". If there
-are more than about 10 lanes, group them (a lane per team, not per person). If a lane has no source of truth,
-mark it `gap: true` so the gap is visible instead of looking like a forgotten node.
+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.