@caddis/cli 0.4.73 → 0.4.74

package/bundles/antigravity-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis",
-  "version": "1.3.159",
+  "version": "1.3.160",
   "description": "caddis — agent-agnostic dev harness as an Antigravity (agy) plugin: TDD skills + commands, single-sourced with the Claude Code plugin."
 }

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

@@ -117,6 +117,7 @@
 | Skill | Path | When to Use |
 |-------|------|-------------|
 | Draw Io | `draw-io/` | draw.io diagram creation, editing, and review. Use for .drawio XML editing, PNG conversion, layout adjustment, and AWS icon usage. |
+| Flow Chart From Counts | `flow-chart-from-counts/` | Turn a from-to-count edge list into a zoomable Mermaid flow chart page with counts, a legend and a render check. |
 | Mermaid Diagrams | `mermaid-diagrams/` | Software diagrams in Mermaid: class, sequence, flowchart, ERD, C4, state, git graph, gantt. Use for domain models, API flows, processes and database schemas. |
 | Particle Art | `particle-art/` | >- |
 

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

@@ -236,7 +236,10 @@ and 7.3. While the queue is frozen (section 5 step 1), do steps 3.1 to 3.3 only.
     Do only the merge or the `go`:
     - Target mode: `GH_TOKEN=$(gh auth token -u <account>) gh pr merge <n> --<merge_method> --match-head-commit <watched sha>`.
       The merge SHA is `mergeCommit.oid` from `gh pr view <n> --json state,mergeCommit`.
-    - Interim mode: send `go <PR> <watched sha>`; the PR's session merges with the same command. Then
+    - Interim mode: send `go <PR> <watched sha>`, and on the next line: `I wrote the ack file
+      ~/.claude/merge-acks/<checkout folder name>/pr-<n>.json. Do not write, change or delete it.` The PR's
+      session merges with the same command. If its merge hook refuses because the ack file is wrong or
+      missing, write the ack file again (step 3.13) and send `go` once more. Then
       poll with a Bash command in `run_in_background`: `gh pr view <n> --json state,mergeCommit` once a
       minute, for at most 15 min, until `state` is `MERGED`. Take `mergeCommit.oid` as the merge SHA; the
       session's `merged` reply only tells you to look. No merge after 15 min: ask the PR's session once.

package/bundles/antigravity-plugin/skills/flow-chart-from-counts/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: flow-chart-from-counts
+description: Turn a from-to-count edge list into a zoomable Mermaid flow chart page with counts, a legend and a render check.
+---
+
+# flow-chart-from-counts
+
+Turns counted paths (N cases went from step A to step B) into a flow chart page that a
+reader can trust: counts on every arrow, a legend for the box types, a title with the date and
+time zone, a note that names what is not drawn, and a viewer with zoom, pan and full screen.
+
+Paths below are relative to the folder that holds this file.
+
+## When to use it
+
+- "Draw how cases move through the process", "show the journey with counts", "flow chart of
+  calls / orders / tickets / sessions from this table".
+- You have, or can query, rows of `from, to, count`, or an event table with one row per step.
+- A Sankey or a funnel was asked for, but the paths branch and rejoin: a flow chart shows that
+  better.
+
+Use something else for:
+
+- An interactive page from a JSON model with lanes, playback and an inspector: `flow-studio`.
+- Mermaid syntax for other diagram kinds (sequence, ERD, class): `mermaid-diagrams`.
+- A diagram of a SQL object's structure: `db-diagram`.
+
+## What is in the folder
+
+| file | use |
+|---|---|
+| `scripts/edges_to_mermaid.py` | CSV edge list to first-draft Mermaid source (standard library only) |
+| `assets/viewer-template.html` | page with the zoom/pan/full-screen viewer, theme tokens and one example chart |
+| `scripts/check-render.mjs` | headless render check: fails on no SVG, error text, too few nodes, page errors; saves screenshots |
+| `references/edge-list-sql.md` | SQL pattern: event table to edge list and box counts, and the checks to run on it |
+
+## Process
+
+1. **Get the edge list.** From an event table, use `references/edge-list-sql.md`. Run its checks
+   (START rows add up to the cases; path occurrences in equal path occurrences out per step).
+   Count arrows as distinct cases per pair. Get the box counts (distinct cases per step) at the
+   same time.
+2. **Name the node types** with the reader, or from the process owner's own glossary: for
+   example automatic step, in-scope step, optional step, hand-off, end. Write a `nodes.csv`
+   (`name,type,count`).
+3. **Make the first draft:**
+   ```
+   python scripts/edges_to_mermaid.py edges.csv --nodes nodes.csv --min 25 \
+          --in-scope scope --optional choice --out chart.mmd --strict
+   ```
+   `--out` writes UTF-8 (do not use `>` in Windows PowerShell 5.1: it can write UTF-16). The note
+   on hidden paths goes to stderr. Keep it: it goes under the chart. `--strict` exits 1 on a
+   `warning:` line, which means an arrow is larger than its box: fix the query before you draw.
+   Duplicate `from,to` rows are added together. Node types become classes named `t_<type>`.
+4. **Put it in the page.** Copy `assets/viewer-template.html`. Paste the source into the
+   `<script type="text/plain">` block. Set `data-title` (what, which day) and `data-sub` (the UTC
+   window, the unit of the counts, the minimum path size). Replace the legend and the note.
+   For more charts, add one `.fv` block and one source script per chart.
+5. **Render and check:**
+   ```
+   node <skill folder>/scripts/check-render.mjs page.html --out shots [--channel msedge]
+   ```
+   Run it from a folder whose `node_modules` has `playwright`. It exits 1 when a check fails.
+6. **Look at the screenshots** (`chart-N.png` is the chart at Fit, `chart-1-full.png` is full
+   screen) and run the tidy checklist below. If a rule fails, change the layout with the layout
+   fixes, and go back to step 5.
+7. **Show** the page and the screenshots only when every checklist rule passes. Say which labels
+   are your reading (see Wording). If a rule cannot be met, say which rule and why.
+
+## Tidy checklist (the chart must pass it before you show it)
+
+A clean, tidy chart is an acceptance rule, not a nice-to-have. A reader who has to trace a
+line across the page stops trusting the numbers on it.
+
+1. **No crossing lines.** No line passes through a box or a label. Use the tree rule with
+   dashed stubs, and split shared targets (layout fixes 1 and 2).
+2. **No overlaps.** No label or box sits on another. Edge labels are short: `(1,234)` and at
+   most a few words. Long text goes in the note under the chart, not on the chart.
+3. **Rows and side flows.** Boxes of the same kind line up in one row where the flow allows
+   (layout fix 5). A side flow sits in its own dashed box at the bottom, pushed down with an
+   invisible link (layout fix 4).
+4. **One look per type.** One box shape per type, a small fixed palette (5 to 7 classes), a
+   legend that matches the chart exactly (stubs included), and the title with the date and the
+   time zone on the chart.
+5. **Readable at Fit and at full screen** on a 1280 x 900 screen. Nothing is clipped.
+6. **Checked by eye.** You opened both screenshots and checked rules 1 to 5 on them. The render
+   check's warnings (box overlaps, labels on boxes) help, but they cannot see a crossing line.
+
+## Count rules
+
+- **Arrows and boxes both count distinct cases.** An arrow says how many distinct cases took
+  that path (`COUNT(DISTINCT case_id)` per from-to pair). A box says how many distinct cases
+  reached it. Do not draw path occurrences (`COUNT(*)`): a case that loops counts twice, and a
+  reader who sees a box of 8,538 followed by an arrow of 8,541 stops trusting the chart. Label
+  every number as cases.
+- **Self-check: no arrow into or out of a box exceeds that box's count.** If one does, the
+  query counts occurrences. The converter warns on stderr when this happens.
+- **Say in the note that arrows into a box can sum to a little more than the box**, because a
+  case can reach it by two paths.
+- **Put counts in brackets, with thousands separators:** `(1,234)`. In Mermaid an edge label that
+  holds brackets must be quoted: `A -->|"(1,234)"| B`. Unquoted, `(` starts a node shape and the
+  chart fails to parse.
+- **Hide small paths with a stated minimum.** Choose a minimum (for example 25), drop the paths
+  under it, and write a note that names them and their total: "Not drawn because fewer than 25
+  cases took them: X to Y (12), ... (41 in total)." A chart that drops paths without a note looks
+  complete and is not.
+- **Merge small boxes into one named box, and say so.** When you merge, the count is a sum of
+  rounded or filtered parts: write `(about 600)`, and say in the note what the box holds.
+- **Put the date and the time zone on the chart.** Write the title as HTML inside the zoomable
+  stage (the template does this from `data-title` and `data-sub`), so it stays with the chart in
+  full screen and in screenshots. Do not use a frontmatter `title:` as well: it would show a second title. Give the
+  local day and the UTC window: `Mon 5 Oct 2026 (4 Oct 23:00 to 5 Oct 23:00 UTC)`.
+- **Name the unit.** "Counts in brackets are calls / orders / cases." A count with no unit gets
+  read as the wrong one.
+
+## Node types and the legend
+
+- One `classDef` per node type, and one `class id1,id2 type;` line per type. The converter writes
+  these from `nodes.csv`.
+- **In-scope boxes get a thick border** (`stroke-width:3px`), so the reader finds the subject of
+  the chart first.
+- **Optional or owner-choice boxes get a dashed border** (`stroke-dasharray:6 4`): a step that is
+  a decision still open, or one that runs only for some cases.
+- End boxes share one quiet grey class. Stubs share one class: white fill, thin dashed grey
+  border (`stroke-dasharray:3 3`), so they read as pointers, not steps.
+- Put a legend above the chart with one swatch per type, with the same fill, border width and
+  dash as the chart. Use light fills with dark text. Keep the chart canvas light in dark mode
+  too (the template's `--canvas` token does this), or the dark text loses contrast.
+
+## Layout fixes that work
+
+Mermaid's layout (dagre) puts each node on a rank and orders each rank to cut crossings. It does
+not know what the reader looks for. These fixes move it.
+
+1. **Draw the chart as a tree.** Give every box exactly one parent edge: the biggest path into
+   it. For every other path into that box, add a small dashed stub under its own source,
+   labelled with the target and the count: `B --> toB_C(["to C (412)"])`. Shared targets and
+   back-edges are what make the layout cross lines; a tree with stubs has none. Add a legend
+   entry for stubs ("dashed: the path continues at the box named"). The converter does this by
+   default (`--no-tree` turns it off).
+2. **Give each source its own end box.** One shared "Ends" box pulls a long line from every step
+   across the chart. Write `A --> endA(["Ends"])` and `B --> endB(["Ends"])` instead. The
+   converter does this. Apply the same fix to any shared target that sits far from its sources:
+   a copy of the box next to each source is easier to read than one box with crossing lines.
+3. **Do not draw a loop-back as an edge.** A line back up the chart crosses everything. End the
+   path in a stub: `A --> backA(["back to Triage (190)"])`. The converter does this for every
+   edge that points back to a step on the path.
+4. **Put a side flow in its own subgraph and push it down.** For example the steps after a
+   hand-off. Draw them in `subgraph AFTER[...] direction LR ... end` and add an invisible link
+   from a low node of the main flow: `X2 ~~~ AFTER`. The subgraph then sits under the main
+   flow, not beside it.
+5. **Put same-kind boxes in one row.** Group them in a subgraph, and lengthen the edges into it
+   (`---->`, one dash per extra rank) so they land on the same rank.
+6. **Replace a long jump with a short stub or a dotted link.** When an edge must reach a box
+   far away, end it in a small stub node near the source, or draw it dotted (`-.->`) with a
+   label such as `"few"`, so the eye can tell it is secondary.
+7. **Order the edges from a node in the order you want the boxes, left to right**, and declare
+   the nodes in the same order. Dagre takes this as its first guess. It can still swap them to
+   cut crossings: check the screenshot.
+8. **Quote every label that holds brackets, quotes or `<br/>`:** `["Text<br/>(12)"]`,
+   `|"(12)"|`. Write a quote inside a label as `#quot;`.
+
+Change one thing at a time and re-render. Two fixes at once hide which one helped.
+
+## Wording
+
+- **Use the process owner's words for box labels** when a glossary or a list of step names
+  exists. A reader checks the chart against those names.
+- **Write neutral endings.** "Case ends" or "Call ends" means the data shows no further step.
+  Do not write a guess such as "hangs up" or "gives up": the data does not say who ended it.
+  Say what "ends" means in the note.
+- **Mark your own reading.** When a label or a grouping is your interpretation, not a name from
+  the source, say so in the note ("'Team queues' is our grouping of four queues").
+
+## Verify
+
+`scripts/check-render.mjs` fails (exit 1) when a chart has no SVG, shows an error message, has
+fewer nodes than `--min-nodes`, or the page throws. Make it fail once on purpose (break one
+line of the source) to see that it can. It also counts box overlaps and arrow labels on boxes
+as warnings. Those are hints: open the screenshots and run the tidy checklist by eye, because
+the check cannot see a crossing line.
+
+Also check the numbers, not only the drawing: the START count equals the cases in the window,
+and no arrow into or out of a box is larger than the box (the converter warns when one is).
+
+## Publishing
+
+- As an Artifact: follow the artifact-design rules. Mermaid loads from
+  `https://cdnjs.cloudflare.com/ajax/libs/mermaid/10.9.1/mermaid.min.js` (an exact version on the
+  allowed CDN). The template already has theme tokens for light and dark, an explicit body
+  background, and a 16px side gutter for phone width.
+- In an app: render with the app's own Mermaid package and keep the same source, title and note.
+  Keep the count rules; they are what makes the chart trustworthy.

package/bundles/antigravity-plugin/skills/flow-chart-from-counts/assets/viewer-template.html

@@ -0,0 +1,190 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Case Flow Chart</title>
+<style>
+/* Flow chart page from the flow-chart-from-counts skill.
+   One .fv block per chart. Each block names a <script type="text/plain"> that holds the Mermaid source.
+   --canvas stays light in dark mode on purpose: the coloured boxes use dark text and need a light ground. */
+:root{
+  --bg:#faf8f5; --surface:#ffffff; --ink-1:#1c1917; --ink-2:#57534e; --ink-3:#78716c; --line:#e7e2da; --canvas:#fbfaf8;
+  --sans:"Segoe UI",system-ui,-apple-system,Arial,sans-serif; --mono:Consolas,ui-monospace,"Courier New",monospace;
+}
+@media (prefers-color-scheme: dark){:root:not([data-theme="light"]){
+  --bg:#23252f; --surface:#2c2f3b; --ink-1:#f3f1ec; --ink-2:#c9c6c0; --ink-3:#a19d97; --line:#3f4250; --canvas:#f4f2ee; color-scheme:dark}}
+:root[data-theme="dark"]{
+  --bg:#23252f; --surface:#2c2f3b; --ink-1:#f3f1ec; --ink-2:#c9c6c0; --ink-3:#a19d97; --line:#3f4250; --canvas:#f4f2ee; color-scheme:dark}
+*{box-sizing:border-box}
+body{margin:0;background:var(--bg);color:var(--ink-1);font-family:var(--sans);font-size:14px;line-height:1.55}
+.wrap{max-width:1000px;margin:0 auto;padding:24px 16px 56px;display:grid;gap:20px}
+h1{font-size:22px;margin:0}
+p{margin:0;max-width:74ch}
+.small{font-size:13px;color:var(--ink-2)}
+.legendrow{display:flex;flex-wrap:wrap;gap:14px;font-size:12px;color:var(--ink-2)}
+.sw{display:inline-block;width:12px;height:12px;border-radius:3px;margin-right:5px;vertical-align:-2px;border:1px solid var(--ink-3)}
+.sw.thick{border-width:3px}
+.sw.dash{border-style:dashed;border-width:2px}
+
+/* Viewer */
+.fv{border:1px solid var(--line);border-radius:8px;background:var(--canvas);overflow:hidden;display:flex;flex-direction:column}
+.fv-bar{display:flex;flex-wrap:wrap;gap:8px;align-items:center;justify-content:space-between;padding:8px 10px;border-bottom:1px solid var(--line);background:var(--surface)}
+.fv-hint{font-size:12px;color:var(--ink-3)}
+.fv-btns{display:flex;gap:6px;align-items:center}
+.fv-btns button{font:inherit;font-size:13px;min-width:34px;padding:5px 10px;border:1px solid var(--line);border-radius:6px;background:var(--bg);color:var(--ink-1);cursor:pointer}
+.fv-btns button:hover{border-color:var(--ink-3)}
+.fv-btns button:focus-visible{outline:2px solid #2563eb;outline-offset:2px}
+.fv-pct{font-family:var(--mono);font-size:12px;color:var(--ink-2);min-width:44px;text-align:center}
+.fv-view{position:relative;height:70vh;min-height:420px;overflow:hidden;cursor:grab;touch-action:pan-y;background:var(--canvas)}
+.fv-view.drag{cursor:grabbing}
+.fv-stage{position:absolute;left:0;top:0;transform-origin:0 0}
+.fv-stage > p{color:#57534e;padding:12px}
+/* The title is HTML inside the zoomable stage, so it zooms with the chart and stays in full screen and screenshots. */
+.fv-title{font-size:22px;line-height:1.35;color:#1c1917;padding:8px 0 14px;text-align:center}
+.fv-title b{font-weight:700}
+.fv-title span{display:block;font-size:15px;color:#57534e}
+.fv-stage svg{max-width:none!important;display:block}
+.fv.expanded{position:fixed;inset:0;z-index:50;border-radius:0}
+.fv.expanded .fv-view{height:auto;flex:1}
+</style>
+</head>
+<body>
+<div class="wrap">
+  <h1>How support cases moved on Mon 5 Oct 2026</h1>
+  <p class="small">Example data. Replace the title, the legend, the chart source and the note.</p>
+
+  <div class="legendrow" aria-label="Legend">
+    <span><span class="sw" style="background:#e7e5e4"></span>Automatic step</span>
+    <span><span class="sw thick" style="background:#bbf7d0;border-color:#15803d"></span>In scope (thick border)</span>
+    <span><span class="sw dash" style="background:#fde68a;border-color:#a16207"></span>Optional, owner choice (dashed)</span>
+    <span><span class="sw" style="background:#f6e7d6"></span>Hand-off to a team</span>
+    <span><span class="sw" style="background:#ffffff;border-color:#57534e;border-width:2px"></span>Start</span>
+    <span><span class="sw" style="background:#eceae6"></span>Case ends</span>
+    <span><span class="sw dash" style="background:#ffffff;border-color:#a8a29e;border-width:1px"></span>Stub: the path continues at the box named</span>
+  </div>
+
+  <!-- One chart. data-src = id of the script that holds the Mermaid source.
+       data-title and data-sub are plain text (set with textContent). data-label is the accessible name. -->
+  <div class="fv" data-src="chart1"
+       data-title="Support cases: Mon 5 Oct 2026"
+       data-sub="(4 Oct 23:00 to 5 Oct 23:00 UTC). Counts in brackets are cases. Paths under 20 cases are not drawn."
+       data-label="Flow of a support case on 5 October, from intake to self-service, team queues and case ends">
+    <div class="fv-bar">
+      <span class="fv-hint">Drag to move. Use + and − or Ctrl + scroll to zoom.</span>
+      <span class="fv-btns">
+        <button type="button" data-z="out" aria-label="Zoom out">−</button>
+        <span class="fv-pct">100%</span>
+        <button type="button" data-z="in" aria-label="Zoom in">+</button>
+        <button type="button" data-z="fit">Fit</button>
+        <button type="button" data-z="full">Full screen</button>
+      </span>
+    </div>
+    <div class="fv-view"><div class="fv-stage"><p class="small">Drawing the flow chart…</p></div></div>
+  </div>
+<script type="text/plain" id="chart1">
+flowchart TD
+  S(["Cases opened<br/>(2,400)"]) --> I["INTAKE<br/>Web form"]
+  I -->|"(180)"| X1(["Case ends"])
+  I -->|"(2,220)"| T["TRIAGE<br/>Rules engine<br/>(2,220)"]
+  T -->|"(1,300)"| A["SELF-SERVICE<br/>Account help<br/>(1,300)"]
+  T -->|"(about 600)"| Q["Team queues"]
+  T -->|"(320)"| C["CHECK, owner choice<br/>Fraud check"]
+  C -->|"(300)"| Q2["Fraud team queue"]
+  A -->|"(1,100)"| X2(["Case ends after self-service"])
+  A --> B(["back to Triage (190)"])
+  subgraph AFTER["After a team picks up a case"]
+    direction LR
+    AG["Agent"] -->|"(700)"| X3(["Case ends"])
+  end
+  X2 ~~~ AFTER
+  classDef auto fill:#e7e5e4,stroke:#78716c,color:#1c1917;
+  classDef scope fill:#bbf7d0,stroke:#15803d,stroke-width:3px,color:#1c1917;
+  classDef choice fill:#fde68a,stroke:#a16207,stroke-width:2px,stroke-dasharray:6 4,color:#1c1917;
+  classDef queue fill:#f6e7d6,stroke:#b45309,color:#1c1917;
+  classDef endn fill:#eceae6,stroke:#78716c,color:#1c1917;
+  classDef startn fill:#ffffff,stroke:#57534e,stroke-width:2px,color:#1c1917;
+  classDef stub fill:#ffffff,stroke:#a8a29e,stroke-dasharray:3 3,color:#57534e;
+  class I,T auto;
+  class A scope;
+  class C choice;
+  class Q,Q2,AG queue;
+  class X1,X2,X3 endn;
+  class S startn;
+  class B stub;
+  style AFTER fill:#fbfaf8,stroke:#a8a29e,stroke-dasharray:4 4,color:#57534e;
+</script>
+  <p class="small">Every number counts distinct cases: an arrow counts the cases that took that path, a box counts the cases that reached it. Arrows into a box can sum to a little more than the box, because a case can reach it by two paths. "Case ends" means the data shows no further step; it does not say why. "Team queues" merges four small queues (about 600). Not drawn: 3 paths with fewer than 20 cases each (41 in total).</p>
+</div>
+
+<script src="https://cdnjs.cloudflare.com/ajax/libs/mermaid/10.9.1/mermaid.min.js" integrity="sha512-6a80OTZVmEJhqYJUmYd5z8yHUCDlYnj6q9XwB/gKOEyNQV/Q8u+XeSG59a2ZKFEHGTYzgfOQKYEBtrZV7vBr+Q==" crossorigin="anonymous"></script>
+<script>
+(function(){
+  if(!window.mermaid){
+    document.querySelectorAll('.fv-stage').forEach(function(s){s.innerHTML='<p class="small">The chart library did not load, so the flow chart cannot be drawn.</p>';});
+    return;
+  }
+  try{
+    mermaid.initialize({startOnLoad:false,securityLevel:'strict',theme:'base',
+      themeVariables:{fontFamily:'Segoe UI, system-ui, sans-serif',fontSize:'15px',lineColor:'#57534e',primaryTextColor:'#1c1917',edgeLabelBackground:'#ffffff',background:'#fbfaf8'},
+      flowchart:{htmlLabels:true,curve:'basis',nodeSpacing:40,rankSpacing:55,padding:10}});
+  }catch(e){console.error('mermaid.initialize failed',e);}
+  var n=0;
+  function viewer(fv){
+    var view=fv.querySelector('.fv-view'),stage=fv.querySelector('.fv-stage'),pct=fv.querySelector('.fv-pct'),full=fv.querySelector('button[data-z="full"]');
+    var k=1,x=0,y=0,w=0,h=0,fitK=1;
+    function msg(t){stage.innerHTML='<p class="small"></p>';stage.firstChild.textContent=t;}
+    // Page scroll stays free on a phone until the chart is zoomed in or in full screen; then a drag pans the chart.
+    function touch(){view.style.touchAction=(fv.classList.contains('expanded')||k>fitK*1.01)?'none':'pan-y';}
+    function apply(){touch();stage.style.transform='translate('+x+'px,'+y+'px) scale('+k+')';pct.textContent=Math.round(k*100)+'%';}
+    function fit(){var vw=view.clientWidth,vh=view.clientHeight;if(!w)return;k=Math.min(vw/w,vh/h)*0.96;fitK=k;x=(vw-w*k)/2;y=(vh-h*k)/2;apply();}
+    function zoomAt(f,cx,cy){var nk=Math.max(Math.min(0.15,fitK),Math.min(4,k*f));x=cx-(cx-x)*nk/k;y=cy-(cy-y)*nk/k;k=nk;apply();}
+    function title(){
+      var d=document.createElement('div');d.className='fv-title';
+      var b=document.createElement('b');b.textContent=fv.dataset.title||'';d.appendChild(b);
+      if(fv.dataset.sub){var s=document.createElement('span');s.textContent=fv.dataset.sub;d.appendChild(s);}
+      return d;
+    }
+    var src=document.getElementById(fv.dataset.src);
+    var done=Promise.resolve();
+    if(!src){msg('The flow chart source is missing.');}
+    else try{
+      done=mermaid.render('flowsvg'+(n++),src.textContent).then(function(r){
+        stage.innerHTML=r.svg;stage.insertBefore(title(),stage.firstChild);
+        var svg=stage.querySelector('svg');
+        var vb=svg.viewBox.baseVal;w=vb&&vb.width?vb.width:svg.getBBox().width;h=vb&&vb.height?vb.height:svg.getBBox().height;
+        svg.setAttribute('width',w);svg.setAttribute('height',h);svg.style.maxWidth='none';
+        w=Math.max(w,stage.scrollWidth);h=stage.scrollHeight;
+        svg.setAttribute('role','img');svg.setAttribute('aria-label',fv.dataset.label||'Flow chart');
+        fit();
+      }).catch(function(e){console.error(e);msg('The flow chart could not be drawn: '+e.message);});
+    }catch(e){console.error(e);msg('The flow chart could not be drawn: '+e.message);}
+    function toggle(){var on=!fv.classList.contains('expanded');fv.classList.toggle('expanded',on);full.textContent=on?'Close':'Full screen';
+      document.body.style.overflow=on?'hidden':'';
+      // Real full screen when the browser allows it; the fixed-position .expanded class is the fallback.
+      try{if(on&&fv.requestFullscreen)fv.requestFullscreen().catch(function(){});else if(!on&&document.fullscreenElement)document.exitFullscreen().catch(function(){});}catch(e){}
+      setTimeout(fit,60);}
+    fv.addEventListener('click',function(ev){var b=ev.target.closest('button[data-z]');if(!b)return;var c=[view.clientWidth/2,view.clientHeight/2];
+      if(b.dataset.z==='in')zoomAt(1.25,c[0],c[1]);else if(b.dataset.z==='out')zoomAt(0.8,c[0],c[1]);else if(b.dataset.z==='fit')fit();else toggle();});
+    document.addEventListener('fullscreenchange',function(){if(!document.fullscreenElement&&fv.classList.contains('expanded')){fv.classList.remove('expanded');full.textContent='Full screen';document.body.style.overflow='';setTimeout(fit,60);}});
+    document.addEventListener('keydown',function(e){if(e.key==='Escape'&&fv.classList.contains('expanded'))toggle();});
+    // Plain scroll keeps scrolling the page; Ctrl + scroll (or any scroll in full screen) zooms.
+    view.addEventListener('wheel',function(e){if(!(e.ctrlKey||e.metaKey||fv.classList.contains('expanded')))return;e.preventDefault();var r=view.getBoundingClientRect();zoomAt(e.deltaY<0?1.12:0.89,e.clientX-r.left,e.clientY-r.top);},{passive:false});
+    var pts={};
+    view.addEventListener('pointerdown',function(e){view.setPointerCapture(e.pointerId);pts[e.pointerId]=[e.clientX,e.clientY];view.classList.add('drag');});
+    view.addEventListener('pointermove',function(e){if(!pts[e.pointerId])return;var p=pts[e.pointerId],ids=Object.keys(pts);
+      if(ids.length===2){var o=pts[ids[0]==e.pointerId?ids[1]:ids[0]];var d0=Math.hypot(p[0]-o[0],p[1]-o[1]);var d1=Math.hypot(e.clientX-o[0],e.clientY-o[1]);var r=view.getBoundingClientRect();if(d0>0)zoomAt(d1/d0,(e.clientX+o[0])/2-r.left,(e.clientY+o[1])/2-r.top);}
+      else{x+=e.clientX-p[0];y+=e.clientY-p[1];apply();}
+      pts[e.pointerId]=[e.clientX,e.clientY];});
+    function up(e){delete pts[e.pointerId];if(!Object.keys(pts).length)view.classList.remove('drag');}
+    view.addEventListener('pointerup',up);view.addEventListener('pointercancel',up);
+    window.addEventListener('resize',fit);
+    return done;
+  }
+  // Render one chart after another, so each chart finishes before the next one starts.
+  var all=document.querySelectorAll('.fv[data-src]'),i=0;
+  (function next(){if(i<all.length){Promise.resolve(viewer(all[i++])).then(next,next);}})();
+})();
+</script>
+</body>
+</html>

package/bundles/antigravity-plugin/skills/flow-chart-from-counts/references/edge-list-sql.md

@@ -0,0 +1,105 @@
+# Edge list from an event table (SQL pattern)
+
+Use this when the steps of each case are rows in an event table. The output is the edge list that
+`scripts/edges_to_mermaid.py` reads: `from,to,count`, plus a box-count list `name,count`.
+
+The SQL is ANSI with window functions. It runs on most SQL engines with small changes
+(parameter style, date functions).
+
+## Input shape
+
+One row per step a case took:
+
+| column      | meaning                                                                     |
+|-------------|-----------------------------------------------------------------------------|
+| `case_id`   | the unit you count: a call, an order, a ticket, a session                   |
+| `step`      | the step name, in the words of the team that owns the process               |
+| `step_time` | when the step started, in UTC                                               |
+| `step_seq`  | a tie-breaker when two steps share one timestamp (an event id or a counter) |
+
+## Query
+
+```sql
+-- 1. Choose the cases by their START time in the window, then take ALL their steps.
+--    If you filter steps by time instead, a case that crosses the window edge loses its
+--    first or last steps, and the chart shows false starts and false ends.
+WITH cases AS (
+    SELECT case_id
+    FROM   events
+    GROUP  BY case_id
+    HAVING MIN(step_time) >= :window_start_utc
+       AND MIN(step_time) <  :window_end_utc
+),
+ordered AS (
+    SELECT e.case_id, e.step, e.step_time, e.step_seq,
+           LAG(e.step) OVER (PARTITION BY e.case_id ORDER BY e.step_time, e.step_seq) AS prev_step
+    FROM   events e
+    JOIN   cases  c ON c.case_id = e.case_id
+),
+-- 2. Collapse consecutive repeats: A, A, B becomes A, B. A repeat is not a path.
+collapsed AS (
+    SELECT case_id, step, step_time, step_seq
+    FROM   ordered
+    WHERE  prev_step IS NULL OR prev_step <> step
+),
+-- 3. The next step of each step. No next step means the case ends: 'END'.
+pairs AS (
+    SELECT case_id,
+           step AS from_step,
+           COALESCE(LEAD(step) OVER (PARTITION BY case_id ORDER BY step_time, step_seq), 'END') AS to_step,
+           ROW_NUMBER() OVER (PARTITION BY case_id ORDER BY step_time, step_seq) AS rn
+    FROM   collapsed
+)
+-- 4. Count DISTINCT cases per pair: the same unit as the boxes. Add one START row per case.
+--    path_count (times taken) is kept only to compare; do not draw it.
+SELECT from_step AS "from", to_step AS "to",
+       COUNT(DISTINCT case_id) AS "count",
+       COUNT(*)                AS path_count
+FROM   pairs
+GROUP  BY from_step, to_step
+HAVING COUNT(DISTINCT case_id) >= :min_cases
+UNION ALL
+SELECT 'START', from_step, COUNT(*), COUNT(*)
+FROM   pairs
+WHERE  rn = 1
+GROUP  BY from_step
+ORDER  BY 3 DESC;
+```
+
+Box counts (distinct cases per step), from the same `collapsed` set:
+
+```sql
+SELECT step AS name, COUNT(DISTINCT case_id) AS count
+FROM   collapsed
+GROUP  BY step;
+```
+
+## What the numbers mean
+
+- **Draw distinct cases on the arrows, the same unit as the boxes.** `count` is
+  `COUNT(DISTINCT case_id)` per pair. `path_count` (`COUNT(*)`) counts each time a path was taken,
+  so a case that loops (A, B, A, B) counts twice. A business reader then sees a box of 8,538
+  followed by an arrow of 8,541 and stops trusting the chart. On one measured day `COUNT(*)`
+  overstated an arrow by 4%. Keep `path_count` only to compare.
+- **Self-check: no arrow into or out of a box exceeds the box's distinct count.** If one does,
+  the query counts occurrences, not cases. The converter warns on this when it has box counts.
+- **Arrows into a box can sum to a little more than the box** when a case reaches it by two
+  paths. That is correct; say so in the note under the chart.
+- **`HAVING` hides small paths.** Apply the threshold to either count, but label every number on
+  the chart as cases. Run the query once without it, or sum the hidden rows, so the
+  note under the chart can name what is not drawn and how many cases that is. A chart that hides
+  paths without saying so looks complete and is not.
+- **The tie-breaker matters.** Without `step_seq`, two steps at one timestamp come out in any
+  order, and `LAG`/`LEAD` give different paths on each run. Check: run the query twice and compare.
+- **Time zone.** Filter in UTC. When the reader thinks in local days, convert the local day to a
+  UTC window first, and put both on the chart title, for example
+  `Mon 5 Oct 2026 (4 Oct 23:00 to 5 Oct 23:00 UTC)`.
+
+## Check the edge list before you draw it
+
+- The `START` rows add up to the number of cases in the window.
+- Before the `HAVING` filter, for each step the paths in equal the paths out (with `END`
+  counted as out). A gap means a filter dropped rows, or a step name differs in spelling
+  between rows.
+- Run the converter: its note lists every hidden path. Read that list. A large hidden total means
+  the minimum is too high, or many small steps need to be merged into one named box.