@1agh/maude 0.43.0 → 0.44.0

package/apps/studio/client/styles/4-components.css

@@ -859,6 +859,12 @@
 }
 .help-modal-body::-webkit-scrollbar { width: 6px; }
 .help-modal-body::-webkit-scrollbar-thumb { background: var(--u-border); }
+
+/* Watch-the-intro player (DDR-166 Phase 1 / T2) — wider modal, no padding
+   around the video so it fills edge-to-edge. */
+.help-modal--wide { width: min(960px, 100%); }
+.intro-video-body { padding: 0; overflow: hidden; }
+.intro-video-el { display: block; width: 100%; aspect-ratio: 16 / 9; background: #000; }
 .help-modal-body details {
   margin: 0 0 var(--u-s-2);
   border-bottom: 1px solid var(--u-border-subtle);
@@ -1652,3 +1658,220 @@
   background: var(--u-accent);
   color: var(--u-accent-fg);
 }
+
+/* ── Settings — AI generation (feature-ai-media-generation, DDR-16x) ─────── */
+.st-settings-intro {
+  font-size: var(--type-xs, 12px);
+  color: var(--fg-3);
+  line-height: 1.5;
+  margin: 6px 0 12px;
+}
+.st-settings-intro code {
+  font-family: var(--font-mono);
+  font-size: 0.92em;
+  color: var(--fg-2);
+}
+.st-provider-card {
+  border: 1px solid var(--border-default);
+  border-radius: var(--radius-sm);
+  background: var(--bg-2);
+  padding: 12px;
+  margin-bottom: 10px;
+}
+.st-provider-hd {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+.st-provider-name {
+  font-family: var(--font-mono);
+  font-size: var(--type-sm, 13px);
+  color: var(--fg-1);
+  font-weight: 600;
+}
+.st-provider-card .st-pill {
+  display: inline-flex;
+  align-items: center;
+  gap: 3px;
+  font-size: 10px;
+  text-transform: uppercase;
+  letter-spacing: 0.03em;
+  color: var(--fg-3);
+  border: 1px solid var(--border-default);
+  border-radius: var(--radius-pill, 999px);
+  padding: 1px 7px;
+}
+.st-provider-card .st-pill.is-local {
+  color: var(--accent);
+  border-color: var(--accent-muted, var(--accent));
+}
+.st-provider-configured {
+  display: inline-flex;
+  align-items: center;
+  gap: 3px;
+  margin-left: auto;
+  font-size: 11px;
+  color: var(--accent);
+}
+.st-provider-modalities {
+  font-family: var(--font-mono);
+  font-size: 11px;
+  color: var(--fg-3);
+  margin-top: 4px;
+}
+.st-provider-notes {
+  font-size: 11px;
+  color: var(--fg-3);
+  line-height: 1.5;
+  margin-top: 6px;
+}
+.st-provider-keylink {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  font-size: 11px;
+  color: var(--accent);
+  text-decoration: none;
+  margin-top: 6px;
+}
+.st-provider-keylink:hover {
+  text-decoration: underline;
+}
+.st-provider-keyrow {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  margin-top: 10px;
+}
+.st-provider-keyinput {
+  flex: 1;
+  min-width: 0;
+}
+.st-provider-status {
+  font-size: 11px;
+  margin-top: 6px;
+}
+
+/* ── Transcription-engine selector (Task 2.6) ───────────────────────────── */
+.st-engine-radios {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  margin-top: 10px;
+}
+.st-engine-radio {
+  display: flex;
+  align-items: flex-start;
+  gap: 9px;
+  padding: 9px 11px;
+  border: 1px solid var(--border-default);
+  border-radius: var(--radius-sm);
+  background: var(--bg-1);
+  cursor: pointer;
+}
+.st-engine-radio.is-selected {
+  border-color: var(--accent);
+  background: var(--bg-2);
+}
+.st-engine-radio input {
+  margin-top: 2px;
+  accent-color: var(--accent);
+}
+.st-engine-radio-body {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+.st-engine-radio-label {
+  font-size: var(--type-sm, 13px);
+  color: var(--fg-1);
+  font-weight: 600;
+}
+.st-engine-radio-note {
+  font-size: 11px;
+  color: var(--fg-3);
+}
+
+/* ── Local whisper model download (Task 2.7) ────────────────────────────── */
+.st-model-list {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  margin-top: 10px;
+}
+.st-model-row {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 10px;
+  padding: 9px 11px;
+  border: 1px solid var(--border-default);
+  border-radius: var(--radius-sm);
+  background: var(--bg-1);
+}
+.st-model-info {
+  display: flex;
+  flex-direction: column;
+  gap: 3px;
+  min-width: 0;
+}
+.st-model-label {
+  display: flex;
+  align-items: center;
+  gap: 7px;
+  flex-wrap: wrap;
+  font-size: var(--type-sm, 13px);
+  color: var(--fg-1);
+  font-weight: 600;
+}
+.st-model-size {
+  font-size: 11px;
+  color: var(--fg-3);
+  font-weight: 400;
+}
+.st-model-progress {
+  font-size: 11px;
+  color: var(--accent);
+  font-variant-numeric: tabular-nums;
+}
+.st-model-actions {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  flex-shrink: 0;
+}
+
+/* ── Generate dialog (feature-ai-media-generation, DDR-16x) ─────────────── */
+.st-gen-prompt {
+  width: 100%;
+  resize: vertical;
+  min-height: 60px;
+  font-family: var(--font-sans, system-ui, sans-serif);
+  margin-bottom: 10px;
+}
+.st-gen-go {
+  color: var(--accent);
+  border-color: var(--accent-muted, var(--accent));
+}
+.st-gen-result {
+  display: flex;
+  gap: 10px;
+  align-items: flex-start;
+  margin-top: 12px;
+  padding: 10px;
+  border: 1px solid var(--border-default);
+  border-radius: var(--radius-sm);
+  background: var(--bg-2);
+}
+.st-gen-thumb {
+  width: 96px;
+  height: 96px;
+  object-fit: cover;
+  border-radius: var(--radius-sm);
+  background: var(--bg-3);
+}
+.st-gen-result-actions {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}

package/apps/studio/client/styles/6-acp-chat.css

@@ -1181,7 +1181,93 @@
   }
   .rdy-copy:hover { color: var(--fg-0); background: var(--bg-3); }
   .rdy-foot { display: flex; justify-content: flex-end; }
+  /* DDR-166 T0c/T0d — verbatim install command + Sign-in action rows. */
+  .rdy-cmd {
+    margin-top: var(--space-2); display: flex; gap: var(--space-2);
+    align-items: center; flex-wrap: wrap;
+  }
+  .rdy-cmd-tx {
+    font-family: var(--font-mono); font-size: var(--type-xs); color: var(--fg-0);
+    background: var(--bg-3); padding: var(--space-1) var(--space-2);
+    border-radius: var(--radius-xs); overflow-wrap: anywhere; flex: 1 1 auto;
+  }
+  .rdy-fix-tx--err { color: var(--status-error); }
+  .rdy-fallback-label { display: block; margin-top: var(--space-2); color: var(--fg-3); }
+  /* DDR-166 Decision 3 — the resolved-binary disclosure shown before Sign-in. */
+  .rdy-resolved-path { display: block; margin-top: var(--space-2); color: var(--fg-3); word-break: break-all; }
+  .rdy-resolved-path code { font-family: var(--font-mono); color: var(--fg-1); }
+  .rdy-signin {
+    flex-shrink: 0; cursor: pointer;
+    font-size: var(--type-xs); font-weight: 600; color: var(--bg-0);
+    background: var(--accent); border: 1px solid var(--accent);
+    border-radius: var(--radius-xs); padding: 3px 10px;
+  }
+  .rdy-signin:hover { filter: brightness(1.08); }
   /* Help ▸ Check AI editing readiness… modal (reuses .help-modal chrome). */
   .rdy-modal { max-width: 520px; }
   .rdy-modal-note { margin: 0 0 var(--space-3); color: var(--fg-2); font-size: var(--type-sm); line-height: var(--lh-md); }
+  /* DDR-166 Decision 5 — auto-setup opt-out, mirrors .ob-crash-optin. */
+  .rdy-autosetup-toggle { display: flex; align-items: flex-start; gap: var(--space-2); margin-top: var(--space-3); color: var(--fg-2); font-size: var(--type-xs); line-height: var(--lh-md); cursor: pointer; text-align: left; }
+  .rdy-autosetup-toggle input { margin-top: 2px; flex: 0 0 auto; accent-color: var(--accent); cursor: pointer; }
+}
+
+/* DDR-166 plan, Phase 2 (T7/T8) — design-setup checklist (SetupChecklist.jsx).
+   Mirrors .rdy-* above (same present/missing two-state shape, no remediation
+   copy — this probe never offers an automated fix, just progress). */
+@layer components {
+  .setup-cl { display: flex; flex-direction: column; gap: var(--space-3); }
+  .setup-cl-list {
+    list-style: none; margin: 0; padding: 0;
+    display: flex; flex-direction: column; gap: var(--space-2);
+  }
+  .setup-cl-row {
+    display: flex; gap: var(--space-2); align-items: flex-start;
+    padding: var(--space-2) var(--space-3);
+    border: 1px solid var(--border-subtle); border-radius: var(--radius-sm);
+    background: var(--bg-2); text-align: left;
+  }
+  .setup-cl-ic { flex-shrink: 0; margin-top: 1px; }
+  .setup-cl-row--present .setup-cl-ic { color: var(--status-success); }
+  .setup-cl-row--missing .setup-cl-ic { color: var(--fg-3); }
+  .setup-cl-tx { display: flex; flex-direction: column; gap: 2px; min-width: 0; }
+  .setup-cl-label { font-size: var(--type-sm); font-weight: 600; color: var(--fg-0); }
+  .setup-cl-detail { font-size: var(--type-xs); color: var(--fg-2); line-height: var(--lh-xs); }
+  .setup-cl-foot { display: flex; justify-content: flex-end; gap: var(--space-2); flex-wrap: wrap; }
+  .setup-cl-brand { text-decoration: none; }
+  .setup-cl-modal { max-width: 520px; }
+  .setup-cl-note { margin: 0 0 var(--space-3); color: var(--fg-2); font-size: var(--type-sm); line-height: var(--lh-md); }
+}
+
+/* T12 (DDR-173) — the in-app Brand-upload panel (BrandUploadPanel.jsx).
+   Reuses .help-modal-* chrome; new rules cover the pick/result content only. */
+@layer components {
+  .brand-up-modal { max-width: 480px; }
+  .brand-up-note { margin: 0 0 var(--space-4); color: var(--fg-2); font-size: var(--type-sm); line-height: var(--lh-md); }
+  .brand-up-pick { display: flex; justify-content: center; padding: var(--space-5) 0; }
+  .brand-up-error { margin: var(--space-2) 0 0; color: var(--status-error); font-size: var(--type-sm); }
+  .brand-up-empty { margin: 0; color: var(--fg-3); font-size: var(--type-xs); line-height: var(--lh-sm); }
+  .brand-up-preview {
+    display: block; max-width: 100%; max-height: 120px; margin: 0 auto var(--space-4);
+    border: 1px solid var(--border-subtle); border-radius: var(--radius-sm); background: var(--bg-3);
+    padding: var(--space-3);
+  }
+  .brand-up-sechd {
+    margin: var(--space-4) 0 var(--space-2); font-size: var(--type-xs); font-weight: 600;
+    text-transform: uppercase; letter-spacing: var(--tracking-wide); color: var(--fg-2);
+  }
+  .brand-up-swatches { list-style: none; margin: 0; padding: 0; display: flex; flex-wrap: wrap; gap: var(--space-2); }
+  .brand-up-swatch { display: flex; align-items: center; gap: var(--space-2); }
+  .brand-up-swatch-chip {
+    display: inline-block; width: 20px; height: 20px; border-radius: var(--radius-xs);
+    border: 1px solid var(--border-default);
+  }
+  .brand-up-swatch-value { font-family: var(--font-mono); font-size: var(--type-xs); color: var(--fg-2); }
+  .brand-up-fonts { list-style: none; margin: 0; padding: 0; display: flex; flex-wrap: wrap; gap: var(--space-2); }
+  .brand-up-font-chip {
+    padding: 2px var(--space-2); border-radius: var(--radius-pill); border: 1px solid var(--border-default);
+    background: var(--bg-2); font-size: var(--type-xs); color: var(--fg-1);
+  }
+  .brand-up-nextstep { margin: var(--space-4) 0 0; font-size: var(--type-sm); color: var(--fg-1); line-height: var(--lh-md); }
+  .brand-up-nextstep code { font-family: var(--font-mono); background: var(--bg-3); padding: 1px 4px; border-radius: var(--radius-xs); }
+  .brand-up-actions { display: flex; gap: var(--space-2); margin-top: var(--space-3); }
 }

package/apps/studio/client/tour/quick-setup-tour.js

@@ -0,0 +1,39 @@
+// quick-setup-tour.js — DDR-166 plan, Phase 2 (T7). The "empty → design system
+// → first canvas → first AI edit" journey, on the existing tour engine
+// (overlay.jsx), never a fork — same convention as usage-tour.js/collab-tour.js.
+//
+// Native, no-terminal posture (DDR-126/128): this deck can't execute
+// `/design:setup-ds` for the user (the canvas iframe is cross-origin — DDR-054 —
+// and the shell has no terminal). It coach-marks the Assistant panel instead:
+// point at it, tell the user what to type, let THEM send it. The terminal
+// `/design:*` path stays the power-user route.
+
+export const QUICK_SETUP_TOUR = [
+  {
+    // Centered, no target — the overview step.
+    title: "Let's get you set up",
+    body: 'Three short steps: a design system for your brand, a first canvas, then your first AI edit. Everything after this happens right here — no terminal.',
+  },
+  {
+    target: "[data-tour='sidebar']",
+    title: 'Your canvases will live here',
+    body: "Empty for now. Once you have a design system, this fills up with real screens — click any one to open it.",
+    placement: 'right',
+  },
+  {
+    target: "[data-testid='assistant-toggle']",
+    title: 'Ask the Assistant to build your design system',
+    body: 'Open the Assistant and describe your brand — colors, type, the vibe you want. It sets up a real design system for you. Already have one? Say so and it can bring it in.',
+    placement: 'left',
+  },
+  {
+    target: "[data-tour='viewport']",
+    title: 'Your first canvas appears here',
+    body: "Once the design system is ready, ask for a first screen and watch it land right in this space, ready to edit.",
+  },
+  {
+    // Centered — the close-out step.
+    title: "You're ready",
+    body: 'Hold ⌘ and click anything on a canvas to point at it, describe the change in the Assistant, and watch it update live. Restart this tour any time from Help ▸ Quick setup.',
+  },
+];

package/apps/studio/commands/annotation-strokes-command.ts

@@ -27,8 +27,18 @@ import { registerCommand } from '../undo-stack.ts';
  * Push-once callable that submits a full `Stroke[]` to the server (or its
  * test stub) AND updates the iframe's local strokes state. The
  * annotations-layer `putStrokes` is the production binding.
+ *
+ * `before` is the baseline THIS command's `next` was computed from — passed
+ * through so the consumer can distinguish "an id `prev` still has that
+ * `before` already lacked too" (a genuinely concurrent addition, fold it in)
+ * from "an id `before` had that `next` deliberately dropped" (this command's
+ * own delete — must stay dropped even if React's rendered state hasn't
+ * caught up yet). See `reconcileCommit` in annotations-layer.tsx.
  */
-export type StrokesPutFn = (next: readonly Stroke[]) => void | Promise<void>;
+export type StrokesPutFn = (
+  next: readonly Stroke[],
+  before: readonly Stroke[]
+) => void | Promise<void>;
 
 export interface AnnotationStrokesPayload {
   before: readonly Stroke[];
@@ -58,10 +68,10 @@ export function createAnnotationStrokesCommand(init: AnnotationStrokesCommandIni
     kind,
     label,
     async do() {
-      await putFn(after.map(cloneStroke));
+      await putFn(after.map(cloneStroke), before.map(cloneStroke));
     },
     async undo() {
-      await putFn(before.map(cloneStroke));
+      await putFn(before.map(cloneStroke), after.map(cloneStroke));
     },
   };
 }

package/apps/studio/config.schema.json

@@ -231,6 +231,76 @@
         }
       },
       "additionalProperties": false
+    },
+    "generation": {
+      "type": "object",
+      "description": "BYOK AI-media generation preferences (feature-ai-media-generation, DDR-16x). NON-SECRET ONLY — provider API keys are NEVER in this committed config; they live in the OS keychain (native) or ~/.config/maude/keys.json mode 0600 (browser). This block only carries routing/UI preferences. Hot-reloadable — Settings saves take effect without a server restart.",
+      "properties": {
+        "defaultImageProvider": {
+          "type": "string",
+          "description": "Provider id used when an image-generation request leaves the provider unspecified (e.g. 'gemini'). Must be a registered provider that supports the image modality.",
+          "default": "gemini"
+        },
+        "defaultAudioProvider": {
+          "type": "string",
+          "description": "Provider id used when an audio-generation request (music / sfx / voiceover) leaves the provider unspecified. Must be a registered provider that supports the audio modality (v1: 'elevenlabs').",
+          "default": "elevenlabs"
+        },
+        "defaultModels": {
+          "type": "object",
+          "description": "Per-provider default model id (e.g. { \"gemini\": \"gemini-2.5-flash-image\" }). Used when a request leaves the model unspecified.",
+          "additionalProperties": { "type": "string" },
+          "default": {}
+        },
+        "preferLocalWhenAvailable": {
+          "type": "boolean",
+          "description": "When a local runtime (Ollama / ComfyUI / Draw Things, post-v1) is detected on loopback, prefer it over a cloud provider for the same modality (free, offline, private). Inert until local engines ship (Phase 5).",
+          "default": false
+        },
+        "transcription": {
+          "type": "object",
+          "description": "Speech-to-text / subtitle engine preference (Task 2.6, DDR-164). The engine is an EXPLICIT user choice, never an automatic fallback: a chosen-but-unavailable engine errors clearly and Maude never silently switches to another. `maude design transcribe --provider` overrides this per-call.",
+          "properties": {
+            "provider": {
+              "type": "string",
+              "enum": ["whisper", "elevenlabs", "groq"],
+              "description": "Which engine transcribes when no --provider flag is given. `whisper` = local whisper.cpp (free, offline, no key); `elevenlabs` = ElevenLabs Scribe (cloud, key); `groq` = Groq Whisper (cloud, key). Absent ⇒ whisper.",
+              "default": "whisper"
+            },
+            "model": {
+              "type": "string",
+              "description": "Optional engine-specific model id override (e.g. a Groq 'whisper-large-v3-turbo', an ElevenLabs 'scribe_v1', or a local ggml model name). Absent ⇒ the engine's own default."
+            },
+            "whisperModel": {
+              "type": "string",
+              "enum": ["tiny", "base", "base.en", "small", "large-v3-turbo"],
+              "description": "Preferred managed local whisper.cpp model id (Task 2.7). Downloaded via Settings → Subtitles → 'Download model' into a per-machine cache; `maude design transcribe --provider whisper` auto-resolves it (no --model). Absent ⇒ any downloaded multilingual model. 'base' is the recommended default; '.en' variants are English-only."
+            }
+          },
+          "additionalProperties": false
+        },
+        "providers": {
+          "type": "object",
+          "description": "Per-provider non-secret toggles keyed by provider id. `enabled: false` hides a provider from the generate UI even if a key is present. `localEndpoint` overrides the default host:port for a local runtime.",
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "enabled": {
+                "type": "boolean",
+                "description": "Whether this provider is offered in the generate UI. Default true.",
+                "default": true
+              },
+              "localEndpoint": {
+                "type": "string",
+                "description": "Override host:port for a local runtime provider (e.g. '127.0.0.1:11434' for Ollama). Ignored for cloud providers."
+              }
+            },
+            "additionalProperties": false
+          },
+          "default": {}
+        }
+      },
+      "additionalProperties": false
     }
   }
 }

package/apps/studio/context-menu.tsx

@@ -216,10 +216,19 @@ const MENU_CSS = `
   font: inherit;
   color: inherit;
 }
-.dc-context-menu .dc-menu-item:hover,
+.dc-context-menu .dc-menu-item:hover {
+  background: color-mix(in oklab, var(--maude-chrome-fg-0, #1c1917) 8%, transparent);
+}
 .dc-context-menu .dc-menu-item:focus-visible {
+  /* fix-photo-editor-followup-debt Task 16 — was outline: none (an
+     ~1.05:1-contrast, effectively invisible focus ring). Reuses
+     --maude-hud-accent (canvas-lib.tsx's own established focus-visible
+     token for this chrome family — artboard labels, zoom toolbar) rather
+     than inventing a new one; -2px inset offset matches that same
+     convention for a control inside a bordered container. */
   background: color-mix(in oklab, var(--maude-chrome-fg-0, #1c1917) 8%, transparent);
-  outline: none;
+  outline: 2px solid var(--maude-hud-accent, #d63b1f);
+  outline-offset: -2px;
 }
 .dc-context-menu .dc-menu-item[disabled] {
   opacity: 0.45;

package/apps/studio/context.ts

@@ -55,9 +55,25 @@ export interface DevServerConfig {
   newCanvasDir: string;
   newComponentDir: string;
   linkedHub?: LinkedHub;
+  /**
+   * feature-ai-media-generation (DDR-16x) — BYOK generation preferences.
+   * NON-SECRET ONLY: provider keys live in the OS keychain / ~/.config/maude/
+   * keys.json (0600), NEVER here. Hot-reloadable via the full in-place cfg swap
+   * in reloadConfig (only designRoot + linkedHub are boot-pinned). See
+   * config.schema.json for the field contract.
+   */
+  generation?: GenerationConfig;
   _source: ConfigSource;
 }
 
+/** Non-secret AI-media generation preferences (DDR-16x). Keys are NOT here. */
+export interface GenerationConfig {
+  defaultImageProvider?: string;
+  defaultModels?: Record<string, string>;
+  preferLocalWhenAvailable?: boolean;
+  providers?: Record<string, { enabled?: boolean; localEndpoint?: string }>;
+}
+
 const DEFAULT_CONFIG: Omit<DevServerConfig, '_source'> = {
   name: 'Design',
   projectLabel: null,

package/apps/studio/design-setup-readiness.ts

@@ -0,0 +1,115 @@
+// Design-setup readiness probe (DDR-166 plan, Phase 2 / T6). Backs
+// `GET /_api/setup-readiness`.
+//
+// Distinct from readiness.ts (which probes the AI-EDITING dependency chain —
+// claude/maude/plugins on the user's machine). This probes the PROJECT's own
+// setup progress: has it moved past the empty scaffold write_minimal_design()
+// leaves behind, toward a project with a real design system, a first canvas,
+// and brand assets. Read-only, mirrors probeReadiness()'s shape and posture —
+// never installs or mutates anything.
+
+import { existsSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import { findHtmlFiles } from './api.ts';
+import type { Context } from './context.ts';
+
+export type SetupReadinessStatus = 'present' | 'missing';
+
+export interface SetupReadinessItem {
+  id: 'project' | 'design-system' | 'first-canvas' | 'brand-assets';
+  label: string;
+  status: SetupReadinessStatus;
+  detail: string;
+}
+
+export interface SetupReadinessReport {
+  /** True once every item is `present`. */
+  ready: boolean;
+  items: SetupReadinessItem[];
+}
+
+/** True when `dsDirAbs/preview/` has a `logo.*` specimen (DDR-141 Tier-0). */
+function hasLogoSpecimen(dsDirAbs: string): boolean {
+  const previewDir = path.join(dsDirAbs, 'preview');
+  let entries: string[];
+  try {
+    entries = readdirSync(previewDir);
+  } catch {
+    return false;
+  }
+  return entries.some((f) => /^logo\./i.test(f));
+}
+
+/**
+ * Side-effect-free. `ctx.cfg` is already schema-clamped (context.ts
+ * `clampToDesignRoot`), so every `designSystems[].path`/`tokensCssRel` and
+ * `canvasGroups[].path` used here is guaranteed to resolve inside `designRoot`.
+ */
+export async function probeSetupReadiness(ctx: Context): Promise<SetupReadinessReport> {
+  const { cfg, paths } = ctx;
+  const items: SetupReadinessItem[] = [];
+
+  // A real, on-disk `.design/config.json` (vs. the in-memory defaults fallback
+  // `createContext()` uses when the file is missing/invalid) — the signal that
+  // this is a genuinely-initialized project, not just the Rust
+  // write_minimal_design() scaffold rendering an empty shell.
+  const hasRealConfig = cfg._source === '.design/config.json';
+  items.push({
+    id: 'project',
+    label: 'Project set up',
+    status: hasRealConfig ? 'present' : 'missing',
+    detail: hasRealConfig
+      ? `“${cfg.name}” — a real .design/config.json is on disk.`
+      : 'No .design/config.json yet — this is the empty starter scaffold.',
+  });
+
+  const designSystems = cfg.designSystems ?? [];
+  const dsWithTokens = designSystems.find((ds) => {
+    const rel = ds.tokensCssRel ?? path.posix.join(ds.path, 'colors_and_type.css');
+    return existsSync(path.join(paths.designRoot, rel));
+  });
+  items.push({
+    id: 'design-system',
+    label: 'Design system',
+    status: dsWithTokens ? 'present' : 'missing',
+    detail: dsWithTokens
+      ? `“${dsWithTokens.name}” — tokens are on disk.`
+      : designSystems.length
+        ? 'Declared in config, but the tokens file is missing.'
+        : 'None yet — ask the Assistant to set one up, or bring your own brand.',
+  });
+
+  // Any real canvas outside the DS specimen groups (canvasGroups whose path
+  // matches /system/i are DS preview specimens, not user canvases).
+  const canvasGroups = (cfg.canvasGroups ?? []).filter((g) => !/system/i.test(g.path));
+  let firstCanvas: string | null = null;
+  for (const g of canvasGroups) {
+    const groupAbs = path.join(paths.designRoot, g.path);
+    const groupRel = path.posix.join(paths.designRel, g.path);
+    const files = await findHtmlFiles(groupAbs, groupRel);
+    if (files.length) {
+      firstCanvas = files[0];
+      break;
+    }
+  }
+  items.push({
+    id: 'first-canvas',
+    label: 'First canvas',
+    status: firstCanvas ? 'present' : 'missing',
+    detail: firstCanvas ? `${path.basename(firstCanvas)} is open for editing.` : 'No canvas yet.',
+  });
+
+  const dsWithLogo = designSystems.find((ds) =>
+    hasLogoSpecimen(path.join(paths.designRoot, ds.path))
+  );
+  items.push({
+    id: 'brand-assets',
+    label: 'Brand assets',
+    status: dsWithLogo ? 'present' : 'missing',
+    detail: dsWithLogo
+      ? `“${dsWithLogo.name}” has a stored logo specimen.`
+      : 'No logo/brand specimen on file yet.',
+  });
+
+  return { ready: items.every((i) => i.status === 'present'), items };
+}