@1agh/maude 0.55.0 → 0.56.0

package/apps/studio/client/panels/GitPanel.jsx

@@ -155,8 +155,19 @@ export default function GitPanel({
   // checkboxes) — the developer commits and pushes from their terminal
   // (DDR-119). Native app keeps the full plain-words cycle.
   readOnly = false,
+  // THE SERVER ALREADY COMMITTED IT. In a cloud cell the hub owns this
+  // project's history and commits every edit as it lands (the studio child's
+  // own autocommit is disabled precisely so there is one committer) — so an
+  // "unsaved changes" list is not a to-do, it is a lie about work that is
+  // already saved, and Save / Publish offer to do a thing that has happened.
+  // The read-only variant of this panel used to answer that with "save and
+  // publish from your terminal", which is advice a browser user cannot take.
+  //
+  // History STAYS, and is the point: what the server committed is exactly what
+  // someone wants to look back at. Only the working-tree half goes.
+  historyOnly = false,
 }) {
-  const [tab, setTab] = useState('changes');
+  const [tab, setTab] = useState(historyOnly ? 'history' : 'changes');
   const [message, setMessage] = useState('');
   const [unchecked, setUnchecked] = useState(() => new Set()); // default = all checked
   const [expanded, setExpanded] = useState(() => new Set()); // unit keys with supporting files shown
@@ -443,13 +454,13 @@ export default function GitPanel({
     <aside
       className={'st-rpanel gp-panel' + (resizing ? ' is-resizing' : '')}
       style={width ? { width, flexBasis: width } : undefined}
-      aria-label="Changes"
+      aria-label={historyOnly ? 'History' : 'Changes'}
       data-testid="git-panel"
     >
       <div className="gp-head">
         <div className="gp-panel-hd">
-          <span className="gp-panel-title">Changes</span>
-          {count > 0 && <span className="gp-count">{count} unsaved</span>}
+          <span className="gp-panel-title">{historyOnly ? 'History' : 'Changes'}</span>
+          {!historyOnly && count > 0 && <span className="gp-count">{count} unsaved</span>}
           <span className="gp-spacer" />
           <span className="gp-draft" title="Your project and shared draft">
             <Icon name="folder" size={12} />
@@ -465,26 +476,28 @@ export default function GitPanel({
             ×
           </button>
         </div>
-        <div className="gp-tabs" role="tablist" aria-label="Changes and history">
-          <button
-            type="button"
-            role="tab"
-            aria-selected={tab === 'changes'}
-            className={'gp-tab' + (tab === 'changes' ? ' is-active' : '')}
-            onClick={() => setTab('changes')}
-          >
-            Changes
-          </button>
-          <button
-            type="button"
-            role="tab"
-            aria-selected={tab === 'history'}
-            className={'gp-tab' + (tab === 'history' ? ' is-active' : '')}
-            onClick={openHistory}
-          >
-            History
-          </button>
-        </div>
+        {!historyOnly && (
+          <div className="gp-tabs" role="tablist" aria-label="Changes and history">
+            <button
+              type="button"
+              role="tab"
+              aria-selected={tab === 'changes'}
+              className={'gp-tab' + (tab === 'changes' ? ' is-active' : '')}
+              onClick={() => setTab('changes')}
+            >
+              Changes
+            </button>
+            <button
+              type="button"
+              role="tab"
+              aria-selected={tab === 'history'}
+              className={'gp-tab' + (tab === 'history' ? ' is-active' : '')}
+              onClick={openHistory}
+            >
+              History
+            </button>
+          </div>
+        )}
       </div>
 
       {banner && (
@@ -530,7 +543,7 @@ export default function GitPanel({
         </div>
       )}
 
-      {tab === 'changes' ? (
+      {tab === 'changes' && !historyOnly ? (
         notRepo ? (
           <div className="gp-empty">
             <span className="gp-empty-glyph">

package/apps/studio/client/panels/SettingsPanel.jsx

@@ -170,6 +170,11 @@ function ProviderCard({ provider, onChanged }) {
 // default. Local whisper is free/offline/no-key; the cloud engines need a key
 // (managed in the provider cards above).
 const TRANSCRIPTION_ENGINES = [
+  {
+    id: 'auto',
+    label: 'Auto',
+    note: 'Use the best engine this machine is set up for — the card says which.',
+  },
   {
     id: 'whisper',
     label: 'Local whisper.cpp',
@@ -183,10 +188,15 @@ const TRANSCRIPTION_ENGINES = [
   { id: 'groq', label: 'Groq Whisper', note: 'Cloud · fast · needs a Groq key' },
 ];
 
+const ENGINE_LABELS = Object.fromEntries(TRANSCRIPTION_ENGINES.map((e) => [e.id, e.label]));
+
 function TranscriptionEngineCard() {
   const [engine, setEngine] = useState(null); // null = loading
   const [busy, setBusy] = useState(false);
   const [status, setStatus] = useState(null);
+  // What `auto` currently resolves to, from the server (key presence lives in
+  // the keychain). Shown verbatim so a delegated choice is still a visible one.
+  const [auto, setAuto] = useState(null);
 
   useEffect(() => {
     fetch('/_api/generate/prefs')
@@ -195,6 +205,15 @@ function TranscriptionEngineCard() {
       .catch(() => setEngine('whisper'));
   }, []);
 
+  // Re-read on every selection change: adding a key elsewhere in Settings moves
+  // what Auto resolves to, and the user should see that immediately.
+  useEffect(() => {
+    fetch('/_api/generate/whisper-model')
+      .then((r) => (r.ok ? r.json() : null))
+      .then((d) => setAuto(d?.auto || null))
+      .catch(() => {});
+  }, []);
+
   async function choose(id) {
     if (id === engine) return;
     const prev = engine;
@@ -223,9 +242,16 @@ function TranscriptionEngineCard() {
         <span className="st-provider-name">Subtitles — transcription engine</span>
       </div>
       <div className="st-provider-notes">
-        Which engine turns audio into subtitles. This is an explicit choice — Maude never silently
-        switches engines; a chosen-but-unavailable engine tells you how to fix it.
+        Which engine turns audio into subtitles. Maude never switches engines behind your back — pin
+        one, or pick <strong>Auto</strong> and it uses the best you're set up for and says so.
       </div>
+      {engine === 'auto' && auto && (
+        <div className="st-provider-notes">
+          Right now Auto uses <strong>{ENGINE_LABELS[auto.engine] || auto.engine}</strong> —{' '}
+          {auto.reason}
+          {auto.cloud && ' Audio is uploaded to that provider and billed to your account.'}
+        </div>
+      )}
       <div className="st-engine-radios" role="radiogroup" aria-label="Transcription engine">
         {TRANSCRIPTION_ENGINES.map((e) => (
           <label key={e.id} className={'st-engine-radio' + (engine === e.id ? ' is-selected' : '')}>
@@ -314,6 +340,7 @@ function WhisperModelCard() {
 
   const dl = state?.downloading;
   const pctOf = (r, t) => (t > 0 ? Math.min(100, Math.round((r / t) * 100)) : 0);
+  const modelsReady = (state?.models || []).some((m) => m.downloaded);
 
   return (
     <div className="st-provider-card">
@@ -321,10 +348,58 @@ function WhisperModelCard() {
         <span className="st-provider-name">Local subtitle models (whisper.cpp)</span>
       </div>
       <div className="st-provider-notes">
-        Download a model once and local subtitles work offline, free, with no key. Requires the
-        whisper.cpp binary (<code>brew install whisper-cpp</code>). Models are stored on this machine
-        only and never committed.
+        Local subtitles need two things: the whisper.cpp engine and one model. Models are stored on
+        this machine only and never committed.
       </div>
+      {state && (
+        <div className="st-setup">
+          <div className={`st-step${state.setup?.installed ? ' is-done' : ''}`}>
+            <span className="st-step-n">{state.setup?.installed ? '✓' : '1'}</span>
+            <div className="st-step-body">
+              <span className="st-step-title">
+                {state.setup?.installed
+                  ? 'whisper.cpp engine is installed'
+                  : 'Install the whisper.cpp engine'}
+              </span>
+              {/* Only routes that work on THIS machine — no `brew install`
+                  without Homebrew. whisper.cpp ships no macOS prebuilt, so the
+                  brew-less answer is a cloud engine or a source build. */}
+              {(state.setup?.options || []).slice(0, 1).map((opt) =>
+                opt.kind === 'command' ? (
+                  <CopyCommand key={opt.id} command={opt.command} label={`Copy: ${opt.label}`} />
+                ) : (
+                  <span key={opt.id} className="st-provider-notes">
+                    {opt.note}
+                  </span>
+                )
+              )}
+            </div>
+          </div>
+          <div className={`st-step${modelsReady ? ' is-done' : ''}`}>
+            <span className="st-step-n">{modelsReady ? '✓' : '2'}</span>
+            <div className="st-step-body">
+              <span className="st-step-title">
+                {modelsReady ? 'Model ready' : 'Download a model (below)'}
+              </span>
+            </div>
+          </div>
+          {(state.setup?.options || []).length > 1 && (
+            <details className="st-setup-more">
+              <summary>Other ways to get the engine</summary>
+              {state.setup.options.slice(1).map((opt) => (
+                <div key={opt.id} className="st-setup-option">
+                  <span className="st-setup-option-label">{opt.label}</span>
+                  <CopyCommand
+                    command={opt.kind === 'command' ? opt.command : opt.url}
+                    label={`Copy: ${opt.label}`}
+                  />
+                  {opt.note ? <span className="st-provider-notes">{opt.note}</span> : null}
+                </div>
+              ))}
+            </details>
+          )}
+        </div>
+      )}
       {err && (
         <div className="st-provider-status" style={{ color: 'var(--danger, #e5484d)' }}>
           {err}
@@ -389,7 +464,7 @@ function WhisperModelCard() {
 // sibling of the Subtitles section. Persists `keyframeEngine` to /_api/generate/prefs.
 const KEYFRAME_ENGINES = [
   { id: 'auto', label: 'Auto', note: 'Use the best available: Gemma scout → ffmpeg → blind.' },
-  { id: 'gemma', label: 'Gemma scout', note: 'Semantic action beats. Needs Apple Silicon + mlx-vlm + a model.' },
+  { id: 'gemma', label: 'Gemma scout', note: 'Semantic action beats. Needs Ollama (gemma3 vision) or mlx-vlm + a model.' },
   { id: 'ffmpeg', label: 'ffmpeg scene-detect', note: 'Scene cuts + endpoints. Needs ffmpeg. No model download.' },
   { id: 'blind', label: 'Blind (even-spaced)', note: 'Chromium fallback — works with neither ffmpeg nor Gemma.' },
 ];
@@ -468,11 +543,115 @@ function KeyframeEngineCard() {
   );
 }
 
+// A copy/paste terminal command with a Copy button (same look as the ACP
+// readiness rows — the rdy-* classes are global in the bundled stylesheet).
+function CopyCommand({ command, label }) {
+  const [copied, setCopied] = useState(false);
+  const copy = () => {
+    navigator.clipboard?.writeText(command).then(
+      () => {
+        setCopied(true);
+        setTimeout(() => setCopied(false), 1500);
+      },
+      () => {}
+    );
+  };
+  return (
+    <span className="rdy-cmd">
+      <code className="rdy-cmd-tx">{command}</code>
+      <button type="button" className="rdy-copy" onClick={copy} aria-label={label || 'Copy command'}>
+        {copied ? 'Copied' : 'Copy'}
+      </button>
+    </span>
+  );
+}
+
+// The setup path, as STEPS rather than a wall of options. Only the shortest
+// route is visible (install → pull); everything else — Homebrew, the download
+// link, the whole mlx-vlm alternative — sits folded behind one disclosure, so a
+// first-time reader sees two commands, not seven.
+function SetupSteps({ state }) {
+  const ollama = state.ollama || {};
+  const setup = ollama.setup || [];
+  // The server orders routes best-first, so the head is the one step to take now
+  // ("install", or "start" when the binary is already there). Everything after
+  // it is an alternative way to reach the same place.
+  const [primary, ...alternatives] = setup;
+  const step1Done = Boolean(ollama.available);
+  const step2Done = Boolean(ollama.model);
+  // Once Ollama is running, its own route list collapses to the pull command —
+  // which IS step 2, so it must not also render as step 1.
+  const step1 = step1Done || primary?.id === 'pull' ? null : primary;
+
+  return (
+    <div className="st-setup">
+      <div className={`st-step${step1Done ? ' is-done' : ''}`}>
+        <span className="st-step-n">{step1Done ? '✓' : '1'}</span>
+        <div className="st-step-body">
+          <span className="st-step-title">
+            {step1Done
+              ? 'Ollama is running'
+              : ollama.installed
+                ? 'Start Ollama'
+                : 'Install Ollama'}
+          </span>
+          {step1?.kind === 'command' ? (
+            <CopyCommand command={step1.command} label="Copy the install command" />
+          ) : null}
+        </div>
+      </div>
+      <div className={`st-step${step2Done ? ' is-done' : ''}`}>
+        <span className="st-step-n">{step2Done ? '✓' : '2'}</span>
+        <div className="st-step-body">
+          <span className="st-step-title">
+            {step2Done ? `Model ready (${ollama.model})` : 'Download the model'}
+          </span>
+          {step2Done ? null : (
+            <CopyCommand command={ollama.pullCommand} label="Copy the model pull command" />
+          )}
+        </div>
+      </div>
+      <details className="st-setup-more">
+        <summary>Other ways to install</summary>
+        {alternatives.map((opt) => (
+          <div key={opt.id} className="st-setup-option">
+            <span className="st-setup-option-label">{opt.label}</span>
+            {/* A link is rendered as a copyable URL, not a button: the desktop
+                shell has no general URL opener by design (DDR-054). */}
+            <CopyCommand
+              command={opt.kind === 'command' ? opt.command : opt.url}
+              label={`Copy: ${opt.label}`}
+            />
+          </div>
+        ))}
+        <div className="st-setup-option">
+          <span className="st-setup-option-label">
+            mlx-vlm instead of Ollama — faster, Apple Silicon only
+          </span>
+          {state.mlx?.supported ? (
+            <>
+              <CopyCommand command={state.mlx.command} label="Copy the mlx-vlm install command" />
+              <span className="st-provider-notes">
+                Then download a model below. Models live in your HuggingFace cache.
+              </span>
+            </>
+          ) : (
+            // Never show a command that would fail here — say why instead.
+            <span className="st-provider-notes">{state.mlx?.reason}</span>
+          )}
+        </div>
+      </details>
+    </div>
+  );
+}
+
 // The MODEL half of the Gemma scout — one click, mirroring WhisperModelCard. The
-// RUNTIME (mlx-vlm) is a manual `pip install` the app can't do, so the download is
-// gated on mlxVlmAvailable and the card says which tier will actually run.
+// RUNTIME is a manual install the app can't do for you (DDR-183), but the card
+// hands you copy/paste commands for BOTH runtime paths — Ollama (simplest: one
+// app, `ollama pull`, no Python) and mlx-vlm (fastest, the benchmarked path) —
+// and re-probes on its own, so the card unlocks itself once you've run one.
 function GemmaModelCard() {
-  const [state, setState] = useState(null); // { models, downloading, mlxVlmAvailable, ffmpegAvailable }
+  const [state, setState] = useState(null); // { models, downloading, mlxVlmAvailable, ffmpegAvailable, installCommand, ollama }
   const [err, setErr] = useState(null);
 
   const load = useCallback(() => {
@@ -492,6 +671,16 @@ function GemmaModelCard() {
     return () => clearInterval(t);
   }, [state?.downloading, load]);
 
+  // No scout runtime yet → the user is likely running one of the install
+  // commands in a terminal right now. Re-probe every 10 s (server-side the
+  // probes are TTL-cached) so the card unlocks itself without a reopen.
+  const noRuntime = state ? !state.mlxVlmAvailable && !state.ollama?.model : false;
+  useEffect(() => {
+    if (!noRuntime) return undefined;
+    const t = setInterval(load, 10_000);
+    return () => clearInterval(t);
+  }, [noRuntime, load]);
+
   async function download(id) {
     setErr(null);
     try {
@@ -510,8 +699,14 @@ function GemmaModelCard() {
   const dl = state?.downloading;
   const mlx = state?.mlxVlmAvailable;
   const ff = state?.ffmpegAvailable;
+  const ollama = state?.ollama;
+  const scoutReady = Boolean(mlx || ollama?.model);
   const pctOf = (r, t) => (t > 0 ? Math.min(100, Math.round((r / t) * 100)) : 0);
-  const activeTier = mlx ? 'Gemma scout' : ff ? 'ffmpeg scene-detect' : 'blind (even-spaced)';
+  const activeTier = scoutReady
+    ? `Gemma scout${mlx ? '' : ` (Ollama · ${ollama.model})`}`
+    : ff
+      ? 'ffmpeg scene-detect'
+      : 'blind (even-spaced)';
 
   return (
     <div className="st-provider-card">
@@ -519,16 +714,14 @@ function GemmaModelCard() {
         <span className="st-provider-name">Gemma scout model (optional)</span>
       </div>
       <div className="st-provider-notes">
-        The <strong>Gemma</strong> tier adds semantic action-beat detection on top of scene cuts. It
-        needs an <strong>Apple-Silicon Mac</strong> and the <code>mlx-vlm</code> runtime
-        (<code>pip install mlx-vlm</code> — a manual step Maude can’t do for you). Downloading a model
-        below is the one-click half. Models live in your HuggingFace cache, never committed.
+        Adds semantic action-beat detection on top of scene cuts. Two short steps in a terminal —
+        Maude picks the result up on its own.
       </div>
+      {state && !scoutReady && <SetupSteps state={state} />}
       {state && (
         <div className="st-provider-notes">
-          On this machine the active tier is <strong>{activeTier}</strong>
-          {!mlx && ff && ' — install mlx-vlm + download a model to unlock the Gemma scout.'}
-          {!mlx && !ff && ' — install ffmpeg for scene-aware frames, or mlx-vlm for the Gemma scout.'}
+          Active tier on this machine: <strong>{activeTier}</strong>
+          {scoutReady && !mlx && ' — Ollama manages its own models, nothing to download below.'}
         </div>
       )}
       {err && (
@@ -545,6 +738,13 @@ function GemmaModelCard() {
       <div className="st-model-list">
         {(state?.models || []).map((m) => {
           const busy = dl && !dl.error && dl.id === m.id;
+          const runtimeReady = m.runtime === 'ollama' ? Boolean(ollama?.available) : Boolean(mlx);
+          const blockedNote =
+            m.runtime === 'ollama'
+              ? ollama?.installed
+                ? 'start Ollama first'
+                : 'needs Ollama'
+              : 'needs mlx-vlm';
           return (
             <div key={m.id} className="st-model-row">
               <div className="st-model-info">
@@ -554,7 +754,10 @@ function GemmaModelCard() {
                 </span>
                 <span className="st-engine-radio-note">{m.note}</span>
                 {busy && (
-                  <span className="st-model-progress">Downloading… {pctOf(dl.received, dl.total)}%</span>
+                  <span className="st-model-progress">
+                    {m.runtime === 'ollama' ? 'Pulling' : 'Downloading'}…{' '}
+                    {pctOf(dl.received, dl.total)}%
+                  </span>
                 )}
               </div>
               <div className="st-model-actions">
@@ -563,15 +766,24 @@ function GemmaModelCard() {
                     <Icon name="check" size={12} /> ready
                   </span>
                 ) : (
-                  <button
-                    type="button"
-                    className="st-btn"
-                    disabled={!mlx || !!(dl && !dl.error)}
-                    title={mlx ? '' : 'Install mlx-vlm first (pip install mlx-vlm)'}
-                    onClick={() => download(m.id)}
-                  >
-                    {busy ? 'Downloading…' : mlx ? 'Download' : 'Needs mlx-vlm'}
-                  </button>
+                  // Each row is enabled by ITS OWN runtime — an Ollama model is
+                  // one click whenever Ollama is running (the server pulls it
+                  // through /api/pull); an mlx snapshot needs mlx-vlm. The
+                  // button keeps its label and just goes disabled, with the
+                  // reason in small type underneath.
+                  <span className="st-model-action">
+                    <button
+                      type="button"
+                      className="st-btn"
+                      disabled={!runtimeReady || !!(dl && !dl.error)}
+                      onClick={() => download(m.id)}
+                    >
+                      {busy ? 'Downloading…' : 'Download'}
+                    </button>
+                    {runtimeReady ? null : (
+                      <span className="st-model-action-note">{blockedNote}</span>
+                    )}
+                  </span>
                 )}
               </div>
             </div>

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

@@ -1725,6 +1725,65 @@
   line-height: 1.5;
   margin-top: 6px;
 }
+/* Scout setup (feature-scene-aware-keyframes) — the shortest path as numbered
+   steps; every alternative route folds behind one disclosure so the default
+   view is two commands, not seven. */
+.st-setup {
+  margin-top: 8px;
+}
+.st-step {
+  display: flex;
+  gap: 8px;
+  align-items: flex-start;
+  margin-top: 8px;
+}
+.st-step-n {
+  flex-shrink: 0;
+  width: 18px;
+  height: 18px;
+  border-radius: 50%;
+  border: 1px solid var(--border-subtle);
+  color: var(--fg-2);
+  font-size: 10px;
+  line-height: 16px;
+  text-align: center;
+}
+.st-step.is-done .st-step-n {
+  border-color: var(--accent);
+  color: var(--accent);
+}
+.st-step-body {
+  min-width: 0;
+  flex: 1 1 auto;
+}
+.st-step-title {
+  display: block;
+  font-size: 11px;
+  color: var(--fg-1);
+}
+.st-step.is-done .st-step-title {
+  color: var(--fg-3);
+}
+.st-setup-more {
+  margin-top: 10px;
+}
+.st-setup-more > summary {
+  cursor: pointer;
+  font-size: 11px;
+  color: var(--fg-3);
+}
+.st-setup-more > summary:hover {
+  color: var(--fg-1);
+}
+.st-setup-option {
+  display: block;
+  margin-top: 8px;
+}
+.st-setup-option-label {
+  display: block;
+  font-size: 11px;
+  color: var(--fg-2);
+}
 .st-provider-keylink {
   display: inline-flex;
   align-items: center;
@@ -1840,6 +1899,19 @@
   gap: 8px;
   flex-shrink: 0;
 }
+/* A disabled action plus the reason it's disabled, in small type underneath —
+   so the button label stays the action, not the explanation. */
+.st-model-action {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-end;
+  gap: 3px;
+}
+.st-model-action-note {
+  font-size: 10px;
+  color: var(--fg-3);
+  text-align: right;
+}
 
 /* ── Generate dialog (feature-ai-media-generation, DDR-16x) ─────────────── */
 .st-gen-prompt {

package/apps/studio/cloud/endpoints.ts

@@ -109,6 +109,19 @@ async function cloudFetch(
 
 interface Ctx {
   paths: { repoRoot: string; designRoot: string };
+  /**
+   * The live sync runtime's owner (server.ts → sync/supervisor.ts). Optional:
+   * unit tests and any non-serving embedder construct a Ctx without one, and a
+   * missing supervisor degrades to exactly the old behaviour — linked on disk,
+   * syncing after the next start.
+   */
+  syncControl?: {
+    restart(linkedHub?: {
+      url: string;
+      linkedAt: number;
+      syncTsx?: boolean;
+    }): Promise<{ syncing: boolean; canvases: number; reason?: string; detail?: string }>;
+  };
 }
 
 export function createCloudEndpoints(ctx: Ctx) {
@@ -225,7 +238,9 @@ export function createCloudEndpoints(ctx: Ctx) {
     /**
      * Attach THIS project to a cloud workspace: open → exchange at the cell →
      * store the hub credential + linkedHub, exactly as `maude design link`
-     * would. The sync agent picks the link up on the next server start.
+     * would — and then START SYNCING (linkToWorkspace cycles the live runtime
+     * through ctx.syncControl). Connecting is the whole gesture; there is no
+     * second step for the person to discover.
      */
     async attach(projectId: string): Promise<CloudEndpointResult> {
       const file = readCloudFile();
@@ -380,9 +395,42 @@ export function createCloudEndpoints(ctx: Ctx) {
     } catch {
       /* absent/malformed → start minimal */
     }
-    cfg.linkedHub = { url: norm, linkedAt: Date.now() };
+    const linkedHub: { url: string; linkedAt: number; syncTsx?: boolean } = {
+      url: norm,
+      linkedAt: Date.now(),
+    };
+    // Carry a project-wide TSX opt-out across the re-link. Only the RESTRICTIVE
+    // direction is carried (`false`, never `true`): somebody who turned canvas
+    // BODIES off (DDR-072/DDR-079) did so deliberately, and silently re-enabling
+    // them on the next Connect would start uploading source they opted out of.
+    // It never mattered while nothing synced until a restart; it does now.
+    const prior = (cfg as { linkedHub?: { syncTsx?: boolean } }).linkedHub;
+    if (prior?.syncTsx === false) linkedHub.syncTsx = false;
+    cfg.linkedHub = linkedHub;
     writeFileSync(cfgPath, `${JSON.stringify(cfg, null, 2)}\n`, 'utf8');
 
+    // START SYNCING — do not hand the person a "restart the server" note and
+    // call the job done. The runtime captures linkedHub once at boot, so this
+    // cycles it in place, with the value we JUST wrote (never re-read from the
+    // committed config file). Best-effort: a supervisor-less embedder, or a
+    // runtime that declines, still leaves a correctly linked project behind.
+    let sync: { syncing: boolean; canvases: number; reason?: string; detail?: string } = {
+      syncing: false,
+      canvases: 0,
+      reason: 'no-supervisor',
+      detail: 'Restart Maude to start syncing.',
+    };
+    try {
+      sync = (await ctx.syncControl?.restart(linkedHub)) ?? sync;
+    } catch (err) {
+      sync = {
+        syncing: false,
+        canvases: 0,
+        reason: 'error',
+        detail: `Linked, but syncing could not start: ${(err as Error).message}`,
+      };
+    }
+
     return {
       status: 200,
       json: {
@@ -390,7 +438,12 @@ export function createCloudEndpoints(ctx: Ctx) {
         url: norm,
         role: role ?? null,
         project: project ?? null,
-        note: 'Linked. Restart the studio server to start syncing.',
+        sync,
+        // Kept for older clients (and the CLI) that read `note` — now it
+        // reports what actually happened instead of assigning homework.
+        note: sync.syncing
+          ? `Linked — syncing ${sync.canvases} canvas${sync.canvases === 1 ? '' : 'es'}.`
+          : `Linked. ${sync.detail ?? 'Restart Maude to start syncing.'}`,
       },
     };
   }