@1agh/maude 0.46.0 → 0.48.0

package/apps/studio/whats-new.json

@@ -1,6 +1,33 @@
 {
   "$schema": "./whats-new.schema.json",
   "entries": [
+    {
+      "id": "figma-smart-select",
+      "version": "0.47.0",
+      "date": "2026-07-21",
+      "kind": "feature",
+      "title": "Click to select, like Figma",
+      "summary": "Your mock now opens live — click a button or link to actually try it. When you want to edit, press V: a plain click selects the object under your cursor, ⌘-click reaches the deepest element, double-click drills in one level, and Enter / Shift+Enter / Tab walk the layer tree. The toolbar's first two tools are Browse (live) and Select (V). The Layers panel grew up too: wrapper groups show at their real depth, component instances render purple with their component's name, you can lock a layer (locked layers can't be selected or dragged on the canvas), double-click a layer's name to rename it, and the tree auto-reveals whatever you pick on the canvas. And when a flex layout fights your manual tweaks, right-click the container → \"Convert children to absolute position\" freezes every child where it sits so you can drag them freely (one undo reverts it) — or convert a whole artboard at once (right-click the artboard, or when switching its kind to Digital/Print). And when a component instance needs its own look, hit Detach on the Inspector's Shared badge — edits stay local to that one instance. Text editing got Figma's exact rhythm too: drilling down to a text layer selects all of it (ready to overwrite), and once you're in, a click places the cursor, a double-click grabs a word, and a triple-click grabs everything.",
+      "surface": "design-ui"
+    },
+    {
+      "id": "acp-safe-defaults-and-attention-notifications",
+      "version": "0.47.0",
+      "date": "2026-07-21",
+      "kind": "improvement",
+      "title": "Fewer prompts in chat, and a nudge when you're needed",
+      "summary": "The assistant chat now runs common design-workflow actions — browser checks, your own local dev-server requests, reading files, and web search — without asking every time. And when a chat is waiting on your approval or an answer, Maude now sends a system notification so you don't miss it.",
+      "surface": "design-ui"
+    },
+    {
+      "id": "web-artboards",
+      "version": "0.47.0",
+      "date": "2026-07-21",
+      "kind": "feature",
+      "title": "Web artboards — breakpoints, duplicate, and a grid editor",
+      "summary": "Set an artboard's kind to Web and it becomes a responsive viewport: a small chip shows its current breakpoint, and \"Duplicate at width…\" (right-click or the Inspector) clones it at Mobile/Tablet/Laptop/Desktop widths for reflow testing. Grid containers also get a new Grid section in the Inspector — define columns and rows with px/%/fr/em/auto units, drag the gutters directly on the canvas, and place children into specific cells.",
+      "surface": "design-ui"
+    },
     {
       "id": "scene-aware-video-analyze",
       "version": "0.46.0",

package/cli/bin/maude.mjs

@@ -18,6 +18,7 @@ const COMMANDS = {
   design: () => import('../commands/design.mjs'),
   'scenario-report': () => import('../commands/scenario-report.mjs'),
   doctor: () => import('../commands/doctor.mjs'),
+  kg: () => import('../commands/kg.mjs'),
   help: () => import('../commands/help.mjs'),
   hub: () => import('../commands/hub.mjs'),
   version: () => import('../commands/version.mjs'),

package/cli/commands/design.mjs

@@ -110,6 +110,22 @@ const BIN_VERBS = new Set([
   // user's ElevenLabs history before spending credits on a new music/SFX/VO
   // track. Runs server-side (key resolved by the sidecar); needs a dev server.
   'audio-search',
+  // DDR-185. `curl-local` is a loopback-only curl: resolves the request's
+  // target host and refuses to invoke real curl at all unless every resolved
+  // address is strictly loopback (127.0.0.0/8 or ::1). Exists so an ACP chat
+  // session can auto-approve "check my local dev server" without widening the
+  // session's Bash allow-list to unscoped curl (`Bash(curl:*)` would reach any
+  // host — see DDR-185's rejected alternatives). No dev server dependency —
+  // pure Node, no `<designRoot>` involvement.
+  'curl-local',
+  // DDR-185 security addendum. `agent-browser-safe` replaces the bare
+  // `Bash(agent-browser:*)` allow-list entry a security review found was a
+  // zero-confirmation session-hijack primitive (agent-browser's own bundled
+  // skill recommends a PERSISTENT authenticated Chrome profile). Closed
+  // subcommand allow-list + forced domain scope + forced ephemeral profile —
+  // see `_agent-browser-safe.mjs` for the full rationale. No dev server
+  // dependency — pure Node.
+  'agent-browser-safe',
 ]);
 
 // Bin verbs that boot the dev-server (directly, or by shelling into server-up.sh).

package/cli/commands/init.mjs

@@ -1,8 +1,29 @@
-import { stat } from 'node:fs/promises';
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { stat, writeFile } from 'node:fs/promises';
 import { basename, resolve } from 'node:path';
 import { parseArgs } from '../lib/argv.mjs';
 import { copyTree } from '../lib/copy-tree.mjs';
 
+// Thin STATE.md written under --kg: the knowledge graph is the history authority,
+// so STATE.md shrinks to a human breadcrumb (Open fork #2 — stub, not removal).
+const KG_STATE_STUB = `# Workflow State
+
+> **kgai-active repo** — decision history + working context live in the knowledge graph, not this file.
+> The \`flow:workflow-state\` skill reads/writes the graph via \`flow:kgai-backend\`.
+
+**Status:** ready
+**Active plan:** —
+
+## Where the history went
+
+- **Decisions / "why is X so":** \`maude kg context --about "<area>"\`
+- **Recent movements:** \`maude kg query "MATCH (d:Decision) WHERE d.author='<you>' RETURN d.title, d.recorded_at ORDER BY d.recorded_at DESC LIMIT 10"\`
+- **Conflicts:** \`maude kg conflicts\`
+
+The old \`.ai/decisions/\` archive (if any) is preserved read-only — never auto-deleted.
+`;
+
 const PLACEHOLDER = 'PROJECT_NAME';
 // Files in the skeleton that contain the project-name placeholder and should
 // be templated on copy.
@@ -43,10 +64,12 @@ const CHANGELOG_STUBS = {
 const VALID_PROVIDERS = new Set(['changesets', 'git-cliff', 'conventional', 'custom', 'none']);
 
 export async function run({ args, pkgRoot }) {
-  const { flags } = parseArgs(args, { booleans: ['force', 'dry-run', 'help'] });
+  const { flags } = parseArgs(args, { booleans: ['force', 'dry-run', 'help', 'kg'] });
   if (flags.help) {
     process.stdout.write(
-      'maude init [--name <project>] [--provider <changesets|git-cliff|conventional|custom|none>] [--force] [--dry-run]\n'
+      'maude init [--name <project>] [--provider <changesets|git-cliff|conventional|custom|none>] [--kg] [--force] [--dry-run]\n' +
+        '  --kg   opt into the kgai knowledge-graph backend: write a thin STATE.md pointer-stub\n' +
+        '         and bootstrap a local store via `kg init` (no-op when `kg` is not installed).\n'
     );
     return;
   }
@@ -136,10 +159,64 @@ export async function run({ args, pkgRoot }) {
     (await pathExists(resolve(cwd, 'CLAUDE.md'))) ||
     (await pathExists(resolve(cwd, '.claude', 'CLAUDE.md')));
 
+  // --kg (opt-in): the knowledge graph becomes the history authority. Replace the
+  // scaffolded STATE.md with a thin pointer-stub and bootstrap a local store.
+  // The `knowledgeGraph` config block stays ABSENT (bias-free skeleton ⇒ auto via
+  // the schema default — onboarding / `maude doctor --fix` fills store + scope).
+  if (flags.kg && !flags['dry-run']) {
+    const statePath = resolve(aiDir, 'state', 'STATE.md');
+    await writeFile(statePath, KG_STATE_STUB, 'utf8');
+    process.stdout.write('  kgai: wrote thin STATE.md pointer-stub (history lives in the graph)\n');
+    const kgBin = resolveKgBin();
+    if (kgBin) {
+      // No --root: kgai defaults the store to `<cwd>/.kgai/store` (which the
+      // resolver auto-detects and the gitignore block ignores). Passing --root
+      // would place the store's loose files at cwd root instead.
+      const r = spawnSync(kgBin, ['init'], {
+        cwd,
+        stdio: 'ignore',
+        env: kgInitEnv(),
+      });
+      process.stdout.write(
+        r.status === 0
+          ? '  kgai: bootstrapped local store via `kg init` (git-author actor captured)\n'
+          : '  kgai: `kg init` did not complete — run it manually (see docs/kgai-onboarding.md)\n'
+      );
+    } else {
+      process.stdout.write(
+        '  kgai: `kg` not installed — store not bootstrapped. See docs/kgai-onboarding.md.\n'
+      );
+    }
+    process.stdout.write(
+      '  kgai: set `knowledgeGraph.store` + `scope` per docs/kgai-onboarding.md\n'
+    );
+  } else if (flags.kg) {
+    process.stdout.write('  kgai: (dry-run) would write STATE.md stub + bootstrap the store\n');
+  }
+
   printSummary(result);
   printNextSteps(projectName, claudeMdExists);
 }
 
+/** KGAI_BIN (desktop-staged sidecar) → `kg` on PATH → null. Mirrors kg.mjs. */
+function resolveKgBin() {
+  if (process.env.KGAI_BIN && existsSync(process.env.KGAI_BIN)) return process.env.KGAI_BIN;
+  const probe = spawnSync('sh', ['-c', 'command -v kg'], { encoding: 'utf8' });
+  const found = (probe.stdout || '').trim();
+  return probe.status === 0 && found ? found : null;
+}
+
+/** Fold KGAI_LIB into DYLD_LIBRARY_PATH so a staged libkuzu resolves (desktop). */
+function kgInitEnv() {
+  const env = { ...process.env };
+  if (process.env.KGAI_LIB) {
+    env.DYLD_LIBRARY_PATH = [process.env.KGAI_LIB, process.env.DYLD_LIBRARY_PATH]
+      .filter(Boolean)
+      .join(':');
+  }
+  return env;
+}
+
 function isValidName(s) {
   return /^[a-z0-9._-]+$/i.test(s);
 }

package/cli/commands/kg.mjs

@@ -0,0 +1,368 @@
+// `maude kg <verb>` — the resolved dispatcher for the kgai knowledge-graph
+// backend (feature-kgai-ecosystem-integration). Plugin markdown reaches kgai
+// ONLY through here (DDR-062), never a raw `kg` binary path: this command
+// resolves the pinned/bundled `kg`, reads the `knowledgeGraph.*` config, gates
+// `active`, and injects the resolved store/scope env before spawning `kg`.
+//
+// The resolver lives here (not duplicated in bash/markdown) so the `kgai-backend`
+// skill and every command gate identically via `maude kg resolve --json`.
+//
+// Capability-gated + opt-out (mirrors orchestration.mode:auto, DDR-130): when
+// `kg` is absent / store unreachable / mode:off, verbs degrade to a clean no-op
+// or an informative message — a command's classic `.ai/` path is unaffected.
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { parseArgs } from '../lib/argv.mjs';
+
+const CONFIG_PATH = '.ai/workflows.config.json';
+const DEFAULT_ENGINE_VERSION = 'v0.1.9';
+const KGAI_REPO = 'kgaidev/kgai';
+
+const VERBS = new Set([
+  'resolve',
+  'doctor',
+  'check-upstream',
+  'session-sync',
+  'sync',
+  'context',
+  'ingest',
+  'scope',
+  'import',
+  'help',
+]);
+
+/** Resolve the project root the SAME way the design dev-server does. */
+function resolveProjectRoot(flags) {
+  return flags.root || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+/** Read the `knowledgeGraph` block with safe defaults (absent ⇒ auto). */
+function readConfig(projectRoot) {
+  const path = resolve(projectRoot, CONFIG_PATH);
+  let raw = {};
+  try {
+    raw = JSON.parse(readFileSync(path, 'utf8'))?.knowledgeGraph ?? {};
+  } catch {
+    raw = {};
+  }
+  return {
+    mode: raw.mode ?? 'auto',
+    engine: raw.engine ?? 'kgai',
+    engineVersion: raw.engineVersion ?? DEFAULT_ENGINE_VERSION,
+    store: raw.store ?? '',
+    scope: raw.scope ?? {},
+    capture: { decisions: true, state: true, auto: true, ...(raw.capture ?? {}) },
+  };
+}
+
+/**
+ * The staged desktop engine, resolved from maude's OWN package root (DDR-045 —
+ * never `import.meta.url`, which is `/$bunfs/root` inside the compiled binary).
+ * In the `.app`, pkgRoot is bridged to `Contents/Resources`, the `kg` sidecar
+ * lands in `Contents/MacOS/`, and `libkuzu` under `Resources/kgai/` (see
+ * apps/desktop/scripts/sync-kg.mjs). Returns `{ bin, lib }` or null elsewhere.
+ */
+function resolveStagedKgai(pkgRoot) {
+  if (!pkgRoot) return null;
+  const lib = join(pkgRoot, 'kgai');
+  if (!existsSync(lib)) return null;
+  const exe = process.platform === 'win32' ? '.exe' : '';
+  for (const bin of [join(pkgRoot, '..', 'MacOS', `kg${exe}`), join(lib, `kg${exe}`)]) {
+    if (existsSync(bin)) return { bin, lib };
+  }
+  return null;
+}
+
+/** KGAI_BIN env → desktop-staged sidecar → `kg` on PATH → null. */
+function resolveKgBin(pkgRoot) {
+  if (process.env.KGAI_BIN && existsSync(process.env.KGAI_BIN)) return process.env.KGAI_BIN;
+  const staged = resolveStagedKgai(pkgRoot);
+  if (staged) {
+    // Make the sibling libkuzu reachable for this process's spawns (kgEnv folds
+    // it into DYLD_/LD_LIBRARY_PATH) without requiring the caller to plumb env.
+    process.env.KGAI_LIB ||= staged.lib;
+    return staged.bin;
+  }
+  const probe = spawnSync('sh', ['-c', 'command -v kg'], { encoding: 'utf8' });
+  const found = (probe.stdout || '').trim();
+  return probe.status === 0 && found ? found : null;
+}
+
+/** The capability gate — the single source of `active`. */
+function resolveState(projectRoot, pkgRoot) {
+  const cfg = readConfig(projectRoot);
+  const kgBin = resolveKgBin(pkgRoot);
+  const localStore = existsSync(resolve(projectRoot, '.kgai', 'store'));
+  const storeResolvable = cfg.store !== '' || localStore;
+  let active;
+  if (cfg.mode === 'on') active = true;
+  else if (cfg.mode === 'off') active = false;
+  else active = Boolean(kgBin) && storeResolvable; // auto
+  return {
+    active,
+    mode: cfg.mode,
+    engine: cfg.engine,
+    engineVersion: cfg.engineVersion,
+    store: cfg.store,
+    scope: cfg.scope,
+    capture: cfg.capture,
+    kgBin,
+    kgPresent: Boolean(kgBin),
+    projectRoot,
+  };
+}
+
+/** Child env for a real `kg` spawn. libkuzu path (desktop); never override actor.
+ *  NOTE: `config.knowledgeGraph.store` is the kgai REMOTE (s3://… / kgai://… / git),
+ *  persisted into the store by `kg init --remote` and read by `kg sync` — it is NOT
+ *  `KGAI_STORE` (which is the LOCAL store-root dir, default `<project>/.kgai/store`).
+ *  So we deliberately do NOT export KGAI_STORE from the config store. */
+function kgEnv() {
+  const env = { ...process.env };
+  // Desktop bundle stages libkuzu next to `kg` and points KGAI_LIB at its dir;
+  // fold it into DYLD_LIBRARY_PATH so the dylib resolves. No-op when unset.
+  if (process.env.KGAI_LIB) {
+    const key = process.platform === 'darwin' ? 'DYLD_LIBRARY_PATH' : 'LD_LIBRARY_PATH';
+    env[key] = [process.env.KGAI_LIB, process.env[key]].filter(Boolean).join(':');
+  }
+  return env;
+}
+
+/** Spawn the resolved `kg` with the given args, inheriting stdio. Returns exit status. */
+function runKg(state, kgArgs, { timeoutMs } = {}) {
+  if (!state.kgBin) {
+    process.stderr.write(
+      'maude kg: the `kg` CLI is not available. kgai is capability-gated — install it (see docs/kgai-onboarding.md) or use classic `.ai/` mode.\n'
+    );
+    return 127;
+  }
+  const child = spawnSync(state.kgBin, kgArgs, {
+    stdio: 'inherit',
+    env: kgEnv(),
+    ...(timeoutMs ? { timeout: timeoutMs } : {}),
+  });
+  if (child.error) {
+    process.stderr.write(`maude kg: ${child.error.message}\n`);
+    return 1;
+  }
+  return child.status ?? 1;
+}
+
+// ── verb: resolve ──────────────────────────────────────────────────────────
+function verbResolve(state, flags) {
+  const out = {
+    active: state.active,
+    mode: state.mode,
+    engine: state.engine,
+    engineVersion: state.engineVersion,
+    store: state.store,
+    scope: state.scope,
+    kgPresent: state.kgPresent,
+  };
+  if (flags.json ?? true)
+    process.stdout.write(`${JSON.stringify(out, null, flags.json ? 2 : 0)}\n`);
+  return 0;
+}
+
+// ── verb: doctor ───────────────────────────────────────────────────────────
+function verbDoctor(state) {
+  const line = (label, val) => process.stdout.write(`    ${label.padEnd(16)} ${val}\n`);
+  process.stdout.write('maude kg doctor\n\n');
+  line('kg binary', state.kgBin || '✗ missing (see docs/kgai-onboarding.md)');
+  line('mode', state.mode);
+  line('engineVersion', state.engineVersion);
+  line('store', state.store || '(local-only .kgai/store)');
+  line('scope', JSON.stringify(state.scope));
+  line('active', state.active ? '✓ yes' : '✗ no (classic .ai/ path)');
+  if (!state.active && state.mode === 'auto') {
+    const why = !state.kgPresent
+      ? 'kg not on PATH'
+      : 'no store configured and no local .kgai/store';
+    process.stdout.write(`\n  auto ⇒ inactive: ${why}. Falls back to classic .ai/ file mode.\n`);
+  }
+  return 0;
+}
+
+// ── verb: check-upstream ───────────────────────────────────────────────────
+async function verbCheckUpstream(state) {
+  const pinned = state.engineVersion;
+  process.stdout.write(`maude kg check-upstream\n\n  pinned (engineVersion): ${pinned}\n`);
+  let latest = null;
+  let assets = [];
+  try {
+    const res = await fetch(`https://api.github.com/repos/${KGAI_REPO}/releases/latest`, {
+      headers: { 'user-agent': 'maude-kg', accept: 'application/vnd.github+json' },
+      signal: AbortSignal.timeout(15000),
+    });
+    if (res.ok) {
+      const rel = await res.json();
+      latest = rel.tag_name;
+      assets = (rel.assets ?? []).map((a) => a.name);
+    }
+  } catch {
+    /* offline — best-effort */
+  }
+  if (!latest) {
+    process.stdout.write('  latest: unknown (offline) — using pinned.\n');
+    return 0;
+  }
+  process.stdout.write(`  latest release:         ${latest}\n`);
+  process.stdout.write(
+    `  status:                 ${latest === pinned ? '✓ up to date' : `⚠ upstream moved ${pinned} → ${latest}`}\n`
+  );
+  // Capability diff — flags/commands the plan's assumptions hinge on.
+  const hasDarwin = assets.some((a) => /kg-darwin/.test(a));
+  const hasKuzu = assets.some((a) => /libkuzu/.test(a));
+  process.stdout.write('\n  prebuilt assets:\n');
+  process.stdout.write(`    macOS kg binary:      ${hasDarwin ? '✓' : '✗'}\n`);
+  process.stdout.write(`    libkuzu dylib/so:     ${hasKuzu ? '✓' : '✗'}\n`);
+  if (latest !== pinned) {
+    process.stdout.write(
+      '\n  → Re-scan the capability surface (native --scope filter? kg import? Stop-hook/guessActor changes?),\n' +
+        '    re-run scripts/kgai-smoke/run.sh pinned to the new tag, reconcile the plan, then bump\n' +
+        '    config.knowledgeGraph.engineVersion deliberately (never float — supply-chain surface, DDR-054/056).\n'
+    );
+  }
+  return 0;
+}
+
+// ── verb: session-sync (SessionStart hook — non-blocking pull) ──────────────
+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 });
+  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
+  }
+  return flags['warn-only'] ? 0 : status;
+}
+
+// ── verb: sync (done/pause push) ───────────────────────────────────────────
+function verbSync(state, flags) {
+  if (!state.active) return 0; // inactive ⇒ nothing to sync (classic path)
+  if (!state.store) return 0; // local-only ⇒ no remote to push
+  const status = runKg(state, ['sync'], { timeoutMs: 60000 });
+  if (status !== 0 && flags['warn-only']) {
+    process.stderr.write('maude kg: sync failed — local append-only log is intact; will retry.\n');
+    return 0;
+  }
+  return status;
+}
+
+// ── verb: scope ────────────────────────────────────────────────────────────
+function verbScope(state) {
+  process.stdout.write(`${JSON.stringify(state.scope, null, 2)}\n`);
+  return 0;
+}
+
+// ── verb: import (migration — productionized in Phase 5) ────────────────────
+async function verbImport(state, args, pkgRoot) {
+  const libPath = join(pkgRoot, 'cli', 'lib', 'ddr-to-kgai.mjs');
+  if (!existsSync(libPath)) {
+    process.stderr.write(
+      'maude kg import: the migration importer (cli/lib/ddr-to-kgai.mjs) is not yet available in this build.\n'
+    );
+    return 1;
+  }
+  const mod = await import(libPath);
+  return mod.run({
+    args,
+    state,
+    projectRoot: state.projectRoot,
+    runKg: (a, o) => runKg(state, a, o),
+  });
+}
+
+// ── passthrough verbs (context / ingest) ───────────────────────────────────
+function verbPassthrough(verb, state, args) {
+  if (!state.active) {
+    process.stderr.write(
+      `maude kg ${verb}: kgai inactive here (mode=${state.mode}) — the caller should use its classic .ai/ path.\n`
+    );
+    return 0; // inactive is not an error; the command's else-branch owns the write
+  }
+  // Everything after the verb token passes straight to `kg`, MINUS maude-owned
+  // flags (`--root <path>` selects the project; it is not a `kg` flag).
+  const raw = args.slice(args.indexOf(verb) + 1);
+  const rest = [];
+  for (let i = 0; i < raw.length; i++) {
+    if (raw[i] === '--root') {
+      i++; // skip its value
+      continue;
+    }
+    if (raw[i].startsWith('--root=')) continue;
+    rest.push(raw[i]);
+  }
+  return runKg(state, [verb, ...rest]);
+}
+
+function usage() {
+  return `maude kg <verb> [options]
+
+  resolve [--json]        Print the resolved {active, mode, store, scope} gate (JSON).
+  doctor                  Human report: kg presence, mode, store, scope, active.
+  check-upstream          Compare pinned engineVersion vs the latest kgai release + capability diff.
+  session-sync [--warn-only]  Non-blocking SessionStart pull (no-op unless active + remote store).
+  sync [--warn-only]      Push the local log to the remote store (done/pause). No-op when inactive/local-only.
+  context <args…>         Scope-biased read (passthrough to \`kg context\`).
+  ingest <args…>          Record a decision + scope tags (passthrough to \`kg ingest\`).
+  scope                   Print the resolved scope ({repo, dept}).
+  import [--dry-run …]    Migrate .ai/decisions/ + .design/ into kgai (Phase 5).
+  --root <path>           Project root (default $CLAUDE_PROJECT_DIR or cwd).
+
+kgai is capability-gated + opt-out. When \`kg\` is absent or mode:off, verbs no-op cleanly
+and the classic .ai/ path is unchanged. See the \`flow:kgai-backend\` skill for the contract.
+`;
+}
+
+export async function run({ args, pkgRoot }) {
+  const verb = args[0];
+  if (!verb || verb === 'help' || verb === '--help' || verb === '-h') {
+    process.stdout.write(usage());
+    return;
+  }
+  if (!VERBS.has(verb)) {
+    process.stderr.write(`maude kg: unknown verb "${verb}".\n${usage()}`);
+    process.exit(2);
+  }
+  const flags = parseArgs(args.slice(1), {
+    booleans: ['json', 'warn-only', 'dry-run', 'design', 'all-scopes', 'force'],
+  }).flags;
+  const projectRoot = resolveProjectRoot(flags);
+  const state = resolveState(projectRoot, pkgRoot);
+
+  let status = 0;
+  switch (verb) {
+    case 'resolve':
+      status = verbResolve(state, flags);
+      break;
+    case 'doctor':
+      status = verbDoctor(state);
+      break;
+    case 'check-upstream':
+      status = await verbCheckUpstream(state);
+      break;
+    case 'session-sync':
+      status = verbSessionSync(state, flags);
+      break;
+    case 'sync':
+      status = verbSync(state, flags);
+      break;
+    case 'scope':
+      status = verbScope(state);
+      break;
+    case 'import':
+      status = await verbImport(state, args.slice(1), pkgRoot);
+      break;
+    case 'context':
+    case 'ingest':
+      status = verbPassthrough(verb, state, args);
+      break;
+    default:
+      status = 2;
+  }
+  if (status && status !== 0) process.exit(status);
+}

package/cli/commands/kg.test.mjs

@@ -0,0 +1,118 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(__dirname, '..', '..');
+const MAUDE_BIN = resolve(REPO_ROOT, 'cli', 'bin', 'maude.mjs');
+
+function kg(args, cwd) {
+  return spawnSync('node', [MAUDE_BIN, 'kg', ...args], {
+    cwd,
+    encoding: 'utf8',
+    env: { ...process.env, NO_COLOR: '1' },
+  });
+}
+
+/** Temp repo carrying a `.ai/workflows.config.json` with the given knowledgeGraph block. */
+function repoWith(knowledgeGraph) {
+  const root = mkdtempSync(join(tmpdir(), 'kg-test-'));
+  mkdirSync(join(root, '.ai'), { recursive: true });
+  const config = { name: 'fixture' };
+  if (knowledgeGraph !== undefined) config.knowledgeGraph = knowledgeGraph;
+  writeFileSync(join(root, '.ai', 'workflows.config.json'), JSON.stringify(config));
+  return root;
+}
+
+function resolveJson(cwd) {
+  const r = kg(['resolve', '--json'], cwd);
+  assert.equal(r.status ?? 0, 0, r.stderr);
+  return JSON.parse(r.stdout);
+}
+
+test('absent block ⇒ mode auto (opt-out default)', () => {
+  const out = resolveJson(repoWith(undefined));
+  assert.equal(out.mode, 'auto');
+  // auto with no store ⇒ inactive regardless of whether kg is on this PATH.
+  assert.equal(out.active, false);
+});
+
+test('mode:off ⇒ inactive even if kg present + store set', () => {
+  const out = resolveJson(repoWith({ mode: 'off', store: 's3://x/store' }));
+  assert.equal(out.mode, 'off');
+  assert.equal(out.active, false);
+});
+
+test('mode:on ⇒ active (forced, independent of kg presence)', () => {
+  const out = resolveJson(repoWith({ mode: 'on' }));
+  assert.equal(out.active, true);
+});
+
+test('mode:auto + store ⇒ active tracks kg presence', () => {
+  const out = resolveJson(repoWith({ mode: 'auto', store: 's3://co/store' }));
+  // storeResolvable is true, so the only remaining gate is the kg binary.
+  assert.equal(out.active, out.kgPresent);
+});
+
+test('store + scope surface in resolve', () => {
+  const out = resolveJson(
+    repoWith({ store: 's3://studyfi-kg/store', scope: { repo: 'maude', dept: 'dev' } })
+  );
+  assert.equal(out.store, 's3://studyfi-kg/store');
+  assert.deepEqual(out.scope, { repo: 'maude', dept: 'dev' });
+});
+
+test('engineVersion defaults to the pinned release when absent', () => {
+  const out = resolveJson(repoWith(undefined));
+  assert.match(out.engineVersion, /^v\d+\.\d+\.\d+$/);
+});
+
+test('doctor prints the active line', () => {
+  const r = kg(['doctor'], repoWith({ mode: 'off' }));
+  assert.equal(r.status ?? 0, 0);
+  assert.match(r.stdout, /active/);
+  assert.match(r.stdout, /classic \.ai\/ path/);
+});
+
+test('scope verb prints the resolved scope', () => {
+  const r = kg(['scope'], repoWith({ scope: { repo: 'x', dept: 'finance' } }));
+  assert.equal(r.status ?? 0, 0);
+  assert.deepEqual(JSON.parse(r.stdout), { repo: 'x', dept: 'finance' });
+});
+
+test('session-sync is a silent no-op when inactive', () => {
+  const r = kg(['session-sync', '--warn-only'], repoWith({ mode: 'off' }));
+  assert.equal(r.status ?? 0, 0);
+  assert.equal(r.stdout.trim(), '');
+});
+
+test('unknown verb exits 2', () => {
+  const r = kg(['frobnicate'], repoWith(undefined));
+  assert.equal(r.status, 2);
+});
+
+test('help exits 0 and prints usage', () => {
+  const r = kg(['help'], repoWith(undefined));
+  assert.equal(r.status ?? 0, 0);
+  assert.match(r.stdout, /maude kg <verb>/);
+});
+
+test('passthrough strips the maude-owned --root flag from the kg argv', () => {
+  // A stub kg that echoes its argv so we can assert --root never leaks through.
+  const root = repoWith({ mode: 'on' });
+  const stub = join(root, 'kg-stub.sh');
+  writeFileSync(stub, '#!/usr/bin/env bash\necho "ARGV:$*"\n');
+  spawnSync('chmod', ['+x', stub]);
+  const r = spawnSync('node', [MAUDE_BIN, 'kg', 'context', '--root', root, '--about', 'x'], {
+    cwd: root,
+    encoding: 'utf8',
+    env: { ...process.env, NO_COLOR: '1', KGAI_BIN: stub },
+  });
+  assert.equal(r.status ?? 0, 0, r.stderr);
+  assert.match(r.stdout, /ARGV:context --about x/);
+  assert.doesNotMatch(r.stdout, /--root/);
+});