@caddis/cli 0.4.49 → 0.4.51

package/bundles/antigravity-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis",
-  "version": "1.3.135",
+  "version": "1.3.137",
   "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/scripts/caddis_routing.py

@@ -14,6 +14,10 @@ from typing import Callable, Mapping
 import oss_model
 
 
+# agy is Flash-only on some machines and is good only at small, exact, mechanical cards (112 of 114 passed
+# in the 2026-10-08 UI-upgrade run) and CI watching. Give design-fidelity, cross-file refactor and judgment
+# work to codex or claude. See .caddis/kb/agy-headless-implementer-limits.md. A separate `design` role is an
+# owner decision: it changes the routing line every session prints.
 DEFAULT_ROUTING: dict[str, list[str]] = {
     "critical": ["opus"],
     "light": ["sonnet"],

package/bundles/antigravity-plugin/session_end_agy.py

@@ -19,6 +19,7 @@ agy Stop stdin (camelCase protojson):
 """
 import json
 import os
+import subprocess
 import sys
 from datetime import datetime, timezone
 
@@ -27,6 +28,30 @@ def _artifact_root(root: str) -> str:
     return os.path.join(str(root), ".caddis")
 
 
+def _repo_root(path: str):
+    """The git top-level folder that holds `path`, or None when `path` is not inside a repository.
+
+    agy can run with its working folder in a SUB-folder of the repo (a monorepo app). The artifact
+    folder belongs at the repo root, where the project's ignore rule (`/.caddis/`) covers it. Creating
+    it in the sub-folder left untracked files that every lane had to delete before staging
+    (UI-upgrade run, 2026-10-08).
+    """
+    try:
+        done = subprocess.run(
+            ["git", "-C", str(path), "rev-parse", "--show-toplevel"],
+            capture_output=True, text=True, timeout=5,
+        )
+        top = done.stdout.strip()
+        return os.path.normpath(top) if done.returncode == 0 and top else None
+    except Exception:
+        return None
+
+
+def _user_artifact_root() -> str:
+    """Where usage goes when the workspace is in no repository: the user's own folder, never the cwd."""
+    return _artifact_root(os.path.expanduser("~"))
+
+
 
 def _hook_note(feature, exc, root=None):
     """Record a swallowed failure in the caddis hook ledger. Never raises, never prints.
@@ -82,13 +107,22 @@ def main() -> None:
         return
     try:
         roots = _workspace_roots(data) or [os.getcwd()]
+        # A workspace folder may sit inside a repo: the artifact dir is the REPO ROOT's, not the sub-folder's.
+        resolved = [(_repo_root(r) or str(r)) for r in roots]
         # Write the record to every root that ALREADY has a .caddis dir, rather than to
         # whichever root happened to be first. A multi-root session's usage belongs to each
         # repo that participates in it, and creating .caddis in a repo that never opted in
         # would be caddis littering someone else's tree.
-        targets = [_artifact_root(r) for r in roots if os.path.isdir(_artifact_root(r))]
+        targets = []
+        for root in resolved:
+            art = _artifact_root(root)
+            if os.path.isdir(art) and art not in targets:
+                targets.append(art)
         if not targets:
-            targets = [_artifact_root(roots[0])]  # single-root default: unchanged behaviour
+            # Nothing has opted in. In a repo, the first root's repo root is the default. Outside any
+            # repo there is no project to attach usage to, so it goes to the user's folder, not the cwd.
+            first_repo = _repo_root(roots[0])
+            targets = [_artifact_root(first_repo) if first_repo else _user_artifact_root()]
         record = {
             "ts": datetime.now(timezone.utc).isoformat(),
             "event": "session_end",

package/bundles/antigravity-plugin/skills/flow-studio/SKILL.md

@@ -70,7 +70,9 @@ In either route, derive node and link IDs from immutable business keys. Preserve
 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.
-11. **Thin links, dotted canvas**: links are hairlines (about 0.8 px, with a 6 px arrowhead) and the canvas background is faint dots, not a grid. Both come from tokens (`--edge-w`, `--dot`, ...), so an app can change them with one CSS line; see `references/design-language.md`.
+11. **The lane is the owner**: a lane is the app, team or system that owns its row. Never add a column that repeats the owner (an "Apps" or "Owner" column); it adds a block between the real stages and the pages and says nothing new.
+12. **Draw a shared node once**: when several rows use the same database, job or table, draw one node, centre it on the rows it serves, and link it to each node downstream. A chip (`kind: "chip"` with `ref`) is only for a node that lives in another lane, never a copy inside the same lane.
+13. **Thin links, dotted canvas**: links are hairlines (about 0.8 px, with a 6 px arrowhead) and the canvas background is faint dots, not a grid. Both come from tokens (`--edge-w`, `--dot`, ...), so an app can change them with one CSS line; see `references/design-language.md`.
 
 ## Model summary
 
@@ -80,7 +82,7 @@ columns [{id, title, short?, width, phase?, continues?}]              stages, le
 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?}]
+          ref?, upgrade?, contains?, collapsed?, stateIn?, visibleIn?, sla?, metrics?, bars?}]
 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}]}

package/bundles/antigravity-plugin/skills/flow-studio/model.schema.json

@@ -75,7 +75,10 @@
           "sla": { "type": "number", "exclusiveMinimum": 0, "description": "Target service level agreement in seconds" },
           "metrics": { "type": "object", "required": ["value"], "additionalProperties": false,
             "properties": { "value": { "type": "number" }, "max": { "type": ["number", "null"], "description": "Upper bound for the badge fill bar; null means there is no maximum" }, "unit": { "type": "string" }, "label": { "type": "string" },
-              "series": { "type": "array", "maxItems": 60, "items": { "type": "number" } } } }
+              "series": { "type": "array", "maxItems": 60, "items": { "type": "number" } } } },
+          "bars": { "type": "array", "maxItems": 120, "description": "A small bar chart on the node, one bar per key. A null value is a missing key (a red tick, never zero). Hovering a bar marks the same key on every chart.",
+            "items": { "type": "object", "required": ["key", "value"], "additionalProperties": false,
+              "properties": { "key": { "type": "string" }, "value": { "type": ["number", "null"], "minimum": 0 }, "kind": { "enum": ["low"] }, "label": { "type": "string" } } } }
         }
       }
     },

package/bundles/antigravity-plugin/skills/flow-studio/react/FlowStudioView.test.tsx

@@ -7,15 +7,17 @@ const lifecycle = vi.hoisted(() => ({
   alive: 0, updates: [] as Model[], mounts: 0, listenerCount: 0,
   notes: [] as (NoteDef[] | undefined)[],
   onSelect: undefined as ((id: string | null) => void) | undefined,
+  onHoverKey: undefined as ((key: string | null) => void) | undefined,
 }));
 vi.mock('../templates/flow-studio.lib.mjs', () => ({
   SHELL_BODY_HTML: '<div id="viewport"></div>',
-  mount: (_root: ParentNode, _model: Model, options: { notes?: NoteDef[]; onSelect?: (id: string | null) => void }) => {
+  mount: (_root: ParentNode, _model: Model, options: { notes?: NoteDef[]; onSelect?: (id: string | null) => void; onHoverKey?: (key: string | null) => void }) => {
     lifecycle.mounts++;
     lifecycle.alive++;
     lifecycle.listenerCount++;
     lifecycle.notes.push(options.notes);
     lifecycle.onSelect = options.onSelect;
+    lifecycle.onHoverKey = options.onHoverKey;
     return {
       update: (model: Model) => { lifecycle.updates.push(model); return { ok: true, issues: [] }; },
       destroy: () => { lifecycle.alive--; lifecycle.listenerCount--; },
@@ -56,6 +58,21 @@ describe('FlowStudioView', () => {
     expect(globals.flowStudioMount).toBe(previousMount);
   });
 
+  it('forwards the hovered bar key to the latest onHoverKey, without remounting', () => {
+    lifecycle.mounts = 0;
+    const first = vi.fn();
+    const second = vi.fn();
+    const rendered = render(<FlowStudioView model={model} onHoverKey={first} />);
+    lifecycle.onHoverKey?.('2026-09-02');
+    expect(first).toHaveBeenCalledWith('2026-09-02');
+    rendered.rerender(<FlowStudioView model={model} onHoverKey={second} />);
+    expect(lifecycle.mounts).toBe(1);
+    lifecycle.onHoverKey?.(null);
+    expect(second).toHaveBeenCalledWith(null);
+    expect(first).toHaveBeenCalledTimes(1);
+    rendered.unmount();
+  });
+
   it('passes notes at mount and ignores later notes-only changes', () => {
     lifecycle.updates = [];
     lifecycle.notes = [];

package/bundles/antigravity-plugin/skills/flow-studio/react/FlowStudioView.tsx

@@ -7,6 +7,8 @@ export interface FlowStudioViewProps {
   /** Read once at mount; later changes to this prop are ignored. For notes that change with the data, put them on `model.notes` — `update` forwards them. */
   notes?: NoteDef[];
   onSelect?: (id: string | null) => void;
+  /** The bar key under the pointer (a node's `bars`), or null when it leaves. The latest function is always called. */
+  onHoverKey?: (key: string | null) => void;
   className?: string;
 }
 
@@ -17,16 +19,18 @@ let mountedViews = 0;
 let previousGlobalMount: typeof mount | undefined;
 
 /** Mounts the finished engine in React. The shell stays outside React's child tree. */
-export function FlowStudioView({ model, notes, onSelect, className }: FlowStudioViewProps) {
+export function FlowStudioView({ model, notes, onSelect, onHoverKey, className }: FlowStudioViewProps) {
   const root = useRef<HTMLDivElement>(null);
   const api = useRef<FlowStudio | null>(null);
   const currentModel = useRef(model);
   const currentNotes = useRef(notes);
   const currentSelect = useRef(onSelect);
+  const currentHoverKey = useRef(onHoverKey);
   const lastModel = useRef<string | null>(null);
   currentModel.current = model;
   currentNotes.current = notes;
   currentSelect.current = onSelect;
+  currentHoverKey.current = onHoverKey;
   const modelJson = JSON.stringify(model);
 
   useEffect(() => {
@@ -36,6 +40,7 @@ export function FlowStudioView({ model, notes, onSelect, className }: FlowStudio
     const instance = mount(container, currentModel.current, {
       notes: currentNotes.current,
       onSelect: id => currentSelect.current?.(id),
+      onHoverKey: key => currentHoverKey.current?.(key),
     });
     if (mountedViews === 0) {
       previousGlobalMount = window.flowStudioMount;

package/bundles/antigravity-plugin/skills/flow-studio/react/README.md

@@ -22,7 +22,7 @@ function FlowPage({ state, onRetry, onSelect }: { state: State; onRetry: () => v
 }
 ```
 
-`FlowStudioView` takes a required `model` and optional `notes`, `onSelect`, and `className`. `notes` is read once at mount; later changes to the prop are ignored. For notes that change with the data, put them on the model (`model.notes`) — `update` forwards them. `onSelect` receives a stable node id or `null` when selection clears. The component mounts the engine once, sends changed models to `update`, and destroys its listeners on unmount. React StrictMode's development mount cycle is supported. Several views may be mounted at once; the engine's global mount helper stays available until the last one unmounts.
+`FlowStudioView` takes a required `model` and optional `notes`, `onSelect`, `onHoverKey`, and `className`. `notes` is read once at mount; later changes to the prop are ignored. For notes that change with the data, put them on the model (`model.notes`) — `update` forwards them. `onSelect` receives a stable node id or `null` when selection clears. `onHoverKey` receives the key of the bar under the pointer (see `bars` on a node) or `null`; call `window.FlowStudio?.highlightKey(key)` to mark a key from outside. The component mounts the engine once, sends changed models to `update`, and destroys its listeners on unmount. React StrictMode's development mount cycle is supported. Several views may be mounted at once; the engine's global mount helper stays available until the last one unmounts.
 
 ## Live data contract
 

package/bundles/antigravity-plugin/skills/flow-studio/references/model-schema.md

@@ -112,6 +112,7 @@ Nodes represent processing units, cards, gateways, groups, and milestones.
 | `collapsed` | `boolean` | Optional | `true` | When true, group starts collapsed hiding child nodes. |
 | `sla` | `number` | Optional | - | Target service level agreement threshold in seconds. |
 | `metrics` | `object` | Optional | - | Telemetry payload (see metrics table). |
+| `bars` | `array` | Optional | - | A small bar chart on the node, one bar per `key` (see bars table). |
 
 ---
 
@@ -129,6 +130,21 @@ Provides numerical telemetry, health bars, and sparklines.
 
 ---
 
+### `bars` items (under `nodes`)
+
+A bar chart drawn inside the node, for example rows per day. Hovering a bar marks the bars with the same `key` on
+every node, so a reader can ask "was this day bad everywhere?". The host page can follow the hover with the
+`onHoverKey` mount option and drive it with `highlightKey(key)`. At most 120 bars.
+
+| Property | Type | Required? | Default | Description |
+|---|---|---|---|---|
+| `key` | `string` | Required | - | Opaque id of the bar (a date or a step). Equal keys are linked across charts. |
+| `value` | `number` or `null` | Required | - | Bar size (finite, not negative). `null` means no data for that key: a short red tick, never a zero bar. |
+| `kind` | `string` | Optional | - | `"low"` draws the bar in the critical colour. The last bar with data is drawn in the accent colour, unless it is `low`. |
+| `label` | `string` | Optional | - | Tooltip text; defaults to `key: value`. |
+
+---
+
 ## 8. `links` array items
 
 Links represent directional data transit, dependencies, or workflow transitions.

package/bundles/antigravity-plugin/skills/flow-studio/references/patterns.md

@@ -21,7 +21,7 @@ You can start from these base states and adjust words to match your domain:
 
 - **Example file:** `examples/lineage.json`
 - **Scenario:** Trace data assets from ingestion sources through storage, pipelines, transformations, to consuming dashboards and applications.
-- **Typical columns:** Source, Host, Database, Pipeline, Tables, Refresher, Views, App, Dashboard.
+- **Typical columns:** Source, Host, Database, Pipeline, Tables, Refresher, Views, Dashboard. Do not add an App or Owner column: the lane is the app (ux-rules 11).
 - **Typical lanes:** Customer Portal, Order Service, Data Warehouse, Reporting Platform. A lane without documentation uses `gap: true`.
 - **Node count guideline:** 15 to 30 nodes.
 - **Recommended inspector relations:**

package/bundles/antigravity-plugin/skills/flow-studio/references/ux-rules.md

@@ -1,8 +1,8 @@
 # UX and design rules
 
-The 10 rules ensure flow-studio pages remain readable, informative, accessible, and fast.
+The 12 rules ensure flow-studio pages remain readable, informative, accessible, and fast.
 
-## The 10 rules
+## The 12 rules
 
 ### 1. One screen
 - **Rule statement:** The full flow fits on one screen without requiring panning in the initial default view.
@@ -66,6 +66,20 @@ The 10 rules ensure flow-studio pages remain readable, informative, accessible,
 
 ---
 
+### 11. The lane is the owner
+- **Rule statement:** A lane names the app, team or system that owns its row. No column repeats the owner.
+- **Rationale:** An "Apps" column between the real stages and the pages adds a block that says nothing new. In the estate lineage it sat between the reporting tables and the pages, and the owner asked why it was there (2026-10-09).
+- **Pre-flight checklist question:** Does any column hold one node per lane that only repeats the lane title?
+- **Common mistake & fix:** Adding an "App" column because the pattern list showed one. *Fix:* Remove the column. Link the stage that feeds a page straight to the page; a page that reads no table stands alone.
+
+### 12. Draw a shared node once
+- **Rule statement:** A database, job or table that several rows share is one node, centred on the rows it serves, with a link to each node downstream. A chip is only for a node that lives in another lane.
+- **Rationale:** Copying a shared node into every row hides that it is shared and makes the reader compare copies. In the app lineage page, a database repeated in every source row looked like several databases (2026-10-09).
+- **Pre-flight checklist question:** Does any node id appear as a chip inside the lane that already holds the real node?
+- **Common mistake & fix:** One row per source, each with its own copy of the host, database and job. *Fix:* Draw each distinct node once, place it at the mean position of its rows, move it down if it would touch its neighbour, and de-duplicate links by their two ends.
+
+---
+
 ## Pre-flight checklist for agents
 
 Before presenting a generated flow page, verify:
@@ -77,6 +91,8 @@ Before presenting a generated flow page, verify:
 6. **Accessible names:** Does every button, input, tab, and control have an `aria-label` or visible text?
 7. **Keyboard navigation:** Can a user Tab through controls and press Escape to close the inspector?
 8. **Responsive breakdown:** Does the layout degrade cleanly down to 820x900?
+9. **No owner column:** Does any column only repeat the lane's owner? Remove it (rule 11).
+10. **Shared nodes once:** Is every shared database, job or table drawn once, not copied per row (rule 12)?
 
 ---
 
@@ -88,4 +104,6 @@ Before presenting a generated flow page, verify:
 - **Text spill:** Node labels exceed card width. *Fix:* Use short titles (under 24 characters) and set `subtitle` for auxiliary metadata.
 - **Permanent side panel:** The inspector remains open on load. *Fix:* The inspector must start closed and open only on selection.
 - **Flat visual hierarchy:** Every card looks identical. *Fix:* Vary card kinds (`card`, `group`, `gateway`, `chip`) and state tones (`ok`, `warn`, `crit`, `accent`).
+- **Owner column:** A column of one node per lane that repeats the lane title. *Fix:* Remove it; the lane is the owner.
+- **Copies of a shared node:** The same database or job drawn in every row. *Fix:* Draw it once and link it to each node downstream.
 - **Unlabelled controls:** Icon buttons without text lack screen reader descriptions. *Fix:* Provide descriptive `aria-label` attributes on all buttons.

package/bundles/antigravity-plugin/skills/flow-studio/src/bars.test.ts

@@ -0,0 +1,90 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { barsHtml, markKey } from "./bars.ts";
+import { validateModel, type Model, type NodeBar } from "./model.ts";
+
+const bars: NodeBar[] = [
+  { key: "2026-09-01", value: 10 },
+  { key: "2026-09-02", value: null },
+  { key: "2026-09-03", value: 4, kind: "low" },
+  { key: "2026-09-04", value: 20 },
+];
+
+test("no bars, no chart", () => {
+  assert.equal(barsHtml(undefined), "");
+  assert.equal(barsHtml([]), "");
+});
+
+test("one rect per bar, each carrying its key; a missing day is a short red tick, never a zero bar", () => {
+  const html = barsHtml(bars);
+  assert.equal((html.match(/<rect /g) ?? []).length, 4);
+  for (const b of bars) assert.match(html, new RegExp(`data-key="${b.key}"`));
+  assert.match(html, /<rect class="miss" data-key="2026-09-02"/);
+  assert.match(html, /<rect class="low" data-key="2026-09-03"/);
+  // The last bar with data is the accent one.
+  assert.match(html, /<rect class="last" data-key="2026-09-04"/);
+});
+
+test("bar height follows the value against the largest, and the largest fills the chart", () => {
+  const html = barsHtml([{ key: "a", value: 5 }, { key: "b", value: 10 }], 20);
+  const heights = [...html.matchAll(/height="([0-9.]+)"/g)].map(m => Number(m[1])).filter(h => h < 20);
+  assert.equal(heights.length, 2);
+  assert.ok(Math.abs(heights[1]! - 15) < 0.01, "the largest bar is height - 5");
+  assert.ok(Math.abs(heights[0]! - 7.5) < 0.01, "half the value is half the height");
+});
+
+test("keys and labels are escaped, so a hostile key cannot become markup", () => {
+  const html = barsHtml([{ key: '"><script>x</script>', value: 1, label: "<b>" }]);
+  assert.doesNotMatch(html, /<script>/);
+  assert.doesNotMatch(html, /<b>/);
+  assert.match(html, /&lt;b&gt;/);
+});
+
+test("the chart is described for a screen reader", () => {
+  assert.match(barsHtml(bars), /role="img" aria-label="[^"]+"/);
+});
+
+interface FakeRect { key: string; attrs: Map<string, string>; getAttribute(n: string): string | null; setAttribute(n: string, v: string): void; removeAttribute(n: string): void }
+const fakeRect = (key: string): FakeRect => {
+  const attrs = new Map<string, string>([["data-key", key]]);
+  return { key, attrs, getAttribute: n => attrs.get(n) ?? null, setAttribute: (n, v) => void attrs.set(n, v), removeAttribute: n => void attrs.delete(n) };
+};
+
+test("markKey marks every bar with that key, on every chart, and clears the others", () => {
+  const rects = [fakeRect("a"), fakeRect("b"), fakeRect("a")];
+  const root = { querySelectorAll: () => rects } as unknown as ParentNode;
+  markKey(root, "a");
+  assert.deepEqual(rects.map(r => r.attrs.get("data-hl")), ["true", undefined, "true"]);
+  markKey(root, "b");
+  assert.deepEqual(rects.map(r => r.attrs.get("data-hl")), [undefined, "true", undefined]);
+  markKey(root, null);
+  assert.deepEqual(rects.map(r => r.attrs.get("data-hl")), [undefined, undefined, undefined]);
+});
+
+const base = (): Model => ({
+  version: 1,
+  meta: { title: "T", help: "h", asOf: "2026-01-01", source: "s" },
+  layout: "columns-lanes",
+  columns: [{ id: "c0", title: "A", width: 150 }],
+  lanes: [{ id: "l1", title: "Lane 1" }],
+  states: { ok: { word: "OK", tone: "ok", border: "solid", edge: "flow", motion: "flow", bucket: "good" } },
+  nodes: [{ id: "a", kind: "card", lane: "l1", col: 0, row: 0, state: "ok", title: "A", allowIsolated: true, bars }],
+  links: [],
+});
+const codes = (m: unknown) => validateModel(m).filter(i => i.level === "error").map(i => i.code);
+
+test("a node may carry bars", () => assert.deepEqual(codes(base()), []));
+test("bars must be a list", () => {
+  const m = base(); (m.nodes[0] as unknown as { bars: unknown }).bars = "nope";
+  assert.ok(codes(m).includes("bars-invalid"));
+});
+test("each bar needs a string key and a finite, non-negative value or null", () => {
+  for (const bad of [{ key: 1, value: 1 }, { key: "k", value: -1 }, { key: "k", value: Number.NaN }, { key: "k", value: "3" }, null]) {
+    const m = base(); (m.nodes[0] as unknown as { bars: unknown[] }).bars = [bad];
+    assert.ok(codes(m).includes("bars-invalid"), JSON.stringify(bad));
+  }
+});
+test("at most 120 bars", () => {
+  const m = base(); m.nodes[0]!.bars = Array.from({ length: 121 }, (_, i) => ({ key: String(i), value: 1 }));
+  assert.ok(codes(m).includes("bars-invalid"));
+});

package/bundles/antigravity-plugin/skills/flow-studio/src/bars.ts

@@ -0,0 +1,53 @@
+// Small bar charts on a node, one bar per key (a day, a step). Hovering a bar marks the same key on
+// every chart on the canvas, so a reader can ask "was this day bad everywhere?". The key is opaque:
+// the model decides what it means. Pure string rendering plus one tiny DOM helper, no layout maths.
+
+import type { Ctx } from "./ctx.ts";
+import { on } from "./ctx.ts";
+import { esc, type NodeBar } from "./model.ts";
+
+const BAR_UNIT = 4; // viewBox units per bar; the chart is stretched to the node's width by CSS
+
+/** The chart as an SVG string, or "" when the node has no bars. A null value is a missing key: a red tick, never a zero bar. */
+export function barsHtml(bars: NodeBar[] | undefined, height = 22): string {
+  if (!bars || bars.length === 0) return "";
+  const width = bars.length * BAR_UNIT;
+  const max = Math.max(1, ...bars.map(b => b.value ?? 0));
+  const lastWithData = bars.map(b => b.value !== null).lastIndexOf(true);
+  const rects = bars.map((b, i) => {
+    const x = i * BAR_UNIT;
+    const w = BAR_UNIT - 1;
+    const label = esc(b.label ?? (b.value === null ? `${b.key}: no data` : `${b.key}: ${b.value}`));
+    if (b.value === null) {
+      return `<rect class="miss" data-key="${esc(b.key)}" x="${x}" y="${height - 4}" width="${w}" height="4"><title>${label}</title></rect>`;
+    }
+    const h = Math.max(1, (b.value / max) * (height - 5));
+    const cls = b.kind === "low" ? "low" : i === lastWithData ? "last" : "";
+    return `<rect${cls ? ` class="${cls}"` : ""} data-key="${esc(b.key)}" x="${x}" y="${height - h}" width="${w}" height="${h}"><title>${label}</title></rect>`;
+  });
+  const first = esc(bars[0]!.key), last = esc(bars[bars.length - 1]!.key);
+  return `<svg class="bars" viewBox="0 0 ${width} ${height}" preserveAspectRatio="none" role="img" aria-label="Bars, ${first} to ${last}">${rects.join("")}</svg>`;
+}
+
+/** Mark every bar with this key, on every chart under root, and clear the rest. null clears all. */
+export function markKey(root: ParentNode, key: string | null): void {
+  for (const r of Array.from(root.querySelectorAll("rect[data-key]"))) {
+    if (key !== null && r.getAttribute("data-key") === key) r.setAttribute("data-hl", "true");
+    else r.removeAttribute("data-hl");
+  }
+}
+
+/** Hovering a bar marks its key everywhere and tells the host page; leaving the canvas clears it. */
+export function installBars(ctx: Ctx): void {
+  const set = (key: string | null): void => {
+    if (ctx.hoverKey === key) return;
+    ctx.hoverKey = key;
+    markKey(ctx.els.world, key);
+    ctx.onHoverKey?.(key);
+  };
+  on(ctx, ctx.els.world, "mouseover", (e: MouseEvent) => {
+    const bar = (e.target as Element | null)?.closest?.("rect[data-key]");
+    set(bar ? bar.getAttribute("data-key") : null);
+  });
+  on(ctx, ctx.els.world, "mouseleave", () => set(null));
+}

package/bundles/antigravity-plugin/skills/flow-studio/src/ctx.ts

@@ -92,6 +92,9 @@ export interface Ctx {
   collapsed: Set<string>;
   selected: string | null;
   hl: string | null;
+  /** The bar key under the pointer (see bars.ts), or null. */
+  hoverKey: string | null;
+  onHoverKey?: (key: string | null) => void;
   query: string;
   hops: number;
   filter: Filter;

package/bundles/antigravity-plugin/skills/flow-studio/src/engine.ts

@@ -17,6 +17,7 @@ import { install as installNotes } from "./notes.ts";
 import { install as installPlayback, type PlaybackController } from "./playbackui.ts";
 import { diffModels } from "./diff.ts";
 import { notifySelection } from "./selection.ts";
+import { installBars, markKey } from "./bars.ts";
 import type { Issue } from "./model.ts";
 
 export interface FlowStudio {
@@ -26,6 +27,8 @@ export interface FlowStudio {
   setView(v: View, animate?: boolean): void;
   fit(animate?: boolean): void;
   select(id: string | null): void;
+  /** Mark one bar key on every chart, as if the pointer were over it. Does not call onHoverKey. */
+  highlightKey(key: string | null): void;
   selected(): string | null;
   mode(): string;
   setMode(id: string): void;
@@ -65,7 +68,7 @@ function findEls(root: ParentNode): Els {
 }
 
 interface SavedState { view: View; mode: string; selected: string | null; inspectorOpen: boolean; query: string; hops: number; filter: Ctx["filter"]; collapsed: Set<string>; knownGroups: Set<string>; playback: ReturnType<PlaybackController["playback"]> }
-export function mount(root: ParentNode, model: Model, opts: { notes?: NoteDef[]; onSelect?: (id: string | null) => void; restore?: SavedState } = {}): FlowStudio {
+export function mount(root: ParentNode, model: Model, opts: { notes?: NoteDef[]; onSelect?: (id: string | null) => void; onHoverKey?: (key: string | null) => void; restore?: SavedState } = {}): FlowStudio {
   if (!model || !Array.isArray(model.columns) || !Array.isArray(model.lanes) || !Array.isArray(model.nodes) || !Array.isArray(model.links) || !model.states) {
     throw new Error("flow-studio: the model needs columns, lanes, states, nodes and links");
   }
@@ -78,7 +81,7 @@ export function mount(root: ParentNode, model: Model, opts: { notes?: NoteDef[];
 
   const rm = matchMedia("(prefers-reduced-motion: reduce)");
   const ctx: Ctx = {
-    model, root, els, onSelect: opts.onSelect,
+    model, root, els, onSelect: opts.onSelect, onHoverKey: opts.onHoverKey, hoverKey: null,
     notes: opts.notes && opts.notes.length ? opts.notes : model.notes ?? [],
     nodes: new Map(model.nodes.map(n => [n.id, n])),
     links: model.links,
@@ -103,6 +106,7 @@ export function mount(root: ParentNode, model: Model, opts: { notes?: NoteDef[];
 
   installInteract(ctx);
   installRender(ctx);
+  installBars(ctx);
   installControls(ctx);
   installInspector(ctx);
   installChrome(ctx);
@@ -145,6 +149,7 @@ export function mount(root: ParentNode, model: Model, opts: { notes?: NoteDef[];
     setView: (v, animate) => ctx.fn.setView(v, animate),
     fit: animate => { ctx.userMoved = false; ctx.fn.fit(animate); },
     select: id => ctx.fn.select(id),
+    highlightKey: key => { ctx.hoverKey = key; markKey(ctx.els.world, key); },
     selected: () => ctx.selected,
     mode: () => ctx.mode,
     setMode: id => ctx.fn.setMode(id),
@@ -167,7 +172,7 @@ export function mount(root: ParentNode, model: Model, opts: { notes?: NoteDef[];
       const changes = diffModels(ctx.model, prepared);
       const saved: SavedState = { view: { ...ctx.view }, mode: ctx.mode, selected: ctx.selected, inspectorOpen: els.inspector.classList.contains("open"), query: ctx.query, hops: ctx.hops, filter: ctx.filter, collapsed: new Set(ctx.collapsed), knownGroups: new Set(ctx.model.nodes.filter(n => n.kind === "group").map(n => n.id)), playback: playback.playback() };
       api.destroy();
-      const replacement = mount(root, prepared, { notes: opts.notes, onSelect: opts.onSelect, restore: saved });
+      const replacement = mount(root, prepared, { notes: opts.notes, onSelect: opts.onSelect, onHoverKey: opts.onHoverKey, restore: saved });
       notifySelection(saved.selected, replacement.selected(), opts.onSelect);
       // Refresh this api in place: callers keep their reference and window.FlowStudio stays this
       // instance, so an update can never overwrite a different mounted engine.

package/bundles/antigravity-plugin/skills/flow-studio/src/layout.test.ts

@@ -142,3 +142,20 @@ test("free layout preserves finite negative node coordinates", () => {
   assert.equal(g.nodes.a!.y, -40);
   assert.ok([g.bounds.x, g.bounds.y, g.bounds.w, g.bounds.h, g.world.w, g.world.h].every(Number.isFinite));
 });
+
+test("a node with bars is taller by default, so the chart does not sit on its text; an explicit height wins", () => {
+  const model = m();
+  model.nodes[0]!.bars = [{ key: "a", value: 1 }];
+  const g = computeGeometry(model);
+  assert.equal(g.nodes.a!.h, 54 + 26);
+  assert.equal(g.nodes.b!.h, 54);
+  const free = m();
+  free.layout = "free";
+  free.nodes = [
+    { id: "x", kind: "card", lane: "l1", x: 0, y: 0, state: "ok", title: "X", bars: [{ key: "a", value: 1 }] },
+    { id: "y", kind: "card", lane: "l1", x: 0, y: 200, h: 100, state: "ok", title: "Y", bars: [{ key: "a", value: 1 }] },
+  ];
+  const gf = computeGeometry(free);
+  assert.equal(gf.nodes.x!.h, 54 + 26);
+  assert.equal(gf.nodes.y!.h, 100);
+});

package/bundles/antigravity-plugin/skills/flow-studio/src/layout.ts

@@ -17,6 +17,7 @@ export interface LayoutOptions { pitch: number; top: number; gap: number; padX:
 
 export const DEFAULTS: LayoutOptions = { pitch: 62, top: 64, gap: 34, padX: 24, visible: () => true };
 
+const BARS_EXTRA = 26; // room for the bar chart under a node's text
 const LANE_PAD_TOP = 38; // room for the lane title
 const LANE_PAD_BOTTOM = 14;
 
@@ -29,7 +30,7 @@ export function computeGeometry(m: Model, opt: Partial<LayoutOptions> = {}): Geo
 
   const nodes: Record<string, Placed> = {};
   for (const n of m.nodes) {
-    const h = NODE_HEIGHT[n.kind] ?? 54;
+    const h = (NODE_HEIGHT[n.kind] ?? 54) + (n.bars?.length ? BARS_EXTRA : 0);
     if (m.layout === "free") {
       nodes[n.id] = { id: n.id, x: n.x ?? 0, y: n.y ?? 0, w: n.w ?? 190, h: n.h ?? h };
       continue;

package/bundles/antigravity-plugin/skills/flow-studio/src/model.ts

@@ -43,6 +43,7 @@ export interface NodeDef {
   collapsed?: boolean;
   sla?: number;
   metrics?: NodeMetric;
+  bars?: NodeBar[];
 }
 export interface NodeMetric {
   value: number;
@@ -52,6 +53,14 @@ export interface NodeMetric {
   label?: string;
   series?: number[];
 }
+/** One bar of a node's chart. `key` is opaque (a date, a step) and links the same key across charts;
+ *  a null `value` means no data for that key and is drawn as a short red tick, never as zero. */
+export interface NodeBar {
+  key: string;
+  value: number | null;
+  kind?: "low";
+  label?: string;
+}
 export interface LinkDef {
   id: string;
   from: string;
@@ -153,6 +162,8 @@ export function validateModel(input: unknown): Issue[] {
     const metric = n.metrics;
     const invalidSeries = metric?.series !== undefined && (!Array.isArray(metric.series) || metric.series.length > 60 || metric.series.some(v => !Number.isFinite(v)));
     if (metric !== undefined && (!metric || !Number.isFinite(metric.value) || (metric.max != null && !Number.isFinite(metric.max)) || invalidSeries)) add("error", "metric-invalid", w, "Metrics need finite values and at most 60 finite series points.");
+    const badBars = n.bars !== undefined && (!Array.isArray(n.bars) || n.bars.length > 120 || n.bars.some(b => !b || typeof b.key !== "string" || (b.value !== null && (typeof b.value !== "number" || !Number.isFinite(b.value) || b.value < 0))));
+    if (badBars) add("error", "bars-invalid", w, "Bars need a list of at most 120 items, each with a string key and a finite, non-negative value or null.");
     if (n.sla !== undefined && (!Number.isFinite(n.sla) || n.sla <= 0)) add("error", "sla-invalid", w, "SLA must be a positive finite number of seconds.");
   }
   for (const n of nodes) {

package/bundles/antigravity-plugin/skills/flow-studio/src/render.ts

@@ -9,6 +9,7 @@ import { elbow, loopBack } from "./routing.ts";
 import { cssId } from "./stateCss.ts";
 import { baselineView, bucketOf, canonOf, effectiveLinks, isImproved, isNew, linkStateId, nodeStateId, nodeVisible } from "./rules.ts";
 import { metricBadge, sparkline } from "./metrics.ts";
+import { barsHtml, markKey } from "./bars.ts";
 
 function loopRoute(ctx: Ctx, fromId: string, toId: string, from: Placed, to: Placed, channel: number): string {
   const detourFor = (end: Placed, other: Placed) => {
@@ -45,7 +46,7 @@ function nodeHtml(ctx: Ctx, n: NodeDef): string {
   const lead = showWord ? `<b class="ev st-${cssId(sid)}">${esc(word)}</b> · ` : "";
   const fold = n.kind === "group" && n.contains?.length ? `<span class="fold">▸ ${n.contains.length}</span>` : "";
   return `<div class="t"><span class="newdot" title="Added in this view"></span><span class="name">${arrow}${esc(n.title)}</span>${fold}${badge}</div>`
-    + `<div class="s${spark ? " has-spark" : ""}" title="${esc(sub)}">${lead}${esc(sub)}</div>${spark}${bar}${improved}${upgrade}`;
+    + `<div class="s${spark ? " has-spark" : ""}" title="${esc(sub)}">${lead}${esc(sub)}</div>${spark}${barsHtml(n.bars)}${bar}${improved}${upgrade}`;
 }
 
 function build(ctx: Ctx): void {
@@ -75,7 +76,7 @@ function build(ctx: Ctx): void {
   for (const n of model.nodes) {
     const p = ctx.geom.nodes[n.id];
     if (!p) continue;
-    const d = el("div", "node" + (n.kind === "chip" ? " ref" : "") + ((n.colSpan ?? 1) > 1 ? " wide" : ""));
+    const d = el("div", "node" + (n.kind === "chip" ? " ref" : "") + ((n.colSpan ?? 1) > 1 ? " wide" : "") + (n.bars?.length ? " has-bars" : ""));
     d.id = "n_" + n.id;
     d.tabIndex = 0;
     d.setAttribute("role", "button");
@@ -190,6 +191,7 @@ function paint(ctx: Ctx, fromSwitch = false): void {
     if (r) { d.style.left = r.x + "px"; d.style.top = r.y + "px"; d.style.width = r.w + "px"; d.style.height = r.h + "px"; }
   }
 
+  markKey(ctx.els.world, ctx.hoverKey);
   ctx.fn.buildChrome();
   ctx.fn.trace(ctx.selected);
   ctx.fn.renderInspector();

package/bundles/antigravity-plugin/skills/flow-studio/src/styles.css

@@ -184,6 +184,11 @@
   .node .metric-badge i { display:block; height:2px; position:absolute; bottom:0; left:0; background:var(--accent); }
   .node .s.has-spark { padding-right:60px; }
   .node .spark { position:absolute; right:6px; bottom:4px; overflow:visible; }
+  .node svg.bars { position:absolute; left:10px; right:10px; bottom:6px; width:calc(100% - 20px); height:22px; overflow:visible; }
+  .node svg.bars rect { fill:var(--muted); opacity:.6; }
+  .node svg.bars rect.last { fill:var(--accent); opacity:1; }
+  .node svg.bars rect.low, .node svg.bars rect.miss { fill:var(--crit); opacity:1; }
+  .node svg.bars rect[data-hl="true"] { stroke:var(--fg); stroke-width:1.5px; vector-effect:non-scaling-stroke; opacity:1; }
   .node.gateway .metric-badge { position:absolute; right:9px; top:18px; }
   .node.gateway:has(.metric-badge) .gw-title, .node.gateway.has-metrics .gw-title { width:45%; margin-right:42px; }
   .node .spark polyline, .metrics polyline { fill:none; stroke:var(--accent); stroke-width:1.5; }