@hybridlabor-api/aos 4.13.2 → 4.14.1

package/skills/global_config/plan-canvas/scripts/lib/plan-builder/README.md

@@ -0,0 +1,285 @@
+# BDB Plan Builder
+
+Renders an Agent-Native-style **plan folder** (local-files format) into ONE
+self-contained HTML file in the BDB look, which `aos-plan-canvas` then opens
+through its normal `.html` artifact path — so annotation, chat and verdict
+already work with no canvas changes.
+
+CommonJS, zero dependencies, no network at build time.
+
+## Input / output
+
+| Path | Role |
+|---|---|
+| `<plan-dir>/plan.mdx` | **required** — frontmatter + document blocks |
+| `<plan-dir>/canvas.mdx` | optional — appended as a "Canvas" section |
+| `<plan-dir>/prototype.mdx` | optional — appended as a "Prototype" section |
+| `<plan-dir>/.plan-state.json` | optional — `title`, `status`/`kind`, `localOnly` |
+| `<plan-dir>/plan.builder.html` | **output** — written next to the plan |
+
+The output lives inside the folder because plan-canvas only opens artifacts
+inside the workspace root.
+
+## Usage
+
+```bash
+# Build and open in one step
+aos-plan-canvas open <plan-dir> --mode bdb-plan-builder
+aos-plan-canvas open <plan-dir>/plan.mdx --mode bdb-plan-builder --no-open
+
+# Then listen for the review verdict
+aos-plan-canvas await <plan-dir>/plan.builder.html
+```
+
+Rebuild by re-running `open`: edit the MDX, run `open` again. A path with no
+`plan.mdx` exits **2** with the reason on stderr and stdout.
+
+Library:
+
+```js
+const { renderPlanFolder, renderPlanSource, parseMdx } = require('./index');
+
+renderPlanFolder('./plans/my-plan');            // { html, warnings, outFile }
+renderPlanSource({ plan, canvas, state });      // { html, warnings }
+parseMdx('<Code code={"x"} />');                // block array
+```
+
+`renderPlanFolder` reports a missing `plan.mdx` as `error` in the return value;
+it never throws.
+
+## Supported tags
+
+Tag names are the block-registry MDX names from `visual-plan` / `visual-recap`.
+The lowercase conceptual names are accepted as aliases.
+
+| Tag (aliases) | Props read | Renders as |
+|---|---|---|
+| `Diagram` (`diagram`) | `data.html`, `data.css`, `data.source`, `data.nodes`, `data.edges`, `frame`, `label` | sandboxed frame for HTML; Mermaid for `source`; table for nodes/edges |
+| `Mermaid` (`mermaid`) | `source`, `code`, `label` | `<pre class="mermaid">` + pinned ESM loader |
+| `FileTree` (`file-tree`) | `entries[]` with `path`, `change`, `note`, `snippet`, `depth` | change-badged monospace tree |
+| `WireframeBlock` (`wireframe`), `Screen` (`screen`) | `html`, `surface`, `css`, `label`, `caption`, `height`, or wireframe-kit children | `html`: sandboxed frame (no `allow-scripts`); kit children: low-fi markup, see [Wireframe kit](#wireframe-kit) |
+| `Diff` (`diff`) | `before`, `after`, `filename`, `language`, `mode`, `summary`, `annotations[]` | split or unified two-pane diff |
+| `Code` (`code`), `AnnotatedCode` (`annotated-code`) | `code`, `filename`, `language`, `annotations[]` | code block + margin notes |
+| `Endpoint` (`endpoint`, `api-endpoint`, `ApiEndpoint`) | `method`, `path`, `params[]`, `examples[]`, children prose | method/path header, param table, JSON examples |
+| `DataModel` (`data-model`) | `entities[].fields[]` with `name`, `type`, `change`, `was`, `note` | nested entity cards |
+| `QuestionForm` (`question-form`) | `title`, `questions[]` with `title`, `mode`, `options[]` | Open Questions card, recommended option marked |
+| `Columns` (`columns`) | `columns[].label` + nested blocks | two-column grid, stacked on phones |
+| `TabsBlock` (`tabs`, `Tabs`) | `tabs[].label` + nested blocks | stacked labelled groups (no click JS — the annotation layer owns clicks) |
+| `Archify` (`archify`) | `src` (relative `.html` inside the plan folder), `label`, `height` | delivered Archify diagram in `<iframe sandbox="allow-scripts">` (never `allow-same-origin`), caption and link row; see [Archify](#archify) |
+| `AgentTrail` (`agent-trail`) | `live` (http(s) URL on localhost/127.0.0.1), `embed` (flag, needs `live`) | static dependency graph of the plan's components (columns by `needs` depth, scaled with CSS to the container width, edges only for stated needs, task progress, expandable tasks) derived from the same folder's `{#id}` headings, `ImplementationMap` and `Checklist`; `live` adds an "Open live agent trail" link, `embed` a sandboxed iframe (`allow-scripts allow-same-origin`); works inside `<Artboard surface="web">`; no components gives a visible card and a warning |
+| `CustomHtml` (`custom-html`) | `html`, `css`, `label`, `height` | sandboxed frame, **no `allow-scripts`** |
+| `RichText` (`rich-text`) | `title`, markdown children | prose |
+| `Callout` | `tone`, `title`, markdown children | bordered card |
+| `Checklist` (`checklist`) | `title`, `items[]` (strings or `{label, checked, note}`), children: `- [x] item` lines or `<Item checked>` tags | checkbox list |
+| `Table` (`table`) | `title`, `columns[]`, `rows[]` (arrays, or objects keyed by column), or a markdown table as children | bordered table, inline markdown in cells |
+| `CodeTabs` (`code-tabs`) | `tabs[]` with `label`, `language`, `code` | one card, every tab stacked under its filename |
+| `Decision` (`decision`) | `title`, `question`, `options[]` (`label`, `detail`, `recommended`), `recommended` (id, label or index), `rationale` or children prose | question, option cards with a `recommended` badge, rationale |
+| `HtmlBlock` (`html-block`) | `html` or children, `title`, `css`, `height` | sandboxed frame, **no `allow-scripts`** (same as `CustomHtml`) |
+| `ImplementationMap` (`implementation-map`) | `title`, `files[]` (`path`, `title`, `note`, `change`, `snippet`), or children lines | file list with change badges; an unparsable `files` shows its escaped raw text in a visible card plus a warning |
+| `Compare` (`compare`) | `before`, `after` (markdown, `{html}`), `beforeLabel`, `afterLabel`, or `<Before>`/`<After>` children, or exactly two child blocks | Before / After two-column comparison |
+| `Json`, `OpenApiSpec` (`openapi`) | `code`/`data`, `spec` | code block |
+| `DesignBoard`, `Section` | children | pass-through (canvas.mdx containers) |
+| `Artboard` | `id`, `label`/`title`, `surface`, `x`, `y`, `width`, `height`, `order`, children | card wrapping the artboard's `Screen`; absolutely positioned when `x`/`y` are set, see [Absolute board layout](#absolute-board-layout) |
+| `Annotation` | `title`, markdown children or `text`, `targetId`, `placement`, `x`, `y` | small muted note with an arrow glyph |
+| `Connector` | `label`/`text` | connector label card |
+
+**Unknown tag → visible card.** Any tag not in the table renders as a bordered
+"unsupported block" card showing the tag name plus its escaped raw source, and
+adds a line to `warnings` (also shown in a banner at the top of the page).
+Content is never dropped silently. A block that fails to render becomes an error
+card instead of taking the document down.
+
+## Prop syntax
+
+`{...}` attribute values are JSON **or** a data-only JavaScript literal:
+unquoted keys, single quotes, trailing commas, comments and `'a' + 'b'` string
+concatenation all parse. Nothing is evaluated; an expression that is neither
+becomes a warning and the raw text is kept.
+
+## Wireframe kit
+
+A `<Screen>` (or `<FrameScreen>`) without an `html` prop whose children are tags
+renders the kit below as plain markup in the page (no iframe). Low-fi look:
+muted greys on dark, 1px borders, the BDB accent only for `active`/`primary`/done
+states, and the same UI font stack as plan-canvas and the AOS store (no handwriting font). An empty `<Screen>` renders an empty frame.
+
+| Tag | Props | Renders |
+|---|---|---|
+| `FrameScreen`, `Main`, `Col`, `Row` | `full` | flex containers; `full` fills the remaining space |
+| `Box`, `Card` | `dashed`, `full` | thin bordered container |
+| `Lines` | `n`, `widths[]` (percent) | `n` text bars |
+| `IconSquare` | `active` | small rounded square, accent when active |
+| `Divider`, `StatusBar` | | rule; phone status strip |
+| `TaskRow` | `title`, `done`, `note` | checkbox row |
+| `Text` | `value` (or children), `tone="muted"`, `weight="bold"` | wireframe text |
+| `Title`, `SectionLabel`, `Btn`, `Chips` | `text`, `label`, `label`/`primary`, `items[]` | heading, caps label, button, chip row |
+| `Skeleton` | `lines` + `widths`, or `width`/`height` | placeholder bars |
+
+An unknown kit tag renders a small labelled placeholder (`<Name>`) and adds a
+warning. Semantic `<Screen html={...}/>` is unchanged: sandboxed iframe.
+
+## Absolute board layout
+
+If any `<Artboard>` carries numeric `x` and `y`, the board switches from numbered
+flow rows to an absolute canvas with a dotted grid:
+
+- Artboards sit at `x`/`y` with `width`/`height` (defaults from `surface`), sorted in
+  the DOM by `order` (shown as a small number chip); the canvas is the bounding box
+  of everything plus a margin.
+- The artboard `label` sits above the frame, a `Screen` `caption` under it, and a
+  `Section` `title`/`subtitle` becomes a numbered label above its artboards.
+- `Annotation` goes under (`placement="bottom"`, default), above, left or right of
+  its `targetId` artboard, or at its own `x`/`y`. Notes for the same target stack.
+- Artboards without coordinates, annotations without a target or position, and
+  non-artboard blocks are listed in a tray below the canvas.
+- Connectors are unchanged: only stated `transitions` / `Connector` / `edges`.
+  A coordinate-free canvas keeps the flow-row layout.
+
+## Visual recap
+
+A plan whose frontmatter has `kind: recap` (or whose `.plan-state.json` has
+`"kind": "recap"`) gets a recap header instead of the plain title: the eyebrow
+`VISUAL RECAP`, a large title, a subtitle, and a chip row.
+
+| Frontmatter | Chip |
+|---|---|
+| `title`, `subtitle` (or `summary`) | title, subtitle |
+| `pr` | `PR #214` |
+| `branch`, `base` | `branch feat/x → main` |
+| `commit`, `author`, `date` | commit, `by …`, date |
+| `files` | `4 files` |
+| `additions`, `deletions` | `+186`, `−41` |
+
+Fields that are missing are skipped. Use `<Compare>` for the Before / After
+comparison:
+
+```mdx
+<Compare>
+<Before><Screen surface="mobile">...</Screen></Before>
+<After><Screen surface="mobile">...</Screen></After>
+</Compare>
+```
+
+`<Compare before="..." after="..." />` takes markdown, and a `<Compare>` with
+exactly two child blocks (paragraphs count) pairs them as before and after.
+
+## Board view
+
+Visual blocks render on a dark, pan/zoomable **board**: numbered rows of
+fixed-width cards (`1 · Auth Entry`), SVG arrows with small muted labels, a
+zoom control bottom-left, and a `VISUAL PLAN` mark in the footer.
+
+**Board markup rule** (everything else stays document-style):
+
+1. Everything in `canvas.mdx` is a board. `<Section title>` (or a Markdown
+   heading) starts a numbered row; `<DesignBoard>` is pass-through.
+2. In `plan.mdx`, a heading tagged `{#board}` (`## Flow {#board}`) hands its
+   section, up to the next heading of the same or a higher level, to a board.
+   The tag is stripped from the heading text.
+3. A block carrying a `board` prop (`<Mermaid board ... />`) is boarded; a run
+   of such blocks shares one board.
+4. A plan with none of these renders exactly as before and ships no board JS.
+
+**Arrows** are drawn only from relations the plan states, never inferred:
+`transitions={[{from, to, label}]}` on any container, `<Connector from to
+label />`, or `data.edges` of a node/edge `Diagram` (its nodes become cards).
+`from`/`to` match a card `id` (or `blockId`, or the slug of its title; `source`,
+`target`, `fromId`, `toId` are accepted too). An unknown endpoint adds a warning
+and draws no arrow.
+
+**Interaction** (`board-client.js`, inlined, no dependencies): `+`, `-`, `fit`,
+`1:1` buttons and Ctrl/Cmd+wheel zoom with a percentage readout; drag empty
+background or hold Space and drag to pan. The script never listens for clicks
+on cards or text (the annotation layer owns those) and only calls
+`preventDefault` for Ctrl/Cmd+wheel and the Space key over a board. Arrow paths
+are measured in the browser, so without JS the board simply scrolls inside its
+own container and arrows are not drawn (a hidden list keeps the relations
+readable). Below 900px the side navigation is hidden when the page is
+board-only.
+
+**Demos** (`aos-plan-canvas open lib/plan-builder/examples/<name> --mode bdb-plan-builder`):
+
+- `demo-plan`: 4 screens, 3 transitions, 2 numbered sections, one Mermaid diagram.
+- `signup-storyboard`: 6 absolutely positioned kit artboards, 2 sections, 5 transitions, 2 annotations.
+- `recap-demo`: `kind: recap` header, Before/After, implementation map, table, code tabs.
+
+All demo content is invented.
+
+## Archify
+
+`<Archify src="00_architecture.html" label="System" height={560} />` embeds the
+standalone HTML produced by the `archify` skill. `src` is resolved against the
+plan folder and must stay inside it: `..`, absolute paths, URLs and symlink
+escapes show an error card plus a warning, as does a missing file ("file not
+found"), a non-`.html` file, or a file over 5 MB. The page runs in
+`sandbox="allow-scripts"` only (no same-origin, forms, popups or top
+navigation) and a link row opens the file standalone.
+
+## Prototype hint
+
+If any `Artboard` or `Screen` has `surface` `web` or `desktop`, or the `plan.mdx`
+frontmatter says `prototype: suggest`, the document ends with one "Suggested next
+step" callout naming those screens and saying a throwaway prototype can be built
+with the `prototype` skill. It is plain escaped text and starts nothing.
+`prototype: skip`, or a plan with no such screens, omits it.
+
+## Trail export
+
+`aos-plan-canvas trail <plan-dir|plan.mdx> [--out <file>] [--force]` writes an
+agenttrail plan file (`trail.js`) so `aos-trail . --plan <file> --no-open` shows
+the live map after approval. Components: headings tagged `{#id}` and `<Section
+id title>`, in document order across `plan.mdx`, `canvas.mdx`, `prototype.mdx`.
+`needs`: `<Section needs=[...]>` or frontmatter `needs-<id>: a, b`. `files`:
+`<ImplementationMap>` entries. Tasks: `<Checklist>` items (`{#id}` kept, else
+generated). The default output is `production_artifacts/00_execution_plan.md`; it must resolve
+inside the workspace root (cwd), is never overwritten without `--force`, and no
+components means exit 2. Prints `{out, components, tasks, next_step}`.
+
+## Templates
+
+Starter plans live in `templates/<id>/` (`meta.json`, `plan.mdx`, optional
+`canvas.mdx`, `standard.md`).
+
+```bash
+aos-plan-canvas templates                         # JSON: id, label, description, useWhen, hasBoard (= has a design canvas)
+aos-plan-canvas new <template-id> <target-dir>    # --mode bdb-plan-builder (default) | standard
+```
+
+Recap templates: `recap` (minimal), `recap-review` (document-style recap for a PR or merge decision: summary, changed areas with FileTree and ImplementationMap, decisions with the rejected alternative, a before/after `Compare`, a commands table plus an explicit Verified / Not verified split, risks) and `recap-board` (design canvas with BEFORE and AFTER artboards, a labelled `change` connector and numbered `Annotation` markers on AFTER, plus a short `plan.mdx` whose numbered change list matches the markers).
+
+Builder mode copies `plan.mdx` (and `canvas.mdx` when the template has a board,
+never `meta.json`); standard mode writes `plan.md` from `standard.md`. A
+non-empty target exits **2** and nothing is overwritten; an unknown id exits
+**2** and lists the valid ids. A "board" template includes a design canvas (screens + arrows). `new` never starts the canvas server. The home page (`GET /`) lists templates, open reviews and installed visual skills read-only. A template
+folder without a readable `meta.json` is skipped by `templates`.
+
+## Section navigation
+
+The left section list has a "Hide sections" toggle in the top bar; the choice is kept in `localStorage` (page works without it). On phone width the list stays visible.
+
+## Security
+
+- Everything from the plan is escaped (`escapeHtml`, and `renderMarkdown` escapes
+  before any inline rule runs).
+- `Archify` is the one sandbox that allows scripts (`allow-scripts`, no same-origin), for a file read from inside the plan folder.
+- Raw HTML — `custom-html`, `HtmlBlock`, and the `html` of wireframe/diagram blocks — only
+  reaches `<iframe sandbox srcdoc=...>` **without `allow-scripts`**.
+- Attribute values are JSON-parsed, never evaluated. Template-literal
+  interpolation is refused with a warning.
+
+## Files
+
+| File | Role |
+|---|---|
+| `index.js` | `renderPlanFolder` / `renderPlanSource` / re-export `parseMdx` |
+| `trail.js` | agenttrail plan file from a plan folder |
+| `mdx.js` | frontmatter, headings, prose, JSX-like tags; never throws |
+| `render.js` | block → HTML, flow and absolute boards, recap header, Mermaid loader, page shell |
+| `kit.js` | wireframe kit tags → markup |
+| `board-client.js` | pan/zoom + arrow routing, inlined only when a board exists |
+| `theme.css` | BDB CI theme, inlined into the output |
+| `examples/demo-plan/` | richer demo: plan.mdx + canvas.mdx |
+| `examples/signup-storyboard/`, `examples/recap-demo/` | kit storyboard and recap demos |
+
+Adding this directory is also what flips `bdb-plan-builder` to **available** in
+`aos-plan-canvas modes`.

package/skills/global_config/plan-canvas/scripts/lib/plan-builder/agent-trail.js

@@ -0,0 +1,129 @@
+'use strict';
+
+/**
+ * <AgentTrail /> — static, embeddable view of the plan's multi-agent workflow.
+ * Components, needs and tasks come from derive() in trail.js (same plan folder);
+ * nothing is parsed twice. The live `aos-trail` app stays the standard; `live`
+ * only links to it, and `embed` additionally frames it.
+ */
+
+const { escapeHtml: esc } = require('../plan-canvas/markdown');
+
+const COL_W = 210;
+const COL_GAP = 60;
+const ROW_H = 80;
+const ROW_GAP = 16;
+const PAD = 8;
+const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1']);
+
+function localUrl(raw) {
+  try {
+    const u = new URL(String(raw));
+    if (!/^https?:$/.test(u.protocol) || !LOCAL_HOSTS.has(u.hostname) || u.username || u.password) return null;
+    return u.href;
+  } catch {
+    return null;
+  }
+}
+
+// Level = longest chain of stated needs; a cycle edge is ignored rather than looping.
+function levels(components) {
+  const byId = new Map(components.map((c) => [c.id, c]));
+  const memo = new Map();
+  const walking = new Set();
+  const level = (c) => {
+    if (memo.has(c.id)) return memo.get(c.id);
+    walking.add(c.id);
+    let n = 0;
+    for (const need of c.needs) {
+      const dep = byId.get(need);
+      if (dep && !walking.has(dep.id)) n = Math.max(n, level(dep) + 1);
+    }
+    walking.delete(c.id);
+    memo.set(c.id, n);
+    return n;
+  };
+  components.forEach(level);
+  return memo;
+}
+
+const pct4 = (f) => Number((f * 100).toFixed(3));
+
+function note(message) {
+  return `<div class="card trail-empty"><div class="label">AgentTrail</div><div>${esc(message)}</div></div>`;
+}
+
+function renderAgentTrail(block, ctx) {
+  const props = block.props || {};
+  let model = [];
+  try {
+    if (!ctx.dir) throw new Error('needs a plan folder on disk');
+    model = require('./trail').derive(ctx.dir).graph;
+  } catch (error) {
+    ctx.warnings.push(`<AgentTrail> could not read the plan folder: ${error.message}`);
+  }
+  if (!model.length) {
+    ctx.warnings.push('<AgentTrail> no components found; add {#id} headings and needs: lines');
+    return note('AgentTrail: no components found - add {#id} headings and needs: lines');
+  }
+
+  const level = levels(model);
+  const rowOf = new Map();
+  const pos = new Map();
+  for (const c of model) {
+    const col = level.get(c.id);
+    const row = rowOf.get(col) || 0;
+    rowOf.set(col, row + 1);
+    pos.set(c.id, { x: PAD + col * (COL_W + COL_GAP), y: PAD + row * (ROW_H + ROW_GAP) });
+  }
+  const width = PAD * 2 + (Math.max(...level.values()) + 1) * COL_W + Math.max(...level.values()) * COL_GAP;
+  const height = PAD * 2 + Math.max(...rowOf.values()) * ROW_H + (Math.max(...rowOf.values()) - 1) * ROW_GAP;
+
+  const edges = [];
+  for (const c of model) {
+    for (const need of c.needs) {
+      const a = pos.get(need);
+      const b = pos.get(c.id);
+      if (!a || !b) continue;
+      const x1 = a.x + COL_W;
+      const y1 = a.y + ROW_H / 2;
+      const x2 = b.x;
+      const y2 = b.y + ROW_H / 2;
+      const mid = (x1 + x2) / 2;
+      edges.push(`<path class="trail-edge" data-from="${esc(need)}" data-to="${esc(c.id)}" d="M${x1},${y1} C${mid},${y1} ${mid},${y2} ${x2},${y2}"/>`);
+    }
+  }
+
+  const cards = model.map((c) => {
+    const done = c.tasks.filter((t) => t.checked).length;
+    const total = c.tasks.length;
+    const pct = total ? Math.round((done / total) * 100) : 0;
+    const tasks = total
+      ? `<ul class="trail-tasks">${c.tasks.map((t) => `<li class="${t.checked ? 'done' : ''}"><span class="mark" aria-hidden="true">${t.checked ? '&#10003;' : '&#9675;'}</span>${esc(t.label)}</li>`).join('')}</ul>`
+      : '<div class="trail-tasks note">no tasks</div>';
+    const p = pos.get(c.id);
+    return `<details class="trail-node" data-id="${esc(c.id)}" style="left:${pct4(p.x / width)}%;top:${p.y}px;width:${pct4(COL_W / width)}%;min-height:${ROW_H}px">` +
+      `<summary><span class="trail-id">${esc(c.id)}</span><span class="trail-title" title="${esc(c.title)}">${esc(c.title)}</span>` +
+      `<span class="trail-count">${done} of ${total} tasks</span>` +
+      `<span class="trail-bar"><span style="width:${pct}%"></span></span></summary>${tasks}</details>`;
+  }).join('');
+
+  let live = '';
+  if (props.live !== undefined && props.live !== true) {
+    const href = localUrl(props.live);
+    if (!href) {
+      ctx.warnings.push(`<AgentTrail live="${String(props.live)}"> must be an http(s) URL on localhost or 127.0.0.1; link and iframe omitted`);
+    } else {
+      live = `<div class="trail-live"><a href="${esc(href)}" target="_blank" rel="noopener">Open live agent trail</a></div>`;
+      if (props.embed !== undefined && props.embed !== false) {
+        live += `<iframe class="trail-frame" sandbox="allow-scripts allow-same-origin" loading="lazy" title="Live agent trail" src="${esc(href)}"></iframe>`;
+      }
+    }
+  }
+
+  return '<div class="card trail"><div class="label">agent trail</div>' +
+    `<div class="trail-scroll"><div class="trail-stage" style="height:${height}px">` +
+    `<svg class="trail-edges" viewBox="0 0 ${width} ${height}" preserveAspectRatio="none" aria-hidden="true">${edges.join('')}</svg>${cards}</div></div>${live}</div>`;
+}
+
+module.exports = { renderAgentTrail, localUrl };

package/skills/global_config/plan-canvas/scripts/lib/plan-builder/board-client.js

@@ -0,0 +1,124 @@
+(function () {
+  var MIN = 0.2, MAX = 2.5;
+  document.documentElement.classList.add('js');
+  document.querySelectorAll('.board').forEach(function (board) {
+    var vp = board.querySelector('.board-viewport');
+    var stage = board.querySelector('.board-stage');
+    var canvas = board.querySelector('.board-canvas');
+    var svg = board.querySelector('.board-edges');
+    var readout = board.querySelector('.zoom-readout');
+    var scale = 1, space = false, hover = false, drag = null;
+
+    function route(a, b) {
+      var A = { l: a.offsetLeft, t: a.offsetTop, w: a.offsetWidth, h: a.offsetHeight };
+      var B = { l: b.offsetLeft, t: b.offsetTop, w: b.offsetWidth, h: b.offsetHeight };
+      var x1, y1, x2, y2, mx, my;
+      if (B.l >= A.l + A.w || A.l >= B.l + B.w) {
+        var right = B.l >= A.l + A.w;
+        x1 = right ? A.l + A.w : A.l; y1 = A.t + A.h / 2;
+        x2 = right ? B.l : B.l + B.w; y2 = B.t + B.h / 2;
+        mx = (x1 + x2) / 2;
+        return { d: 'M' + x1 + ' ' + y1 + 'H' + mx + 'V' + y2 + 'H' + x2, x: mx, y: (y1 + y2) / 2 };
+      }
+      var down = B.t >= A.t + A.h;
+      x1 = A.l + A.w / 2; y1 = down ? A.t + A.h : A.t;
+      x2 = B.l + B.w / 2; y2 = down ? B.t : B.t + B.h;
+      my = (y1 + y2) / 2;
+      return { d: 'M' + x1 + ' ' + y1 + 'V' + my + 'H' + x2 + 'V' + y2, x: (x1 + x2) / 2, y: my };
+    }
+
+    function layout() {
+      stage.style.width = canvas.offsetWidth * scale + 'px';
+      stage.style.height = canvas.offsetHeight * scale + 'px';
+      if (!svg) return;
+      svg.setAttribute('width', canvas.offsetWidth);
+      svg.setAttribute('height', canvas.offsetHeight);
+      svg.querySelectorAll('.edge').forEach(function (g) {
+        var a = document.getElementById(g.getAttribute('data-from'));
+        var b = document.getElementById(g.getAttribute('data-to'));
+        if (!a || !b) return;
+        var r = route(a, b);
+        g.querySelector('path').setAttribute('d', r.d);
+        var label = g.querySelector('text');
+        label.setAttribute('x', r.x);
+        label.setAttribute('y', r.y - 6);
+      });
+    }
+
+    function zoomTo(next, cx, cy) {
+      next = Math.min(MAX, Math.max(MIN, next));
+      var k = next / scale, sx = vp.scrollLeft + cx, sy = vp.scrollTop + cy;
+      scale = next;
+      canvas.style.transform = 'scale(' + next + ')';
+      layout();
+      vp.scrollLeft = sx * k - cx;
+      vp.scrollTop = sy * k - cy;
+      readout.textContent = Math.round(next * 100) + '%';
+    }
+
+    function fit() {
+      // Fit the width; a tall board scrolls vertically instead of shrinking to an unreadable scale.
+      var byWidth = Math.min(1, vp.clientWidth / canvas.offsetWidth);
+      var byHeight = vp.clientHeight / canvas.offsetHeight;
+      zoomTo(byHeight < byWidth ? Math.max(byHeight, Math.min(byWidth, 0.45)) : byWidth, 0, 0);
+      vp.scrollLeft = 0;
+      vp.scrollTop = 0;
+    }
+
+    board.querySelectorAll('[data-zoom]').forEach(function (btn) {
+      btn.addEventListener('click', function () {
+        var mode = btn.getAttribute('data-zoom');
+        var cx = vp.clientWidth / 2, cy = vp.clientHeight / 2;
+        if (mode === 'in') zoomTo(scale * 1.25, cx, cy);
+        else if (mode === 'out') zoomTo(scale / 1.25, cx, cy);
+        else if (mode === 'fit') fit();
+        else { zoomTo(1, 0, 0); vp.scrollLeft = 0; vp.scrollTop = 0; }
+      });
+    });
+
+    vp.addEventListener('wheel', function (e) {
+      if (!(e.ctrlKey || e.metaKey)) return;
+      e.preventDefault();
+      var r = vp.getBoundingClientRect();
+      zoomTo(scale * Math.exp(-e.deltaY * 0.0015), e.clientX - r.left, e.clientY - r.top);
+    }, { passive: false });
+
+    vp.addEventListener('pointerdown', function (e) {
+      if (e.button !== 0 || e.offsetX > vp.clientWidth || e.offsetY > vp.clientHeight) return;
+      if (!space && e.target.closest('.bcard')) return;
+      drag = { x: e.clientX, y: e.clientY, l: vp.scrollLeft, t: vp.scrollTop };
+      vp.classList.add('panning');
+      vp.setPointerCapture(e.pointerId);
+    });
+    vp.addEventListener('pointermove', function (e) {
+      if (!drag) return;
+      vp.scrollLeft = drag.l - (e.clientX - drag.x);
+      vp.scrollTop = drag.t - (e.clientY - drag.y);
+    });
+    function endDrag() { drag = null; vp.classList.remove('panning'); }
+    vp.addEventListener('pointerup', endDrag);
+    vp.addEventListener('pointercancel', endDrag);
+
+    board.addEventListener('mouseenter', function () { hover = true; });
+    board.addEventListener('mouseleave', function () { hover = false; });
+    document.addEventListener('keydown', function (e) {
+      if (e.code !== 'Space' || !hover || e.target.isContentEditable || /^(INPUT|TEXTAREA|SELECT|BUTTON)$/.test(e.target.tagName)) return;
+      space = true;
+      vp.classList.add('space');
+      e.preventDefault();
+    });
+    document.addEventListener('keyup', function (e) {
+      if (e.code !== 'Space') return;
+      space = false;
+      vp.classList.remove('space');
+    });
+
+    if (window.ResizeObserver) {
+      var ro = new ResizeObserver(layout);
+      ro.observe(canvas);
+      board.querySelectorAll('.bcard').forEach(function (c) { ro.observe(c); });
+    }
+    window.addEventListener('resize', layout);
+    fit();
+  });
+})();

package/skills/global_config/plan-canvas/scripts/lib/plan-builder/examples/demo-plan/canvas.mdx

@@ -0,0 +1,19 @@
+<DesignBoard transitions={[{"from":"entry","to":"check-email","label":"submit email"},{"from":"check-email","to":"home","label":"open link"},{"from":"check-email","to":"expired","label":"link too old"}]}>
+<Section title="Auth Entry">
+<Artboard id="entry" title="Sign in">
+<Screen surface="mobile" html={'<div class="wf-card"><h3>Welcome back</h3><p class="wf-muted">Enter your email</p><p>name@example.com</p><button class="primary">Send link</button></div>'} />
+</Artboard>
+<Artboard id="check-email" title="Check your email">
+<Screen surface="mobile" html={'<div class="wf-card"><h3>Link sent</h3><p class="wf-muted">Open the link on this device.</p></div>'} />
+</Artboard>
+</Section>
+<Section title="Outcome">
+<Artboard id="home" title="Home">
+<Screen surface="mobile" html={'<div class="wf-card"><h3>Signed in</h3><p class="wf-muted">Your projects</p></div>'} />
+</Artboard>
+<Artboard id="expired" title="Link expired">
+<Screen surface="mobile" html={'<div class="wf-card"><h3>This link expired</h3><button class="primary">Send a new link</button></div>'} />
+</Artboard>
+<Annotation>Expired links never reveal whether the email has an account.</Annotation>
+</Section>
+</DesignBoard>

package/skills/global_config/plan-canvas/scripts/lib/plan-builder/examples/demo-plan/plan.mdx

@@ -0,0 +1,18 @@
+---
+title: Demo Plan - Sign-in Flow
+status: draft
+---
+
+# Sign-in flow
+
+## Goal
+
+Let a returning user sign in with an email link, and show a clear error when the link has expired. All data here is invented for the demo.
+
+## Sequence
+
+<Mermaid label="Sign-in sequence" source={"sequenceDiagram\n  participant U as User\n  participant A as App\n  participant M as Mailer\n  U->>A: request link\n  A->>M: send link\n  M-->>U: email\n  U->>A: open link\n  A-->>U: signed in"} />
+
+## Open questions
+
+<QuestionForm title="Open Questions" questions={[{"title":"How long is a link valid?","mode":"single","options":[{"label":"15 minutes","recommended":true},{"label":"1 hour"}]}]} />

package/skills/global_config/plan-canvas/scripts/lib/plan-builder/examples/recap-demo/plan.mdx

@@ -0,0 +1,72 @@
+---
+title: Offline drafts for the notes editor
+subtitle: Drafts now survive a lost connection and sync when the network returns. Invented example.
+kind: recap
+pr: "#214"
+branch: feat/offline-drafts
+base: main
+commit: 4f2a9c1
+files: 4
+additions: 186
+deletions: 41
+author: sample-author
+date: 2026-01-15
+---
+
+## What changed
+
+Typing in the editor no longer stops when the connection drops. Each edit is written to a local queue first and replayed in order once the network is back.
+
+## Before and after
+
+<Compare>
+<Before>
+<Screen surface="mobile" caption="Connection lost">
+  <FrameScreen>
+    <Col full>
+      <Title text="Untitled note" />
+      <Lines n={3} widths={[90, 70, 40]} />
+      <Box dashed><Text value="Could not save. Retry" tone="muted" /></Box>
+    </Col>
+  </FrameScreen>
+</Screen>
+</Before>
+<After>
+<Screen surface="mobile" caption="Connection lost">
+  <FrameScreen>
+    <Col full>
+      <Title text="Untitled note" />
+      <Lines n={3} widths={[90, 70, 40]} />
+      <Row><IconSquare active /><Text value="Saved on this device" tone="muted" /></Row>
+    </Col>
+  </FrameScreen>
+</Screen>
+</After>
+</Compare>
+
+## Files
+
+<ImplementationMap files={[
+  { path: "editor/draft-queue.ts", change: "added", note: "Ordered local queue with replay" },
+  { path: "editor/save.ts", change: "modified", note: "Write to the queue before the network call" },
+  { path: "editor/status-pill.tsx", change: "modified", note: "New 'Saved on this device' state" },
+  { path: "editor/legacy-retry.ts", change: "removed", note: "Replaced by the queue" },
+]} />
+
+## Behaviour
+
+<Table columns={["State", "Before", "After"]} rows={[
+  ["Offline typing", "Edits lost on reload", "Edits kept and replayed"],
+  ["Reconnect", "Manual retry", "Automatic replay in order"],
+]} />
+
+<CodeTabs tabs={[
+  { label: "draft-queue.ts", language: "ts", code: "export function enqueue(edit: Edit) {\n  queue.push(edit);\n  persist(queue);\n}" },
+  { label: "save.ts", language: "ts", code: "await enqueue(edit);\nif (online) await flush();" },
+]} />
+
+<Callout tone="note" title="Review focus">
+
+Check the replay order when two tabs edit the same note.
+
+</Callout>