sonorance 0.1.0-beta.4.1

package/src/cli.mjs

@@ -0,0 +1,315 @@
+#!/usr/bin/env node
+/**
+ * cli.mjs — the Sonorance CLI. Subcommands:
+ *   serve [<folder>] [--port <n>] [--open]     run the editor over a folder (default: cwd)
+ *   comment list                               the open comments from a running editor (as JSON)
+ *   comment <id> resolve [--note "<t>"] [--revised]   mark a comment resolved (back to the editor)
+ *   source [list | add <location> ["<d>"] | remove <location>]   the shared grounding sources
+ *   install-skill [--project <dir> | --here]   install the /sonorance skill into a harness
+ *
+ * The comment bridge (`comment list` / `comment <id> resolve`) are HTTP clients of the running
+ * server; the port is discovered from the `.sonorance/local/serve.json` the server writes on
+ * `serve`. Standalone, no host.
+ */
+import { resolve as pathResolve, join, dirname } from 'node:path';
+import { readFileSync, existsSync, writeFileSync, mkdirSync, cpSync, realpathSync } from 'node:fs';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { spawn } from 'node:child_process';
+import { homedir } from 'node:os';
+import { ensureGitignore } from './gitignore.mjs';
+import { createRegistry } from './vault-registry.mjs';
+import { parseSources, serializeSources } from './sources.mjs';
+import { configureTelemetry, refreshTelemetry, emit, telemetry, telemetryMode, telemetryPreview, readAudit, shutdownTelemetry, flushTelemetry, resolveTransport } from './telemetry.mjs';
+import { installId, ensureInstallId, resetInstallId, getConsent, setConsent } from './identity.mjs';
+import { CommentClientError, fetchCommentBatch, resolveComment } from './comment-client.mjs';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const VERSION = (() => { try { return String(JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8')).version || '0'); } catch { return '0'; } })();
+const A = process.argv.slice(2);
+const cmd = A[0];
+const rest = A.slice(1);
+const P = (...a) => console.log(...a);
+const opt = (f) => { const i = A.indexOf(f); return i >= 0 ? A[i + 1] : null; };
+// Flags that consume the next token as their value — so it isn't mistaken for a positional.
+const VALUE_FLAGS = new Set(['--name', '--port', '--project', '--note', '--section']);
+// Positional args from `rest`, skipping flags and the values that follow value-flags.
+function positionals() {
+  const out = [];
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a.startsWith('--')) { if (VALUE_FLAGS.has(a)) i++; continue; }
+    out.push(a);
+  }
+  return out;
+}
+
+// ---- shared config helpers (the hidden `.sonorance/` platform dir at the folder root) ----
+const sonoranceDir = (root) => join(root, '.sonorance');
+const readJson = (p) => { try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return {}; } };
+
+// A recorded server process is only trustworthy if it's still alive: `process.kill(pid, 0)`
+// probes liveness without signalling. Lenient — only a definitively-dead pid (ESRCH) is
+// rejected; a missing/opaque pid is trusted (backward compatible), so a stale serve.json left
+// behind by a crashed server no longer points `address`/`resolve` at a dead port.
+function pidAlive(pid) {
+  if (!Number.isInteger(pid)) return true;
+  try { process.kill(pid, 0); return true; } catch (e) { return e.code !== 'ESRCH'; }
+}
+// Discover the running editor's port: the `.sonorance/local/serve.json` it wrote in the cwd, else --port, else default.
+function discoverPort() {
+  try { const j = JSON.parse(readFileSync(join(process.cwd(), '.sonorance', 'local', 'serve.json'), 'utf8')); if (j && j.port && pidAlive(j.pid)) return +j.port; } catch { /* none */ }
+  return +opt('--port') || 7777;
+}
+const apiUrl = (p) => `http://localhost:${discoverPort()}${p}`;
+
+async function serve() {
+  const { startServer } = await import('./server/index.mjs');
+  const { resolveEngine } = await import('./plugins.mjs');
+  let port, open = false, dir;
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === '--open') open = true;
+    else if (a === '--port') port = +rest[++i];
+    else if (!a.startsWith('--') && !dir) dir = a;
+  }
+  const root = pathResolve(dir || process.cwd());
+  const engine = await resolveEngine(root);              // load the vault's plugin flavor (or the generic editor)
+  const { port: bound } = await startServer(Number.isFinite(port) ? { engine, port } : { engine });
+  const u = `http://localhost:${bound}`;
+  P(`Sonorance → ${u}`);
+  P(`  folder: ${root}`);
+  if (open) {
+    const c = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
+    const args = process.platform === 'win32' ? ['/c', 'start', '', u] : [u];
+    try { spawn(c, args, { stdio: 'ignore', detached: true }).unref(); } catch { /* best-effort */ }
+  }
+  P('  Ctrl-C to stop.');
+}
+
+// The comment bridge — a machine surface over the running editor:
+//   comment list                → the open in-record comments as JSON (always JSON; the skill parses it)
+//   comment <id> resolve [...]   → mark one comment resolved back to the editor
+// The port is auto-discovered from `.sonorance/local/serve.json` — no host, no port flag.
+async function comment() {
+  const [a, b] = positionals();
+  if (!a || a === 'list') return commentList();
+  if (b === 'resolve') return commentResolve(a);
+  return P('usage: sonorance comment <list | <id> resolve [--note "<text>"] [--revised]>');
+}
+
+async function commentList() {
+  const j = await fetchCommentBatch(
+    apiUrl('/api/address'),
+    `could not reach Sonorance on port ${discoverPort()} — is it running? (sonorance serve)`,
+  );
+  return P(JSON.stringify(j));
+}
+
+async function commentResolve(id) {
+  const body = { commentId: id, revised: A.includes('--revised') };
+  const note = opt('--note'); if (note) body.note = note;
+  await resolveComment(
+    apiUrl('/api/resolve'),
+    body,
+    `could not reach Sonorance on port ${discoverPort()} — is it running? (sonorance serve)`,
+  );
+  return P(`✓ resolved comment ${id}`);
+}
+
+// `init` — scaffold a Sonorance project in a folder: the hidden `.sonorance/config.json` (the
+// ONE per-vault file — identity + sources + settings). This is the PLATFORM-level init; a skill
+// like Deliberate layers its own `deliberate/…` content on top and its engine pointer (`deliberate init`).
+function init() {
+  const dir = pathResolve(positionals()[0] || process.cwd());
+  const sd = sonoranceDir(dir);
+  mkdirSync(sd, { recursive: true });
+  const cfgPath = join(sd, 'config.json');
+  const fresh = !readJson(cfgPath).id;
+  // register writes identity (id/name/created_at) into .sonorance/config.json (merge-safe) and
+  // makes this the current vault in the global ~/.sonorance registry.
+  createRegistry().register(dir, { name: opt('--name') || undefined });
+  const sourcesPath = join(sd, 'sources.md');
+  if (!existsSync(sourcesPath)) writeFileSync(sourcesPath, serializeSources([]));
+  // Committed config (identity · sources · plugins) stays in git; only machine-local runtime
+  // state under `.sonorance/local/` is ignored.
+  const ignored = ensureGitignore(dir, ['.sonorance/local/']);
+  P(`${fresh ? '✓ initialized' : '✓ already a'} Sonorance project → ${dir}`);
+  P(`  config: .sonorance/config.json  (identity · settings, committed)`);
+  P(`  sources: .sonorance/sources.md  (grounding, hand-editable, committed)`);
+  if (ignored.length) P(`  gitignore: added ${ignored.join(', ')}`);
+  P(`  next → add grounding: sonorance source add <location>`);
+  P(`         open it:        sonorance serve`);
+}
+
+// `open` — register an existing folder as a vault in the global `~/.sonorance` registry and make
+// it current, so it shows up in the app's vault switcher.
+// Unlike `init` it assumes the folder already exists; it writes `.sonorance/config.json` if absent.
+function openCmd() {
+  const dir = pathResolve(positionals()[0] || process.cwd());
+  if (!existsSync(dir)) return P(`no such folder: ${dir}`);
+  const v = createRegistry().register(dir, { name: opt('--name') || undefined });
+  P(`✓ opened vault → ${v.dir}`);
+  P(`  it's now current — run \`sonorance serve\` here, or switch to it in the app's vault switcher.`);
+}
+
+// `source` — manage the shared grounding sources, stored in the hand-editable
+// `.sonorance/sources.md`. Platform-level, so every skill running on the project can read them.
+//   source list | source add <location> ["<description>"] [--section <section>] | source remove <location>
+function source() {
+  const dir = process.cwd();
+  const mdPath = join(sonoranceDir(dir), 'sources.md');
+  const read = () => { try { return parseSources(readFileSync(mdPath, 'utf8')); } catch { return []; } };
+  const write = (list) => { mkdirSync(dirname(mdPath), { recursive: true }); writeFileSync(mdPath, serializeSources(list)); };
+  const pos = positionals();
+  const sub = pos[0];
+  const args = pos.slice(1);
+  if (sub === 'add') {
+    const location = args[0]; if (!location) return P('usage: sonorance source add <location> ["<description>"] [--section <section>]');
+    const list = read();
+    if (!list.some(s => s.location === location)) list.push({ location, description: args.slice(1).join(' '), section: opt('--section') || 'other' });
+    write(list); return P(`✓ added source ${location}`);
+  }
+  if (sub === 'remove' || sub === 'rm') {
+    const location = args[0]; if (!location) return P('usage: sonorance source remove <location>');
+    write(read().filter(s => s.location !== location)); return P(`✓ removed source ${location}`);
+  }
+  const list = read();
+  if (!list.length) return P('no sources — add one with `sonorance source add <location>`');
+  let section = null;
+  for (const s of list) {
+    if (s.sectionTitle !== section) { section = s.sectionTitle; P(`${section}:`); }
+    P(`- ${s.location}${s.description ? `  (${s.description})` : ''}`);
+  }
+}
+
+function installSkill() {
+  const src = join(here, '..', 'skill');
+  if (!existsSync(src)) return P(`skill source not found at ${src}`);
+  const projectDir = opt('--project') || (A.includes('--here') ? process.cwd() : (positionals()[0] || null));
+  const project = !!projectDir;
+  const dest = project ? join(pathResolve(projectDir), '.github', 'skills', 'sonorance') : join(homedir(), '.copilot', 'skills', 'sonorance');
+  mkdirSync(dirname(dest), { recursive: true });
+  cpSync(src, dest, { recursive: true });
+  // Bake this checkout's CLI path so the launcher resolves it without a global install.
+  const engineFile = fileURLToPath(new URL('./cli.mjs', import.meta.url));
+  writeFileSync(join(dest, 'scripts', 'engine.json'), JSON.stringify({ engine: engineFile }, null, 2) + '\n');
+  P(`✓ installed the /sonorance skill (${project ? 'project' : 'global'}) → ${dest}`);
+  P(`  open a folder in your coding agent, run \`sonorance serve\`, leave comments, then /sonorance address`);
+}
+
+export const dispatch = { init, open: openCmd, source, serve, comment, telemetry: telemetryCmd, 'install-skill': installSkill };
+
+// `sonorance telemetry [status|on|off|show|reset-id|test]` — inspect and control the anonymous,
+// content-free product telemetry. This is the standalone/CLI surface for the opt-out switch; the
+// UI has an equivalent settings control, and both resolve the same ~/.sonorance consent.
+async function telemetryCmd() {
+  const [sub] = positionals();
+  configureTelemetry({ surface: 'cli', product: 'sonorance', version: VERSION, vaultDir: process.cwd() });
+  const shortId = () => (installId() || '').slice(0, 8);
+  switch (sub || 'status') {
+    case 'status': {
+      const active = telemetryMode() !== 'off';
+      const consent = getConsent();
+      const choice = consent === undefined ? 'default on (opt-out)' : (consent ? 'on' : 'off');
+      const transport = resolveTransport();
+      P(`telemetry: ${active ? 'on' : 'off'} (mode: ${telemetryMode()}, consent: ${choice})`);
+      P(`  install id: ${shortId()}…`);
+      P(`  destination: ${transport.label}`);
+      P(`  audit log:  ~/.sonorance/telemetry.jsonl  (sonorance telemetry show)`);
+      P(`  it is anonymous and content-free — never prompts, completions, or file contents.`);
+      break;
+    }
+    case 'on': {
+      setConsent(true);
+      refreshTelemetry();
+      emit('telemetry.enabled', {});
+      await flushTelemetry();
+      P('✓ telemetry on — thank you; it helps shape what to build next. Turn it off anytime with `sonorance telemetry off`.');
+      break;
+    }
+    case 'off': {
+      emit('telemetry.disabled', {});                     // record the opt-out itself, while still on
+      await flushTelemetry();
+      setConsent(false);
+      refreshTelemetry();
+      P('✓ telemetry off — nothing further will be sent from this machine.');
+      break;
+    }
+    case 'show': {
+      const rows = await readAudit(50);
+      if (!rows.length) { P('(no telemetry recorded yet)'); break; }
+      P(`last ${rows.length} events (from ~/.sonorance/telemetry.jsonl):`);
+      for (const r of rows) {
+        const when = typeof r.ts === 'number' ? new Date(r.ts).toISOString() : (r.ts || '');
+        P(`  ${when}  ${r.type || r.name || ''}`);
+      }
+      break;
+    }
+    case 'reset-id': {
+      const id = resetInstallId();
+      P(`✓ rotated install id → ${id.slice(0, 8)}… (prior history is now unlinkable)`);
+      break;
+    }
+    case 'test': {
+      // Local pipeline check: mint a sample event and print (or send) exactly what would leave over
+      // the active transport (Azure Monitor by default, OTLP if configured, or local-only).
+      emit('session.start', {});
+      emit('command.run', { name: 'telemetry-test', ok: true, duration_ms: 0 });
+      const pv = telemetryPreview();
+      P(`telemetry test — mode: ${telemetryMode()}, destination: ${pv.transport.label}`);
+      P(`  buffered ${pv.count} record(s). To watch the raw payload locally, set SONORANCE_TELEMETRY=console.`);
+      if (telemetryMode() === 'off') {
+        P('  telemetry is off — run `sonorance telemetry on` (or set SONORANCE_TELEMETRY=console) first.');
+      } else if (telemetryMode() === 'console') {
+        await flushTelemetry();
+        P('  ✓ printed above in console mode (nothing sent over the network).');
+      } else if (pv.transport.kind === 'none') {
+        P('  no destination configured — set APPLICATIONINSIGHTS_CONNECTION_STRING (Azure Monitor) or');
+        P('  SONORANCE_OTLP_ENDPOINT (a collector / OTLP backend). Everything is still kept locally.');
+      } else {
+        const res = await flushTelemetry();
+        P(res && res.ok
+          ? `  ✓ reached ${pv.transport.label} (HTTP ${res.status}) — check your destination.`
+          : `  ✗ could not reach ${pv.transport.label} (${(res && (res.error || res.status)) || 'unknown'}). Everything is still kept locally.`);
+      }
+      break;
+    }
+    default:
+      P('usage: sonorance telemetry [status | on | off | show | reset-id | test]');
+  }
+}
+
+// Only dispatch when run as the entry point (`sonorance <cmd>`); importing this module to inspect
+// `dispatch` must have no side effects.
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+  const run = dispatch[cmd];
+  if (!run) {
+    P('usage: sonorance <init|open|serve|source|comment|telemetry|install-skill>');
+  } else if (cmd === 'serve' || cmd === 'telemetry') {
+    // `serve` is the surface=ui process (the server configures telemetry); `telemetry` is the
+    // control surface itself — neither is wrapped as a plain `command.run`.
+    await run();
+  } else {
+    const freshInstall = ensureInstallId().fresh;           // capture BEFORE configure (which mints the id)
+    configureTelemetry({ surface: 'cli', product: 'sonorance', version: VERSION, vaultDir: process.cwd() });
+    if (freshInstall) emit('install.created', {});
+    emit('session.start', {});
+    const t0 = Date.now();
+    let ok = true;
+    try {
+      await run();
+    } catch (err) {
+      ok = false;
+      try { emit('error', { command: cmd, class: (err && err.constructor && err.constructor.name) || 'Error' }); } catch { /* never let telemetry break the CLI */ }
+      if (err instanceof CommentClientError) {
+        process.stderr.write(`${err.message}\n`);
+        process.exitCode = 1;
+      } else {
+        throw err;
+      }
+    } finally {
+      try { emit('command.run', { name: cmd, ok, duration_ms: Date.now() - t0 }); } catch { /* ignore */ }
+      await shutdownTelemetry();
+    }
+  }
+}

package/src/comment-client.mjs

@@ -0,0 +1,75 @@
+export class CommentClientError extends Error {}
+
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const isComment = (comment) => {
+  if (!isObject(comment)
+    || typeof comment.id !== 'string'
+    || !comment.id.trim()
+    || typeof comment.file !== 'string'
+    || !comment.file.trim()
+    || typeof comment.body !== 'string'
+    || !comment.body.trim()
+    || !isObject(comment.anchor)
+    || typeof comment.anchor.quote !== 'string'
+    || typeof comment.anchor.heading !== 'string'
+    || (comment.addressing !== undefined && typeof comment.addressing !== 'string')
+    || (comment.ts !== undefined && !Number.isFinite(comment.ts))) return false;
+  const hasTextAnchor = Boolean(comment.anchor.quote.trim() || comment.anchor.heading.trim());
+  if (comment.anchor.line === undefined) return comment.anchor.endLine === undefined && hasTextAnchor;
+  return Number.isInteger(comment.anchor.line)
+    && comment.anchor.line >= 0
+    && Number.isInteger(comment.anchor.endLine)
+    && comment.anchor.endLine >= comment.anchor.line;
+};
+
+async function responseJson(url, init, operation, unavailableMessage) {
+  let response;
+  try {
+    response = await fetch(url, init);
+  } catch {
+    throw new CommentClientError(unavailableMessage);
+  }
+  if (!response.ok) throw new CommentClientError(`${operation} failed: app returned HTTP ${response.status}`);
+  try {
+    return await response.json();
+  } catch {
+    throw new CommentClientError(`${operation} failed: app returned an invalid response`);
+  }
+}
+
+export async function fetchCommentBatch(url, unavailableMessage) {
+  const payload = await responseJson(url, undefined, 'comment list', unavailableMessage);
+  if (isObject(payload) && payload.error) throw new CommentClientError(`comment list failed: ${payload.error}`);
+  if (!isObject(payload)
+    || !Array.isArray(payload.comments)
+    || !Number.isInteger(payload.count)
+    || payload.count !== payload.comments.length
+    || payload.comments.some(comment => !isComment(comment))) {
+    throw new CommentClientError('comment list failed: app returned an invalid response');
+  }
+  return payload;
+}
+
+export async function fetchCommentProject(url, unavailableMessage) {
+  const payload = await responseJson(url, undefined, 'project check', unavailableMessage);
+  if (!isObject(payload)
+    || !isObject(payload.project)
+    || typeof payload.project.id !== 'string'
+    || !payload.project.id.trim()
+    || typeof payload.project.dir !== 'string'
+    || !payload.project.dir.trim()) {
+    throw new CommentClientError('project check failed: app is serving a different or invalid project');
+  }
+  return payload.project;
+}
+
+export async function resolveComment(url, body, unavailableMessage) {
+  const payload = await responseJson(url, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  }, 'resolve', unavailableMessage);
+  if (!isObject(payload)) throw new CommentClientError('resolve failed: app returned an invalid response');
+  if (payload.ok !== true) throw new CommentClientError(`resolve failed: ${payload.error || 'unknown'}`);
+  return payload;
+}

package/src/engine-default.mjs

@@ -0,0 +1,136 @@
+/**
+ * engine-default.mjs — the app's built-in GENERIC engine, so it runs standalone as a plain
+ * Markdown file viewer/editor over any folder, with no host (no Deliberate) required.
+ *
+ * A host (e.g. the `deliberate` package) injects a richer engine to light up cases, briefs,
+ * scores and the inbox. With this default there are no such concepts: every `.md` under the
+ * current vault is just a file the tree lists and the editor edits. It implements the exact
+ * surface `startServer` needs — the store methods the routes call plus the project resolvers,
+ * funnel constants (empty), the kind registry (empty), and a console logger.
+ *
+ * Multiple vaults + switching are delegated to the shared `vault-registry`: the registry owns
+ * the list of known folders and which is current at
+ * `~/.sonorance/config.json`; this engine reads the current vault dynamically, so `/api/switch`
+ * and "Open folder…" work without restarting the daemon. Per-vault state (comments, tabs,
+ * Explorer) lives in that vault's own `.sonorance/`.
+ *
+ * Usage:  startServer({ engine: makeDefaultEngine(rootDir) })
+ */
+import { readFileSync, writeFileSync, renameSync, mkdirSync } from 'node:fs';
+import { join, dirname, isAbsolute, relative, sep } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { createRegistry } from './vault-registry.mjs';
+
+const now = () => Date.now();
+const randId = () => 'c' + randomBytes(5).toString('hex');
+const ensureDir = (d) => mkdirSync(d, { recursive: true });
+// Write a file atomically (temp file + rename) so a crash mid-write can never leave a
+// truncated/corrupt `.sonorance/` state file — readers always see the old or the new whole.
+const atomicWrite = (path, data) => { const tmp = `${path}.tmp-${process.pid}`; writeFileSync(tmp, data); renameSync(tmp, path); };
+
+// A generic, MULTI-VAULT store: comments + per-vault config live in the current vault's hidden
+// `.sonorance/` dir; everything case/brief/stage-shaped returns empty (this host has none of
+// those). The active folder is resolved from the registry on every call, so a project switch
+// (which just moves the registry's `current` pointer) is picked up with no restart.
+function makeStore(registry, root) {
+  // THIS store's own current-vault pointer. It lives on the store (not the engine) because the
+  // server keeps a single module-global engine `E` but a per-server `store` closure — so routes
+  // resolve the right vault via the store even when several servers share one process (tests).
+  // Serving a folder makes it current here; switching / opening moves it.
+  let currentDir = root ? registry.register(root, { makeCurrent: true }).dir : (registry.current()?.dir || null);
+  // The folder a request targets. The server passes the current project's id, so a bare pid
+  // resolves via the registry; fall back to THIS store's current dir.
+  const dirFor = (pid) => (pid && registry.get(pid)?.dir) || currentDir;
+  const stateDir = (dir) => join(dir, '.sonorance', 'local');
+
+  const relFile = (pid, file) => {
+    const root = dirFor(pid); if (!root || !file) return null;
+    const abs = isAbsolute(file) ? file : join(root, file);
+    const rel = relative(root, abs).split(sep).join('/');
+    if (!rel || rel.startsWith('..') || isAbsolute(rel)) return null;
+    return rel;
+  };
+  const commentsPathFor = (pid) => { const d = dirFor(pid); return d ? join(stateDir(d), 'comments.jsonl') : null; };
+  const statePathFor = (pid) => { const d = dirFor(pid); return d ? join(stateDir(d), 'state.json') : null; };
+  const readComments = (pid) => {
+    const p = commentsPathFor(pid); if (!p) return [];
+    try { return readFileSync(p, 'utf8').trim().split('\n').filter(Boolean).map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean); }
+    catch { return []; }
+  };
+  const writeComments = (pid, arr) => { const p = commentsPathFor(pid); if (!p) return; ensureDir(dirname(p)); atomicWrite(p, arr.length ? arr.map(c => JSON.stringify(c)).join('\n') + '\n' : ''); };
+  // Editor STATE (open tabs, active tab, Explorer collapse/expand) lives in
+  // `.sonorance/local/state.json`, separate from `config.json` (identity). It describes the
+  // session, not the project — it's disposable/regenerable and never needed to open a vault.
+  const readState = (pid) => { const p = statePathFor(pid); if (!p) return {}; try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return {}; } };
+  const writeState = (pid, st) => { const p = statePathFor(pid); if (!p) return; ensureDir(dirname(p)); atomicWrite(p, JSON.stringify(st, null, 2) + '\n'); };
+
+  return {
+    // ---- projects (delegated to the shared multi-vault registry) ----
+    listProjects: () => registry.list().map(v => ({ id: v.id, name: v.name, dir: v.dir, exists: v.exists })),
+    getProject: (id) => { const v = id ? registry.get(id) : registry.current(); return v ? { id: v.id, name: v.name, dir: v.dir } : undefined; },
+    // ---- editor state (open tabs / active tab / Explorer state), per-vault, in state.json ----
+    getState: (pid) => readState(pid),
+    setState: (pid, key, value) => { const c = readState(pid); c[key] = value; writeState(pid, c); },
+    // Merge many keys in ONE read-modify-write (atomic) — the buffered-flush target so a
+    // multi-key patch never does a partial series of rewrites.
+    setStateMany: (pid, patch) => { const c = readState(pid); for (const [k, v] of Object.entries(patch || {})) c[k] = v; writeState(pid, c); },
+    // ---- cases / briefs / readouts / matchups / stages: none in generic mode ----
+    listCases: () => [], listBriefs: () => [], listReadouts: () => [], listMatchups: () => [], listStages: () => [],
+    getCase: () => null, getBrief: () => null, getReadout: () => null, getMatchup: () => null,
+    recordFile: () => null, briefFilePath: () => null, readoutFilePath: () => null, matchupFilePath: () => null,
+    readRecord: () => null, writeRecord: () => false,
+    readBriefRecord: () => null, readReadoutRecord: () => null, readMatchupRecord: () => null, prototypeRef: () => null, listPrototypes: () => [],
+    // ---- files (path-relative to the current vault root) ----
+    relFile,
+    // ---- comments (file-anchored, per-vault .sonorance/local/comments.jsonl) ----
+    allComments: (pid) => readComments(pid),
+    comments: (pid, file) => { const rel = relFile(pid, file); if (!rel) return []; return readComments(pid).filter(c => c.file === rel); },
+    addComment: (pid, file, entry) => {
+      const rel = relFile(pid, file); if (!rel) return null;
+      const rec = { id: randId(), file: rel, status: 'open', ts: now(), ...entry }; rec.file = rel;
+      const all = readComments(pid); all.push(rec); writeComments(pid, all); return rec;
+    },
+    resolveComment: (pid, id, patch) => { const all = readComments(pid); let hit = null; const next = all.map(c => (c.id === id ? (hit = { ...c, ...patch }) : c)); if (!hit) return null; writeComments(pid, next); return hit; },
+    deleteComment: (pid, id) => { const all = readComments(pid); const hit = all.find(c => c.id === id); if (!hit) return null; writeComments(pid, all.filter(c => c.id !== id)); return hit; },
+    // ---- current-vault pointer (per store; the engine wrapper delegates here) ----
+    _current: () => (currentDir ? registry.get(currentDir) : registry.current()),
+    _setCurrent: (idOrDir) => { const v = registry.get(idOrDir); if (v) { currentDir = v.dir; registry.setCurrent(v.dir); } return v; },
+    _open: (dir, opts = {}) => { const v = registry.register(dir, opts); if (v && opts.makeCurrent !== false) currentDir = v.dir; return v; },
+    _remove: (idOrDir) => { registry.remove(idOrDir); return true; },
+  };
+}
+
+// Build a generic engine over `root` (the folder to view/edit). Registering `root` makes it a
+// vault and the current one; the UI can then open/switch to other registered vaults. This is
+// what standalone `serve` injects into startServer.
+export function makeDefaultEngine(root) {
+  const registry = createRegistry();
+  const store = makeStore(registry, root);
+  const toProject = (v) => (v ? { id: v.id, name: v.name, dir: v.dir, exists: v.exists } : null);
+  return {
+    openVault: () => store,
+    // ---- project resolution / switching — delegated to the per-server store ----
+    currentProject: (s) => toProject((s || store)._current()),
+    setCurrentProject: (s, idOrDir) => { (s || store)._setCurrent(idOrDir); },
+    resolveProject: (_s, idOrDir) => toProject(registry.get(idOrDir)),
+    // Open a folder as a vault (register + make current) — the UI's "Open folder…" / the
+    // `sonorance open` CLI. Returns the project.
+    openVaultFolder: (s, dir, opts = {}) => toProject((s || store)._open(dir, opts)),
+    // Forget a registered vault (the UI's Remove for a missing folder). Never deletes the folder.
+    removeProject: (s, idOrDir) => (s || store)._remove(idOrDir),
+    // The generic app serves the WHOLE folder (no `deliberate/` subfolder confinement).
+    contentDir: (project) => ({ dir: project.dir, base: '' }),
+    // Where the running server records its port for the CLI's `address`/`resolve` clients.
+    serveInfoPath: (project) => join(project.dir, '.sonorance', 'local', 'serve.json'),
+    // Machine state to keep out of git when the app initiates a project in a folder — only the
+    // hidden `.sonorance/local/` (runtime/session state); the committed config (identity,
+    // sources, plugins) at `.sonorance/` stays in git.
+    gitignoreEntries: () => ['.sonorance/local/'],
+    // No document kinds → the inbox shows a generic recent-files view / empty state.
+    KINDS: [],
+    // Logger.
+    info: (...a) => console.log(...a),
+    error: (...a) => console.error(...a),
+    installCrashHandlers: () => {},
+  };
+}