@1agh/maude 0.55.0 → 0.57.0

package/apps/studio/test/sync-supervisor.test.ts

@@ -0,0 +1,212 @@
+// The sync supervisor — the piece that makes "Connect" mean "syncing", not
+// "now go restart something".
+//
+// The runtime itself is injected here (a fake factory): what is under test is
+// the SUPERVISION — that a just-authorized link is adopted in memory and
+// applied by a real stop→start cycle, that two Connects can't interleave, and
+// that a refusal comes back as a sentence a person can act on instead of a
+// silent null.
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import * as Y from 'yjs';
+
+import { type Context, createBus, type DevServerConfig } from '../context.ts';
+import type { SyncProvider, SyncRuntime } from '../sync/index.ts';
+import { createSyncSupervisor } from '../sync/supervisor.ts';
+
+let hubsEnv: string | undefined;
+
+beforeEach(() => {
+  hubsEnv = process.env.HUBS_CONFIG_PATH;
+});
+
+afterEach(() => {
+  // Assigning undefined would store the literal string "undefined".
+  if (hubsEnv === undefined) delete process.env.HUBS_CONFIG_PATH;
+  else process.env.HUBS_CONFIG_PATH = hubsEnv;
+});
+
+function makeCtx(linkedHub?: DevServerConfig['linkedHub']): Context {
+  const dir = mkdtempSync(join(tmpdir(), 'sync-supervisor-'));
+  const designRoot = join(dir, '.design');
+  return {
+    cfg: {
+      name: 'test',
+      projectLabel: null,
+      designRoot: '.design',
+      canvasGroups: [{ label: 'Canvases', path: 'ui' }],
+      rootClass: 'app',
+      themeDefault: 'dark',
+      tokensCssRel: 'system/colors.css',
+      teamAccentDefault: null,
+      handoffTargets: [],
+      newCanvasDir: 'ui',
+      newComponentDir: 'ui/components',
+      linkedHub,
+      _source: 'defaults',
+    },
+    projectLabel: 'test',
+    paths: {
+      repoRoot: dir,
+      designRel: '.design',
+      designRoot,
+      serverInfoFile: join(designRoot, '_server.json'),
+      activeFile: join(designRoot, '_active.json'),
+      commentsDir: join(designRoot, '_comments'),
+      canvasStateDir: join(designRoot, '_canvas-state'),
+      historyDir: join(designRoot, '_history'),
+      tokensUrlRel: '.design/system/colors.css',
+      systemDirRel: 'system',
+    },
+    bus: createBus(),
+  };
+}
+
+/** A runtime that records its lifecycle and reports `size` canvases. */
+function fakeRuntime(log: string[], id: string, size = 3): SyncRuntime {
+  return {
+    start: async () => {
+      log.push(`start:${id}`);
+    },
+    stop: async () => {
+      log.push(`stop:${id}`);
+    },
+    size: () => size,
+    agentFor: () => undefined,
+    status: () => null,
+  };
+}
+
+describe('createSyncSupervisor', () => {
+  test('an unlinked project starts nothing and says so in words', async () => {
+    const ctx = makeCtx();
+    const sup = createSyncSupervisor(ctx, {}, () => null);
+    const out = await sup.start();
+    expect(out.syncing).toBe(false);
+    expect(out.reason).toBe('unlinked');
+    expect(out.detail).toMatch(/not linked/i);
+    expect(sup.current()).toBeNull();
+    rmSync(ctx.paths.repoRoot, { recursive: true, force: true });
+  });
+
+  test('restart adopts the link it is HANDED and cycles the runtime', async () => {
+    const ctx = makeCtx();
+    const log: string[] = [];
+    let n = 0;
+    const sup = createSyncSupervisor(ctx, {}, (c) =>
+      c.cfg.linkedHub ? fakeRuntime(log, `r${++n}`) : null
+    );
+
+    // Boot unlinked — solo mode, exactly as before.
+    expect((await sup.start()).syncing).toBe(false);
+    expect(log).toEqual([]);
+
+    // The attach lane hands the value it just wrote; the supervisor adopts it
+    // (never re-reading the committed config file) and starts syncing.
+    const link = { url: 'https://hub.example', linkedAt: 1, syncTsx: false };
+    const out = await sup.restart(link);
+    expect(out).toEqual({ syncing: true, canvases: 3 });
+    expect(ctx.cfg.linkedHub).toEqual(link);
+    expect(log).toEqual(['start:r1']);
+
+    // A second Connect tears the first runtime down before opening the next.
+    await sup.restart({ url: 'https://other.example', linkedAt: 2 });
+    expect(log).toEqual(['start:r1', 'stop:r1', 'start:r2']);
+    expect(ctx.cfg.linkedHub?.url).toBe('https://other.example');
+    rmSync(ctx.paths.repoRoot, { recursive: true, force: true });
+  });
+
+  test('two Connects in flight at once do not interleave stop with start', async () => {
+    const ctx = makeCtx({ url: 'https://hub.example', linkedAt: 1 });
+    const log: string[] = [];
+    let n = 0;
+    const sup = createSyncSupervisor(ctx, {}, () => fakeRuntime(log, `r${++n}`));
+    await sup.start();
+    await Promise.all([
+      sup.restart({ url: 'https://a.example', linkedAt: 2 }),
+      sup.restart({ url: 'https://b.example', linkedAt: 3 }),
+    ]);
+    expect(log).toEqual(['start:r1', 'stop:r1', 'start:r2', 'stop:r2', 'start:r3']);
+    rmSync(ctx.paths.repoRoot, { recursive: true, force: true });
+  });
+
+  test('linked but zero syncable canvases is reported, not mistaken for syncing', async () => {
+    const ctx = makeCtx({ url: 'https://hub.example', linkedAt: 1 });
+    const log: string[] = [];
+    const empty: SyncRuntime = {
+      ...fakeRuntime(log, 'empty', 0),
+      status: () => ({ reason: 'no canvases found under .design' }) as never,
+    };
+    const sup = createSyncSupervisor(ctx, {}, () => empty);
+    const out = await sup.start();
+    expect(out.syncing).toBe(false);
+    expect(out.reason).toBe('nothing-syncable');
+    // The runtime already wrote the full explanation into _sync.json — the
+    // panel repeats THAT, so the two can never drift apart.
+    expect(out.detail).toBe('no canvases found under .design');
+    rmSync(ctx.paths.repoRoot, { recursive: true, force: true });
+  });
+
+  test('END TO END with the REAL runtime: an unlinked server starts syncing on Connect', async () => {
+    // No fake runtime here — this is the actual `createSyncRuntime`, reached
+    // exactly as the attach lane reaches it: the server booted solo (no
+    // linkedHub anywhere), and one restart() with the value the cloud endpoint
+    // just wrote turns the project into a syncing one, in place.
+    const ctx = makeCtx();
+    mkdirSync(join(ctx.paths.designRoot, 'ui'), { recursive: true });
+    mkdirSync(ctx.paths.commentsDir, { recursive: true });
+    writeFileSync(join(ctx.paths.designRoot, 'ui', 'home.html'), '<main>home</main>');
+    writeFileSync(join(ctx.paths.designRoot, 'ui', 'pricing.html'), '<main>pricing</main>');
+
+    const url = 'https://hub.example.com';
+    process.env.HUBS_CONFIG_PATH = join(ctx.paths.repoRoot, 'hubs.json');
+    writeFileSync(
+      process.env.HUBS_CONFIG_PATH,
+      JSON.stringify({ hubs: { [url]: { token: 'mau_test', linkedAt: 1 } } })
+    );
+    chmodSync(process.env.HUBS_CONFIG_PATH, 0o600);
+
+    const opened: string[] = [];
+    const providerFactory = (args: { documentName: string; document?: Y.Doc }): SyncProvider => {
+      opened.push(args.documentName);
+      const document = args.document ?? new Y.Doc();
+      return { document, onceSynced: () => Promise.resolve(), destroy: () => {} };
+    };
+
+    const sup = createSyncSupervisor(ctx, { providerFactory });
+    expect((await sup.start()).syncing).toBe(false); // solo — nothing linked yet
+
+    const out = await sup.restart({ url, linkedAt: Date.now() });
+    expect(out).toEqual({ syncing: true, canvases: 2 });
+    expect(opened.sort()).toEqual(['ui-home', 'ui-pricing']);
+    expect(sup.current()).not.toBeNull();
+
+    await sup.stop();
+    rmSync(ctx.paths.repoRoot, { recursive: true, force: true });
+  });
+
+  test('a throwing start leaves the server up and answers with the reason', async () => {
+    const ctx = makeCtx({ url: 'https://hub.example', linkedAt: 1 });
+    const sup = createSyncSupervisor(ctx, {}, () => ({
+      start: async () => {
+        throw new Error('hub refused the handshake');
+      },
+      stop: async () => {},
+      size: () => 0,
+      agentFor: () => undefined,
+      status: () => null,
+    }));
+    const out = await sup.start();
+    expect(out.syncing).toBe(false);
+    expect(out.reason).toBe('error');
+    expect(out.detail).toContain('hub refused the handshake');
+    // And the NEXT attach still runs — a failed cycle must not poison the chain.
+    const log: string[] = [];
+    expect((await sup.restart()).syncing).toBe(false);
+    expect(log).toEqual([]);
+    rmSync(ctx.paths.repoRoot, { recursive: true, force: true });
+  });
+});

package/apps/studio/test/trusted-request-host.test.ts

@@ -0,0 +1,66 @@
+// `isTrustedRequestHost` — the mode-aware DNS-rebind guard.
+// RCA: issue-cloud-inspector-edits-refused-by-loopback-guard.
+//
+// The bug: 97 studio route handlers gated on `isLoopbackHost(Host)`, and in a
+// cell the hub proxy rewrites Host to the project's PUBLIC name (D4), so that
+// check could never pass — every Inspector/artboard edit 403'd while annotations
+// (no such guard) synced. The fix keeps the loopback check verbatim OUTSIDE
+// workspace mode and, INSIDE a cell, accepts the proxy's unforgeable
+// `x-maude-role` vouch instead (the proxy strips every inbound `x-maude-*`
+// before injecting its own, so the header's presence proves hub provenance).
+
+import { afterEach, describe, expect, test } from 'bun:test';
+
+import { isTrustedRequestHost } from '../http.ts';
+
+const WS = 'MAUDE_WORKSPACE_MODE';
+const prior = process.env[WS];
+afterEach(() => {
+  if (prior === undefined) delete process.env[WS];
+  else process.env[WS] = prior;
+});
+
+const req = (host: string | null, extra: Record<string, string> = {}) =>
+  new Request('http://x/_api/edit-css', {
+    headers: { ...(host ? { host } : {}), ...extra },
+  });
+
+describe('local mode — loopback Host only (verbatim DNS-rebind guard)', () => {
+  test('loopback Hosts pass', () => {
+    delete process.env[WS];
+    expect(isTrustedRequestHost(req('localhost:4399'))).toBe(true);
+    expect(isTrustedRequestHost(req('127.0.0.1:4399'))).toBe(true);
+    expect(isTrustedRequestHost(req('[::1]:4399'))).toBe(true);
+  });
+
+  test('a rebound foreign Host is refused — even carrying x-maude-role', () => {
+    delete process.env[WS];
+    expect(isTrustedRequestHost(req('evil.example:4399'))).toBe(false);
+    // Outside a cell the injected header means nothing: there is no proxy in
+    // front to have stamped it, so it is attacker-supplied and ignored.
+    expect(isTrustedRequestHost(req('evil.example:4399', { 'x-maude-role': 'owner' }))).toBe(false);
+  });
+});
+
+describe('workspace mode — the hub proxy vouch is accepted', () => {
+  test('a public Host WITH an injected role is trusted (the cell shell-edit path)', () => {
+    process.env[WS] = '1';
+    expect(
+      isTrustedRequestHost(req('alligators.cloud.maude.sh', { 'x-maude-role': 'owner' }))
+    ).toBe(true);
+    expect(
+      isTrustedRequestHost(req('alligators.cloud.maude.sh', { 'x-maude-role': 'member' }))
+    ).toBe(true);
+  });
+
+  test('a public Host WITHOUT an injected role is still refused', () => {
+    process.env[WS] = '1';
+    // No proxy vouch ⇒ no proof of hub provenance ⇒ the guard holds.
+    expect(isTrustedRequestHost(req('alligators.cloud.maude.sh'))).toBe(false);
+  });
+
+  test('loopback still passes in workspace mode (the studio binds 127.0.0.1)', () => {
+    process.env[WS] = '1';
+    expect(isTrustedRequestHost(req('127.0.0.1:4399'))).toBe(true);
+  });
+});

package/apps/studio/test/whisper-setup.test.ts

@@ -0,0 +1,97 @@
+// whisper-setup.test.ts — the subtitle stack's runtime detection and the `auto`
+// engine choice. Both exist to close the same gap the scout card had: the card
+// used to print `brew install whisper-cpp` unconditionally, never checked
+// whether the engine was there, and never adapted to the keys you'd set.
+
+import { describe, expect, test } from 'bun:test';
+import { resolveAutoEngine, whisperSetup } from '../generation/whisper-models.ts';
+
+describe('whisperSetup', () => {
+  test('either installed with nothing to do, or a route to fix it', () => {
+    const s = whisperSetup();
+    if (s.installed) expect(s.options).toHaveLength(0);
+    else expect(s.options.length).toBeGreaterThan(0);
+  });
+
+  test('every offered route is actionable as-is', () => {
+    for (const o of whisperSetup().options)
+      expect(o.kind === 'command' ? o.command : o.url).toBeTruthy();
+  });
+
+  test('a source-build route is always among the options when not installed', () => {
+    const s = whisperSetup();
+    if (!s.installed) expect(s.options.some((o) => o.id === 'source')).toBe(true);
+  });
+});
+
+// DDR-164's rule is "no engine switch behind your back". `auto` keeps it by
+// being a SELECTED mode whose resolution is stated — these tests pin the
+// resolution itself, including the part that costs money.
+describe('resolveAutoEngine', () => {
+  test('no keys → local whisper, and it says nothing leaves the machine', () => {
+    const r = resolveAutoEngine([], true);
+    expect(r.engine).toBe('whisper');
+    expect(r.cloud).toBe(false);
+    expect(r.reason).toContain('No cloud key');
+  });
+
+  test('an ElevenLabs key wins — Scribe beats a local base model', () => {
+    const r = resolveAutoEngine(['elevenlabs'], true);
+    expect(r.engine).toBe('elevenlabs');
+    expect(r.cloud).toBe(true);
+  });
+
+  test('Groq is used when it is the only key', () => {
+    expect(resolveAutoEngine(['groq'], true).engine).toBe('groq');
+  });
+
+  test('ElevenLabs outranks Groq when both keys are set', () => {
+    expect(resolveAutoEngine(['groq', 'elevenlabs'], true).engine).toBe('elevenlabs');
+  });
+
+  test('an unrelated provider key never routes audio to the cloud', () => {
+    // A Google key is for image generation — it must not drag transcription
+    // off-machine.
+    const r = resolveAutoEngine(['google'], true);
+    expect(r.engine).toBe('whisper');
+    expect(r.cloud).toBe(false);
+  });
+
+  test('a cloud resolution is always flagged as cloud (the billing/egress tell)', () => {
+    for (const keys of [['elevenlabs'], ['groq']])
+      expect(resolveAutoEngine(keys, true).cloud).toBe(true);
+  });
+
+  test('without the whisper binary it still resolves local, but says "once installed"', () => {
+    const r = resolveAutoEngine([], false);
+    expect(r.engine).toBe('whisper');
+    expect(r.reason).toContain('once its binary is installed');
+  });
+});
+
+// The server-side probe and the transcriber's own resolution MUST agree, or the
+// card claims an engine the CLI can't find. Same drift guard the scout has.
+describe('server ↔ CLI whisper resolution parity', () => {
+  test('the same candidate names, and `main` is excluded in both', async () => {
+    const cli = await import('../bin/_transcribe.mjs');
+    const src = await Bun.file(`${import.meta.dir}/../bin/_transcribe.mjs`).text();
+    const serverSrc = await Bun.file(`${import.meta.dir}/../generation/whisper-models.ts`).text();
+    // Both probe whisper-cli then whisper, and neither probes the bare `main`
+    // (executing a seeded `main` from `.` on $PATH was a security finding).
+    for (const s of [src, serverSrc]) {
+      expect(s).toContain("'whisper-cli'");
+      expect(s).toContain("'whisper'");
+      expect(s).not.toContain("'main'");
+    }
+    expect(typeof cli.resolveProvider).toBe('function');
+  });
+
+  test('both accept the same engine vocabulary incl. auto', async () => {
+    const cli = await import('../bin/_transcribe.mjs');
+    const { TRANSCRIPTION_PROVIDERS } = await import('../generation/prefs.ts');
+    // resolveProvider rejects anything outside the vocabulary, so a value the
+    // UI can persist must survive it.
+    for (const p of TRANSCRIPTION_PROVIDERS)
+      expect(cli.resolveProvider(p, '/nonexistent').provider).toBe(p);
+  });
+});

package/apps/studio/whats-new.json

@@ -1,6 +1,51 @@
 {
   "$schema": "./whats-new.schema.json",
   "entries": [
+    {
+      "id": "cloud-connect-tells-you-what-happened",
+      "version": "0.57.0",
+      "date": "2026-08-07",
+      "kind": "fix",
+      "title": "Connecting a cloud project tells you what happened",
+      "summary": "The line you see after Connect is now live and true: it moves from Connecting, through Syncing 40 of 75, to Synced — and names any canvases that came down from the project. Every outcome says what to do next, so a refused connection tells you to reconnect instead of sitting on “syncing” forever.",
+      "surface": "design-ui"
+    },
+    {
+      "id": "acp-turn-notifications",
+      "version": "0.57.0",
+      "date": "2026-08-07",
+      "kind": "feature",
+      "title": "Get notified when a background chat finishes",
+      "summary": "Maude now sends a real notification when a chat finishes or needs your input — even in a project you're not currently viewing. The notification never shows what was said, only which project needs you.",
+      "surface": "design-ui"
+    },
+    {
+      "id": "cloud-projects-save-themselves",
+      "version": "0.56.0",
+      "date": "2026-08-06",
+      "kind": "fix",
+      "title": "Cloud projects save themselves",
+      "summary": "A project open in Maude Cloud now records every edit as you make it — from a browser tab or from the app — so there is nothing to save by hand. The browser panel that used to ask you to Save and Publish is now simply History, showing what was already kept. Drawn annotations are stored where they are read from again, so they survive a reload.",
+      "surface": "design-ui"
+    },
+    {
+      "id": "desktop-cloud-live-pairing",
+      "version": "0.56.0",
+      "date": "2026-08-06",
+      "kind": "feature",
+      "title": "Desktop and browser now meet live in the cloud",
+      "summary": "Open a Maude Cloud project in the app and in a browser tab at the same time, and you now see each other — cursors, edits, everything, live. Rolling out to pilot projects first.",
+      "surface": "design-ui"
+    },
+    {
+      "id": "gemma-scout-ollama-easy-install",
+      "version": "0.56.0",
+      "date": "2026-08-06",
+      "kind": "improvement",
+      "title": "Easier Gemma scout setup — Ollama supported",
+      "summary": "Scene-aware keyframes' Gemma scout now also runs on Ollama — one app and `ollama pull gemma3:4b`, no Python required. The Settings card hands you copy/paste install commands for both runtimes and unlocks itself automatically once one is installed.",
+      "surface": "design-ui"
+    },
     {
       "id": "cloud-connect-browser-open-and-decision-modal",
       "version": "0.55.0",

package/apps/studio/ws.ts

@@ -8,8 +8,9 @@ import type { Activity } from './activity.ts';
 import type { Api } from './api.ts';
 import type { Collab, RoomConn } from './collab/index.ts';
 import type { Context } from './context.ts';
-import { createHmrBroadcaster } from './hmr-broadcast.ts';
+import { createContainerWriteBridge, createHmrBroadcaster } from './hmr-broadcast.ts';
 import type { InspectRegistry } from './inspect.ts';
+import { isWorkspaceMode } from './workspace-mode.ts';
 
 /**
  * Per-connection state. `kind` discriminates between the legacy JSON
@@ -268,6 +269,13 @@ export function createWs(
   // Uses broadcastHmr so the segregated canvas origin's HMR-only sockets get it.
   createHmrBroadcaster(ctx, (msg) => broadcastHmr(msg));
 
+  // In a cell the container's recursive fs.watch misses our atomic tmp+rename
+  // writes, so the broadcaster above never sees an edit and a peer's canvas
+  // iframe stays stale until a manual reload (inspector-edits-live-render RCA).
+  // Synthesise the fs:any the watcher owes us from each write's activity:suppress
+  // arm. Workspace-mode only — locally fs.watch fires and this would double-load.
+  if (isWorkspaceMode()) createContainerWriteBridge(ctx);
+
   // Phase 13 / DDR-029 — canvas activity overlay. activity.ts emits
   // `activity:change` per file as edits land + go idle. The overlay renders
   // INSIDE the canvas iframe, which (with the default origin split, DDR-054)

package/cli/commands/kg.mjs

@@ -18,7 +18,7 @@ import { basename, join, resolve } from 'node:path';
 import { parseArgs } from '../lib/argv.mjs';
 
 const CONFIG_PATH = '.ai/workflows.config.json';
-const DEFAULT_ENGINE_VERSION = 'v1.0.0';
+const DEFAULT_ENGINE_VERSION = 'v1.4.0';
 const KGAI_REPO = 'kgaidev/kgai';
 
 const VERBS = new Set([
@@ -268,7 +268,14 @@ async function verbCheckUpstream(state) {
 function verbSessionSync(state, flags) {
   // Silent no-op unless active AND a remote store is set (a pull needs a remote).
   if (!state.active || !state.store) return 0;
-  const status = runKg(state, ['sync'], { timeoutMs: 20000 });
+  // `--auto` (kgai v1.2.0+) is the engine's own fire-and-forget mode: safe no-op
+  // without a store/remote, honors a 60s cooldown so rapid session restarts don't
+  // hammer the remote, and skips (never blocks) when another sync/write holds the
+  // store lock. That's a strict improvement over a plain blocking `kg sync` here —
+  // this call already runs backgrounded from the SessionStart hook (see
+  // plugins/flow/hooks/hooks.json), but the engine-level non-blocking guarantee is
+  // what actually prevents a queued/blocked spawn from piling up across sessions.
+  const status = runKg(state, ['sync', '--auto'], { timeoutMs: 20000 });
   if (status !== 0 && flags['warn-only']) {
     process.stderr.write('maude kg: session sync-pull failed — working on the local cache.\n');
     return 0; // never block session start

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1agh/maude",
-  "version": "0.55.0",
+  "version": "0.57.0",
   "description": "Marketplace of Claude Code plugins by Michal Dovrtěl: `design` (canvas-first design iteration) + `flow` (generic agentic workflow loop with .ai second brain). Ships the `maude` CLI (with `mdcc` legacy alias) to scaffold workspace, run the design dev server, and manage configs.",
   "type": "module",
   "engines": {
@@ -54,13 +54,13 @@
     "test:e2e:desktop:parity:cloud": "pnpm --filter @maude/desktop-e2e e2e:parity:cloud"
   },
   "optionalDependencies": {
-    "@1agh/maude-darwin-arm64": "0.55.0",
-    "@1agh/maude-darwin-x64": "0.55.0",
-    "@1agh/maude-linux-arm64": "0.55.0",
-    "@1agh/maude-linux-arm64-musl": "0.55.0",
-    "@1agh/maude-linux-x64": "0.55.0",
-    "@1agh/maude-linux-x64-musl": "0.55.0",
-    "@1agh/maude-win32-x64": "0.55.0"
+    "@1agh/maude-darwin-arm64": "0.57.0",
+    "@1agh/maude-darwin-x64": "0.57.0",
+    "@1agh/maude-linux-arm64": "0.57.0",
+    "@1agh/maude-linux-arm64-musl": "0.57.0",
+    "@1agh/maude-linux-x64": "0.57.0",
+    "@1agh/maude-linux-x64-musl": "0.57.0",
+    "@1agh/maude-win32-x64": "0.57.0"
   },
   "files": [
     "cli",

package/plugins/design/dependencies.json

@@ -254,17 +254,35 @@
       "type": "cli",
       "hardness": "soft",
       "check": {
-        "command": "python3 -c \"import mlx_vlm\"",
+        "command": "MAUDE_VENV=\"${XDG_CACHE_HOME:+$XDG_CACHE_HOME/maude}\"; MAUDE_VENV=\"${MAUDE_VENV:-$HOME/.maude}/mlx-venv\"; \"$MAUDE_VENV/bin/python3\" -c \"import mlx_vlm\" 2>/dev/null || python3 -c \"import mlx_vlm\"",
         "expectExit": 0
       },
       "install": {
-        "darwin": "pip install mlx-vlm",
+        "darwin": "MAUDE_VENV=\"${XDG_CACHE_HOME:+$XDG_CACHE_HOME/maude}\"; MAUDE_VENV=\"${MAUDE_VENV:-$HOME/.maude}/mlx-venv\"; python3 -m venv \"$MAUDE_VENV\" && \"$MAUDE_VENV/bin/pip\" install -U mlx-vlm",
         "preferred": "https://github.com/Blaizzy/mlx-vlm"
       },
       "autoInstall": false,
-      "fallbackBehavior": "feature-scene-aware-keyframes — OPT-IN. The `gemma` tier of `maude design smart-frames` runs a local Gemma-4 MLX scout (Apple Silicon only) to flag semantic action beats. Without it, smart-frames uses the ffmpeg or blind tier — no model download required. The scout also needs a Gemma-4 MLX model (--engine gemma / $MAUDE_GEMMA_MODEL, one-click in Studio Settings → Scene-aware keyframes).",
+      "fallbackBehavior": "feature-scene-aware-keyframes — OPT-IN. The `gemma` tier of `maude design smart-frames` runs a local Gemma-4 MLX scout (Apple Silicon only) to flag semantic action beats. Without it, smart-frames uses Ollama (if a gemma3 vision model is pulled), else the ffmpeg or blind tier — no model download required. The scout also needs a Gemma-4 MLX model (--engine gemma / $MAUDE_GEMMA_MODEL, one-click in Studio Settings → Video).",
       "usedBy": ["dev-server/bin/_smart-frames.mjs"],
       "docsUrl": "https://github.com/Blaizzy/mlx-vlm"
+    },
+    {
+      "id": "ollama",
+      "type": "cli",
+      "hardness": "soft",
+      "check": {
+        "command": "which ollama",
+        "expectExit": 0
+      },
+      "install": {
+        "darwin": "curl -fsSL https://ollama.com/install.sh | sh && ollama pull gemma3:4b",
+        "linux": "curl -fsSL https://ollama.com/install.sh | sh && ollama pull gemma3:4b",
+        "preferred": "https://ollama.com/download"
+      },
+      "autoInstall": false,
+      "fallbackBehavior": "feature-scene-aware-keyframes — OPT-IN alternative scout runtime. The `gemma` tier of `maude design smart-frames` can run its semantic-beat scout through a local Ollama server with a vision-capable gemma3 model (`ollama pull gemma3:4b`) instead of mlx-vlm — the simpler install story (one app, no Python; works beyond Apple Silicon). mlx-vlm is preferred when both are present. Without either, smart-frames uses the ffmpeg or blind tier.",
+      "usedBy": ["dev-server/bin/_smart-frames.mjs"],
+      "docsUrl": "https://ollama.com"
     }
   ]
 }