@1agh/maude 0.22.2 → 0.24.0

package/plugins/design/dev-server/use-selection-set.tsx

@@ -189,6 +189,18 @@ export function SelectionSetProvider({
   return <SelectionSetContext.Provider value={value}>{children}</SelectionSetContext.Provider>;
 }
 
+/**
+ * Mount a `SelectionSetProvider` only when none exists above us. The shell-
+ * owned comment mount layer provides one so both the lite comment router and
+ * `CanvasShell` share a single selection set. Hook called unconditionally;
+ * only the returned tree branches (hook rules).
+ */
+export function MaybeSelectionSetProvider({ children }: { children: ReactNode }) {
+  const outer = useContext(SelectionSetContext);
+  if (outer) return <>{children}</>;
+  return <SelectionSetProvider>{children}</SelectionSetProvider>;
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Hooks
 

package/plugins/design/dev-server/use-tool-mode.tsx

@@ -21,6 +21,7 @@ import {
   useState,
 } from 'react';
 
+import { TOOL_CURSORS } from './canvas-cursors.ts';
 import type { Tool } from './input-router.tsx';
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -35,19 +36,21 @@ export interface ToolDescriptor {
   cursor: string;
 }
 
+// Phase 21 — every tool ships a custom 32×32 SVG cursor (canvas-cursors.ts)
+// with a white outline halo so the glyph reads on any background. The native
+// crosshair/text/cell were thin + tiny ("pen almost invisible"); these mirror
+// the tool-palette icons. `move` keeps the system arrow on purpose.
 export const DEFAULT_TOOLS: readonly ToolDescriptor[] = Object.freeze([
-  { id: 'move', label: 'Move', shortcut: 'V', cursor: 'default' },
-  { id: 'hand', label: 'Hand', shortcut: 'H', cursor: 'grab' },
-  { id: 'comment', label: 'Comment', shortcut: 'C', cursor: 'crosshair' },
-  // Phase 5 — draw / annotation tools. Cursors stay as `crosshair` for pen /
-  // rect / arrow (the pen-tip glyph is reserved for the system text caret).
-  // Eraser uses `cell` as the closest cross-browser substitute for a rubber
-  // affordance (no native rubber cursor exists).
-  { id: 'pen', label: 'Pen', shortcut: 'B', cursor: 'crosshair' },
-  { id: 'rect', label: 'Rect', shortcut: 'R', cursor: 'crosshair' },
-  { id: 'ellipse', label: 'Ellipse', shortcut: 'O', cursor: 'crosshair' },
-  { id: 'arrow', label: 'Arrow', shortcut: 'A', cursor: 'crosshair' },
-  { id: 'eraser', label: 'Eraser', shortcut: 'E', cursor: 'cell' },
+  { id: 'move', label: 'Move', shortcut: 'V', cursor: TOOL_CURSORS.move },
+  { id: 'hand', label: 'Hand', shortcut: 'H', cursor: TOOL_CURSORS.hand },
+  { id: 'comment', label: 'Comment', shortcut: 'C', cursor: TOOL_CURSORS.comment },
+  { id: 'pen', label: 'Pen', shortcut: 'B', cursor: TOOL_CURSORS.pen },
+  { id: 'rect', label: 'Rect', shortcut: 'R', cursor: TOOL_CURSORS.rect },
+  { id: 'ellipse', label: 'Ellipse', shortcut: 'O', cursor: TOOL_CURSORS.ellipse },
+  { id: 'sticky', label: 'Sticky', shortcut: 'N', cursor: TOOL_CURSORS.sticky },
+  { id: 'arrow', label: 'Arrow', shortcut: 'A', cursor: TOOL_CURSORS.arrow },
+  { id: 'text', label: 'Text', shortcut: 'T', cursor: TOOL_CURSORS.text },
+  { id: 'eraser', label: 'Eraser', shortcut: 'E', cursor: TOOL_CURSORS.eraser },
 ]);
 
 interface ToolContextValue {
@@ -122,6 +125,18 @@ export function ToolProvider({
   return <ToolContext.Provider value={value}>{children}</ToolContext.Provider>;
 }
 
+/**
+ * Mount a `ToolProvider` only when none exists above us. When the shell-owned
+ * comment mount layer (canvas-comment-mount.tsx) already provides one,
+ * `DesignCanvas` consumes that instance instead of double-mounting. The hook
+ * is called unconditionally; only the returned tree branches (hook rules).
+ */
+export function MaybeToolProvider({ children }: { children: ReactNode }) {
+  const outer = useContext(ToolContext);
+  if (outer) return <>{children}</>;
+  return <ToolProvider>{children}</ToolProvider>;
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Hook
 

package/plugins/design/dev-server/ws.ts

@@ -25,6 +25,16 @@ export type WsData =
       remote: string;
       kind: 'collab';
       slug: string;
+    }
+  | {
+      // T2 (9.1-A) — HMR-only socket for the segregated canvas origin. Receives
+      // ONLY `canvas-hmr` broadcasts; never the privileged inspector feed
+      // (comments / ai-activity / git-lifecycle / sync:status / selection) and
+      // ignores all inbound messages. Hub-pushed canvas code on the canvas
+      // origin can open this, but it leaks nothing and mutates nothing.
+      id: string;
+      remote: string;
+      kind: 'canvas-hmr';
     };
 
 /**
@@ -77,6 +87,8 @@ export function createWs(ctx: Context, api: Api, inspect: Inspect, collab: Colla
     }
   }
 
+  // Privileged inspector feed — comments, selection, ai-activity, git-lifecycle,
+  // sync:status, fs:*. ONLY the same-origin inspector clients (the shell) get it.
   function broadcast(payload: unknown) {
     const msg = typeof payload === 'string' ? payload : JSON.stringify(payload);
     for (const ws of clients) {
@@ -85,6 +97,17 @@ export function createWs(ctx: Context, api: Api, inspect: Inspect, collab: Colla
     }
   }
 
+  // HMR feed — `canvas-hmr` reload signals. Safe to deliver to the segregated
+  // canvas origin, so both inspector (shell) AND canvas-hmr (canvas iframe)
+  // sockets receive it. T2 (9.1-A).
+  function broadcastHmr(payload: unknown) {
+    const msg = typeof payload === 'string' ? payload : JSON.stringify(payload);
+    for (const ws of clients) {
+      if (ws.data.kind !== 'inspector' && ws.data.kind !== 'canvas-hmr') continue;
+      send(ws, msg);
+    }
+  }
+
   // Wire bus -> WS broadcasts. inspect.ts emits 'selected' / 'active' after every
   // state write; fs-watch.ts emits 'fs:*' on every save.
   ctx.bus.on('selected', (sel) => broadcast({ type: 'selected', selected: sel }));
@@ -106,9 +129,17 @@ export function createWs(ctx: Context, api: Api, inspect: Inspect, collab: Colla
   // canvas iframes both subscribe.
   ctx.bus.on('git-lifecycle', (payload: unknown) => broadcast({ type: 'git-lifecycle', payload }));
 
+  // Phase 9 Task 8 — hub-down offline mode. The linked-mode sync runtime emits
+  // 'sync:status' on every connection-state change (online / connecting /
+  // offline / offline-long, queued-op count, conflict notices). Browser tabs
+  // render the offline/synced/escalation banner from this. Solo mode never
+  // emits, so this is a no-op for unlinked projects.
+  ctx.bus.on('sync:status', (payload: unknown) => broadcast({ type: 'sync:status', payload }));
+
   // HMR broadcaster — turns fs:any change events into `canvas-hmr` messages.
   // The iframe-side client (in _shell.html) decides reload strategy from `mode`.
-  createHmrBroadcaster(ctx, (msg) => broadcast(msg));
+  // Uses broadcastHmr so the segregated canvas origin's HMR-only sockets get it.
+  createHmrBroadcaster(ctx, (msg) => broadcastHmr(msg));
 
   // Bind a connection to its room. Stored per-socket so close() can find the
   // right room to disconnect from. Multiplexed via ws.data.id.
@@ -138,6 +169,11 @@ export function createWs(ctx: Context, api: Api, inspect: Inspect, collab: Colla
         await room.connect(conn);
         return;
       }
+      if (ws.data.kind === 'canvas-hmr') {
+        // HMR-only: join the broadcast set but get NO inspector snapshot.
+        clients.add(ws);
+        return;
+      }
       clients.add(ws);
       send(ws, { type: 'snapshot', state: inspect.state });
     },
@@ -159,6 +195,9 @@ export function createWs(ctx: Context, api: Api, inspect: Inspect, collab: Colla
       clients.delete(ws);
     },
     async message(ws, raw) {
+      // HMR-only canvas-origin socket: never accepts inbound messages (the
+      // canvas iframe only listens for canvas-hmr; it never sends).
+      if (ws.data.kind === 'canvas-hmr') return;
       if (ws.data.kind === 'collab') {
         const binding = collabConns.get(ws.data.id);
         if (!binding) return;

package/plugins/design/templates/_shell.html

@@ -28,6 +28,26 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width,initial-scale=1" />
     <title>Canvas</title>
+    <script>
+      // T2 (9.1 / DDR-060 F1 re-audit) — best-effort WebRTC denial in the canvas
+      // iframe. CSP `webrtc 'block'` is specified but UNIMPLEMENTED in shipping
+      // Chrome/Firefox as of 2026 (Chromium #40188662, Firefox bug 1783489), so
+      // it is currently a no-op, and `connect-src 'self'` does NOT cover WebRTC
+      // (it is not Fetch). Hub-pushed canvas JS could otherwise exfil via
+      // ICE/STUN. Locking these to undefined raises the bar against the naive
+      // case before any canvas module loads. NOT bulletproof — a nested
+      // same-origin (about:blank) frame can re-acquire them — so WebRTC exfil
+      // stays a DOCUMENTED residual of opt-in linked mode (see the linked-mode
+      // README banner). `webrtc 'block'` stays in the CSP for when browsers
+      // enforce it. The canvas runtime itself uses zero WebRTC.
+      for (var __k of ['RTCPeerConnection', 'webkitRTCPeerConnection', 'RTCDataChannel']) {
+        try {
+          Object.defineProperty(window, __k, { value: undefined, configurable: false, writable: false });
+        } catch (_) {
+          /* already locked / not present */
+        }
+      }
+    </script>
     <style>
       :root {
         color-scheme: light dark;
@@ -122,6 +142,10 @@
         const styleEl = document.getElementById('canvas-hide-chrome');
         if (styleEl) styleEl.media = 'all';
       }
+      // Shell-owned comment layer toggle. Gallery thumbnails pass `?comments=0`
+      // so the comment chrome is suppressed in previews; opened tabs omit it
+      // (comments on). hide-chrome exports also suppress comments.
+      const commentsEnabled = params.get('comments') !== '0' && params.get('hide-chrome') !== '1';
 
       function showError(msg) {
         const el = document.getElementById('canvas-mount-error');
@@ -146,13 +170,28 @@
               const v = msg.version || Date.now();
               // Match by exact filename when we have one; otherwise refresh all.
               const targetFile = (msg.file || '').split('/').pop();
+              let matched = false;
               for (const link of document.querySelectorAll('link[rel="stylesheet"]')) {
                 const href = link.getAttribute('href') || '';
                 if (!targetFile || href.includes(targetFile)) {
                   const base = href.split('?')[0];
                   link.setAttribute('href', base + '?v=' + v);
+                  matched = true;
                 }
               }
+              // A per-canvas `<slug>.css` imported by the TSX is INLINED into the
+              // canvas module as a <style> by Bun.build — there is no <link> to
+              // swap, so the loop above matches nothing and the edit is silently
+              // dropped until a manual hard-reload (RCA hmr-inlined-css-dropped).
+              // When nothing matched AND the changed CSS lives in THIS canvas's
+              // directory, reload so the rebuilt module re-inlines the fresh CSS.
+              // Scoped to same-dir so an unrelated specimen's CSS write doesn't
+              // reload every open tab.
+              if (!matched && msg.file && canvasRel) {
+                const cssDir = msg.file.replace(/[^/]+$/, '');
+                const canvasDir = canvasRel.replace(/[^/]+$/, '');
+                if (cssDir === canvasDir) location.reload();
+              }
             } else if (msg.mode === 'module' || msg.mode === 'hard') {
               // Only reload when the change touches *this* canvas (or `_lib`).
               if (msg.mode === 'hard' || !msg.file || (canvasRel && msg.file === canvasRel)) {
@@ -234,10 +273,13 @@
             window.__canvas_meta_file__ = designRel + '/' + canvasRel;
           });
         try {
-          const [{ createRoot }, mod, react] = await Promise.all([
-            import('react-dom/client'),
+          // mountCanvas (dist/comment-mount.js) owns the React root + the lite
+          // comment provider tree. It externalizes react / react-dom/client to
+          // the importmap so the canvas module and the comment layer share one
+          // React singleton (inlining a second React would break hooks).
+          const [{ mountCanvas }, mod] = await Promise.all([
+            import('/_client/comment-mount.js'),
             import(canvasUrl),
-            import('react'),
             metaFetch,
           ]);
           const Canvas = mod.default;
@@ -246,8 +288,24 @@
               'Canvas module at ' + canvasUrl + ' has no default export (or it is not a component).'
             );
           }
-          const root = createRoot(document.getElementById('canvas-root'));
-          root.render(react.createElement(Canvas));
+          const rootEl = document.getElementById('canvas-root');
+          mountCanvas(Canvas, {
+            rootEl,
+            file: designRel + '/' + canvasRel,
+            commentsEnabled,
+          });
+          // T2 (9.1-A) diagnostic — tell the parent the canvas mounted + how many
+          // root children it rendered. Lets the shell (and tooling) confirm a
+          // cross-origin canvas actually rendered, which a parent-page screenshot
+          // of an OOPIF cannot show. Harmless heartbeat; ignored if unhandled.
+          setTimeout(() => {
+            try {
+              window.parent.postMessage(
+                { dgn: 'canvas-mounted', file: designRel + '/' + canvasRel, children: rootEl ? rootEl.children.length : 0 },
+                '*'
+              );
+            } catch (e) { /* parent gone */ }
+          }, 800);
         } catch (err) {
           showError((err && err.stack) || String(err));
         }

package/plugins/design/templates/canvas.tsx.template

@@ -29,6 +29,19 @@
  * server (canvas-pipeline.ts pass 1). Don't author them by hand — they'd be
  * stripped + replaced. `/design:handoff` strips them again before the registry
  * sidecar leaves dev (production has no business with dev-time scaffolding).
+ *
+ * Theme model (two ISOLATED layers — system-review D9):
+ *   • Canvas-shell CHROME (workspace plane, floating toolbar, minimap, zoom
+ *     HUD, halos) auto-follows the Maude dev-server theme via `data-maude-theme`
+ *     on the iframe <html> — the dev-server sets it; never theme the chrome
+ *     from canvas code.
+ *   • ARTBOARDS keep THEIR design system's theme. The `data-theme` on the
+ *     `{{ROOT_CLASS}}` wrapper pins this artboard to a specific DS theme block;
+ *     leave it at the DS default ({{THEME_DEFAULT}}). Do NOT hardcode a theme
+ *     the DS doesn't intend — a reviewer flips an individual artboard at will
+ *     via right-click → Theme ▸ Light / Dark / Follow chrome (enabled when the
+ *     DS ships both light + dark token blocks). Only pin a non-default theme
+ *     when the canvas is intentionally single-theme.
  */
 
 import { useState } from "react";

package/plugins/design/templates/design-system-inspiration/SUB-AGENT-PROMPTS.md

@@ -14,6 +14,7 @@ The three MANDATORY safety blocks (ANIMATION SAFETY, RELATIVE-URL SAFETY, PLACEH
 
 ### ANIMATION SAFETY (mandatory — applies to motion specimen + any canvas with @keyframes / transitions)
 
+- **Tooling contract first (DDR-049).** The authoritative rule for WHICH tool to use is the "Animation tooling contract" in `skills/design-system/SKILL.md`: the **default for both specimens and canvases is `<MotionDemo role>` / the canvas-lib vocabulary from `@maude/canvas-lib`** (wraps `motion/react`), NOT hand-rolled `@keyframes`. Pure-CSS `.motion-*` role classes are a justified-only zero-JS escape hatch. The CSS rules below apply to that escape hatch and to the bounded-geometry constraints the vocabulary already satisfies — they do NOT license reaching for `@keyframes` by default.
 - **Bounded geometry.** Every tile that hosts a rotating / scaling animation MUST have `overflow: hidden`. Otherwise the bounding box extends ~√2× at 45°/135° rotations and overflows adjacent rows. **The motion specimen tiles all set `overflow: hidden` explicitly** — codify this with a CSS comment so future agents reading the file see the rationale.
 - **Sparkle / pulse / twinkle = small only.** Keyframes that scale from `0 → 1 → 0` (or similar "appear-and-disappear" patterns) are for elements ≤56px. **Never apply to full-width tiles.** Demo sparkle on a 32×32 chip inside a tile, never on the tile itself. The studyfi imprint retro D-3 caught a sparkle-on-full-tile that exploded the whole row.
 - **Loop motion = `infinite alternate`.** Specimens meant for continuous display use `animation: <kf> <dur> infinite alternate <easing>`. Single-shot animations finish in 150-200ms and leave the demo invisible on the second look — "looks dead until you hover" is the regression mode.
@@ -24,9 +25,9 @@ The three MANDATORY safety blocks (ANIMATION SAFETY, RELATIVE-URL SAFETY, PLACEH
 ### RELATIVE-URL SAFETY (mandatory — applies to any specimen referencing assets, logos, glyphs)
 
 - The dev-server serves canvases via `/_canvas-shell.html?canvas=<rel-path>`. **Relative URLs (`../foo.svg`, `./assets/logo.svg`) resolve against the SHELL's URL, not the canvas file's location.** Result: 404 / broken-image icon. Studyfi imprint retro D-4 was caught by the user mid-flow because of exactly this.
-- **Always inline SVGs** in JSX. Use `useId()` for any `<filter id>` / `<linearGradient id>` so multiple instances of the same component don't collide on a single page. OR
-- **Always use absolute paths rooted at `/assets/...`** served from the dev-server's static mount. The `system/<ds>/assets/` directory is mounted at `/assets/<ds>/` in production-handoff mode.
-- **Forbidden:** `<img src="../foo.svg">`, `<image href="./logo.svg">`, `url('../bg.png')` inside inline `<style>` blocks. Any of these surviving in a specimen is a graphic-design-critic blocker.
+- **Always inline SVGs** in JSX. Use `useId()` for any `<filter id>` / `<linearGradient id>` so multiple instances of the same component don't collide on a single page. This is the **strongly-preferred** default. OR
+- **Use an absolute path that mirrors the real on-disk location under the repo root** — the ONE correct form is `/<designRoot>/system/<ds>/assets/<file>`, e.g. `/.design/system/<ds>/assets/logo.svg` (with the default `designRoot` of `.design`). The dev-server's fall-through serves any file by its real path under the repo root (`http.ts` `safePathUnderRoot`); there is **no `/assets/<ds>/` alias** — that earlier wording was wrong and 404s. Substitute the project's actual `designRoot` (read `config.json` `designRoot`) if it isn't `.design`.
+- **Forbidden:** `<img src="../foo.svg">`, `<image href="./logo.svg">`, `url('../bg.png')` inside inline `<style>` blocks, AND the bogus `/assets/<ds>/…` alias. Any of these surviving in a specimen is a graphic-design-critic blocker.
 
 ### PLACEHOLDER POLICY (mandatory — applies to logo / mark / wordmark / mascot / glyph / illustration claims)
 
@@ -133,7 +134,8 @@ SAFETY BLOCKS — apply to every file in your slice:
   + compositor-only + reduced-motion + no-bouncy-springs.
 - **RELATIVE-URL SAFETY** (see SUB-AGENT-PROMPTS.md). Mandatory if your slice
   references ANY asset (logo, glyph, illustration, background image). Inline
-  SVG with `useId()`, OR absolute `/assets/<ds>/...` path. NEVER relative.
+  SVG with `useId()`, OR absolute `/<designRoot>/system/<ds>/assets/...` path
+  (e.g. `/.design/system/<ds>/assets/...`). NEVER relative, NEVER `/assets/<ds>/`.
 - **PLACEHOLDER POLICY** (see SUB-AGENT-PROMPTS.md). Mandatory if your slice
   scaffolds the `logo` / `empty-state` specimen or any brand-asset surface.
   Read the roster `assets:` block FIRST. If `source:` is populated, copy the
@@ -211,13 +213,17 @@ The base template above applies to every slice. Each slice gets a small addendum
 
 **Apply RELATIVE-URL SAFETY in full.** The `iconography` specimen tends to reference glyph SVGs; the `focus` specimen sometimes references focus-ring fixtures. Inline ALL SVGs.
 
+**Restraint-default type ladder (D-8).** The `type-scale` specimen demonstrates the scale the tokens already encode — do NOT reintroduce drama the tokens deliberately held back. The default ceiling is **type-scale ratio ≤ 1.2, optical-size ≤ 72, display weight ≤ semibold, tracking ≥ -0.02em**. If `colors_and_type.css` already carries a more dramatic ladder (a high-confidence research recommendation explicitly asked for maximalism), mirror what the tokens declare — never push *beyond* the tokens on your own initiative. Restraint is the default; the user opts UP via `/design:edit`, not the sub-agent.
+
+**Research type-fidelity (D-7).** Read the research payload's type recommendation (in the discovery payload / DS README). **Mirror its PRIMARY display-face ROLE exactly.** A "grotesque" direction yields a grotesque display face even when an open-source serif is more convenient to wire up — do NOT let font availability flip the role. Distinguish the **display role** from the **body-accent role**: a recommendation like `display-grotesque-editorial-serif` means a grotesque sans for the DISPLAY face *with* an editorial serif for BODY accents — it does NOT mean the serif is the display face. If the named face is unavailable, substitute within the SAME classification (grotesque → grotesque, not grotesque → serif) and note the substitution so it lands in the bypass-log. (Studyfi read "serif" off `display-grotesque-editorial-serif` and picked Fraunces as the display face — inverting the roles.)
+
 ### Slice: `brand + voice` (empty-state, logo)
 
 **Apply PLACEHOLDER POLICY in full.** This slice is the highest-risk for placeholder-bleed. The `logo` specimen MUST start by reading the roster's `assets:` block:
 - If `assets.logo.source` is a real path, the specimen `<img>`s / inlines the real asset.
 - If `assets.logo.source` is empty, fall back to a `-placeholder` SVG with the rationale in the JSX comment block. Set `source: placeholder` on roster update.
 
-**Apply RELATIVE-URL SAFETY in full.** Logo specimens are 100% asset-bound. Inline SVG is the default; absolute `/assets/<ds>/logo.svg` is the alternative.
+**Apply RELATIVE-URL SAFETY in full.** Logo specimens are 100% asset-bound. Inline SVG is the default; absolute `/<designRoot>/system/<ds>/assets/logo.svg` (e.g. `/.design/system/<ds>/assets/logo.svg`) is the alternative — never the bogus `/assets/<ds>/` alias.
 
 ### Slice: `core components` (components-buttons, components-cards, components-inputs)
 
@@ -229,6 +235,8 @@ No slice-specific addenda — the base template covers them.
 
 ### Slice: `ui_kits-*-showcase` (main agent OR signature sub-agent)
 
+**Showcase-from-real-app (D-6) — read the real layout BEFORE composing, for existing products.** If the prompt injects real layout paths (the orchestrator passes the app's `AppLayout` + primary-nav component paths when the DS is for a shipped product), you MUST **read those files first and mirror that UX, restyling only** — apply the DS tokens + signature treatment to the *real* screen anatomy. Do NOT invent a plausible-but-fictional product UX when a real one was handed to you; inventing it is the studyfi D-6 regression that forced a ~5500-LOC rebuild. If NO real layout paths are injected (greenfield DS), compose a project-specific mock from `domain_nouns` per the creativity rubric — that path is unchanged.
+
 **Apply ANIMATION SAFETY.** Showcase is the highest-density "DS in use" artifact; presence cursors, route transitions, and panel slides all show up here. Every animation must be bounded + reduced-motion-safe + token-derived.
 
 **Apply RELATIVE-URL SAFETY.** Showcase often references domain product imagery. Inline SVG mocks, never `<img src="../assets/...">`.
@@ -241,5 +249,5 @@ No slice-specific addenda — the base template covers them.
 - Discovery probe templates (sibling): `plugins/design/skills/design-system/_pastier-probe-templates.md`
 - Motion library decision: `.ai/decisions/DDR-049-motion-one-as-canonical-motion-library.md`
 - Imprint-bootstrap retro (source of D-1 … D-5): `.ai/logs/system-reviews/imprint-bootstrap-review-2026-05-26.md`
-- Asset sweep helper: `plugins/design/dev-server/bin/asset-sweep.sh`
-- Visual sanity helper: `plugins/design/dev-server/bin/visual-sanity.sh`
+- Asset sweep helper: `maude design asset-sweep` (on-PATH `maude` dispatches to the bundled helper — DDR-062)
+- Visual sanity helper: `maude design visual-sanity` (on-PATH `maude` dispatches to the bundled helper — DDR-062)

package/plugins/flow/.claude-plugin/config.schema.json

@@ -42,6 +42,11 @@
           "type": "string",
           "description": "Living codebase snapshot. Default: `.ai/context/codebase-map.md`.",
           "default": ".ai/context/codebase-map.md"
+        },
+        "designRoot": {
+          "type": "string",
+          "description": "Root of the design plugin's canvas workspace, relative to repo root. Where flow looks for `.meta.json` sidecars + canvases when bridging to design (`/flow:plan` canvas detection, `/flow:done` handoff sweep, `codebase-intelligence` design-artifacts section). Mirrors the design plugin's own default. Flow reads this directory read-only — it never writes into the design root except the `/flow:done` handoff sweep's meta status update. Default: `.design`.",
+          "default": ".design"
         }
       }
     },

package/plugins/flow/templates/ai-skeleton/README.md

@@ -27,7 +27,7 @@ These live at the root of `.ai/` (not in subfolders) and are referenced by `work
 
 - `<name>-prd.md` — product requirements / brief
 - `<name>-design-system.md` — design system reference (look & feel, tokens, density)
-- `workflows.config.json` — config consumed by all flow commands and skills
+- `workflows.config.json` — config consumed by all flow commands and skills. The optional top-level `quality` map (lint / format / typecheck / tests / build → shell command) is **not** scaffolded here — run `maude doctor --fix` once your `package.json` scripts exist and it detects + adds them (additive, never overwrites your edits).
 
 ## Conventions
 

package/plugins/flow/templates/ai-skeleton/gitignore

@@ -0,0 +1,10 @@
+# Sidecar cache — Phase C / DDR-061 (cli/lib/cache.mjs).
+# Commit the shareable, content-addressed layers (research/domain + codebase-
+# intelligence are SHA-keyed and reusable across collaborators); keep the
+# brief/run/HEAD-specific layers (research/project, design-context, scenario,
+# security) and the local telemetry (_stats.json, README.md) out of git.
+cache/*
+!cache/codebase-intelligence/
+!cache/research/
+cache/research/*
+!cache/research/domain/

package/plugins/flow/templates/ai-skeleton/scenarios/README.md

@@ -9,6 +9,7 @@ scenarios/
 ├── _lib/                       — shared helpers (selectors, fixtures, env)
 └── <scenario-slug>/
     ├── spec.md                 — what the flow does, success criteria, platform matrix
+    ├── covers.json             — OPTIONAL: { web/native/shared git pathspecs } the scenario exercises
     └── <YYYY-MM-DD-HHMM>/
         ├── report.md           — TL;DR + per-platform pivot table + counter deltas
         ├── web-desktop/        — screenshots, logs
@@ -21,6 +22,7 @@ scenarios/
 
 - **Scenario slug:** kebab-case, action-oriented (`coach-creates-recurring-practice`, `signup-via-invite`).
 - **Run timestamp:** local time of the run start. Latest run = lexicographically last folder.
-- **Report format:** owned by the `scenario` skill — see plugin docs.
+- **Report format:** owned by the `scenario` skill — `maude scenario-report <run-dir>` generates the mechanical tables; the LLM authors only the prose sections.
+- **`covers.json`** (optional): declares the source globs the scenario exercises, split into `web` / `native` / `shared` git pathspecs. Enables the route-aware skip (re-run only when covered files changed) and the web-only scope skip (no sim boot for web-only diffs). Example: `{"web":["app/(video)/**"],"native":["expo-app/**"],"shared":["packages/api-client/**"]}`. Absent → the scenario always runs the full platform matrix.
 
 Run with `/flow:scenario <slug>` (registered scenarios) or `/flow:scenario <ad-hoc description>` (one-off).

package/plugins/flow/templates/ai-skeleton/workflows.config.json

@@ -6,7 +6,8 @@
   "paths": {
     "prd": ".ai/PROJECT_NAME-prd.md",
     "designSystem": ".ai/PROJECT_NAME-design-system.md",
-    "codebaseMap": ".ai/context/codebase-map.md"
+    "codebaseMap": ".ai/context/codebase-map.md",
+    "designRoot": ".design"
   },
   "platforms": ["web-desktop"],
   "stack": {