@animalabs/connectome-host 0.7.3 → 0.8.0

package/package.json

@@ -1,23 +1,23 @@
 {
   "name": "@animalabs/connectome-host",
-  "version": "0.7.3",
+  "version": "0.8.0",
   "description": "General-purpose agent TUI host with recipe-based configuration",
   "type": "module",
   "scripts": {
     "start": "bun src/index.ts",
     "dev": "bun --watch src/index.ts",
     "test": "bun test",
-    "version": "bun scripts/release-changelog.ts && git add CHANGELOG.md",
+    "version": "bun scripts/release-changelog.ts && git add CHANGELOG.md changelog.d",
     "build:web": "npm --prefix web install && npm --prefix web run build",
     "build:web:ci": "npm ci --prefix web && npm --prefix web run build",
     "relock:web": "rm -rf web/node_modules web/package-lock.json && npm --prefix web install",
     "postinstall": "test -d web && npm --prefix web install && npm --prefix web run build || true"
   },
   "dependencies": {
-    "@animalabs/agent-framework": "^0.7.2",
-    "@animalabs/chronicle": "^0.2.0",
-    "@animalabs/context-manager": "^0.6.0",
-    "@animalabs/membrane": "^0.5.77",
+    "@animalabs/agent-framework": "^0.12.0",
+    "@animalabs/chronicle": "^0.3.0",
+    "@animalabs/context-manager": "^0.6.3",
+    "@animalabs/membrane": "^0.5.82",
     "@opentui/core": "^0.1.82"
   },
   "devDependencies": {

package/recipes/SETUP.md

@@ -69,17 +69,17 @@ Works with both gitlab.com and self-hosted GitLab instances.
 
 No separate installation needed — the recipe uses `npx` to run `@zereight/mcp-gitlab` on demand.
 
-### Notion (optional, via an MCP server)
+### Notion (optional, via an MCP server — not included by default)
 
-If you want the agent to read your Notion workspace, point the recipe at any MCP server that exposes Notion search and page-read tools. The recipe's template entry is named `syncntn` after the particular Notion MCP adapter it was developed against, but the key is just a label — any Notion MCP server works, as long as its exposed tool names match what the system prompt references (`syncntn--search_pages`, `syncntn--get_page_markdown`, and friends). If your server uses different tool names, either rename the MCP key and update the prompt, or skip Notion entirely by removing the block.
+The recipe ships **without** a Notion server: the adapter its prompt was developed against (`syncntn`) is not publicly available. If you want the agent to read your Notion workspace, add an `mcpServers` entry pointing at any MCP server that exposes Notion search and page-read tools. The entry name `syncntn` is just a label — any Notion MCP server works, as long as its exposed tool names match what the system prompt references (`syncntn--search_pages`, `syncntn--get_page_markdown`, and friends). If your server uses different tool names, either name the MCP key `syncntn` and update the prompt, or accept that the agent will discover the tools under whatever names they export.
 
 Typical setup:
 
 1. Install and start your Notion MCP server somewhere the recipe can launch it.
 2. Note any configuration it needs (API credentials, workspace ID, storage URL).
-3. Fill those values into the recipe's `syncntn` env block in Step 3 below.
+3. Add a `syncntn` block with those values to the recipe in Step 3 below.
 
-Don't have a Notion MCP server? Remove the `syncntn` entry from the recipe — the agent will adapt and work with whatever sources remain.
+Don't have a Notion MCP server? Skip this — the agent adapts and works with whatever sources remain.
 
 ### DuckDuckGo web search (optional, but enabled by default)
 
@@ -98,6 +98,10 @@ cd ../connectome-host
 
 The recipe expects the entry-point script at `../duckduckgo-mcp-server/.venv/bin/duckduckgo-mcp-server`. No API key needed. Don't want public-web access? Remove the `ddg` block from the recipe.
 
+### Scribe — audio/video transcription (optional, not included by default)
+
+The miner's prompt also knows how to drive [`dariakroshka/scribe-mcp`](https://github.com/dariakroshka/scribe-mcp) for transcribing recordings. It needs a Gemini API key (media is uploaded to Google's Gemini API) and a sibling checkout, so the shipped recipe omits it. To enable: clone scribe-mcp as a sibling of `connectome-host/`, run `bun install` in it, add a `scribe` block under `mcpServers` (see the [Triumvirate guide's Scribe section](./TRIUMVIRATE-SETUP.md#scribe--audiovideo-transcription-optional-off-by-default) for the exact JSON), and set `GEMINI_API_KEY` in `.env`.
+
 ## Step 3: Configure the recipe
 
 Copy the template recipe and fill in your credentials:
@@ -120,8 +124,10 @@ Edit `my-recipe.json` and replace the placeholder values in `mcpServers`:
         "ZULIP_RC_PATH": "./.zuliprc"          // path to your .zuliprc
       }
     },
+    // Optional — NOT in the shipped recipe. Add only if you set up a
+    // Notion MCP server (see Step 2 above):
     "syncntn": {
-      "command": "../syncntn/services/mcp/start_mcp_local.sh",
+      "command": "../your-notion-mcp/start.sh",
       "env": {
         "STORAGE_URL": "http://localhost:8000",
         "WORKSPACE_ID": "YOUR_WORKSPACE_ID"    // <-- replace this

package/recipes/TRIUMVIRATE-SETUP.md

@@ -138,23 +138,26 @@ ANTHROPIC_API_KEY=sk-ant-...
 ZULIP_CHANNEL=your-channel-name
 ```
 
-Optional — **only** if you want the miner to extract from those sources (otherwise remove the relevant `mcpServers` block from `recipes/knowledge-miner.json` and skip these):
+Optional — **only** if you want the miner to extract from GitLab (otherwise remove the `gitlab` block from `recipes/knowledge-miner.json` and skip these):
 
 ```ini
 # GitLab (knowledge-miner.json: gitlab)
 GITLAB_TOKEN=glpat-...
 GITLAB_API_URL=https://gitlab.example.com/api/v4
+```
 
-# Notion (knowledge-miner.json: syncntn)
-NOTION_STORAGE_URL=http://localhost:8000
-NOTION_WORKSPACE_ID=...
+Optional — the conductor's web UI is protected by Basic-Auth that defaults to `admin` / `admin`. Fine for a laptop; **change it** the moment the machine is reachable by anyone else:
+
+```ini
+WEBUI_USERNAME=...
+WEBUI_PASSWORD=...
 ```
 
 Bun auto-loads `.env`, so nothing else to wire. If a recipe references a `${VAR}` you haven't set, the child's startup will fail with a clear message telling you which variable is missing and which recipe referenced it.
 
 ## Step 6: Decide which data sources you want
 
-The miner child uses `recipes/knowledge-miner.json`, which comes pre-wired to talk to **Zulip, Notion, GitLab, and DuckDuckGo** (public web). The recipe itself references credentials via `${VAR}` placeholders — you don't edit the recipe to fill in secrets; you set the env vars in Step 5 and the framework substitutes at load time.
+The miner child uses `recipes/knowledge-miner.json`, which comes pre-wired to talk to **Zulip, GitLab, and DuckDuckGo** (public web); **Notion** and **Scribe** (audio/video transcription) connections can be added — see their subsections below. The recipe itself references credentials via `${VAR}` placeholders — you don't edit the recipe to fill in secrets; you set the env vars in Step 5 and the framework substitutes at load time.
 
 You decide which sources are active by whether you **set the matching env vars** and whether you **keep the matching mcpServers block in the recipe**.
 
@@ -175,17 +178,29 @@ No separate install — the recipe runs `npx @zereight/mcp-gitlab` on demand.
 
 To disable: remove the `gitlab` block from `recipes/knowledge-miner.json`. If you leave it in but don't set the env vars, the child will fail to start with a message like `Recipe "recipes/knowledge-miner.json" references environment variable ${GITLAB_TOKEN} which is not set.` — that's the system telling you to either fill in the env var or delete the block.
 
-### Notion (optional)
+### Notion (optional, off by default)
+
+The recipe ships **without** a Notion server — the adapter it was developed against (`syncntn`) is not publicly available, so a default block would only produce a startup failure. The miner's system prompt still describes the `syncntn--*` tools; the agent simply won't have them until you wire a server in.
 
-To enable: install a Notion MCP server (the recipe's template is named `syncntn`; any MCP server with matching tool names works — see [SETUP.md → Notion](./SETUP.md#notion-optional-via-an-mcp-server) for selection caveats) and set:
+To enable: install a Notion MCP server (any server whose tool names match what the prompt references — see [SETUP.md → Notion](./SETUP.md#notion-optional-via-an-mcp-server) for selection caveats), then add a block to `recipes/knowledge-miner.json` under `mcpServers`:
+
+```jsonc
+"syncntn": {
+  "command": "../your-notion-mcp/start.sh",   // however your server is launched
+  "env": {
+    "STORAGE_SERVICE_URL": "${NOTION_STORAGE_URL}",
+    "WORKSPACE_ID": "${NOTION_WORKSPACE_ID}"
+  }
+}
+```
+
+and set the referenced vars in `.env`:
 
 ```ini
 NOTION_STORAGE_URL=http://localhost:8000
 NOTION_WORKSPACE_ID=...
 ```
 
-To disable: remove the `syncntn` block from `recipes/knowledge-miner.json`. Same behavior as above — unset env + kept block = startup failure with a clear message.
-
 ### DuckDuckGo web search (optional, enabled by default)
 
 The miner is wired to [`nickclyde/duckduckgo-mcp-server`](https://github.com/nickclyde/duckduckgo-mcp-server) as `ddg`. No API key — DuckDuckGo's public HTML search, scraped at request time.
@@ -207,14 +222,51 @@ Web hits get tagged `[WEB: <url>]` in mined reports — internal `[SRC]` always
 
 To disable: remove the `ddg` block from `recipes/knowledge-miner.json`. The agent will skip the public web.
 
+### Scribe — audio/video transcription (optional, off by default)
+
+The miner's prompt knows how to use [`dariakroshka/scribe-mcp`](https://github.com/dariakroshka/scribe-mcp) to transcribe recordings (via Google's Gemini API — media leaves your machine). The recipe ships without the block: it requires a Gemini API key and a sibling checkout, neither of which a demo should demand.
+
+To enable: install the server as a sibling of `connectome-host/`:
+
+```bash
+cd ..
+git clone https://github.com/dariakroshka/scribe-mcp.git
+cd scribe-mcp
+bun install
+cd ../connectome-host
+```
+
+then add this block to `recipes/knowledge-miner.json` under `mcpServers`:
+
+```jsonc
+"scribe": {
+  "command": "bun",
+  "args": ["../scribe-mcp/src/index.ts"],
+  "env": {
+    "GEMINI_API_KEY": "${GEMINI_API_KEY}",
+    "NOTION_API_KEY": "${NOTION_API_KEY:-}",           // only scribe--scribe_notion_page needs it
+    "SCRIBE_GLOSSARY_PATH": "./input/glossary.txt",
+    "SCRIBE_GLOSSARY_URL": "${SCRIBE_GLOSSARY_URL:-}"  // optional domain glossary
+  },
+  "source": {
+    "url": "https://github.com/dariakroshka/scribe-mcp.git",
+    "install": { "runtime": "bun", "run": "bun install --frozen-lockfile" },
+    "inContainer": { "path": "/scribe-mcp" }
+  }
+}
+```
+
+and set `GEMINI_API_KEY=...` in `.env`.
+
 ### Summary table
 
-| Source | Keep the block in recipe? | Env vars needed |
+| Source | Block in recipe? | Env vars needed |
 |---|---|---|
-| Zulip | Yes | (configured via `.zuliprc`, no `${VAR}`) |
-| GitLab | Yes if using, remove otherwise | `GITLAB_TOKEN`, `GITLAB_API_URL` |
-| Notion | Yes if using, remove otherwise | `NOTION_STORAGE_URL`, `NOTION_WORKSPACE_ID` |
-| DuckDuckGo | Yes if you want public web search, remove otherwise | none (no API key) |
+| Zulip | Yes (default) | (configured via `.zuliprc`, no `${VAR}`) |
+| GitLab | Yes (default) — remove if not using | `GITLAB_TOKEN`, `GITLAB_API_URL` |
+| Notion | **No** — add a `syncntn` block if using | `NOTION_STORAGE_URL`, `NOTION_WORKSPACE_ID` |
+| DuckDuckGo | Yes (default) — remove if not using | none (no API key) |
+| Scribe | **No** — add a `scribe` block if using | `GEMINI_API_KEY` (+ optional `NOTION_API_KEY`, `SCRIBE_GLOSSARY_URL`) |
 
 ### Tweaks you can still make to the recipe files
 
@@ -237,6 +289,8 @@ What you'll see:
 3. Press **Tab** a couple of times to cycle through view modes. One of them is the **process fleet** view — it lists the three children and their status. All three should reach **ready** (green). If any show **crashed** (red), jump to Troubleshooting.
 4. Ask the conductor `are all three ready?` — it'll run `fleet--list` and confirm. This also serves as a quick "am I set up correctly" smoke test.
 
+The conductor also serves a **web UI** on port 7340 (all interfaces, Basic-Auth). Credentials default to `admin` / `admin` unless you set `WEBUI_USERNAME` / `WEBUI_PASSWORD` in `.env` — see Step 5. Open `http://localhost:7340` to watch the fleet from a browser.
+
 ### The four view modes
 
 Press **Tab** to cycle between views. Press **Ctrl+F** to jump straight to the process fleet view from anywhere.

package/recipes/knowledge-miner.json

@@ -32,13 +32,6 @@
         }
       }
     },
-    "syncntn": {
-      "command": "../syncntn/services/mcp/start_mcp_local.sh",
-      "env": {
-        "STORAGE_SERVICE_URL": "${NOTION_STORAGE_URL}",
-        "WORKSPACE_ID": "${NOTION_WORKSPACE_ID}"
-      }
-    },
     "gitlab": {
       "command": "npx",
       "args": [
@@ -66,29 +59,6 @@
           "path": "/duckduckgo-mcp-server"
         }
       }
-    },
-    "scribe": {
-      "command": "bun",
-      "args": [
-        "../scribe-mcp/src/index.ts"
-      ],
-      "env": {
-        "GEMINI_API_KEY": "${GEMINI_API_KEY}",
-        "NOTION_API_KEY": "${NOTION_API_KEY:-}",
-        "SCRIBE_GLOSSARY_PATH": "./input/glossary.txt",
-        "SCRIBE_GLOSSARY_URL": "${SCRIBE_GLOSSARY_URL:-}"
-      },
-      "source": {
-        "url": "https://github.com/dariakroshka/scribe-mcp.git",
-        "ref": "828ae8ba6ea83ce439ce6ba020ed0223cf096f82",
-        "install": {
-          "runtime": "bun",
-          "run": "bun install --frozen-lockfile"
-        },
-        "inContainer": {
-          "path": "/scribe-mcp"
-        }
-      }
     }
   },
   "modules": {

package/recipes/mock-test.json

@@ -0,0 +1,19 @@
+{
+  "name": "Mock Test",
+  "description": "Zero-cost offline smoke recipe: membrane's mock adapter, no API key, no provider spend. Echoes your messages back through the full host loop.",
+  "agent": {
+    "name": "agent",
+    "provider": "mock",
+    "systemPrompt": "You are a mock agent for offline host testing."
+  },
+  "modules": {
+    "subagents": false,
+    "lessons": false,
+    "retrieval": false,
+    "wake": false,
+    "workspace": false,
+    "webui": {
+      "host": "127.0.0.1"
+    }
+  }
+}

package/recipes/triumvirate.json

@@ -22,7 +22,12 @@
     "retrieval": false,
     "wake": true,
     "workspace": false,
-    "webui": true,
+    "webui": {
+      "basicAuth": {
+        "username": "${WEBUI_USERNAME:-admin}",
+        "password": "${WEBUI_PASSWORD:-admin}"
+      }
+    },
     "fleet": {
       "children": [
         {

package/scripts/audit-module-optins.ts

@@ -0,0 +1,288 @@
+/**
+ * Report-only audit of subagents/lessons/retrieval opt-ins across recipes.
+ *
+ * Background: published v0.7.2 and earlier treated these three modules as
+ * opt-OUT (an omitted `modules` key meant enabled), and DEFAULT_RECIPE
+ * enabled all three explicitly. Current main treats them as opt-IN
+ * (a4bd9fd). That flip is the right default, but it leaves existing
+ * deployments with two things only a human can settle:
+ *
+ *   1. A source recipe that explicitly says `lessons: true` stays enabled
+ *      after upgrade — intentionally. Whether that `true` was a real choice
+ *      or boilerplate copied from the old onboarding guide is not something
+ *      a defaults change (or this script) can infer. It gets reported;
+ *      the operator decides.
+ *   2. A persisted `data/.recipe.json` is a resolved snapshot of whatever
+ *      was in effect at launch — under the old defaults that includes
+ *      `subagents/lessons/retrieval: true` the operator never wrote. It is
+ *      not necessarily the authoritative source recipe, so it's reported
+ *      separately, as a pointer back to the source, never as a finding in
+ *      itself.
+ *
+ * This script reads and reports. It never modifies a file, and it has no
+ * flag that would make it modify a file.
+ *
+ * Usage:
+ *   bun scripts/audit-module-optins.ts <recipe.json | directory> [...more]
+ *
+ * Directories are scanned recursively for *.json (including .recipe.json
+ * snapshots; node_modules/.git skipped). Fleet children referenced by
+ * local path are followed automatically.
+ *
+ * Exit codes: 0 = nothing needs an operator decision; 2 = explicit enables
+ * (or inert-retrieval combinations) found — review the report; 1 = a path
+ * argument could not be read.
+ */
+
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
+
+export const AUDITED_MODULES = ['subagents', 'lessons', 'retrieval'] as const;
+export type AuditedModule = (typeof AUDITED_MODULES)[number];
+
+export type ModuleState = 'explicit-enable' | 'explicit-disable' | 'omitted';
+
+export interface RecipeAudit {
+  /** Path as reported (relative to cwd where possible). */
+  path: string;
+  recipeName: string;
+  /** basename === '.recipe.json': a resolved launch snapshot, not a source. */
+  isSnapshot: boolean;
+  states: Record<AuditedModule, ModuleState>;
+  /** Snapshot has all three explicitly true — the old DEFAULT_RECIPE shape.
+   *  Almost certainly captured pre-flip defaults, not an operator choice. */
+  matchesOldDefaultBoilerplate: boolean;
+  /** retrieval explicitly enabled while lessons is omitted: worked under the
+   *  old defaults (omitted lessons = on), silently inert after upgrade. */
+  inertRetrieval: boolean;
+  /** Local fleet-children recipe paths referenced by this recipe. */
+  childRecipePaths: string[];
+}
+
+interface RawRecipeShape {
+  name?: unknown;
+  agent?: unknown;
+  modules?: Record<string, unknown>;
+}
+
+/** A JSON document we treat as a recipe: object with a name and an agent
+ *  block. Anything else in a scanned directory is silently skipped. */
+export function looksLikeRecipe(raw: unknown): raw is RawRecipeShape {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return false;
+  const o = raw as RawRecipeShape;
+  return typeof o.name === 'string' && !!o.agent && typeof o.agent === 'object';
+}
+
+export function classifyModule(value: unknown): ModuleState {
+  if (value === undefined || value === null) return 'omitted';
+  if (value === false) return 'explicit-disable';
+  // true or a config object both enable (matches createFramework wiring).
+  return 'explicit-enable';
+}
+
+export function auditRecipe(raw: RawRecipeShape, path: string): RecipeAudit {
+  const modules = (raw.modules && typeof raw.modules === 'object' ? raw.modules : {}) as Record<string, unknown>;
+  const states = Object.fromEntries(
+    AUDITED_MODULES.map((m) => [m, classifyModule(modules[m])]),
+  ) as Record<AuditedModule, ModuleState>;
+
+  const isSnapshot = basename(path) === '.recipe.json';
+
+  const childRecipePaths: string[] = [];
+  const fleet = modules.fleet;
+  if (fleet && typeof fleet === 'object') {
+    const children = (fleet as { children?: unknown }).children;
+    if (Array.isArray(children)) {
+      for (const child of children) {
+        const ref = (child as { recipe?: unknown })?.recipe;
+        if (typeof ref !== 'string' || !ref) continue;
+        if (ref.startsWith('http://') || ref.startsWith('https://')) continue;
+        childRecipePaths.push(isAbsolute(ref) ? ref : resolve(dirname(resolve(path)), ref));
+      }
+    }
+  }
+
+  return {
+    path,
+    recipeName: String(raw.name),
+    isSnapshot,
+    states,
+    matchesOldDefaultBoilerplate:
+      isSnapshot &&
+      modules.subagents === true && modules.lessons === true && modules.retrieval === true,
+    inertRetrieval: states.retrieval === 'explicit-enable' && states.lessons === 'omitted',
+    childRecipePaths,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Filesystem walk (main-path only; the logic above is what the tests pin)
+// ---------------------------------------------------------------------------
+
+const SKIP_DIRS = new Set(['node_modules', '.git', 'web']);
+
+function collectJsonFiles(root: string, out: string[]): void {
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    const full = join(root, entry.name);
+    if (entry.isDirectory()) {
+      if (!SKIP_DIRS.has(entry.name)) collectJsonFiles(full, out);
+    } else if (entry.name.endsWith('.json')) {
+      out.push(full);
+    }
+  }
+}
+
+export function auditPaths(paths: string[]): { audits: RecipeAudit[]; unreadable: string[] } {
+  const files: string[] = [];
+  const unreadable: string[] = [];
+  for (const p of paths) {
+    if (!existsSync(p)) {
+      unreadable.push(p);
+      continue;
+    }
+    if (statSync(p).isDirectory()) collectJsonFiles(p, files);
+    else files.push(p);
+  }
+
+  const audits: RecipeAudit[] = [];
+  const seen = new Set<string>();
+  const queue = [...files];
+  while (queue.length > 0) {
+    const file = queue.shift()!;
+    const key = resolve(file);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    let raw: unknown;
+    try {
+      raw = JSON.parse(readFileSync(file, 'utf-8'));
+    } catch {
+      continue; // not JSON we can read — not our business to complain about
+    }
+    if (!looksLikeRecipe(raw)) continue;
+    const audit = auditRecipe(raw, file);
+    audits.push(audit);
+    // Follow local fleet children so a parent path argument covers the tree.
+    for (const child of audit.childRecipePaths) {
+      if (existsSync(child)) queue.push(child);
+    }
+  }
+  return { audits, unreadable };
+}
+
+// ---------------------------------------------------------------------------
+// Report
+// ---------------------------------------------------------------------------
+
+const STATE_LINES: Record<AuditedModule, Record<ModuleState, string>> = {
+  subagents: {
+    'explicit-enable':
+      'explicitly enabled — stays on after upgrade. Keep if this agent really forks workers.',
+    'explicit-disable': 'explicitly disabled — no change on upgrade (belt-and-braces for old checkouts).',
+    omitted:
+      'omitted — ON under published ≤0.7.2, OFF after upgrade. Declare `true` only if this agent relied on forking.',
+  },
+  lessons: {
+    'explicit-enable':
+      'explicitly enabled — stays on after upgrade. Keep if this agent curates a lesson library.',
+    'explicit-disable': 'explicitly disabled — no change on upgrade (belt-and-braces for old checkouts).',
+    omitted:
+      'omitted — ON under published ≤0.7.2, OFF after upgrade. Declare `true` only if this agent relied on lessons.',
+  },
+  retrieval: {
+    'explicit-enable':
+      'explicitly enabled — stays on after upgrade: per-compile injection plus two Haiku calls per turn. Keep only as a real choice.',
+    'explicit-disable': 'explicitly disabled — no change on upgrade (belt-and-braces for old checkouts).',
+    omitted: 'omitted — ON under published ≤0.7.2 (when lessons ran), OFF after upgrade.',
+  },
+};
+
+export function renderReport(audits: RecipeAudit[]): { text: string; needsDecision: number } {
+  const lines: string[] = [];
+  let needsDecision = 0;
+
+  const sources = audits.filter((a) => !a.isSnapshot);
+  const snapshots = audits.filter((a) => a.isSnapshot);
+
+  for (const a of sources) {
+    lines.push(`${a.path}  (recipe "${a.recipeName}")`);
+    for (const m of AUDITED_MODULES) {
+      const state = a.states[m];
+      if (state === 'explicit-enable') needsDecision++;
+      lines.push(`  ${m}: ${STATE_LINES[m][state]}`);
+    }
+    if (a.inertRetrieval) {
+      needsDecision++;
+      lines.push(
+        '  ⚠ retrieval is enabled but lessons is omitted. Under the old defaults omitted lessons still ran,',
+        '    so retrieval worked; after upgrade lessons is off and retrieval is silently inert.',
+        '    Either add `lessons: true` (if retrieval is a real choice) or drop `retrieval`.',
+      );
+    }
+    lines.push('');
+  }
+
+  if (snapshots.length > 0) {
+    lines.push('Resolved snapshots (data/.recipe.json) — informational only:');
+    lines.push(
+      '  These are launch-time captures, not authoritative sources. Under the old defaults they',
+      '  include enables the operator never wrote. Audit the source recipe each run was launched',
+      '  from; the snapshot refreshes on the next launch from source.',
+    );
+    for (const a of snapshots) {
+      const enabled = AUDITED_MODULES.filter((m) => a.states[m] === 'explicit-enable');
+      const note = a.matchesOldDefaultBoilerplate
+        ? 'all three enabled — matches the old DEFAULT_RECIPE shape, almost certainly pre-flip defaults, not a choice'
+        : enabled.length > 0
+          ? `explicitly enabled here: ${enabled.join(', ')}`
+          : 'no audited modules enabled';
+      lines.push(`  ${a.path}  (recipe "${a.recipeName}"): ${note}`);
+    }
+    lines.push('');
+  }
+
+  return { text: lines.join('\n'), needsDecision };
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main(): void {
+  const args = process.argv.slice(2).filter((a) => !a.startsWith('--'));
+  if (args.length === 0) {
+    console.error('Usage: bun scripts/audit-module-optins.ts <recipe.json | directory> [...more]');
+    console.error('Report-only: reads recipes, changes nothing.');
+    process.exit(1);
+  }
+
+  const { audits, unreadable } = auditPaths(args);
+  for (const p of unreadable) console.error(`cannot read: ${p}`);
+
+  console.log('connectome-host module opt-in audit — report only, nothing is modified\n');
+  console.log(
+    'Published ≤0.7.2 treated subagents/lessons/retrieval as opt-OUT (omitted = enabled).\n' +
+      'Current main treats them as opt-IN (omitted = disabled). Explicit enables survive the\n' +
+      'upgrade by design — this report shows where each recipe stands so you can decide which\n' +
+      'of those are real choices and which are old boilerplate.\n',
+  );
+
+  let needsDecision = 0;
+  if (audits.length === 0) {
+    console.log('No recipe-shaped JSON found under the given paths.');
+  } else {
+    const report = renderReport(audits);
+    needsDecision = report.needsDecision;
+    console.log(report.text);
+    const sources = audits.filter((a) => !a.isSnapshot).length;
+    console.log(
+      `Summary: ${audits.length} recipe(s) audited (${sources} source, ${audits.length - sources} snapshot), ` +
+        `${needsDecision} item(s) need an operator decision.`,
+    );
+  }
+
+  // Unreadable path arguments outrank findings in the exit code.
+  if (unreadable.length > 0) process.exit(1);
+  if (needsDecision > 0) process.exit(2);
+}
+
+if (import.meta.main) main();