monomind 2.3.3 → 2.4.0

package/packages/@monomind/cli/.claude/skills/mastermind-skills/stoporg.md

@@ -57,13 +57,17 @@ echo "Stop requested for org '${org_name}' (v2 daemon exits within 2s)."
 ```
 - Exit.
 
+<!-- LEGACY-ORG-V1: remove this branch when v1 orgs are gone -->
+Everything below this point only runs for v1 orgs — v2 orgs already exited above.
+
 If `current_status == "stopped"`:
 - Print: "Org '<org_name>' is already stopped."
 - Exit.
 
 ---
 
-## Step 2 — Set Status to Stopped and Clear next_run
+<!-- LEGACY-ORG-V1: remove this step when v1 orgs are gone -->
+## Step 2 — Set Status to Stopped and Clear next_run (v1 only)
 
 ```bash
 orgFile=".monomind/orgs/${org_name}.json"
@@ -74,7 +78,8 @@ jq '.status = "stopped" | if .loop then .loop.next_run = null else . end' "$orgF
 
 ---
 
-## Step 3 — Write Stop File (for any running boss agents)
+<!-- LEGACY-ORG-V1: remove this step when v1 orgs are gone -->
+## Step 3 — Write Stop File (for any running boss agents, v1 only)
 
 Any persistent boss agent checks for this file at the start of each loop iteration:
 
@@ -85,6 +90,7 @@ touch ".monomind/orgs/.stops/${org_name}.stop"
 
 ---
 
+<!-- LEGACY-ORG-V1: remove this step when v1 orgs are gone -->
 ## Step 4 — Emit Dashboard Events
 
 ```bash
@@ -103,7 +109,8 @@ curl -s -X POST "${CTRL_URL}/api/mastermind/event" -H "x-monomind-token: $(cat "
 
 ---
 
-## Step 5 — Report to User
+<!-- LEGACY-ORG-V1: remove this step when v1 orgs are gone -->
+## Step 5 — Report to User (v1 only)
 
 ```
 ✓ Org "<org_name>" stopped.

package/packages/@monomind/cli/.claude/skills/mastermind-skills/tasks.md

@@ -35,13 +35,16 @@ If `caller` is not "command", load brain context following _protocol.md Brain Lo
 ## Step 1 — Load Org Config
 
 ```bash
+# LEGACY-ORG-V1: this whole board/column lookup is the pre-v2 board-backed
+# task model — boards belong to the legacy v1 runner, see runorgv1.
 orgFile=".monomind/orgs/${org_name}.json"
 board_id=$(jq -r '.board_id // empty' "$orgFile")
 todo_col=$(jq -r '.todo_col_id // empty' "$orgFile")
 doing_col=$(jq -r '.doing_col_id // empty' "$orgFile")
 done_col=$(jq -r '.done_col_id // empty' "$orgFile")
 
-[ -z "$board_id" ] && { echo "ERROR: org config missing board_id — run /mastermind:createorg to rebuild."; exit 1; }
+[ -z "$board_id" ] && { echo "ERROR: org config missing board_id — boards belong to the legacy v1 runner, see runorgv1."; exit 1; }
+# end LEGACY-ORG-V1
 ```
 
 ---

package/packages/@monomind/cli/README.md

@@ -102,11 +102,25 @@ monomind org run content-team --task "Build and publish 3 blog posts per week"
 #   assigns work to role agents, coordinates until the task completes
 #   or you stop it. Every event streams into the dashboard above.
 
-monomind org status content-team    # runtime state
+monomind org status content-team    # runtime state (detects crashed daemons)
 monomind org stop content-team      # request a graceful stop
-monomind org list                   # every org + status
+monomind org list                   # every org + roles, schedule, status
 ```
 
+### Observe, steer, and let it learn
+
+```bash
+monomind org logs content-team --follow      # live event stream in the terminal
+monomind org report content-team             # outcome, per-role tokens vs budget, assets
+monomind org questions content-team          # what agents asked via ask_human
+monomind org answer content-team q-123 "yes" # answer live or queued — no dashboard needed
+monomind org create blog --template content-team --goal "3 posts/week"   # scaffold from a template
+monomind org validate blog                   # schema + structural checks before running
+monomind org run blog --dry-run              # preview each role's exact briefing
+```
+
+Orgs are self-improving: the coordinator records every run's outcome (`org_complete`), the next run is briefed on it, and all agents can query accumulated cross-run memory with `org_recall` — a scheduled org gets smarter every cycle instead of starting cold. Crashed agent sessions restart automatically with backoff.
+
 ### What runs under the hood
 
 | What | How |
@@ -196,9 +210,28 @@ monomind org run my-team          # run your first AI org (see .monomind/orgs/sa
 
 ---
 
+## 📚 Second Brain — Your Documents, Retrieved by Meaning
+
+Drop documents (Markdown, TXT, PDF, DOCX) anywhere in your project and run `monomind init` — the Second Brain activates itself. No flags, no configuration, no accounts. Everything runs on your machine: a local embedding model (MiniLM via transformers.js) and a local SQLite vector store. **Your notes never leave your computer.**
+
+From then on, every substantive prompt you type in Claude Code is automatically answered *with your own knowledge in context* — a hook retrieves the most relevant excerpts semantically (the always-on dashboard keeps the model warm, ~60ms per lookup) and injects them before Claude starts thinking. Ask "when do new parents get time off" and the parental-leave section of your handbook is already on the table, even though you never used the word "leave".
+
+```bash
+monomind doc ingest ./notes        # index documents (init + session-start do this automatically)
+monomind doc search -q "pricing psychology in checkout"   # semantic search, by meaning not keywords
+monomind doc list                  # what's indexed
+monomind doc export                # portable OKF bundle — move your brain between machines
+```
+
+Retrieval quality is a tested invariant, not a hope: a golden-set eval (paraphrase queries against notes written in different vocabulary) runs in CI with an 80% recall bar.
+
+> **Privacy note:** the embedding model (~90MB) is fetched once from HuggingFace's CDN when your first document is indexed, then cached locally forever. That download is the only outbound request the Second Brain ever makes — your documents and queries never leave your machine. Offline at first index? Search degrades gracefully to keyword matching and `monomind doctor` tells you how to warm up later.
+
+---
+
 ## 🧠 Memory That Persists
 
-Every session, every agent, every org writes to a persistent memory store — a JSON pattern store with episodic recall that survives across sessions. The next time you run anything, Monomind already knows what was built, what failed, and which patterns work.
+Every session, every agent, every org writes to a persistent memory store that survives across sessions — text plus embedding vectors in local SQLite (better-sqlite3, pure-WASM fallback), embedded by a local model. No cloud vector database, no API keys, no data transmission. The next time you run anything, Monomind already knows what was built, what failed, and which patterns work.
 
 ```mermaid
 graph TD
@@ -217,7 +250,7 @@ graph TD
 
 ```bash
 monomind memory store "key insight" --namespace my-project
-monomind memory search "auth implementation"     # BM25 + semantic hybrid
+monomind memory search "auth implementation"     # semantic (local embeddings) with keyword fallback
 ```
 
 ---

package/packages/@monomind/cli/dist/src/commands/cleanup.js

@@ -57,16 +57,23 @@ export function findOrphanedProjectData(baseDir, now, aggressive) {
         if (name.startsWith('.'))
             continue;
         const dir = join(baseDir, name);
-        let mtime = 0;
         try {
-            const st = lstatSync(dir);
-            if (!st.isDirectory())
+            if (!lstatSync(dir).isDirectory())
                 continue;
-            mtime = st.mtimeMs;
         }
         catch {
             continue;
         }
+        // Staleness must consider the files writes actually touch: appends to
+        // lancedb/memory.db and origin.json refreshes do NOT bump the slug dir's
+        // own mtime, so an actively-used project would otherwise look 30d stale.
+        const mtimeOf = (p) => { try {
+            return lstatSync(p).mtimeMs;
+        }
+        catch {
+            return 0;
+        } };
+        const mtime = Math.max(mtimeOf(dir), mtimeOf(join(dir, 'origin.json')), mtimeOf(join(dir, 'lancedb', 'memory.db')), mtimeOf(join(dir, 'memory.db')));
         const originFile = join(dir, 'origin.json');
         let originPath = null;
         let hasOrigin = false;
@@ -76,13 +83,28 @@ export function findOrphanedProjectData(baseDir, now, aggressive) {
         }
         catch { /* no/corrupt marker */ }
         if (hasOrigin && originPath && existsSync(originPath)) {
+            // NOTE: the directory is *named* lancedb for historical reasons, but the
+            // current SQLite engine keeps its LIVE memory.db inside it. Only genuine
+            // LanceDB leftovers (*.lance datasets, no memory.db) are dead weight.
             const lance = join(dir, 'lancedb');
-            if (existsSync(lance))
-                out.push({ path: lance, description: `dead lancedb store (project: ${originPath})`, size: 0 });
+            if (existsSync(lance) && !existsSync(join(lance, 'memory.db'))) {
+                let hasLanceData = false;
+                try {
+                    hasLanceData = readdirSync(lance).some(f => f.endsWith('.lance') || f === '__manifest');
+                }
+                catch { /* unreadable — leave it */ }
+                if (hasLanceData)
+                    out.push({ path: lance, description: `dead lancedb store (project: ${originPath})`, size: 0 });
+            }
             continue;
         }
-        if (hasOrigin) {
-            out.push({ path: dir, description: `orphaned project data (origin gone: ${originPath})`, size: 0 });
+        if (hasOrigin && originPath) {
+            // Only classify as orphaned when the origin's PARENT exists — an
+            // unmounted volume / disconnected network share makes the whole subtree
+            // vanish temporarily, and that must never count as "project deleted".
+            if (existsSync(dirname(originPath))) {
+                out.push({ path: dir, description: `orphaned project data (origin gone: ${originPath})`, size: 0 });
+            }
         }
         else if (aggressive || now - mtime > UNKNOWN_DIR_MAX_AGE_MS) {
             out.push({ path: dir, description: aggressive ? 'unverifiable project data (no origin marker)' : 'unverifiable project data (untouched >30d)', size: 0 });

package/packages/@monomind/cli/dist/src/commands/doc.js

@@ -3,22 +3,41 @@
  */
 import * as path from 'node:path';
 import { output } from '../output.js';
+import { getGlobalBrainDir } from '../memory/memory-bridge.js';
 const ingestCommand = {
     name: 'ingest',
     description: 'Ingest documents into the knowledge base',
     options: [
-        { name: 'scope', short: 's', description: 'Knowledge scope (default: shared)', type: 'string', default: 'shared' },
+        // No `default` on scope: the auto-global routing below must be able to
+        // tell "user typed --scope shared" apart from "user typed nothing" — a
+        // parser-injected default makes them indistinguishable.
+        { name: 'scope', short: 's', description: 'Knowledge scope (default: shared; auto-routes to global for paths outside the project)', type: 'string' },
+        { name: 'global', short: 'g', description: 'Ingest into the personal cross-project global brain (~/.monomind/global-brain)', type: 'boolean' },
     ],
     examples: [
         { command: 'monomind doc ingest ./docs', description: 'Ingest all docs in a directory' },
+        { command: 'monomind doc ingest ~/notes --global', description: 'Ingest into the global brain (auto-detected for paths outside the project)' },
         { command: 'monomind doc ingest report.pdf', description: 'Ingest a single file' },
     ],
     action: async (ctx) => {
         const target = ctx.args[0] || '.';
-        const scope = String(ctx.flags.scope || 'shared');
         const { ingestDocument, ingestDirectory } = await import('../knowledge/document-pipeline.js');
         const fs = await import('node:fs');
         const resolved = path.resolve(target);
+        // Zero-decision routing: an explicit --global wins; otherwise paths OUTSIDE
+        // the current project belong to the personal brain (a project store keyed
+        // to this cwd would never see them again from another project).
+        let scope = String(ctx.flags.scope || 'shared');
+        if (ctx.flags.global === true) {
+            scope = 'global';
+        }
+        else if (!ctx.flags.scope) {
+            const relToCwd = path.relative(process.cwd(), resolved);
+            if (relToCwd.startsWith('..') || path.isAbsolute(relToCwd)) {
+                scope = 'global';
+                output.writeln(output.dim(`  ${target} is outside this project — ingesting into the global brain (use --scope shared to force project scope)`));
+            }
+        }
         const spinner = output.createSpinner({ text: 'Indexing documents...' });
         spinner.start();
         try {
@@ -68,9 +87,11 @@ const searchDocCommand = {
         { name: 'limit', short: 'l', description: 'Max results (default: 10)', type: 'number', default: 10 },
         { name: 'scope', short: 's', description: 'Knowledge scope (default: shared)', type: 'string', default: 'shared' },
         { name: 'min-score', description: 'Minimum similarity (default: 0.3)', type: 'number', default: 0.3 },
+        { name: 'store', description: 'Which store(s): project | global | all (default: all — project results win ties)', type: 'string', default: 'all' },
     ],
     examples: [
-        { command: 'monomind doc search -q "authentication flow"', description: 'Search for auth docs' },
+        { command: 'monomind doc search -q "authentication flow"', description: 'Search project + global brain' },
+        { command: 'monomind doc search -q "pricing notes" --store global', description: 'Search only the personal global brain' },
     ],
     action: async (ctx) => {
         const query = String(ctx.flags.query || ctx.args[0] || '');
@@ -79,10 +100,12 @@ const searchDocCommand = {
             return { success: false, exitCode: 1 };
         }
         const { searchKnowledge } = await import('../knowledge/document-pipeline.js');
+        const storeFlag = String(ctx.flags.store || 'all');
         const excerpts = await searchKnowledge(query, {
             scope: String(ctx.flags.scope || 'shared'),
             limit: Number(ctx.flags.limit || 10),
             minScore: Number(ctx.flags['min-score'] || 0.3),
+            store: storeFlag === 'project' || storeFlag === 'global' ? storeFlag : 'all',
         });
         if (!excerpts.length) {
             output.writeln(output.dim('No results found.'));
@@ -92,7 +115,8 @@ const searchDocCommand = {
         output.writeln();
         for (let i = 0; i < excerpts.length; i++) {
             const ex = excerpts[i];
-            output.writeln(`${output.highlight(`${i + 1}.`)} ${output.dim(`(${ex.similarity.toFixed(3)})`)} ${ex.filePath || 'unknown'}`);
+            const origin = ex.scope === 'global' ? ` ${output.dim('[global]')}` : '';
+            output.writeln(`${output.highlight(`${i + 1}.`)} ${output.dim(`(${ex.similarity.toFixed(3)})`)} ${ex.filePath || 'unknown'}${origin}`);
             const preview = ex.text.length > 200 ? ex.text.slice(0, 200) + '...' : ex.text;
             output.writeln(`   ${output.dim(preview)}`);
             output.writeln();
@@ -105,11 +129,13 @@ const listDocCommand = {
     description: 'List indexed documents',
     options: [
         { name: 'scope', short: 's', description: 'Knowledge scope', type: 'string' },
+        { name: 'global', short: 'g', description: 'List the personal cross-project global brain', type: 'boolean' },
     ],
     action: async (ctx) => {
         const { listDocuments } = await import('../knowledge/document-pipeline.js');
-        const scope = ctx.flags.scope ? String(ctx.flags.scope) : undefined;
-        const docs = listDocuments(process.cwd(), scope);
+        const isGlobal = ctx.flags.global === true;
+        const scope = isGlobal ? 'global' : ctx.flags.scope ? String(ctx.flags.scope) : undefined;
+        const docs = listDocuments(isGlobal ? getGlobalBrainDir() : process.cwd(), scope);
         if (!docs.length) {
             output.writeln(output.dim('No documents indexed. Run: monomind doc ingest <path>'));
             return { success: true, data: [] };
@@ -133,15 +159,17 @@ const exportDocCommand = {
     options: [
         { name: 'output', short: 'o', description: 'Output directory', type: 'string', default: '.monomind/knowledge-export' },
         { name: 'scope', short: 's', description: 'Knowledge scope (default: shared)', type: 'string', default: 'shared' },
+        { name: 'global', short: 'g', description: 'Export the personal cross-project global brain (portable between machines)', type: 'boolean' },
     ],
     action: async (ctx) => {
         const { exportToOKF } = await import('../knowledge/document-pipeline.js');
         const outDir = path.resolve(String(ctx.flags.output || '.monomind/knowledge-export'));
-        const scope = String(ctx.flags.scope || 'shared');
+        const isGlobal = ctx.flags.global === true;
+        const scope = isGlobal ? 'global' : String(ctx.flags.scope || 'shared');
         const spinner = output.createSpinner({ text: 'Exporting to OKF...' });
         spinner.start();
         try {
-            const result = await exportToOKF(outDir, process.cwd(), scope);
+            const result = await exportToOKF(outDir, isGlobal ? getGlobalBrainDir() : process.cwd(), scope);
             spinner.succeed(`Exported ${result.exported} documents to ${result.outputDir}`);
             return { success: true, data: result };
         }

package/packages/@monomind/cli/dist/src/commands/doctor-project-checks.js

@@ -52,19 +52,32 @@ export async function checkSecondBrainModel() {
     if (!existsSync(join(process.cwd(), '.monomind', 'knowledge', 'chunks.jsonl'))) {
         return { name, status: 'pass', message: 'No knowledge base in this project (nothing to check)' };
     }
-    let pkgDir;
+    let entryPath = null;
     try {
-        // exports map blocks package.json — resolve the entry file and walk up
-        const entry = await import.meta.resolve?.('@huggingface/transformers');
-        if (!entry)
-            throw new Error('resolver unavailable');
-        pkgDir = fileURLToPath(entry).replace(/\/dist\/.*$/, '');
-    }
-    catch {
-        return { name, status: 'warn', message: '@huggingface/transformers not installed — semantic search degraded to keyword matching', fix: 'reinstall monomind (the model dependency is optional and may have failed to build)' };
+        // exports map blocks package.json — resolve the entry file, then walk UP
+        // with path ops (no separator-sensitive regex: '/dist/'.replace broke on
+        // Windows paths, and any install layout without a dist segment).
+        // import.meta.resolve is missing on Node 20.0–20.5; fall back to CJS resolve.
+        const viaEsm = import.meta.resolve?.('@huggingface/transformers');
+        if (viaEsm)
+            entryPath = fileURLToPath(await viaEsm);
+    }
+    catch { /* try CJS below */ }
+    if (!entryPath) {
+        try {
+            const { createRequire } = await import('node:module');
+            entryPath = createRequire(import.meta.url).resolve('@huggingface/transformers');
+        }
+        catch {
+            return { name, status: 'warn', message: '@huggingface/transformers not installed — semantic search degraded to keyword matching', fix: 'reinstall monomind (the model dependency is optional and may have failed to build)' };
+        }
     }
+    // Walk up from the entry file to the package root (the dir named 'transformers').
+    let pkgDir = dirname(entryPath);
+    while (pkgDir !== dirname(pkgDir) && !pkgDir.endsWith('transformers'))
+        pkgDir = dirname(pkgDir);
     const modelCache = join(pkgDir, '.cache', 'Xenova');
-    if (existsSync(modelCache)) {
+    if (pkgDir.endsWith('transformers') && existsSync(modelCache)) {
         return { name, status: 'pass', message: 'Local embedding model cached — semantic search active' };
     }
     return { name, status: 'warn', message: 'Embedding model not downloaded yet — searches use keyword matching until it is', fix: 'run once while online: monomind doc search -q "warmup" (downloads ~90MB locally, one time)' };

package/packages/@monomind/cli/dist/src/commands/org-observe.js

@@ -7,7 +7,7 @@ import { output } from '../output.js';
 import { ORG_DIR, OrgDefSchema } from '../orgrt/types.js';
 import { formatEvent, listRunDirs, readHistory, readRunEvents, summarizeRun } from '../orgrt/reporting.js';
 import { ORG_TEMPLATES, buildFromTemplate } from '../orgrt/templates.js';
-import { parseSchedule } from '../orgrt/scheduler.js';
+import { checkOrgStructure } from '../orgrt/migrate.js';
 import { listOrgConfigFiles, validateOrgName } from './org.js';
 const log = (text) => { console.log(text); };
 /** Validate org config(s) against OrgDefSchema — the exact parse `org run`/`org serve`
@@ -42,23 +42,7 @@ export const validateAction = async (ctx) => {
         }
         try {
             const def = OrgDefSchema.parse(JSON.parse(readFileSync(path, 'utf8')));
-            const ids = def.roles.map(r => r.id);
-            const dupes = ids.filter((id, i) => ids.indexOf(id) !== i);
-            if (dupes.length)
-                errors.push(`duplicate role id(s): ${[...new Set(dupes)].join(', ')}`);
-            const roots = def.roles.filter(r => r.reports_to === null);
-            if (roots.length === 0)
-                errors.push('no root role — exactly one role must have reports_to: null');
-            if (roots.length > 1)
-                errors.push(`multiple root roles (${roots.map(r => r.id).join(', ')}) — exactly one may have reports_to: null`);
-            for (const r of def.roles) {
-                if (r.reports_to !== null && !ids.includes(r.reports_to))
-                    errors.push(`role "${r.id}": reports_to "${r.reports_to}" matches no role id`);
-                if (r.reports_to === r.id)
-                    errors.push(`role "${r.id}" reports to itself`);
-            }
-            if (def.schedule != null && parseSchedule(def.schedule) === null)
-                errors.push(`schedule "${def.schedule}" is not parseable — use "<N>s", "<N>m", or "<N>h"`);
+            errors.push(...checkOrgStructure(def));
             if (def.name !== stem)
                 warnings.push(`def.name "${def.name}" differs from filename — the runtime addresses this org as "${stem}"`);
         }
@@ -80,9 +64,13 @@ export const validateAction = async (ctx) => {
         ? { success: false, message: `${failed} of ${files.length} org config(s) failed validation` }
         : { success: true, message: `${files.length} org config(s) valid` };
 };
+// Run ids are joined into filesystem paths — enforce the daemon's own id shape
+// so a crafted --run can't traverse out of the org directory (same reason the
+// org-name guard exists).
+const RUN_ID_RE = /^run-[A-Za-z0-9-]+$/;
 const resolveRun = (cwd, name, runFlag) => {
     if (typeof runFlag === 'string' && runFlag)
-        return runFlag;
+        return RUN_ID_RE.test(runFlag) ? runFlag : null;
     return listRunDirs(cwd, name)[0] ?? null;
 };
 /** `org logs <name> [--run id] [--role r] [--follow]` — formatted bus.jsonl tail. */
@@ -103,14 +91,19 @@ export const logsAction = async (ctx, name) => {
         if (!existsSync(file))
             return;
         const lines = readFileSync(file, 'utf8').split('\n').filter(Boolean);
-        for (const l of lines.slice(seenLines)) {
+        for (let i = seenLines; i < lines.length; i++) {
             try {
-                show(JSON.parse(l));
-                seenLines++;
+                show(JSON.parse(lines[i]));
+                seenLines = i + 1;
             }
             catch {
-                break;
-            } // partial line mid-append — retry it next tick
+                // Only the FINAL line can be a partial mid-append write worth
+                // retrying; a corrupt interior line would otherwise stall the tail
+                // forever — skip it and keep going.
+                if (i === lines.length - 1)
+                    break;
+                seenLines = i + 1;
+            }
         }
     };
     drain();
@@ -249,10 +242,21 @@ export const answerAction = async (ctx, name) => {
         }
     }
     // Offline path: mirror daemon.answerQuestion's org-not-running branch.
-    const updated = questions.map(x => x.questionId === questionId ? { ...x, answer, answeredAt: Date.now() } : x);
+    // RE-READ and merge by questionId just before writing — the pre-fetch
+    // snapshot can be up to 10s stale (live-delivery timeout), and rewriting
+    // from it would delete questions the daemon appended meanwhile and revert
+    // answers it recorded (atomic rename prevents torn writes, not lost updates).
+    const fresh = readQuestions(ctx.cwd, name);
+    const freshQ = fresh.find(x => x.questionId === questionId);
+    if (freshQ && freshQ.answer !== null) {
+        return { success: false, message: `question "${questionId}" was answered while this command was running` };
+    }
+    const merged = fresh.some(x => x.questionId === questionId)
+        ? fresh.map(x => x.questionId === questionId ? { ...x, answer, answeredAt: Date.now() } : x)
+        : [...fresh, { ...q, answer, answeredAt: Date.now() }];
     const dest = join(ctx.cwd, ORG_DIR, name, 'questions.json');
     const tmp = `${dest}.${process.pid}.tmp`;
-    writeFileSync(tmp, JSON.stringify({ questions: updated }, null, 2));
+    writeFileSync(tmp, JSON.stringify({ questions: merged }, null, 2));
     const { renameSync } = await import('node:fs');
     renameSync(tmp, dest);
     const { queueMessage } = await import('../orgrt/inbox.js');

package/packages/@monomind/cli/dist/src/commands/org.js

@@ -5,6 +5,7 @@ import { output } from '../output.js';
 import { OrgDaemon } from '../orgrt/daemon.js';
 import { startOrgServer } from '../orgrt/server.js';
 import { ORG_DIR, OrgDefSchema } from '../orgrt/types.js';
+import { migrateOrgFile } from '../orgrt/migrate.js';
 const log = (text) => { console.log(text); };
 /** Org names are used to build filesystem paths under .monomind/orgs — reject
  * anything that isn't a plain identifier to prevent path traversal (e.g.
@@ -31,8 +32,13 @@ const ORG_ARTIFACT_SUFFIXES = [
     '-approval-comments', '-skills',
 ];
 export function listOrgConfigFiles(orgsDir) {
+    // endsWith, not includes: substring matching hid legitimate orgs whose NAME
+    // merely contains an artifact suffix anywhere (e.g. "state-machine.json",
+    // "issues-triage.json") — and anything hidden here is also invisible to
+    // run/list/serve while `org delete <sibling>` would still remove its files.
     return readdirSync(orgsDir)
-        .filter(f => f.endsWith('.json') && !f.startsWith('._') && !ORG_ARTIFACT_SUFFIXES.some(suf => f.includes(suf)));
+        .filter(f => f.endsWith('.json') && !f.startsWith('._') && !f.endsWith('.v1.json')
+        && !ORG_ARTIFACT_SUFFIXES.some(suf => f.endsWith(`${suf}.json`)));
 }
 /** Remove a lingering stopfile so a fresh `org run` doesn't self-terminate. */
 export const clearStopfile = (cwd, name) => {
@@ -152,6 +158,11 @@ const statusAction = async (ctx) => {
         if (!validated.ok)
             return validated.result;
         name = validated.name;
+        // A named org that doesn't exist must error, not report "never run" with exit 0.
+        if (!existsSync(join(ctx.cwd, ORG_DIR, `${name}.json`))) {
+            log(output.error(`Org not found: ${name}`));
+            return { success: false, message: 'org not found' };
+        }
     }
     const orgDir = join(ctx.cwd, ORG_DIR);
     const targets = name ? [name] : (existsSync(orgDir)
@@ -385,6 +396,40 @@ const markCompleteAction = async (ctx) => {
         return { success: false, message: 'server unreachable' };
     }
 };
+const migrateAction = async (ctx) => {
+    const validated = validateOrgName(ctx.args[0]);
+    if (!validated.ok)
+        return validated.result;
+    const name = validated.name;
+    const cwd = ctx.cwd;
+    const cfgPath = join(cwd, ORG_DIR, `${name}.json`);
+    if (!existsSync(cfgPath)) {
+        log(output.error(`Org not found: ${name}`));
+        return { success: false, message: 'org not found' };
+    }
+    if (isOrgRunning(cwd, name)) {
+        log(output.error(`Org "${name}" is currently running — stop it first, then migrate.`));
+        return { success: false, message: 'org is running' };
+    }
+    try {
+        const outcome = migrateOrgFile(cfgPath, join(cwd, ORG_DIR, `${name}.v1.json`));
+        if (outcome.status === 'already-v2') {
+            log(output.info(`${name}: already v2 — nothing to migrate.`));
+            return { success: true, message: 'already v2' };
+        }
+        log(output.success(`${name}: migrated to v2 (backup: ${name}.v1.json)`));
+        for (const d of outcome.dropped)
+            log(output.info(`  dropped v1 field: ${d}`));
+        for (const n of outcome.notes)
+            log(output.info(`  ${n}`));
+        log(output.info(`  run it with: monomind org run ${name}`));
+        return { success: true, message: `migrated ${name}` };
+    }
+    catch (err) {
+        log(output.error(`Cannot migrate ${name}: ${err instanceof Error ? err.message : String(err)}`));
+        return { success: false, message: 'migration produced an invalid config' };
+    }
+};
 export const orgCommand = {
     name: 'org',
     description: 'SDK-based org runtime — run agent organizations as a controlled daemon',
@@ -495,6 +540,11 @@ export const orgCommand = {
                 return validateAction(ctx);
             },
         },
+        {
+            name: 'migrate', description: 'Convert a v1 org config (topology/board/loop) to the v2 daemon shape',
+            examples: [{ command: 'monomind org migrate growth', description: 'Migrate one org; original saved as growth.v1.json' }],
+            action: migrateAction,
+        },
         { name: 'list', description: 'List all orgs in the current project', action: listAction },
         {
             name: 'delete', description: 'Delete an org and all its data',
@@ -511,7 +561,7 @@ export const orgCommand = {
         // index.ts's dispatcher never prints result.message on a failed action —
         // it only exits with result.exitCode — so this must log itself or bare
         // `monomind org` exits silently with code 1 and zero output.
-        const message = 'usage: monomind org <run|stop|status|serve|test-loop|logs|report|questions|answer|create|validate|list|delete|mark-complete>';
+        const message = 'usage: monomind org <run|stop|status|serve|test-loop|logs|report|questions|answer|create|validate|migrate|list|delete|mark-complete>';
         log(output.error(message));
         return { success: false, message };
     },

package/packages/@monomind/cli/dist/src/index.js

@@ -220,6 +220,13 @@ export class CLI {
                     this.output.printDebug(`Completed in ${Date.now() - startTime}ms`);
                 }
                 if (result && !result.success) {
+                    // Always surface the failure reason: many actions return
+                    // { success: false, message } without logging, and exiting 1 with
+                    // zero output left users guessing (swarm finding #12). Actions that
+                    // already printed a rich error produce one extra terse summary line
+                    // — acceptable; silence is not.
+                    if (result.message)
+                        this.output.printError(result.message);
                     process.exit(result.exitCode || 1);
                 }
             }

package/packages/@monomind/cli/dist/src/knowledge/document-pipeline.d.ts

@@ -43,6 +43,8 @@ export declare function searchKnowledge(query: string, opts?: {
     limit?: number;
     minScore?: number;
     rootDir?: string;
+    /** which store(s): project-only, global-only, or both (default). */
+    store?: 'project' | 'global' | 'all';
 }): Promise<KnowledgeExcerpt[]>;
 export declare function listDocuments(rootDir?: string, scope?: string): DocumentMeta[];
 export declare function removeDocument(filePath: string, scope?: string, rootDir?: string): Promise<void>;