@1agh/maude 0.28.1 → 0.30.0

package/apps/studio/whats-new.json

@@ -0,0 +1,264 @@
+{
+  "$schema": "./whats-new.schema.json",
+  "entries": [
+    {
+      "id": "in-canvas-token-editor",
+      "version": "0.30.0",
+      "date": "2026-06-12",
+      "kind": "feature",
+      "title": "A real token editor, right in the canvas",
+      "summary": "The Inspector's CSS tab grew into a Figma-style design-token editor. Numeric fields carry a property glyph and scrub left/right to change; spacing fields take Webflow-style modifiers. Any value can bind to a design-system Variable through a searchable popover that shows where the token is defined — and it resolves the right system in multi-DS projects. One unified colour picker now drives every colour field, fill and border alike, with Custom and Variables tabs. Values you've set stand out while untouched rows recede, so the diff is scannable at a glance.",
+      "surface": "design-ui",
+      "tour": [
+        {
+          "target": "[data-tour='inspector-tabs']",
+          "inspector": true,
+          "tab": "css",
+          "title": "Inspect · Layers · CSS",
+          "body": "Here's the Inspector — opened to its CSS tab. It reads and writes your maude design system itself, not a generic :root. Three tabs: Inspect, Layers, CSS.",
+          "placement": "left"
+        },
+        {
+          "target": "[data-tour='css-panel']",
+          "inspector": true,
+          "tab": "css",
+          "requireSelection": true,
+          "title": "Your real element, live",
+          "body": "Hold ⌘ and click any element in the canvas. The CSS panel fills with its real, editable properties — and every change writes back to the source on blur, no AI round-trip.",
+          "placement": "left"
+        },
+        {
+          "target": ".st-cp-row",
+          "inspector": true,
+          "tab": "css",
+          "requireSelection": true,
+          "title": "Figma-style property rows",
+          "body": "Each row leads with a property glyph. Drag a numeric field left or right to scrub the value, or just type it; spacing fields accept Webflow-style modifiers.",
+          "placement": "left"
+        },
+        {
+          "target": ".st-cp-tokbtn",
+          "inspector": true,
+          "tab": "css",
+          "requireSelection": true,
+          "title": "Bind to a design token",
+          "body": "Click a field's token chip for the Variables popover — Custom for a literal, Variables for the design system's tokens. Search the list; each Variable shows its provenance. One unified colour picker drives every colour field, fill and border alike.",
+          "placement": "left"
+        },
+        {
+          "target": ".st-cp-sechd-row",
+          "inspector": true,
+          "tab": "css",
+          "requireSelection": true,
+          "title": "Scannable, resettable",
+          "body": "Values you've set stand out; untouched rows recede so the difference from the default reads at a glance. The leading dot on each row carries both its status and its reset.",
+          "placement": "left"
+        }
+      ]
+    },
+    {
+      "id": "in-canvas-direct-edit",
+      "version": "0.30.0",
+      "date": "2026-06-12",
+      "kind": "feature",
+      "title": "Edit the canvas directly — text & layers",
+      "summary": "Double-click any text to retype it in place — the new copy is written straight back to the source, no AI round-trip. The Layers tab is a browsable tree with type icons: click a layer to select it in the canvas, hover to highlight, and toggle any layer's visibility from its row. Together with the CSS token editor, small tweaks no longer need a command.",
+      "surface": "design-ui",
+      "tour": [
+        {
+          "target": "[data-tour='inspector-tabs']",
+          "inspector": true,
+          "tab": "layers",
+          "requireSelection": true,
+          "title": "Browsable layers",
+          "body": "⌘-click an element, then this Layers tab shows the artboard's elements as a tree with type icons — click a row to select it in the canvas, hover to highlight.",
+          "placement": "left"
+        },
+        {
+          "target": ".st-layer-eye",
+          "inspector": true,
+          "tab": "layers",
+          "requireSelection": true,
+          "title": "Toggle visibility",
+          "body": "The eye on each layer row hides or shows that element while you work — handy for seeing what sits underneath. Double-click any text in the canvas to retype it in place too.",
+          "placement": "left"
+        }
+      ]
+    },
+    {
+      "id": "studio-chrome-polished-end-to-end",
+      "version": "0.30.0",
+      "date": "2026-06-12",
+      "kind": "feature",
+      "title": "Studio chrome, polished end to end",
+      "summary": "The whole browser feels hand-finished now. Drag the file and inspector panels to resize them (or nudge with the arrow keys — your widths are remembered), watch a calm skeleton while a canvas compiles, and press ? for a full keyboard-shortcuts cheat sheet. Collaborator cursors and Claude's own cursor now match the design system, annotations snap to the dot grid as you drag, and focus rings, tooltips and scrollbars are consistent throughout. The View menu's Layers and Zoom are wired up, and a shortcut clash is gone — the inspector is ⌘⇧I, so I stays free for the canvas highlighter.",
+      "surface": "design-ui"
+    },
+    {
+      "id": "hub-sync-cold-start-safety",
+      "version": "0.30.0",
+      "date": "2026-06-12",
+      "kind": "feature",
+      "title": "Hub sync that can't eat your work",
+      "summary": "Boot two machines or checkouts linked to the same hub in any order — your local canvas work is safe. When both sides changed the same canvas, Maude keeps a copy of each, takes the newer one, and tells you exactly how to bring back the other; a clean catch-up just updates quietly. The sync status is honest now too: you can see which canvases are synced, pending, or rejected, and why.",
+      "surface": "design-ui"
+    },
+    {
+      "id": "canvas-annotations-figjam-v3",
+      "version": "0.30.0",
+      "date": "2026-06-12",
+      "kind": "feature",
+      "title": "Annotations grew up: diagram on the canvas",
+      "summary": "Marquee-select strokes and just drag them, group with ⌘G, copy/paste, align and reorder. Shapes rotate (hover near a corner), resize from edges with size-matching guides, hold text (double-click any shape), and switch kind — square, circle, diamond, triangle — right from the toolbar. Arrows snap to shapes and re-route as you move things, and the new Section tool (⇧S) frames a region that moves with its content. AI tools can read the board and draw on it too.",
+      "surface": "design-ui",
+      "tour": [
+        {
+          "target": ".dc-tool-palette",
+          "title": "New tools in the palette",
+          "body": "Section (⇧S) frames a region; the Shape tool's primitives can all hold text now — select a shape and press Enter to type."
+        }
+      ]
+    },
+    {
+      "id": "studio-full-functionality",
+      "version": "0.29.0",
+      "date": "2026-06-08",
+      "kind": "feature",
+      "title": "The studio is fully wired now",
+      "summary": "Everything in the chrome is live: the top bar shows the real zoom + artboard count, the status bar always shows hub-sync, and your avatar (plus Claude when it's editing) appears in the menubar. The ⌘K palette grew real Canvas/Tools commands (New canvas, Export, Handoff, Draw), there's a proper Export & handoff dialog (PNG/PDF/SVG/HTML/shadcn/ZIP) right in the shell, and a new display-only Inspector panel (Inspect · Layers · CSS) reads any element you ⌘-click.",
+      "surface": "design-ui",
+      "tour": [
+        {
+          "target": "[data-tour='status']",
+          "title": "Live status, finally",
+          "body": "Zoom, artboard count, presence and hub-sync now reflect the real state — no more static placeholders.",
+          "placement": "bottom"
+        },
+        {
+          "target": "[data-tour='inspector']",
+          "inspector": true,
+          "title": "Inspector",
+          "body": "Opened from View → Inspector (I). ⌘-click an element to read its position, size, ancestry and markup — and now edit its CSS against your tokens, live.",
+          "placement": "left"
+        }
+      ]
+    },
+    {
+      "id": "draw-animation-lottie",
+      "version": "0.29.0",
+      "date": "2026-06-08",
+      "kind": "feature",
+      "title": "Animate draw marks → ship one Lottie",
+      "summary": "/design:draw now handles motion briefs (morph, pulse, blink) and proves the animation is actually live. /design:to-lottie productionizes it into one Lottie that plays 1:1 on web and React Native.",
+      "surface": "design-ui"
+    },
+    {
+      "id": "studio-maude-ds-redesign",
+      "version": "0.29.0",
+      "date": "2026-06-08",
+      "kind": "feature",
+      "title": "The studio, redesigned in maude",
+      "summary": "The canvas browser chrome is now built in the maude design system itself — a dark-first studio shell with a branded menubar + real dropdowns, a collapsible file-tree sidebar with a rail, a cohesive bottom context bar, a maude-styled comments panel, and a clean light handoff. New: a ⌘K command palette for jumping to the design-system view, comments, theme, reload, and help. The in-canvas chrome (tools, minimap, selection halos) was re-skinned to the same indigo accent so the whole surface reads as one product.",
+      "surface": "design-ui",
+      "tour": [
+        {
+          "target": "[data-tour='brand']",
+          "title": "Built in maude",
+          "body": "The studio chrome now dogfoods the maude DS — one cohesive material across the menubar, sidebar, canvas and status bar.",
+          "placement": "bottom"
+        },
+        {
+          "target": "[data-tour='menus']",
+          "title": "Press ⌘K",
+          "body": "A command palette jumps you to the design-system view, comments, theme toggle, reload, and help — no mouse needed.",
+          "placement": "bottom"
+        }
+      ]
+    },
+    {
+      "id": "annotation-tooling-polish",
+      "version": "0.29.0",
+      "date": "2026-06-08",
+      "kind": "improvement",
+      "title": "Richer annotations — highlighter, lists & text shortcuts",
+      "summary": "Annotations got a full polish pass: a new highlighter tool (translucent marker with multiply blend), dashed strokes on shapes, FigJam-style sticky corner, multi-line text with Enter, italic/underline/lists, and Cmd+B/I/U formatting shortcuts that work the same way in sticky notes, shapes, and the text tool.",
+      "surface": "design-ui",
+      "tour": [
+        {
+          "target": "[data-tour='viewport']",
+          "canvas": true,
+          "title": "New: Highlighter",
+          "body": "Open a canvas and press P to enter annotate mode, then pick the Highlighter from the toolbar — a translucent marker whose overlapping strokes darken with multiply blend. Sticky notes, shapes and text all take Cmd+B/I/U too.",
+          "placement": "auto"
+        }
+      ]
+    },
+    {
+      "id": "canvas-media-images-links",
+      "version": "0.29.0",
+      "date": "2026-06-08",
+      "kind": "feature",
+      "title": "Drop images & paste links onto the canvas",
+      "summary": "Drag a screenshot from your desktop — or paste a clipboard image or a URL — straight onto the canvas. Images sit alongside your annotations; links render as a tidy preview chip you can open in one click.",
+      "surface": "design-ui"
+    },
+    {
+      "id": "in-app-whats-new-tour",
+      "version": "0.29.0",
+      "date": "2026-06-08",
+      "kind": "feature",
+      "title": "What's New, right in the canvas browser",
+      "summary": "The Maude UI now tells you what shipped — a dismissible notice plus a panel you can reopen from the menubar. Each closed-out feature adds an entry automatically.",
+      "surface": "design-ui",
+      "tour": [
+        {
+          "target": "[data-tour='whatsnew']",
+          "title": "Your What's New badge",
+          "body": "This ✦ badge lights up when a new maude version ships features. Click it any time to reopen this panel."
+        },
+        {
+          "target": "[data-tour='help']",
+          "title": "Tours live in Help too",
+          "body": "Open Help to replay the full \"how Maude works\" walkthrough whenever you want."
+        }
+      ]
+    },
+    {
+      "id": "canvas-create-delete-from-browser",
+      "version": "0.28.1",
+      "date": "2026-06-03",
+      "kind": "feature",
+      "title": "Create & delete canvases from the browser",
+      "summary": "Spin up a blank brief-board straight from the file tree (+ board) and remove canvases without leaving the UI — no /design:new round-trip needed.",
+      "learnMore": "https://github.com/1aGh/maude#readme",
+      "surface": "design-ui"
+    },
+    {
+      "id": "canvas-activity-overlay",
+      "version": "0.28.0",
+      "date": "2026-06-02",
+      "kind": "feature",
+      "title": "Live canvas activity overlay",
+      "summary": "See at a glance which artboard Claude (or a teammate) is editing — a soft rim + badge highlights the active canvas and fades when work settles.",
+      "surface": "design-ui"
+    },
+    {
+      "id": "draw-as-code-svg-agent",
+      "version": "0.28.0",
+      "date": "2026-05-30",
+      "kind": "feature",
+      "title": "Draw production SVGs as code",
+      "summary": "/design:draw generates logos, icons, and diagrams through a deterministic geometry engine — no hand-guessed path data — and proofs them across the 16/24/48/256 verify ladder.",
+      "surface": "design-ui"
+    },
+    {
+      "id": "self-hostable-hub-sync",
+      "version": "0.27.0",
+      "date": "2026-05-28",
+      "kind": "feature",
+      "title": "Self-hostable hub + live file sync",
+      "summary": "Run your own Maude hub and co-edit canvases with bidirectional file sync, offline-aware status, and conflict handling.",
+      "surface": "design-ui"
+    }
+  ]
+}

package/apps/studio/whats-new.schema.json

@@ -0,0 +1,86 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/1aGh/maude/main/apps/studio/whats-new.schema.json",
+  "title": "Maude What's New feed",
+  "description": "User-facing product-update entries surfaced in the Maude UI (and mirrored to the docs site). Single source of truth — ships with the dev-server, appended on /flow:done, stamped at release. See .ai/plans/feature-in-app-whats-new-tour.md (DDR-A).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["entries"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "entries": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/entry" }
+    }
+  },
+  "$defs": {
+    "entry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "kind", "title", "summary"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Stable slug (usually the plan slug). Used for de-dup and as the React key.",
+          "pattern": "^[a-z0-9][a-z0-9-]*$"
+        },
+        "version": {
+          "type": ["string", "null"],
+          "description": "Semver the feature shipped in, or null while pending (stamped at release).",
+          "pattern": "^\\d+\\.\\d+\\.\\d+"
+        },
+        "date": {
+          "type": ["string", "null"],
+          "description": "Release date YYYY-MM-DD, or null while pending."
+        },
+        "kind": { "enum": ["feature", "improvement", "usage", "fix"] },
+        "title": { "type": "string", "minLength": 1 },
+        "summary": { "type": "string", "minLength": 1 },
+        "learnMore": {
+          "type": "string",
+          "description": "Optional URL to docs / release notes. Constrained to http(s) — the feed renders this as an <a href>, so a javascript:/data: scheme is rejected at the data-contract layer (defense-in-depth alongside React's URL sanitizer).",
+          "pattern": "^https?://"
+        },
+        "surface": {
+          "type": "string",
+          "description": "Which UI surface this targets (e.g. design-ui). Future-proofing."
+        },
+        "tour": {
+          "type": "array",
+          "description": "Optional spotlight steps that highlight the new UI (consumed by the tour engine — Phase 3).",
+          "items": { "$ref": "#/$defs/tourStep" }
+        }
+      }
+    },
+    "tourStep": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["target", "title", "body"],
+      "properties": {
+        "target": {
+          "type": "string",
+          "description": "CSS selector or [data-tour=\"<key>\"] anchor to spotlight. Prefer the stable [data-tour] anchors over styling classes (which churn on redesigns)."
+        },
+        "title": { "type": "string", "minLength": 1 },
+        "body": { "type": "string", "minLength": 1 },
+        "placement": { "enum": ["top", "bottom", "left", "right", "auto"] },
+        "canvas": {
+          "type": "boolean",
+          "description": "Setup: ensure a canvas is open before the step (the tour opens the first one if none)."
+        },
+        "inspector": {
+          "type": "boolean",
+          "description": "Setup: open the right-hand Inspector panel before the step."
+        },
+        "tab": {
+          "enum": ["inspect", "layers", "css"],
+          "description": "Setup: switch the Inspector to this tab before the step."
+        },
+        "requireSelection": {
+          "type": "boolean",
+          "description": "The target only exists once an element is ⌘-clicked in the (cross-origin) canvas. The card shows a '⌘-click to continue' hint and the spotlight snaps onto the real row when a selection lands."
+        }
+      }
+    }
+  }
+}

package/apps/studio/whats-new.ts

@@ -0,0 +1,87 @@
+// whats-new.ts — server-side loader for the Maude "What's New" feed.
+//
+// Single source of truth: `<DEV_SERVER_ROOT>/whats-new.json` (DDR-A). The feed
+// describes **Maude's own product** updates — it is resolved from the maude
+// package root (via paths.ts, NOT cwd), so the dev-server surfaces the same
+// product news whether it runs in this repo or a downstream user's project.
+//
+// Disk paths MUST come from paths.ts (DDR-045) — never
+// `dirname(fileURLToPath(import.meta.url))`, which is the virtual `/$bunfs/root`
+// inside a `bun --compile` standalone binary.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { DEV_SERVER_ROOT } from './paths.ts';
+
+export type WhatsNewKind = 'feature' | 'improvement' | 'usage' | 'fix';
+
+export interface WhatsNewTourStep {
+  target: string;
+  title: string;
+  body: string;
+  placement?: 'top' | 'bottom' | 'left' | 'right' | 'auto';
+}
+
+export interface WhatsNewEntry {
+  id: string;
+  version: string | null;
+  date: string | null;
+  kind: WhatsNewKind;
+  title: string;
+  summary: string;
+  learnMore?: string;
+  surface?: string;
+  tour?: WhatsNewTourStep[];
+}
+
+export interface WhatsNewFeed {
+  /** The installed maude version (key the client compares "seen" against). */
+  version: string;
+  entries: WhatsNewEntry[];
+}
+
+let cache: WhatsNewFeed | null = null;
+
+/**
+ * Read the installed maude version from the design plugin manifest.
+ * `apps/studio/` → `plugins/design/.claude-plugin/plugin.json`.
+ * That manifest ships in BOTH npm installs and marketplace-cache clones
+ * (same rationale as build.ts `readPluginVersion`). Falls back to `dev`.
+ */
+export function resolveMaudeVersion(root: string = DEV_SERVER_ROOT): string {
+  const manifest = join(root, '..', '..', 'plugins', 'design', '.claude-plugin', 'plugin.json');
+  try {
+    const parsed = JSON.parse(readFileSync(manifest, 'utf8')) as { version?: unknown };
+    if (typeof parsed.version === 'string') return parsed.version;
+  } catch {
+    /* fall through */
+  }
+  return 'dev';
+}
+
+/**
+ * Load `<root>/whats-new.json`. Fails soft to an empty entry list — a missing
+ * or malformed feed must never 500 the dev-server (it's a non-critical chrome
+ * surface). Caches the default-root result; pass `{ root }` for an uncached
+ * read (tests) and `{ fresh: true }` to bypass the cache.
+ */
+export function loadWhatsNew(opts: { root?: string; fresh?: boolean } = {}): WhatsNewFeed {
+  const usingDefaultRoot = opts.root === undefined;
+  if (cache && usingDefaultRoot && !opts.fresh) return cache;
+
+  const root = opts.root ?? DEV_SERVER_ROOT;
+  const file = join(root, 'whats-new.json');
+  let entries: WhatsNewEntry[] = [];
+  try {
+    if (existsSync(file)) {
+      const parsed = JSON.parse(readFileSync(file, 'utf8')) as { entries?: unknown };
+      if (Array.isArray(parsed.entries)) entries = parsed.entries as WhatsNewEntry[];
+    }
+  } catch {
+    /* malformed feed → empty, never throw */
+  }
+
+  const feed: WhatsNewFeed = { version: resolveMaudeVersion(root), entries };
+  if (usingDefaultRoot) cache = feed;
+  return feed;
+}

package/cli/bin/maude.mjs

@@ -50,6 +50,16 @@ async function main(argv) {
     return run({ args: [], pkgRoot: PKG_ROOT });
   }
 
+  // `maude studio [...]` — top-level alias for `maude design serve` (DDR-095:
+  // the verb now matches the apps/studio home). Checked BEFORE the COMMANDS map
+  // so it never falls through to the unknown-command branch; it is deliberately
+  // NOT a COMMANDS entry (that would dispatch design.run with positional[0]
+  // wrong). `maude design serve` keeps working unchanged.
+  if (cmd === 'studio') {
+    const { run } = await COMMANDS.design();
+    return run({ args: ['serve', ...args.slice(1)], pkgRoot: PKG_ROOT });
+  }
+
   const loader = COMMANDS[cmd];
   if (!loader) {
     process.stderr.write(

package/cli/commands/design-link.test.mjs

@@ -282,6 +282,90 @@ test('status reports zero-syncable when _sync.json is notSyncable (DDR-060 / 9.1
   cleanup();
 });
 
+// --------------------------------------------------- DDR-102 status surfaces
+
+test('DDR-102: status renders docs counts, rejected slugs, and the conflict recovery hint', async () => {
+  await runCli(['design', 'link', URL, '--token', 'mau_test']);
+  writeFileSync(
+    join(workspace, '.design/_sync.json'),
+    JSON.stringify({
+      state: 'online',
+      queuedOps: 0,
+      lastSyncAt: 1760000000000,
+      offlineSince: null,
+      flash: null,
+      updatedAt: Date.now(),
+      url: URL,
+      canvases: 83,
+      docs: { synced: 81, pending: 0, rejected: 2 },
+      rejectedSlugs: ['system-tokens', 'system-type'],
+      conflicts: [
+        {
+          slug: 'ui-maskot',
+          kind: 'cold-start-diverged',
+          winner: 'local',
+          snapshots: {
+            local: '2026-06-11T10:00:00.000Z',
+            hub: '2026-06-11T10:00:00.001Z',
+          },
+          at: 1760000001000,
+        },
+      ],
+    }),
+    'utf8'
+  );
+
+  const human = await runCli(['design', 'status']);
+  assert.equal(human.status, 0, human.stderr);
+  assert.match(human.stdout, /docs: 81 synced · 0 pending · 2 rejected/);
+  assert.match(human.stdout, /not syncing:\s+system-tokens, system-type/);
+  assert.match(human.stdout, /ui-maskot — diverged, kept local \(newest-wins\)/);
+  assert.match(human.stdout, /local@2026-06-11T10:00:00\.000Z/);
+  assert.match(human.stdout, /hub@2026-06-11T10:00:00\.001Z/);
+  assert.match(human.stdout, /\/design:rollback ui-maskot/);
+
+  // --json passes the new fields through verbatim.
+  const json = await runCli(['design', 'status', '--json']);
+  const payload = JSON.parse(json.stdout);
+  assert.equal(payload.sync.docs.rejected, 2);
+  assert.equal(payload.sync.conflicts[0].winner, 'local');
+  cleanup();
+});
+
+test('DDR-102: status renders an OLD-shape _sync.json (no docs/rejectedSlugs) unchanged', async () => {
+  await runCli(['design', 'link', URL, '--token', 'mau_test']);
+  writeFileSync(
+    join(workspace, '.design/_sync.json'),
+    JSON.stringify({
+      state: 'online',
+      queuedOps: 0,
+      lastSyncAt: null,
+      offlineSince: null,
+      flash: null,
+      updatedAt: Date.now(),
+      url: URL,
+      canvases: 5,
+      conflicts: [],
+    }),
+    'utf8'
+  );
+  const human = await runCli(['design', 'status']);
+  assert.equal(human.status, 0, human.stderr);
+  assert.match(human.stdout, /sync agent:\s+online/);
+  assert.doesNotMatch(human.stdout, /docs:/);
+  assert.doesNotMatch(human.stdout, /not syncing:/);
+  cleanup();
+});
+
+test('DDR-102: re-linking the same hub prints the token-replacement notice', async () => {
+  await runCli(['design', 'link', URL, '--token', 'mau_first']);
+  const second = await runCli(['design', 'link', URL, '--token', 'mau_second']);
+  assert.equal(second.status, 0, second.stderr);
+  assert.match(second.stdout, /replacing the stored token for/);
+  assert.match(second.stdout, /EVERY project linked to this hub on this machine/);
+  cleanup();
+});
+
 // --------------------------------------------------- DDR-054 F2/F4 trust gate
 
 const REMOTE_URL = 'http://hub.invalid:9999'; // .invalid never resolves (RFC 6761)

package/cli/commands/design.mjs

@@ -40,6 +40,9 @@ const BIN_VERBS = new Set([
   'draw-build',
   'draw-proof',
   'svg-optimize',
+  'to-lottie',
+  'read-annotations',
+  'annotate',
 ]);
 
 // Bin verbs that boot the dev-server (directly, or by shelling into server-up.sh).
@@ -86,11 +89,16 @@ function runBinDispatch(verb, { args, pkgRoot }) {
     process.stderr.write(`maude design: "${verb}" is not a dev-tooling verb.\n${usage()}`);
     process.exit(2);
   }
+  // CLAUDE_PLUGIN_ROOT stays the design *plugin* dir (plugins/design) — that's
+  // its true meaning, and it remains 2 levels under pkgRoot so the helpers'
+  // `$PLUGIN_ROOT/../../cli` side-channel + `$PLUGIN_ROOT/../..` pkg-root math
+  // still resolve. The bin scripts themselves now live under apps/studio/bin
+  // (DDR-095) and resolve the dev-server tree via $SCRIPT_DIR/.. regardless.
   const pluginRoot = join(pkgRoot, 'plugins', 'design');
-  const script = join(pluginRoot, 'dev-server', 'bin', `${verb}.sh`);
+  const script = join(pkgRoot, 'apps', 'studio', 'bin', `${verb}.sh`);
   if (!existsSync(script)) {
     process.stderr.write(
-      `maude design ${verb}: helper not found at ${script}. Reinstall maude (the dev-server bin ships in the npm package).\n`
+      `maude design ${verb}: helper not found at ${script}. Reinstall maude (the studio bin ships in the npm package).\n`
     );
     process.exit(1);
   }
@@ -127,7 +135,7 @@ Lifecycle:
 Dev-tooling (dispatch to the dev-server bash helpers — DDR-062):
   screenshot · server-up · prep · slug · bootstrap-check · runtime-health
   smoke · canvas-edit · handoff · asset-sweep · visual-sanity
-  draw-build · draw-proof · svg-optimize
+  draw-build · draw-proof · svg-optimize · to-lottie · read-annotations · annotate
         Invoke the bundled helper of the same name. maude resolves it from its
         own package root and sets CLAUDE_PLUGIN_ROOT for the child; stdout,
         stderr, and exit code pass straight through (so command-substitution
@@ -140,7 +148,8 @@ Dev-tooling (dispatch to the dev-server bash helpers — DDR-062):
 
   serve [--port N] [--root PATH]
         Start the design plugin's dev server in the current repo. Equivalent
-        to invoking 'claude-design-server'. Forwards all remaining args.
+        to 'maude studio' (top-level alias) or invoking 'claude-design-server'.
+        Forwards all remaining args.
 
   init  [--name <slug>] [--ds <name>] [--force] [--dry-run]
         [--no-discovery | --discovery-payload <path>]
@@ -259,8 +268,8 @@ async function runServe({ args, pkgRoot }) {
     process.exit(1);
   }
 
-  const tsEntry = resolve(pkgRoot, 'plugins', 'design', 'dev-server', 'server.ts');
-  const mjsEntry = resolve(pkgRoot, 'plugins', 'design', 'dev-server', 'server.mjs');
+  const tsEntry = resolve(pkgRoot, 'apps', 'studio', 'server.ts');
+  const mjsEntry = resolve(pkgRoot, 'apps', 'studio', 'server.mjs');
 
   const hasBun = await new Promise((res) => {
     const probe = spawn('bun', ['--version'], { stdio: 'ignore' });
@@ -414,7 +423,7 @@ function checkDevDeps({ pkgRoot }) {
   // with a less actionable error.
   const required = ['magic-string', 'oxc-parser'];
   const missing = [];
-  const paths = [resolve(pkgRoot, 'plugins', 'design', 'dev-server'), resolve(pkgRoot)];
+  const paths = [resolve(pkgRoot, 'apps', 'studio'), resolve(pkgRoot)];
   for (const dep of required) {
     try {
       require.resolve(dep, { paths });

package/cli/commands/design.test.mjs

@@ -150,3 +150,43 @@ test('isPlausiblePlatformBinary — accepts maude-<slug>/maude, rejects everythi
   assert.equal(isPlausiblePlatformBinary(''), false);
   assert.equal(isPlausiblePlatformBinary(null), false);
 });
+
+// DDR-095 — `maude studio` is a top-level alias for `maude design serve`. Both
+// must resolve the same server-entry path. We prove parity by booting each
+// against a temp dir with no .design/: the dev-server fails loud (exit 1) with
+// an identical first-line signature, which only happens if `studio` routed
+// through design-serve resolution (`apps/studio/server.{ts,mjs}` / the binary).
+test('`maude studio` aliases `maude design serve` (identical boot resolution)', () => {
+  const BIN_PATH = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'bin', 'maude.mjs');
+  function bootAgainstEmpty(argv) {
+    const cwd = mkdtempSync(join(tmpdir(), 'maude-studio-'));
+    try {
+      const r = spawnSync(process.execPath, [BIN_PATH, ...argv, '--root', cwd], {
+        encoding: 'utf8',
+        timeout: 30000,
+      });
+      // Each invocation mkdtemp's its own root, and the diagnostic embeds that
+      // path — mask it so we compare the path-independent signature (the test's
+      // actual intent: same exit code + same error shape from both entrypoints).
+      const firstErr = ((r.stderr || '').split('\n').find(Boolean) ?? '').replaceAll(cwd, '<root>');
+      return { status: r.status, firstErr };
+    } finally {
+      rmSync(cwd, { recursive: true, force: true });
+    }
+  }
+  const viaDesign = bootAgainstEmpty(['design', 'serve']);
+  const viaStudio = bootAgainstEmpty(['studio']);
+  // Both fail loud (no .design/) — same exit code, same first-line diagnostic.
+  assert.notEqual(viaStudio.status, 0, `studio should not boot cleanly: ${viaStudio.firstErr}`);
+  assert.equal(viaStudio.status, viaDesign.status);
+  assert.equal(viaStudio.firstErr, viaDesign.firstErr);
+});
+
+test('`maude studio` is recognized (not an unknown command)', () => {
+  const BIN_PATH = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'bin', 'maude.mjs');
+  const r = spawnSync(process.execPath, [BIN_PATH, 'studio', '--root', '/nonexistent-xyz'], {
+    encoding: 'utf8',
+    timeout: 30000,
+  });
+  assert.doesNotMatch(r.stderr || '', /unknown command/);
+});