@caddis/cli 0.4.43 → 0.4.45

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

@@ -0,0 +1,61 @@
+<!doctype html>
+<!--
+  flow-studio page (generated). Do not edit this file by hand.
+  Source: .github/skills/frontend/flow-studio (src/*.ts, src/styles.css, templates/engine.shell.html).
+  Rebuild the engine:  node --experimental-strip-types scripts/build-engine.mjs
+  Build a page:        node --experimental-strip-types scripts/build.mjs model.json out.html
+  The model and the notes are JSON in the two script tags at the end of the body.
+-->
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>flow-studio</title>
+<style id="state-css"></style>
+<style>/*__CSS__*/</style>
+</head>
+<body>
+<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>
+
+  <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">
+    <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="0"><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 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>
+
+<script type="application/json" id="flow-model">/*__MODEL__*/{}</script>
+<script type="application/json" id="flow-notes">/*__NOTES__*/[]</script>
+<script>/*__ENGINE__*/</script>
+</body>
+</html>

package/bundles/antigravity-plugin/skills/flow-studio/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023", "DOM"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "types": []
+  },
+  "include": ["src"],
+  "exclude": ["src/**/*.test.ts"]
+}

package/bundles/antigravity-plugin/skills/implement/SKILL.md

@@ -154,6 +154,14 @@ row, visible to any later reader without an Advisory Hub having to catch it live
     `AGENTS.md`. Never write orchestration notes to `.caddis/kb/`.
 7. **Never write a load or stress test into a lane prompt or findings file.** The script refuses
    this wording without `--allow-load`. Only the owner gives that flag.
+7b. **Write test economy into every agent brief, not only the lane prompt.** The script already adds it
+   to its lane prompts. A brief you write yourself (an Agent-tool subagent, a peer session) needs the same
+   five lines: after each step run only the tests for the file or module you changed; run the full suite only
+   for the baseline and once at the end; run no review loop inside the agent (you review); report progress
+   every 20 minutes; never start a second heavy test run while one is still running. **Two parallel agents
+   must not both run full suites.** Measured 2026-10-02 on one shared box: a 2,063-test suite took 2.7 min
+   alone and 6.7 min beside a second test-heavy agent, and one agent's brief (baseline, tests after each of 9
+   module switches, full gates, in-agent review) cost 30-40 of its 59 minutes.
 8. Record these Tracker values:
    - `Model` = the packet's `model`.
    - `Lane` = the lanes tried, joined with ` -> ` and followed by the reason. For example,

package/bundles/antigravity-plugin/skills/particle-art/SKILL.md

@@ -1,7 +1,12 @@
 ---
 name: particle-art
 version: 1.0.0
-description: Zero-dependency animated particle art as a React/Next.js component (spring physics, CSS-variable theming, mouse interaction). Use for animated hero art or a living logo, or on "particles that form a shape", "particle animation", "node network", "animated letter/logo/initials", "living letter", "morphing particles", "constellation", "neural net art", "dot field", "stipple portrait", "halftone animation", "ASCII art animation", "background art for my site", or "art that reacts to mouse".
+description: >-
+  Zero-dependency animated particle art as a React/Next.js component (spring physics, CSS-variable
+  theming, mouse interaction). Use for animated hero art or a living logo, or on "particle animation",
+  "particles that form a shape", "animated letter/logo/initials", "morphing particles",
+  "constellation", "neural net art", "halftone animation", "ASCII art animation", or "art that reacts
+  to mouse".
 ---
 
 # Particle Art Generator

package/bundles/antigravity-plugin/skills/port-to-github/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: port-to-github
-description: Port an app or repo to GitHub from any source (git server, local folder, UNC share, Windows box over WinRM) — all branches and tags, SHA-verified, CI translated, history kept source-only, deploy cut over with rollback. Use when the user says "move this app to GitHub", "port X to GitHub", "migrate from Gitea", "put this folder on GitHub", "this app only exists on the server", "import the repo from the prod box", "keep binaries / MariaDB / PHP out of the repo", "check the repo only holds source", or "cut the deploy over to GitHub".
+description: >-
+  Port an app or repo to GitHub from any source (git server, local folder, UNC share, Windows box over
+  WinRM): all branches and tags, SHA-verified, CI translated, source-only history, deploy cut over
+  with rollback. Use when the user says "move this app to GitHub", "port X to GitHub", "migrate from
+  Gitea", "this app only exists on the server", "import the repo from the prod box", "keep binaries
+  out of the repo", or "cut the deploy over to GitHub".
 ---
 
 # port-to-github

package/bundles/antigravity-plugin/skills/tech-explainer/SKILL.md

@@ -3,12 +3,11 @@ name: tech-explainer
 context: fork
 description: >-
   Plain-language explainer, with ranked Mermaid diagrams and Simplified Technical English, for a
-  reader who did NOT do the investigation (manager, stakeholder). Use when the user says "explain
-  this to X", "explainer", "write this up for someone non-technical", "plain English", "simplified
-  technical english", "STE", "explain our findings", "write up the benchmark results", "answer my
-  manager's recommendations", "why is it slow — document it", "make a doc with diagrams explaining
-  the stack", or summarises an investigation for a reader who won't read the raw data. Not for build
-  hand-offs (explainer-doc) or READMEs.
+  reader who did NOT do the investigation (manager, stakeholder). Use when the user says "explain this
+  to X", "explainer", "write this up for someone non-technical", "plain English", "STE", "explain our
+  findings", "write up the benchmark results", "why is it slow — document it", or summarises an
+  investigation for a reader who won't read the raw data. Not for build hand-offs (explainer-doc) or
+  READMEs.
 ---
 
 # tech-explainer — make a stranger understand, and able to push back

package/bundles/antigravity-plugin-extras/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis-extras",
-  "version": "1.3.40",
+  "version": "1.3.41",
   "description": "caddis-extras — the long-tail skills for the Antigravity (agy) caddis plugin; install alongside caddis for the full set."
 }

package/bundles/antigravity-plugin-extras/skills/_registry.md

@@ -22,11 +22,13 @@
 
 | Skill | Path | When to Use |
 |-------|------|-------------|
+| Adopt Rbac | `adopt-rbac/` | >- |
 | Anchor Review | `anchor-review/` | Single-model adversarial review technique — 3-lens analysis with confidence scoring and self-challenge |
 | Api Client Patterns | `api-client-patterns/` | Typed client-side API consumption: fetch wrappers, zod validation, auth injection, TanStack Query (useQuery, useMutation, optimistic updates), tRPC, OpenAPI codegen, pagination. Use when consuming REST or tRPC APIs. |
 | Architecture Design | `architecture-design/` | Design application architecture and system diagrams with layered patterns, Mermaid C4 diagrams, SQL Server data platform, and on-premise deployment considerations. |
 | Backend To Frontend Handoff Docs | `backend-to-frontend-handoff/` | Document a finished backend API for frontend integration. Use when the user says 'create handoff', 'document API', 'frontend handoff', or 'API documentation'. |
 | Caching Patterns | `caching-patterns/` | Caching strategies for Streamlit and FastAPI applications |
+| Case Management | `case-management/` | >- |
 | Code Explainer | `code-explainer/` | Explain code with diagrams, analogies and step-by-step walkthroughs. Use when teaching a codebase or answering "how does this work?" |
 | Cross Review | `cross-review/` | Have a different vendor's model (DeepSeek, GLM, any OpenAI-compatible endpoint) review the current diff. Use after a phase is green and before commit/merge, or for a second opinion on a risky diff. |
 | Llm Application Dev | `llm-application-dev/` | LLM applications: prompt engineering, RAG and LLM integration. Use for AI-powered features, chatbots or LLM automation. |

package/bundles/antigravity-plugin-extras/skills/adopt-rbac/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: adopt-rbac
+description: >-
+  Pointer to the org's RBAC adoption skill. Use for "add RBAC to this app" or "adopt rbac-kit".
+---
+
+# adopt-rbac (pointer)
+
+RBAC adoption depends on organisation-specific things: the shared package and its pin, the auth
+proxy that supplies identity, prod paths, the rollout order. So the real skill lives in the
+organisation's private platform repo, next to the package it describes:
+
+    <PLATFORM_REPO>/.claude/skills/adopt-rbac/SKILL.md
+
+**Find it, read it in full, and follow it.** This pointer only makes it findable from a session
+opened in another repo.
+
+1. If `.github/project-config.md` sets `<PLATFORM_REPO>`, use that checkout.
+2. Otherwise look in the folders next to the current project for one that contains
+   `.claude/skills/adopt-rbac/SKILL.md`.
+3. If the repo is only on the remote, read the file with `gh api` from the platform repo.
+4. If none of these works, stop and ask the user where it is. Do not improvise RBAC from memory:
+   improvised copies drift, and a drifted copy is how a privilege escalation ships.
+
+The skill and the package live in one repo on purpose, so a package change and its skill update
+land in the same PR.

package/bundles/antigravity-plugin-extras/skills/case-management/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: case-management
+description: >-
+  Pointer to the org's case-management blueprint. Use for "add case management".
+---
+
+# case-management (pointer)
+
+The blueprint is drawn from a live, organisation-specific implementation, so it lives in the
+organisation's private platform repo:
+
+    <PLATFORM_REPO>/.claude/skills/case-management/SKILL.md
+
+**Find it, read it in full, and follow it.** This pointer only makes it findable from a session
+opened in another repo. Case management needs RBAC first: see the sibling **adopt-rbac** skill.
+
+1. If `.github/project-config.md` sets `<PLATFORM_REPO>`, use that checkout.
+2. Otherwise look in the folders next to the current project for one that contains
+   `.claude/skills/case-management/SKILL.md`.
+3. If the repo is only on the remote, read the file with `gh api` from the platform repo.
+4. If none of these works, stop and ask the user where it is.
+
+It is a blueprint, not a package yet. When a second app adopts case management, the blueprint
+says to extract the generic half into a `case-kit` package with that app as the first consumer.

package/bundles/codex/.codex/skills/devops/adopt-app/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: adopt-app
-description: Bring an app that was never scaffolded (POC, server folder, checkout with no remote) up to standard — inventory without running it, pass/gap/question verdicts, ordered plan. Use when the user says "this app was never set up properly", "adopt this POC", "onboard this app", "it just runs from a folder on the server", "bring this up to standard", "what would it take to get this into CI", "nobody knows how this is deployed", or "it started as a prototype and now it is production".
+description: >-
+  Bring an app that was never scaffolded (POC, server folder, checkout with no remote) up to standard:
+  inventory without running it, pass/gap/question verdicts, ordered plan. Use when the user says "this
+  app was never set up properly", "adopt this POC", "onboard this app", "it just runs from a folder on
+  the server", "what would it take to get this into CI", "nobody knows how this is deployed", or "it
+  started as a prototype and now it is production".
 ---
 
 # adopt-app

package/bundles/codex/.codex/skills/devops/port-to-github/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: port-to-github
-description: Port an app or repo to GitHub from any source (git server, local folder, UNC share, Windows box over WinRM) — all branches and tags, SHA-verified, CI translated, history kept source-only, deploy cut over with rollback. Use when the user says "move this app to GitHub", "port X to GitHub", "migrate from Gitea", "put this folder on GitHub", "this app only exists on the server", "import the repo from the prod box", "keep binaries / MariaDB / PHP out of the repo", "check the repo only holds source", or "cut the deploy over to GitHub".
+description: >-
+  Port an app or repo to GitHub from any source (git server, local folder, UNC share, Windows box over
+  WinRM): all branches and tags, SHA-verified, CI translated, source-only history, deploy cut over
+  with rollback. Use when the user says "move this app to GitHub", "port X to GitHub", "migrate from
+  Gitea", "this app only exists on the server", "import the repo from the prod box", "keep binaries
+  out of the repo", or "cut the deploy over to GitHub".
 ---
 
 # port-to-github

package/bundles/codex/.codex/skills/docs/tech-explainer/SKILL.md

@@ -3,12 +3,11 @@ name: tech-explainer
 context: fork
 description: >-
   Plain-language explainer, with ranked Mermaid diagrams and Simplified Technical English, for a
-  reader who did NOT do the investigation (manager, stakeholder). Use when the user says "explain
-  this to X", "explainer", "write this up for someone non-technical", "plain English", "simplified
-  technical english", "STE", "explain our findings", "write up the benchmark results", "answer my
-  manager's recommendations", "why is it slow — document it", "make a doc with diagrams explaining
-  the stack", or summarises an investigation for a reader who won't read the raw data. Not for build
-  hand-offs (explainer-doc) or READMEs.
+  reader who did NOT do the investigation (manager, stakeholder). Use when the user says "explain this
+  to X", "explainer", "write this up for someone non-technical", "plain English", "STE", "explain our
+  findings", "write up the benchmark results", "why is it slow — document it", or summarises an
+  investigation for a reader who won't read the raw data. Not for build hand-offs (explainer-doc) or
+  READMEs.
 ---
 
 # tech-explainer — make a stranger understand, and able to push back

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

@@ -0,0 +1,53 @@
+# flow-studio (engine source)
+
+Stage S1a of 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.
+
+## Use it
+
+```bash
+# 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
+```
+
+Open `out/lineage.html`. It has no network access and no libraries.
+
+`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
+`#viewport`.
+
+## Check a page
+
+The harness drives a real browser. Run it from a folder whose `node_modules` has `playwright`
+(it is looked up from the current folder, not from this one):
+
+```bash
+node /path/to/flow-studio/scripts/check.mjs out/lineage.html --out shots --hostile out/hostile.html --channel msedge
+```
+
+It checks structure (no overlap, links touch their nodes, text stays inside cards, readable first view),
+interaction (zoom, pan, select, what-if, view switch), accessibility (names, focus, contrast in both themes,
+reduced motion), safety (no network, hostile text stays inert) and performance (200 nodes). Exit code 0 means
+every check passed.
+
+`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`.
+
+## Develop it
+
+- The source of truth is `src/*.ts`. The pure modules (`model`, `viewport`, `routing`, `trace`, `layout`,
+  `rules`, `stateCss`) have unit tests. The DOM modules (`render`, `controls`, `interact`, `inspector`,
+  `chrome`, `notes`, `engine`) are tested through the check harness.
+- `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
+  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).
+- 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

@@ -0,0 +1,103 @@
+---
+name: flow-studio
+description: Design an interactive flow, lifecycle or journey page (nodes, lanes, links, motion, inspector, notes) from a JSON model as a self-contained demo, then build it in an app. Use for lineage, pipelines, ticket or agent journeys.
+---
+
+# 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.
+
+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.
+
+## What works today (version 0.1)
+
+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.
+
+**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.
+
+## Process: demo mode
+
+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
+
+```
+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
+```
+
+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.
+
+## Build mode: implement it in a real app
+
+Use the demo page as the visual contract and `model.schema.json` as the data contract.
+
+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).
+
+A packaged React kit and live-update API are planned; until then, build mode is "copy the pure modules, port the
+DOM modules".
+
+## 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`).

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

@@ -0,0 +1,11 @@
+# Examples
+
+Model files only. Build one with `node --experimental-strip-types scripts/build.mjs examples/<name>.json out/<name>.html`.
+
+| 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. |
+| `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.
+`lineage.json` and `hostile.json` are generated by a script that is not part of the skill; edit the JSON directly.