@caddis/cli 0.4.45 → 0.4.46

package/bundles/antigravity-plugin/skills/flow-studio/templates/shell-body.html

@@ -0,0 +1,50 @@
+<header class="top">
+  <span class="brand"><i></i>flow-studio</span>
+  <span class="spacer"></span>
+  <button id="notesBtn" type="button" aria-pressed="false">Implementation notes (N)</button>
+  <button id="theme" type="button" aria-label="Toggle light and dark">☀ / ☾</button>
+</header>
+<main>
+  <div class="titlerow"><h1 id="title"></h1><span class="readline" id="readat"></span></div>
+  <p class="help" id="help"></p>
+  <div id="banner" role="alert" hidden></div>
+
+  <section class="summary"><div class="layerstrip" id="layerstrip" aria-label="Completeness by column"></div><div class="tiles" id="kpis" aria-label="Summary"></div></section>
+
+  <div class="toolbar">
+    <div class="seggrp" role="tablist" aria-label="View" id="modeSwitch"></div>
+    <input id="q" type="search" placeholder="Find a group or member…  ( / )" aria-label="Find a group or member">
+    <select id="hops" aria-label="Search radius"><option value="0">This group</option><option value="1">+1 hop</option><option value="2">+2 hops</option><option value="3">+3 hops</option></select>
+    <span id="matchinfo" class="note" style="margin:0"></span>
+  </div>
+
+  <div class="workspace" id="workspace">
+    <section class="canvaswrap">
+      <div id="viewport" tabindex="0" role="application" aria-label="Flow canvas. Scroll to zoom, drag to pan. Keys: V select, H hand, plus and minus zoom, 0 fit, 1 actual size, F zoom to selection, arrows pan.">
+        <div id="world"><svg id="edges" aria-hidden="true"><defs><marker id="arr" viewBox="0 0 8 8" refX="7" refY="4" markerWidth="9" markerHeight="9" markerUnits="userSpaceOnUse" orient="auto"><path d="M0 0 L8 4 L0 8 z" fill="context-stroke"/></marker></defs><g id="edgeLayer"></g></svg></div>
+        <div id="cols" aria-hidden="true"></div>
+        <div id="tools" role="toolbar" aria-label="Canvas controls" aria-orientation="vertical"></div>
+        <div id="zoomLabel" aria-hidden="true">100%</div>
+      </div>
+      <div id="playbar" hidden aria-label="Scenario playback">
+        <select id="pbScenario" aria-label="Scenario"></select>
+        <button id="pbPlay" type="button" aria-label="Play">▶</button>
+        <button id="pbStep" type="button" aria-label="Step">Step</button>
+        <button id="pbReset" type="button" aria-label="Reset">Reset</button>
+        <select id="pbSpeed" aria-label="Speed"><option value="0.5">0.5x</option><option value="1" selected>1x</option><option value="2">2x</option></select>
+        <input id="pbScrub" type="range" min="0" max="1000" value="0" aria-label="Playback position" aria-valuetext="Step 1 of 1">
+        <span id="pbCaption"></span><span id="pbCounter"></span><span id="pbChoices"></span>
+      </div>
+      <div class="keyline" id="legend" aria-label="Legend"></div>
+      <aside class="insp" id="inspector" aria-label="Inspector" aria-hidden="true"></aside>
+    </section>
+  </div>
+  <div id="live" class="sr" role="status" aria-live="polite"></div>
+
+  <div class="ledger" id="ledger"></div>
+  <details class="tableview"><summary>Table view</summary><table class="sources" id="tbl"></table></details>
+  <details class="spec" id="spec"><summary>Model reference (for the person or agent who builds this)</summary><div id="specbody"></div></details>
+</main>
+<footer id="footer"></footer>
+<aside id="drawer" aria-label="Implementation notes"><h2>Implementation notes</h2><p class="note">Numbered markers on the page match these cards. Hover a card to find its place; click a marker to jump to its card.</p><div id="notelist"></div></aside>
+

package/bundles/codex/.codex/skills/frontend/flow-studio/README.md

@@ -1,10 +1,10 @@
 # flow-studio (engine source)
 
-Stage S1a of the `flow-studio` skill: a model file (JSON) describes a flow, lifecycle or journey, and one
+The `flow-studio` skill: a model file (JSON) describes a flow, lifecycle or journey, and one
 engine draws it as a self-contained HTML page with pan and zoom, lanes, linked nodes, a slide-in
-inspector, motion that carries state, and numbered implementation notes. The design is in
-`.caddis/plans/flow-studio-skill-design.md`; the plan for this stage is `.caddis/plans/flow-studio-s1a-plan.md`.
-There is no `SKILL.md` yet: the playbook arrives in stage S2.
+inspector, scenario playback, metric overlays, live update, motion that carries state, and numbered implementation notes. The design is in
+`.caddis/plans/flow-studio-skill-design.md`; the S4 stage status is in `.caddis/plans/flow-studio-s4-status.md`.
+`SKILL.md` is the current playbook.
 
 ## Use it
 
@@ -12,12 +12,22 @@ There is no `SKILL.md` yet: the playbook arrives in stage S2.
 # from this folder (Node 22.6 or newer)
 node --experimental-strip-types scripts/validate.mjs examples/lineage.json
 node --experimental-strip-types scripts/build.mjs examples/lineage.json out/lineage.html
+node --experimental-strip-types scripts/validate.mjs examples/order-desk.json
+node --experimental-strip-types scripts/build.mjs examples/order-desk.json out/order-desk.html
 ```
 
 Open `out/lineage.html`. It has no network access and no libraries.
+`order-desk.json` shows auto layout, a loop-back link, a gateway with labelled exits, a group that opens, two playback scenarios, an SLA, and metrics.
+See [examples/README.md](examples/README.md) for the full catalog of worked scenario models.
+A group with `contains` starts collapsed unless `collapsed` is `false`.
 
-`build.mjs` embeds the model's own `notes` plus any extra notes from `--notes notes.json` (the model's
-notes come first, then the file's). Note anchors are CSS selectors for parts of the page, for example
+Play or step through a scenario with the playbar. At a gateway, step mode offers each exit and marks the scenario's next link as suggested. A model can provide `metrics` on nodes and `scenarios` with exact link ids. `FlowStudio.update(model)` validates a new model and keeps the current view, selection, search and playback position. The caller must derive node and link ids from stable business keys. Array positions are not stable ids.
+
+`build.mjs` embeds the model's own `notes` plus any extra notes from `--notes notes.json`. Pass
+`--demo-pack` to include the standard shell implementation notes: default notes come first, then
+the model's notes, then extra notes, numbered sequentially 1..n. Default notes whose target elements
+do not exist in the page are dropped (such as `#playbar` when there are no scenarios, or `#modeSwitch`
+when there are fewer than two views). Note anchors are CSS selectors for parts of the page, for example
 `#viewport`.
 
 ## Check a page
@@ -34,6 +44,34 @@ interaction (zoom, pan, select, what-if, view switch), accessibility (names, foc
 reduced motion), safety (no network, hostile text stays inert) and performance (200 nodes). Exit code 0 means
 every check passed.
 
+## Build inside a React app
+
+Choose the route in [implement-in-app.md](references/implement-in-app.md):
+
+- **Fast wrapper:** copy `templates/flow-studio.lib.mjs`, its `flow-studio.lib.d.mts` declaration,
+  `templates/flow-studio.css`, `react/`, and `src/`. Keep the relative folder layout. Import the CSS once and
+  render `FlowStudioView` with a validated `Model`. This route uses the engine's own look and behaviour.
+- **Native components:** copy `react/native/` and `src/`. The hooks handle viewport, geometry, and trace
+  state. Adapt `FlowCanvas` and `Inspector` to the app's design system. The app owns the final behaviour and
+  visual checks.
+
+Both routes need stable node and link ids based on business keys. Use typed loading, empty, ready, and error
+states. Keep the last good graph on a failed refresh. See [react/README.md](react/README.md) for wrapper props
+and the proof app command. The proof creates a temporary Vite app and removes it when finished:
+
+```text
+node scripts/react-proof.mjs
+```
+
+Run the browser harness against a running app page:
+
+```text
+node <skill>/scripts/check.mjs http://127.0.0.1:<port>/<route> --out shots --channel msedge --skip hostile
+```
+
+The `hostile` group needs a separate hostile page, which the proof app does not provide. Record any other
+feature group that the app intentionally skips. A skipped check is not a pass.
+
 `scripts/lib/check-selftest.test.mjs` feeds the harness pages with one deliberate defect each and fails
 if a defect is not caught. It is skipped when Playwright cannot be resolved, so run it from a folder that has
 it: `FLOW_STUDIO_CHANNEL=msedge node --test /path/to/flow-studio/scripts/lib/check-selftest.test.mjs`.
@@ -46,8 +84,9 @@ it: `FLOW_STUDIO_CHANNEL=msedge node --test /path/to/flow-studio/scripts/lib/che
 - `npm test` runs the unit tests (`node --experimental-strip-types --test`).
 - `templates/engine.html` is generated and committed. After you change `src/` or `templates/engine.shell.html`,
   run `node --experimental-strip-types scripts/build-engine.mjs`. A test fails when the committed file is stale.
-- `build-engine.mjs` needs `esbuild`. It looks in this folder, then in the caddis `cli/` folder, then in the
+- `build-engine.mjs` needs `esbuild`. It looks in `FLOW_STUDIO_NODE_MODULES` first, then this folder, the caddis `cli/` folder, then in the
   current folder. In a caddis checkout, `cli/node_modules` already has it. Elsewhere, run `npm i -D esbuild`. The stale-engine check compares bytes, so use the same esbuild version as the checkout that committed the file (the caddis `cli/` one).
+- Set `FLOW_STUDIO_NODE_MODULES` to a shared `node_modules` folder to use its `esbuild` first when building in a worktree.
 - Type check with `tsc -p tsconfig.json` (TypeScript from `cli/node_modules` or your own install).
 - Examples use fictional data only: this repository is public.
 - Delete the `out/` folder before exporting bundles. It is ignored by git but not by a file copy.

package/bundles/codex/.codex/skills/frontend/flow-studio/SKILL.md

@@ -5,99 +5,98 @@ description: Design an interactive flow, lifecycle or journey page (nodes, lanes
 
 # flow-studio
 
-Turns a one-paragraph brief into an explorable page: stages across, lanes down, linked nodes, pan and zoom,
-a slide-in inspector, motion that carries meaning, and numbered implementation notes. One JSON **model**
-describes the scenario. One engine draws it. A check script proves it is sound.
+Turns a one-paragraph brief into an explorable interactive flow page: stages across, lanes down, linked nodes, pan and zoom, a slide-in inspector, motion that carries meaning, and numbered implementation notes. One JSON model describes the scenario. One engine renders it. A check script proves it is sound.
+
+Paths in the commands below are relative to the folder that holds this file, and `<skill folder>` in a command means that folder. Node 22.6 or newer is needed for `--experimental-strip-types`.
+
+## When to use it
+
+Use it for:
+- Data lineage and dependency impact analysis.
+- Ticket, case, and support workflows.
+- Agent and customer journey mapping.
+- CI/CD and release pipelines.
+- Multi-step approval flows.
+- Incident timelines and blast-radius exploration.
+- Microservice architecture dependency maps.
+See `references/patterns.md` for scenario recipes.
+
+Do not use it for:
+- Static UI layouts or component screen variants (use `mockup` or `sketch`).
+- Manual whiteboard architectural diagrams (use `draw-io`).
+- Simple text-based markdown diagrams (use `mermaid-diagrams`).
+- Pure data schema specs without flow visualization (use `data-lineage`).
+
+## What works today
+
+- **Layouts**: columns and lanes, free coordinate placement (`layout: "free"`), and automatic layout (`layout: "auto"`).
+- **Nodes and links**: forward links, loop-back links, gateway diamonds with labelled exits, collapsible groups, portal chips, placeholders, and cards.
+- **Search and filter**: text search with an N-hop neighborhood filter.
+- **Scenarios and playback**: token animation along links, SLA breach indicators, step mode with branch selection, speed control, and scrubber.
+- **Metrics and what-if**: node metric badges with sparkline history, and inspector what-if ripple simulations.
+- **Views and diffing**: baseline views with automatic addition and gap detection.
+- **Live updates**: `FlowStudio.update(model)` updates data while preserving viewport, selection, and playback state.
+- **Notes and demo pack**: numbered notes anchored to page elements, and built-in demo pack guidance (`--demo-pack`).
 
-Use it for: data lineage and dependency impact, a ticket or case lifecycle, an agent or customer journey, a CI/CD
-or release pipeline, an approval flow, an incident timeline, a service map. See `references/patterns.md`.
-Not for: a static screen or UI variants (use `mockup` or `sketch`), a chart, a graph with more than 300 nodes.
+## Process: demo mode
 
-## What works today (version 0.1)
+1. **Ask at most three questions**: what is the page for, who reads it, and what are the stages, lanes, and states. If the brief already specifies them, ask nothing.
+2. **Map the scenario** to columns, lanes, states, nodes, and links using `references/patterns.md`.
+3. **Write `model.json`**. Check fields in `references/model-schema.md`. Use `examples/lineage.json` or `examples/order-desk.json` as references.
+4. **Validate**: `node --experimental-strip-types scripts/validate.mjs model.json`. Fix every error and review warnings.
+5. **Build**: `node --experimental-strip-types scripts/build.mjs model.json out/page.html` (optionally pass `--demo-pack` or `--notes`).
+6. **Check**: run `node <skill folder>/scripts/check.mjs out/page.html --out shots [--channel msedge]` from a folder whose `node_modules` resolves `playwright`. Every check must pass. Open the screenshots to inspect visual hierarchy and legibility.
+7. **Show**: present the standalone page and screenshots. Do not declare completion until checks pass.
 
-Left-to-right flows in **columns** (stages) and **lanes** (apps, systems or actors): states with their own look
-and motion, portal chips for shared nodes, wide placeholders for what is not recorded, two or more views
-(for example Today and Complete), search, a what-if action (a red ripple downstream), a table view, and notes.
+## Build mode: implement it in a real app
 
-**Not yet** (planned, do not promise them): links that go back to an earlier stage (loops), gateway diamonds,
-automatic placement, token playback along a path, live data updates, free x and y placement. If the scenario
-needs a loop, show the return as its own node in a later column (for example "Reopened") and say so.
+Use `references/model-schema.md` as the data contract. Follow `references/implement-in-app.md` for the test-first procedure.
 
-## Process: demo mode
+Choose one React route:
+- **Fast wrapper route**: copy `templates/flow-studio.lib.mjs`, `templates/flow-studio.lib.d.mts`, `templates/flow-studio.css`, `react/`, and `src/` into the app. Import the CSS once and render `FlowStudioView`.
+- **Native components route**: copy `react/native/` and `src/` into the app. Wire `useFlowGeometry`, `useViewport`, and `useTrace`. Style `FlowCanvas` and `Inspector` using the app design system.
 
-1. **Ask at most three questions**: what is the page for, who reads it, and what are the nouns (the stages, the
-   lanes, the states). If the brief already says, ask none.
-2. **Map the scenario** to the model (`references/patterns.md` has a recipe per scenario):
-   columns = stages left to right, lanes = who or what owns the row, states = the vocabulary (for example
-   new, open, waiting, breached, resolved), nodes = the things, links = the flow.
-3. **Write `model.json`.** Fields are in `model.schema.json`; `examples/lineage.json` is a complete model.
-4. **Validate:** `node --experimental-strip-types scripts/validate.mjs model.json`. Fix every error. Read every
-   warning.
-5. **Build:** `node --experimental-strip-types scripts/build.mjs model.json out/page.html`. It is one file with
-   no network use.
-6. **Check:** from a folder that has `playwright`:
-   `node <skill folder>/scripts/check.mjs out/page.html --out shots [--channel msedge]`.
-   Every check must pass. Open the screenshots and look at them: the checks do not judge taste.
-7. **Show** the page and the screenshots. Do not call it done until the checks pass and you have looked.
-
-Paths above are relative to the folder that holds this file. Node 22.6 or newer is needed.
-
-## Design rules (the engine and the checks enforce most of them)
-
-1. **No orphan.** Every node sits in a lane and has a link. A missing neighbour is a dotted placeholder that says
-   what is missing. Never guess a link.
-2. **The first view is readable**: fit to width at zoom 0.6 or more (up to 60 groups). Key `0` shows everything.
-3. **Read left to right**, with pinned column headers and a phase ribbon.
-4. **Motion carries state**: links flow by state, gaps breathe, the selected path draws in, a what-if ripples.
-   No decorative loops, no sweeping scan line, no bounce.
-5. **No permanent side panel.** The inspector slides in on a click and closes with Esc.
-6. **Standard controls**: select, hand, zoom in and out, fit, 100 percent, zoom to selection, fullscreen, keys.
-7. **Every state has a word as well as a colour.** Contrast at least 4.5 in light and dark.
-8. **Titles stay short** (one line at the column width). Long text goes in `subtitle` or `members`.
-9. **Fixed node sizes per kind.** The engine never measures text, so layout does not depend on fonts.
-10. **Reduced motion** removes all motion and keeps the glow.
-
-## Model in one screen
+In either route, derive node and link IDs from immutable business keys. Preserve these IDs across data refreshes so `update(model)` retains user state. Represent loading, empty, and error as typed states.
 
-```
-version 1, meta {title, help, asOf, source, labels?}, layout "columns-lanes"
-columns [{id, title, short?, width, phase?}]              stages, left to right
-lanes   [{id, title, badge?, badgeTone?, note?, gap?}]    rows; gap true = dashed amber "no document" lane
-states  {id: {word, tone, border, edge, motion, bucket}} the vocabulary; bucket good|neutral|gap
-nodes   [{id, kind, lane, col, colSpan?, row, state, title, subtitle?, members?, weight?, ref?, upgrade?,
-          stateIn?, visibleIn?}]                          kind: card group chip placeholder (others draw as cards)
-links   [{id, from, to, state, label?, stateIn?, visibleIn?}]   from must be in an earlier column than to
-views   [{id, label, default?}]                           the first view is the baseline
-inspector {relations [3 of {id,label,dir,filter?}], actions [{id,label,dir,staleText}]}
-notes   [{anchor, title, text}]                           anchor is a CSS selector for a part of the page
-```
+## Design rules
 
-Rows are numbers (1 row = 62 px). Keep nodes in one column at least 1 row apart. A lane needs about 1.75 rows of
-space between single-row lanes. `validate.mjs` checks all of this and names the node or link at fault.
+1. **No orphan**: every node sits in a lane and has a link. Missing neighbours use dotted placeholders.
+2. **Readable first view**: the initial view fits width at zoom 0.6 or higher (up to 60 visible groups). Key `0` fits all.
+3. **Read left to right**: pinned column headers and a phase ribbon guide the reader.
+4. **Motion carries state**: links flow by state, gaps breathe, selected paths pulse, what-if ripples. Avoid decorative animation.
+5. **No permanent side panel**: the inspector slides in on click and closes with Escape.
+6. **Standard controls**: select, hand, zoom in/out, fit, 100%, zoom to selection, fullscreen, and keyboard shortcuts.
+7. **Word and colour**: every state provides a label word and tone. Contrast meets 4.5:1 in light and dark themes.
+8. **Short titles**: titles fit one line at column width. Long descriptions belong in subtitles or member lists.
+9. **Fixed node dimensions**: node kinds use fixed box sizes so font rendering does not shift layout.
+10. **Reduced motion**: removes all animations while preserving static borders and status glows.
 
-## Build mode: implement it in a real app
+## Model summary
 
-Use the demo page as the visual contract and `model.schema.json` as the data contract.
+```
+version 1, meta {title, help, asOf, source, labels?}, layout "columns-lanes" | "free" | "auto"
+columns [{id, title, short?, width, phase?}]              stages, left to right
+lanes   [{id, title, badge?, badgeTone?, note?, gap?}]    rows; gap true = dashed amber lane
+states  {id: {word, tone, border, edge, motion, bucket}}  tone: ok|warn|crit|info|muted|accent; bucket: good|neutral|gap
+nodes   [{id, kind, lane?, col?, colSpan?, row?, x?, y?, w?, h?, state, title, subtitle?, members?, weight?,
+          ref?, upgrade?, contains?, collapsed?, stateIn?, visibleIn?, sla?, metrics?}]
+links   [{id, from, to, state, kind?, label?, stateIn?, visibleIn?}]   kind: forward | loop-back
+views   [{id, label, default?}]                           first view serves as baseline
+inspector {relations [up to 3], actions [{id, label, dir, staleText}]}
+notes   [{anchor, title, text}]                           anchor is a CSS selector in the page
+scenarios [{id, label, steps:[{link, at?, dur?, caption?}]}] at in seconds, dur in milliseconds
+```
 
-1. Copy the pure modules from `src/` into the app: `model.ts`, `layout.ts`, `viewport.ts`, `routing.ts`,
-   `trace.ts`, `rules.ts`, `stateCss.ts`, and their `*.test.ts` files. They have no DOM and no dependencies.
-2. Work test first: run the copied tests, then write a failing test for each change.
-3. Write the components in the app's own framework and design system (the demo's DOM and CSS are in
-   `src/render.ts`, `src/controls.ts`, `src/inspector.ts`, `src/chrome.ts`, `src/styles.css`). Feed them from the
-   app's real data through the app's hook and service layer. Make node and link ids stable (use business keys, not
-   array positions).
-4. Keep typed loading, empty and error states. A failed refresh keeps the last good graph. Never draw a missing
-   value as zero.
-5. Run `scripts/check.mjs` against the running app page for the structural, interaction and accessibility checks
-   (the page must expose the same element ids, or copy the harness and adapt it).
+## Limits
 
-A packaged React kit and live-update API are planned; until then, build mode is "copy the pure modules, port the
-DOM modules".
+- **Size**: up to 60 visible groups for a readable initial view.
+- **Node capacity**: up to 300 nodes using collapsible groups.
+- **No image export**: the engine does not export PNG, SVG, or PDF files. Use browser print or screenshots.
+- **No visual editor**: models are author-defined JSON; there is no drag-and-drop authoring canvas.
 
 ## Gotchas
 
-- Examples and any committed data must be invented: a public repo must not carry real host, job or repo names.
-- A model string is data, never markup. The engine renders text safely; keep it that way in any port.
-- The caddis pool budgets all skill descriptions together. Keep this one short.
-- `templates/engine.html` is generated. After changing `src/`, run `node --experimental-strip-types
-  scripts/build-engine.mjs` (it needs `esbuild`; see `README.md`).
+- **Time units**: `at` and `sla` use seconds for business elapsed time; `dur` uses milliseconds for UI token transitions.
+- **Fictional data only**: public repositories must never include real hosts, databases, jobs, or customer names.
+- **Data over markup**: strings are treated as plain text and escaped safely. Do not insert raw HTML into model fields.
+- **Generated engine**: `templates/engine.html` is generated. Run `node --experimental-strip-types scripts/build-engine.mjs` after modifying `src/`.

package/bundles/codex/.codex/skills/frontend/flow-studio/examples/README.md

@@ -5,6 +5,14 @@ Model files only. Build one with `node --experimental-strip-types scripts/build.
 | File | What it shows |
 |---|---|
 | `lineage.json` | A fictional data estate ("Northwind Analytics"): nine columns from source system to page, eight lanes (documented, infrastructure, gaps), four evidence states, two views (Today and Complete), portal chips, wide placeholders, the failure what-if. The proof that the generic engine reproduces a hand-built lineage page. |
+| `order-desk.json` | A retail order lifecycle that shows column-lane layout, gateway diamonds, and scenario playback with SLA breach detection. |
+| `ticket-lifecycle.json` | A support ticket workflow that shows column-and-lane layout, loop-back links, metrics, and scenario playback with SLA breach. |
+| `agent-journey.json` | An AI customer service workflow that shows phase columns, actor lanes, gateway branching, and loop-back error recovery. |
+| `incident-timeline.json` | A service outage timeline that shows time bucket columns, blast radius simulation, and before-and-after views. |
+| `ci-cd-pipeline.json` | A deployment pipeline that shows build stages, service lanes, approval gateways, and release rollback links. |
+| `approval-flow.json` | An expense approval workflow that shows automatic layout, role lanes, multiple decision gateways, and loop-back review paths. |
+| `service-map.json` | A microservice architecture that shows auto layout, collapsible data store groups, service health metrics, and blast radius simulation. |
+| `state-machine.json` | An order state machine that shows automatic layout, terminal and active order states, and return-flow loop-back transitions. |
 | `hostile.json` | The same model with markup and script text in every free-text field (`</script>`, an image with an `onerror`, quotes, U+2028 and U+2029). The check harness loads it to prove nothing executes. Do not use it as a template. |
 
 All data is fictional. The names are invented, and no real host, job, table or repository appears in them.

package/bundles/codex/.codex/skills/frontend/flow-studio/examples/agent-journey.json

@@ -0,0 +1,103 @@
+{
+  "version": 1,
+  "meta": {
+    "title": "AUTONOMOUS AGENT JOURNEY",
+    "help": "Follow an AI agent handling a customer service request from intake through tool execution and human supervision.",
+    "asOf": "2026-10-06",
+    "source": "Fictional Contoso Retail support telemetry. No real agent executions or customer records are used."
+  },
+  "layout": "columns-lanes",
+  "columns": [
+    { "id": "receive", "title": "Receive", "width": 150 },
+    { "id": "understand", "title": "Understand", "width": 160 },
+    { "id": "plan", "title": "Plan", "width": 150 },
+    { "id": "act", "title": "Act", "width": 160 },
+    { "id": "verify", "title": "Verify", "width": 160 },
+    { "id": "respond", "title": "Respond", "width": 150 }
+  ],
+  "lanes": [
+    { "id": "customer", "title": "Customer" },
+    { "id": "agent", "title": "Agent" },
+    { "id": "tools", "title": "Tools" },
+    { "id": "human", "title": "Human reviewer" }
+  ],
+  "states": {
+    "smooth": { "word": "SMOOTH", "tone": "ok", "border": "solid", "edge": "flow", "motion": "flow", "bucket": "good" },
+    "friction": { "word": "FRICTION", "tone": "warn", "border": "dashed", "edge": "dash", "motion": "flow-slow", "bucket": "neutral" },
+    "failure": { "word": "FAILURE", "tone": "crit", "border": "dotted", "edge": "dot", "motion": "breathe", "bucket": "gap" },
+    "settled": { "word": "SETTLED", "tone": "muted", "border": "solid", "edge": "dash-short", "motion": "none", "bucket": "good" }
+  },
+  "nodes": [
+    { "id": "cust-req", "kind": "start", "lane": "customer", "col": 0, "row": 0, "state": "smooth", "title": "Submit prompt" },
+    { "id": "cust-ack", "kind": "end", "lane": "customer", "col": 5, "row": 0, "state": "settled", "title": "Receive response" },
+    { "id": "agent-parse", "kind": "card", "lane": "agent", "col": 1, "row": 2, "state": "smooth", "title": "Parse prompt", "metrics": { "label": "Intent match", "value": 94, "max": 100, "unit": "%" } },
+    { "id": "agent-gate", "kind": "gateway", "lane": "agent", "col": 2, "row": 2, "state": "smooth", "title": "Confident?" },
+    { "id": "agent-eval", "kind": "card", "lane": "agent", "col": 4, "row": 2, "state": "smooth", "title": "Validate response" },
+    { "id": "agent-synth", "kind": "card", "lane": "agent", "col": 4, "row": 3.2, "state": "smooth", "title": "Synthesize answer" },
+    { "id": "tool-search", "kind": "card", "lane": "tools", "col": 3, "row": 5.2, "state": "smooth", "title": "Search catalog", "metrics": { "label": "Search latency", "value": 140, "max": 500, "unit": "ms", "series": [95, 110, 130, 125, 140] } },
+    { "id": "tool-exec", "kind": "card", "lane": "tools", "col": 3, "row": 6.4, "state": "friction", "title": "Execute mutation", "metrics": { "label": "API latency", "value": 480, "max": 600, "unit": "ms", "series": [210, 260, 310, 390, 480] } },
+    { "id": "tool-db", "kind": "card", "lane": "tools", "col": 3, "row": 7.6, "state": "smooth", "title": "State verification" },
+    { "id": "human-alert", "kind": "card", "lane": "human", "col": 3, "row": 9.6, "state": "friction", "title": "Escalation queue" },
+    { "id": "human-review", "kind": "card", "lane": "human", "col": 4, "row": 9.6, "state": "failure", "title": "Reviewer verdict", "sla": 30, "metrics": { "label": "Hold time", "value": 42, "max": 60, "unit": "s" } },
+    { "id": "human-approve", "kind": "end", "lane": "human", "col": 5, "row": 9.6, "state": "settled", "title": "Human override" }
+  ],
+  "links": [
+    { "id": "l-cust-parse", "from": "cust-req", "to": "agent-parse", "state": "smooth" },
+    { "id": "l-parse-gate", "from": "agent-parse", "to": "agent-gate", "state": "smooth" },
+    { "id": "l-gate-alert", "from": "agent-gate", "to": "human-alert", "state": "friction", "label": "Uncertain intent" },
+    { "id": "l-gate-search", "from": "agent-gate", "to": "tool-search", "state": "smooth", "label": "Search query" },
+    { "id": "l-gate-exec", "from": "agent-gate", "to": "tool-exec", "state": "friction", "label": "Run action" },
+    { "id": "l-search-eval", "from": "tool-search", "to": "agent-eval", "state": "smooth" },
+    { "id": "l-exec-db", "from": "tool-exec", "to": "agent-eval", "state": "friction" },
+    { "id": "l-db-eval", "from": "tool-db", "to": "agent-eval", "state": "smooth" },
+    { "id": "l-alert-review", "from": "human-alert", "to": "human-review", "state": "friction" },
+    { "id": "l-review-gate", "from": "human-review", "to": "agent-gate", "state": "friction", "kind": "loop-back", "label": "Refined guidance" },
+    { "id": "l-eval-synth", "from": "agent-eval", "to": "cust-ack", "state": "smooth" },
+    { "id": "l-synth-ack", "from": "agent-synth", "to": "cust-ack", "state": "smooth" },
+    { "id": "l-exec-alert", "from": "tool-exec", "to": "human-review", "state": "failure", "label": "Tool failure" },
+    { "id": "l-review-approve", "from": "human-review", "to": "human-approve", "state": "settled", "label": "Direct approval" }
+  ],
+  "scenarios": [
+    {
+      "id": "normal",
+      "label": "Normal request",
+      "steps": [
+        { "link": "l-cust-parse", "at": 0, "caption": "User requests store operating hours" },
+        { "link": "l-parse-gate", "at": 10, "caption": "Agent parses intent with high confidence" },
+        { "link": "l-gate-search", "at": 25, "caption": "Knowledge base search tool dispatched" },
+        { "link": "l-search-eval", "at": 45, "caption": "Answer returned and verified" },
+        { "link": "l-eval-synth", "at": 60, "caption": "Verified response delivered to user" }
+      ]
+    },
+    {
+      "id": "escalated",
+      "label": "Tool fails, human steps in",
+      "steps": [
+        { "link": "l-cust-parse", "at": 0, "caption": "User requests order address update" },
+        { "link": "l-parse-gate", "at": 10, "caption": "Intent recognized with moderate ambiguity" },
+        { "link": "l-gate-exec", "at": 20, "caption": "Agent attempts address update mutation" },
+        { "link": "l-exec-alert", "at": 45, "caption": "Mutation times out and crosses SLA target" },
+        { "link": "l-review-gate", "at": 65, "caption": "Reviewer inputs valid account address" },
+        { "link": "l-gate-search", "at": 80, "caption": "Agent re-runs lookup under new guidance" },
+        { "link": "l-search-eval", "at": 95, "caption": "Lookup confirms corrected address" },
+        { "link": "l-eval-synth", "at": 110, "caption": "Confirmation sent to customer" }
+      ]
+    }
+  ],
+  "inspector": {
+    "relations": [
+      { "id": "up", "label": "Invoked from", "dir": "up" },
+      { "id": "down", "label": "Dispatches to", "dir": "down" },
+      { "id": "outcomes", "label": "Journey completion", "dir": "down", "filter": { "kind": "end" } }
+    ],
+    "actions": [
+      { "id": "sim-tool-fail", "label": "Simulate: Tool timeout", "dir": "down", "staleText": "Simulating tool timeout and reviewer handoff" }
+    ]
+  },
+  "notes": [
+    { "anchor": "#n_agent-gate", "title": "Confidence evaluation gateway", "text": "The agent checks model confidence before executing tools or escalating to human staff." },
+    { "anchor": "#n_tool-search", "title": "Tool latency tracking", "text": "Tool invocation latency is measured across executions to detect API slowdowns early." },
+    { "anchor": "#n_human-review", "title": "Supervisory intervention SLA", "text": "Escalated actions wait in the supervisor queue with a 30-second target SLA." },
+    { "anchor": "#playbar", "title": "Scenario reproduction", "text": "Replay normal requests or examine supervisory intervention when tool failures occur." }
+  ]
+}

package/bundles/codex/.codex/skills/frontend/flow-studio/examples/approval-flow.json

@@ -0,0 +1,134 @@
+{
+  "version": 1,
+  "meta": {
+    "title": "EXPENSE APPROVAL WORKFLOW",
+    "help": "Track corporate expense reports from submission through management review, policy thresholds, and final disbursement.",
+    "asOf": "2026-10-06",
+    "source": "Fictional Contoso Retail expense system. No real employee records or transactions are used."
+  },
+  "layout": "auto",
+  "columns": [
+    { "id": "submit", "title": "Submit", "width": 150 },
+    { "id": "review", "title": "Manager review", "width": 160 },
+    { "id": "policy", "title": "Policy check", "width": 160 },
+    { "id": "finance", "title": "Finance review", "width": 160 },
+    { "id": "audit", "title": "Compliance", "width": 150 },
+    { "id": "payout", "title": "Disbursement", "width": 160 },
+    { "id": "settled", "title": "Close", "width": 150 }
+  ],
+  "lanes": [
+    { "id": "employee", "title": "Employee" },
+    { "id": "manager", "title": "Manager" },
+    { "id": "finance", "title": "Finance" },
+    { "id": "auditor", "title": "Auditor" }
+  ],
+  "states": {
+    "pending": { "word": "PENDING", "tone": "warn", "border": "dashed", "edge": "dash", "motion": "flow-slow", "bucket": "neutral" },
+    "approved": { "word": "APPROVED", "tone": "ok", "border": "solid", "edge": "flow", "motion": "flow", "bucket": "good" },
+    "rejected": { "word": "REJECTED", "tone": "crit", "border": "dotted", "edge": "dot", "motion": "none", "bucket": "gap" },
+    "waiting": { "word": "WAITING", "tone": "accent", "border": "dashed", "edge": "dash", "motion": "breathe", "bucket": "neutral" }
+  },
+  "nodes": [
+    { "id": "emp_draft", "kind": "start", "lane": "employee", "state": "pending", "title": "Draft claim", "subtitle": "Enter expenses" },
+    { "id": "emp_submit", "kind": "card", "lane": "employee", "state": "pending", "title": "Submit claim", "subtitle": "Attach receipts" },
+    { "id": "emp_resubmit", "kind": "card", "lane": "employee", "state": "waiting", "title": "Revise claim", "subtitle": "Add details", "sla": 120 },
+    { "id": "emp_notified", "kind": "end", "lane": "employee", "state": "approved", "title": "Receive notice", "subtitle": "Claim updated" },
+    { "id": "mgr_review", "kind": "card", "lane": "manager", "state": "pending", "title": "Review claim", "subtitle": "Verify line items" },
+    { "id": "mgr_gate", "kind": "gateway", "lane": "manager", "state": "pending", "title": "Manager approves?", "subtitle": "Approval threshold" },
+    { "id": "mgr_reject", "kind": "end", "lane": "manager", "state": "rejected", "title": "Manager rejected", "subtitle": "Claim denied" },
+    { "id": "fin_gate", "kind": "gateway", "lane": "finance", "state": "pending", "title": "Over the limit?", "subtitle": "Policy limit check" },
+    { "id": "fin_standard", "kind": "card", "lane": "finance", "state": "approved", "title": "Standard approve", "subtitle": "Within limits" },
+    { "id": "fin_exec", "kind": "card", "lane": "finance", "state": "pending", "title": "Exec approval", "subtitle": "Above threshold", "sla": 45 },
+    { "id": "fin_disburse", "kind": "card", "lane": "finance", "state": "approved", "title": "Process payment", "subtitle": "Issue reimbursement", "metrics": { "label": "Batch queue", "value": 14, "max": 20, "unit": "claims", "series": [8, 10, 12, 11, 14] } },
+    { "id": "fin_paid", "kind": "end", "lane": "finance", "state": "approved", "title": "Paid", "subtitle": "Funds transferred" },
+    { "id": "fin_reject", "kind": "end", "lane": "finance", "state": "rejected", "title": "Rejected", "subtitle": "Policy violation" },
+    { "id": "aud_sample", "kind": "card", "lane": "auditor", "state": "pending", "title": "Sample review", "subtitle": "Random audit" },
+    { "id": "aud_verify", "kind": "card", "lane": "auditor", "state": "approved", "title": "Tax check", "subtitle": "Validate tax codes" },
+    { "id": "aud_archive", "kind": "end", "lane": "auditor", "state": "approved", "title": "Archive file", "subtitle": "Store records" }
+  ],
+  "links": [
+    { "id": "l_draft_sub", "from": "emp_draft", "to": "emp_submit", "state": "pending" },
+    { "id": "l_sub_rev", "from": "emp_submit", "to": "mgr_review", "state": "pending" },
+    { "id": "l_rev_mgate", "from": "mgr_review", "to": "mgr_gate", "state": "pending" },
+    { "id": "l_mgate_fgate", "from": "mgr_gate", "to": "fin_gate", "state": "approved", "label": "Approved" },
+    { "id": "l_mgate_mrej", "from": "mgr_gate", "to": "mgr_reject", "state": "rejected", "label": "Rejected" },
+    { "id": "l_mgate_info", "from": "mgr_gate", "to": "emp_resubmit", "state": "waiting", "kind": "loop-back", "label": "Needs more info" },
+    { "id": "l_resub_rev", "from": "emp_resubmit", "to": "mgr_review", "state": "pending" },
+    { "id": "l_fgate_std", "from": "fin_gate", "to": "fin_standard", "state": "approved", "label": "Under limit" },
+    { "id": "l_fgate_exec", "from": "fin_gate", "to": "fin_exec", "state": "pending", "label": "Over limit" },
+    { "id": "l_fgate_frej", "from": "fin_gate", "to": "fin_reject", "state": "rejected", "label": "Policy breach" },
+    { "id": "l_std_pay", "from": "fin_standard", "to": "fin_disburse", "state": "approved" },
+    { "id": "l_exec_aud", "from": "fin_exec", "to": "aud_verify", "state": "approved" },
+    { "id": "l_aud_pay", "from": "aud_verify", "to": "fin_disburse", "state": "approved" },
+    { "id": "l_pay_paid", "from": "fin_disburse", "to": "fin_paid", "state": "approved" },
+    { "id": "l_paid_notif", "from": "fin_paid", "to": "emp_notified", "state": "approved" },
+    { "id": "l_aud_sample", "from": "fin_standard", "to": "aud_sample", "state": "pending" },
+    { "id": "l_sample_arch", "from": "aud_sample", "to": "aud_archive", "state": "approved" }
+  ],
+  "inspector": {
+    "relations": [
+      { "id": "upstream", "label": "Submitted by", "dir": "up" },
+      { "id": "down", "label": "Routes to", "dir": "down" },
+      { "id": "audit", "label": "Audit record", "dir": "down" }
+    ],
+    "actions": [
+      {
+        "id": "sim_reject",
+        "label": "Simulate: reject claim",
+        "dir": "down",
+        "staleText": "Claim rejected. Notification sent to employee."
+      }
+    ]
+  },
+  "notes": [
+    {
+      "anchor": "#viewport",
+      "title": "Expense routing overview",
+      "text": "Expenses route through management sign-off and finance policy thresholds before payment."
+    },
+    {
+      "anchor": "#n_mgr_gate",
+      "title": "Manager approval gate",
+      "text": "Managers verify expense legitimacy, reject non-compliant items, or ask for receipts."
+    },
+    {
+      "anchor": "#n_fin_gate",
+      "title": "Policy limit gateway",
+      "text": "Expenses above the standard threshold escalate to executive finance approval."
+    },
+    {
+      "anchor": "#playbar",
+      "title": "Scenario playback",
+      "text": "Select the standard or executive path to see workflow routing and SLA timing."
+    }
+  ],
+  "scenarios": [
+    {
+      "id": "standard_path",
+      "label": "Standard approval",
+      "steps": [
+        { "link": "l_draft_sub", "at": 0, "caption": "Employee submits expense report" },
+        { "link": "l_sub_rev", "at": 10, "caption": "Direct manager begins receipt review" },
+        { "link": "l_rev_mgate", "at": 20, "caption": "Receipts verified and approved by manager" },
+        { "link": "l_mgate_fgate", "at": 30, "caption": "Claim enters finance policy check" },
+        { "link": "l_fgate_std", "at": 40, "caption": "Total falls within standard spending policy" },
+        { "link": "l_std_pay", "at": 50, "caption": "Finance schedules payment batch" },
+        { "link": "l_pay_paid", "at": 60, "caption": "Payment disbursed directly to bank account" }
+      ]
+    },
+    {
+      "id": "exec_path",
+      "label": "Executive approval",
+      "steps": [
+        { "link": "l_draft_sub", "at": 0, "caption": "Employee submits high-value travel claim" },
+        { "link": "l_sub_rev", "at": 10, "caption": "Manager approves baseline receipts" },
+        { "link": "l_rev_mgate", "at": 20, "caption": "Manager routes to finance queue" },
+        { "link": "l_mgate_fgate", "at": 30, "caption": "Policy engine flags claim above standard limit" },
+        { "link": "l_fgate_exec", "at": 55, "caption": "Executive review exceeds target SLA window" },
+        { "link": "l_exec_aud", "at": 70, "caption": "Tax compliance auditor validates receipts" },
+        { "link": "l_aud_pay", "at": 85, "caption": "Auditor clears claim for disbursement" },
+        { "link": "l_pay_paid", "at": 100, "caption": "Reimbursement paid to employee" }
+      ]
+    }
+  ]
+}