leedab 0.8.0 → 0.9.1

package/dist/brain/ingest/indexer.js

@@ -0,0 +1,175 @@
+import { readFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { openDb } from "../db/connection.js";
+import { scanRoot } from "./scanner.js";
+import { classify } from "./classifier.js";
+import { parseText, PARSER_VERSION as TEXT_PARSER_VERSION } from "./parsers/text.js";
+export async function registerRoot(root) {
+    const db = openDb(root.clientId);
+    db.prepare(`INSERT INTO roots (id, client_id, kind, uri, added_at, excludes_file)
+     VALUES (?, ?, ?, ?, ?, ?)
+     ON CONFLICT(id) DO UPDATE SET
+       kind = excluded.kind,
+       uri = excluded.uri,
+       excludes_file = excluded.excludes_file`).run(root.id, root.clientId, root.kind, root.uri, root.addedAt, root.excludesFile ?? null);
+}
+export async function scanAndIndex(clientId, entitlement) {
+    const t0 = Date.now();
+    const db = openDb(clientId);
+    const ctx = { db, clientId, entitlement };
+    const stats = {
+        rootsScanned: 0,
+        filesSeen: 0,
+        filesIndexed: 0,
+        filesSkipped: 0,
+        filesUnchanged: 0,
+        filesDeleted: 0,
+        errors: 0,
+        durationMs: 0,
+    };
+    const roots = db.prepare("SELECT id, client_id, kind, uri, added_at, excludes_file FROM roots WHERE client_id = ?").all(clientId);
+    for (const row of roots) {
+        stats.rootsScanned++;
+        const seenUris = new Set();
+        const root = {
+            id: row.id,
+            clientId: row.client_id,
+            kind: row.kind,
+            uri: row.uri,
+            addedAt: row.added_at,
+            excludesFile: row.excludes_file ?? undefined,
+        };
+        for await (const scanned of scanRoot(root)) {
+            stats.filesSeen++;
+            seenUris.add(scanned.sourceUri);
+            try {
+                const outcome = await ingestOne(ctx, scanned);
+                if (outcome === "indexed")
+                    stats.filesIndexed++;
+                else if (outcome === "unchanged")
+                    stats.filesUnchanged++;
+                else
+                    stats.filesSkipped++;
+            }
+            catch (err) {
+                stats.errors++;
+                recordParseError(ctx, scanned, err.message);
+            }
+        }
+        stats.filesDeleted += cleanupVanished(ctx, row.id, seenUris);
+    }
+    updateMeta(db, "last_full_scan_at", Date.now().toString());
+    stats.durationMs = Date.now() - t0;
+    return stats;
+}
+async function ingestOne(ctx, scanned) {
+    const { db, clientId, entitlement } = ctx;
+    if (scanned.skippedReason) {
+        upsertSkipped(db, clientId, scanned, scanned.skippedReason);
+        return "skipped";
+    }
+    const cls = classify(scanned.sourceUri);
+    if (!cls) {
+        upsertSkipped(db, clientId, scanned, "unsupported");
+        return "skipped";
+    }
+    if (!entitlement.parsers.includes(cls.parser)) {
+        upsertSkipped(db, clientId, scanned, "unsupported");
+        return "skipped";
+    }
+    if (cls.parser !== "text") {
+        // Phase 1 ships text parser only. Other parsers land in Phase 5+.
+        upsertSkipped(db, clientId, scanned, "unsupported");
+        return "skipped";
+    }
+    const bytes = await readFile(scanned.sourceUri);
+    const contentHash = sha256(bytes);
+    const existing = db.prepare(`SELECT id, content_hash, parser_version
+       FROM documents
+      WHERE client_id = ? AND root_id = ? AND source_uri = ?`).get(clientId, scanned.rootId, scanned.sourceUri);
+    if (existing &&
+        existing.content_hash === contentHash &&
+        existing.parser_version === TEXT_PARSER_VERSION) {
+        return "unchanged";
+    }
+    const parsed = await parseText(scanned.sourceUri);
+    const tx = db.transaction(() => {
+        let docId;
+        if (existing) {
+            db.prepare(`UPDATE documents
+            SET mime = ?, size = ?, mtime = ?, content_hash = ?,
+                parser_id = ?, parser_version = ?, last_ingested = ?,
+                parse_error = NULL, skipped_reason = NULL
+          WHERE id = ?`).run(cls.mime, scanned.size, scanned.mtime, contentHash, parsed.parserId, parsed.parserVersion, Date.now(), existing.id);
+            docId = existing.id;
+            db.prepare("DELETE FROM chunks WHERE doc_id = ?").run(docId);
+        }
+        else {
+            const info = db.prepare(`INSERT INTO documents
+           (client_id, root_id, source_uri, mime, size, mtime,
+            content_hash, parser_id, parser_version, last_ingested)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(clientId, scanned.rootId, scanned.sourceUri, cls.mime, scanned.size, scanned.mtime, contentHash, parsed.parserId, parsed.parserVersion, Date.now());
+            docId = Number(info.lastInsertRowid);
+        }
+        if (parsed.chunks.length > 0) {
+            const insertChunk = db.prepare("INSERT INTO chunks (doc_id, ord, text) VALUES (?, ?, ?)");
+            for (const chunk of parsed.chunks) {
+                insertChunk.run(docId, chunk.ord, chunk.text);
+            }
+        }
+    });
+    tx();
+    return "indexed";
+}
+function upsertSkipped(db, clientId, scanned, reason) {
+    const existing = db.prepare(`SELECT id FROM documents WHERE client_id = ? AND root_id = ? AND source_uri = ?`).get(clientId, scanned.rootId, scanned.sourceUri);
+    if (existing) {
+        db.prepare(`UPDATE documents
+          SET mime = NULL, size = ?, mtime = ?, content_hash = NULL,
+              parser_id = NULL, parser_version = NULL, last_ingested = ?,
+              parse_error = NULL, skipped_reason = ?
+        WHERE id = ?`).run(scanned.size, scanned.mtime, Date.now(), reason, existing.id);
+        db.prepare("DELETE FROM chunks WHERE doc_id = ?").run(existing.id);
+        return;
+    }
+    db.prepare(`INSERT INTO documents
+       (client_id, root_id, source_uri, size, mtime, last_ingested, skipped_reason)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`).run(clientId, scanned.rootId, scanned.sourceUri, scanned.size, scanned.mtime, Date.now(), reason);
+}
+function recordParseError(ctx, scanned, message) {
+    const { db, clientId } = ctx;
+    const existing = db.prepare(`SELECT id FROM documents WHERE client_id = ? AND root_id = ? AND source_uri = ?`).get(clientId, scanned.rootId, scanned.sourceUri);
+    if (existing) {
+        db.prepare(`UPDATE documents
+          SET parse_error = ?, skipped_reason = ?, last_ingested = ?,
+              content_hash = NULL, parser_id = NULL, parser_version = NULL
+        WHERE id = ?`).run(message.slice(0, 500), "parse-error", Date.now(), existing.id);
+        db.prepare("DELETE FROM chunks WHERE doc_id = ?").run(existing.id);
+    }
+    else {
+        db.prepare(`INSERT INTO documents
+         (client_id, root_id, source_uri, size, mtime, last_ingested,
+          parse_error, skipped_reason)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`).run(clientId, scanned.rootId, scanned.sourceUri, scanned.size, scanned.mtime, Date.now(), message.slice(0, 500), "parse-error");
+    }
+}
+function cleanupVanished(ctx, rootId, seen) {
+    const { db, clientId } = ctx;
+    const known = db.prepare("SELECT id, source_uri FROM documents WHERE client_id = ? AND root_id = ?").all(clientId, rootId);
+    let removed = 0;
+    const del = db.prepare("DELETE FROM documents WHERE id = ?");
+    for (const row of known) {
+        if (!seen.has(row.source_uri)) {
+            del.run(row.id);
+            removed++;
+        }
+    }
+    return removed;
+}
+function updateMeta(db, key, value) {
+    db.prepare(`INSERT INTO _meta (key, value) VALUES (?, ?)
+     ON CONFLICT(key) DO UPDATE SET value = excluded.value`).run(key, value);
+}
+function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}

package/dist/brain/ingest/parsers/text.d.ts

@@ -0,0 +1,4 @@
+import type { ParsedDoc } from "../../types.js";
+export declare const PARSER_ID = "text";
+export declare const PARSER_VERSION = 1;
+export declare function parseText(path: string): Promise<ParsedDoc>;

package/dist/brain/ingest/parsers/text.js

@@ -0,0 +1,38 @@
+import { readFile } from "node:fs/promises";
+export const PARSER_ID = "text";
+export const PARSER_VERSION = 1;
+const TARGET_CHARS = 2048;
+const OVERLAP_CHARS = 256;
+export async function parseText(path) {
+    const buffer = await readFile(path);
+    const text = stripBom(buffer.toString("utf-8"));
+    const chunks = chunkText(text);
+    return { chunks, parserId: PARSER_ID, parserVersion: PARSER_VERSION };
+}
+function stripBom(s) {
+    return s.charCodeAt(0) === 0xfeff ? s.slice(1) : s;
+}
+function chunkText(text) {
+    if (text.trim().length === 0)
+        return [];
+    if (text.length <= TARGET_CHARS) {
+        return [{ ord: 0, text: text.trim() }];
+    }
+    const out = [];
+    let start = 0;
+    let ord = 0;
+    while (start < text.length) {
+        const end = Math.min(start + TARGET_CHARS, text.length);
+        const slice = text.slice(start, end).trim();
+        if (slice.length > 0) {
+            out.push({ ord, text: slice });
+            ord++;
+        }
+        if (end >= text.length)
+            break;
+        start = end - OVERLAP_CHARS;
+        if (start < 0)
+            start = 0;
+    }
+    return out;
+}

package/dist/brain/ingest/scanner.d.ts

@@ -0,0 +1,19 @@
+import { relative } from "node:path";
+import type { Root, RootKind } from "../types.js";
+export interface ScannedFile {
+    rootId: string;
+    rootKind: RootKind;
+    sourceUri: string;
+    size: number;
+    mtime: number;
+    skippedReason?: "oversize" | "denied" | "binary";
+}
+export declare function scanRoot(root: Root): AsyncGenerator<ScannedFile>;
+declare function isHardDenied(absPath: string): boolean;
+export declare const _internal: {
+    isHardDenied: typeof isHardDenied;
+    VAULT_ALLOWED_PREFIXES: string[];
+    DEFAULT_SKIP_EXTENSIONS: Set<string>;
+    MAX_FILE_SIZE: number;
+};
+export { relative as _rel };

package/dist/brain/ingest/scanner.js

@@ -0,0 +1,181 @@
+import { opendir, stat } from "node:fs/promises";
+import { resolve, join, relative, sep } from "node:path";
+import { homedir } from "node:os";
+// Hard denylist applied to EXTERNAL roots only. Vault roots use a
+// separate allowlist (see scanVaultRoot below).
+// Anything matching one of these is unreachable even if the customer
+// adds it to their excludes file.
+// Resolved up-front so the symlink-aware comparison in isHardDenied()
+// matches canonical paths (on macOS /etc → /private/etc, /tmp → /private/tmp,
+// etc). We intentionally do NOT block /private or /var blanket — those are
+// the parents of /tmp and /var/folders, which are valid user work locations.
+const HARD_DENYLIST_PATHS = [
+    "/Applications",
+    "/System",
+    "/Library",
+    "/etc",
+    "/usr",
+    "/bin",
+    "/sbin",
+].map((p) => resolve(p));
+const HARD_DENYLIST_HOME_RELATIVE = [
+    ".ssh",
+    ".gnupg",
+    ".aws",
+    ".config/secrets",
+    "Library",
+    ".cache",
+    ".leedab",
+    "leedab-brains",
+];
+// Default file/dir name patterns excluded from external roots.
+// Anchored via simple substring/prefix/extension matching.
+const DEFAULT_EXTERNAL_EXCLUDES = [
+    ".git",
+    "node_modules",
+    ".venv",
+    "__pycache__",
+    ".DS_Store",
+    ".env",
+    ".env.local",
+    ".env.production",
+    "id_rsa",
+    "id_rsa.pub",
+    "secrets.json",
+];
+// Default extensions that are clearly binary or noise — skipped before
+// any mime sniffing. Saves a stat + open call.
+const DEFAULT_SKIP_EXTENSIONS = new Set([
+    ".lock",
+    ".bak",
+    ".tmp",
+    ".swp",
+    ".pyc",
+    ".class",
+    ".o",
+    ".so",
+    ".dylib",
+    ".dll",
+    ".exe",
+    ".bin",
+    ".log",
+]);
+// Files larger than this are skipped with skipped_reason='oversize'
+// (default 25 MB; parsers can take a long time on huge text files).
+const MAX_FILE_SIZE = 25 * 1024 * 1024;
+// Vault prefixes from apps/console/lib/agent-tools/vault.ts. Kept in
+// sync manually — the vault prefix policy is owned by vault.ts.
+const VAULT_ALLOWED_PREFIXES = [
+    "_inbox",
+    "_Workflows",
+    "00_Org",
+    "01_Customers",
+    "02_Sales",
+    "03_Product",
+    "04_Operations",
+    "05_Finance",
+    "06_Legal",
+    "Permanent",
+    "Wiki",
+];
+export async function* scanRoot(root) {
+    if (root.kind === "vault") {
+        yield* scanVaultRoot(root);
+    }
+    else {
+        yield* scanExternalRoot(root);
+    }
+}
+async function* scanVaultRoot(root) {
+    const base = resolve(root.uri);
+    for (const prefix of VAULT_ALLOWED_PREFIXES) {
+        const subRoot = join(base, prefix);
+        try {
+            yield* walkDir(subRoot, root.id, "vault", null);
+        }
+        catch {
+            // Missing subdir is fine — not every vault has every prefix
+        }
+    }
+}
+async function* scanExternalRoot(root) {
+    const base = resolve(root.uri);
+    if (isHardDenied(base)) {
+        return;
+    }
+    yield* walkDir(base, root.id, "external", DEFAULT_EXTERNAL_EXCLUDES);
+}
+async function* walkDir(dir, rootId, rootKind, excludeNames) {
+    let handle;
+    try {
+        handle = await opendir(dir);
+    }
+    catch {
+        return;
+    }
+    for await (const entry of handle) {
+        if (excludeNames && excludeNames.some((ex) => entry.name === ex || entry.name.startsWith(ex + "."))) {
+            continue;
+        }
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (rootKind === "external" && isHardDenied(full))
+                continue;
+            yield* walkDir(full, rootId, rootKind, excludeNames);
+            continue;
+        }
+        if (!entry.isFile())
+            continue;
+        const ext = extOf(entry.name);
+        if (DEFAULT_SKIP_EXTENSIONS.has(ext))
+            continue;
+        let info;
+        try {
+            info = await stat(full);
+        }
+        catch {
+            continue;
+        }
+        if (info.size > MAX_FILE_SIZE) {
+            yield {
+                rootId,
+                rootKind,
+                sourceUri: full,
+                size: info.size,
+                mtime: Math.floor(info.mtimeMs),
+                skippedReason: "oversize",
+            };
+            continue;
+        }
+        yield {
+            rootId,
+            rootKind,
+            sourceUri: full,
+            size: info.size,
+            mtime: Math.floor(info.mtimeMs),
+        };
+    }
+}
+function isHardDenied(absPath) {
+    const home = homedir();
+    for (const denied of HARD_DENYLIST_PATHS) {
+        if (absPath === denied || absPath.startsWith(denied + sep))
+            return true;
+    }
+    for (const rel of HARD_DENYLIST_HOME_RELATIVE) {
+        const denied = resolve(home, rel);
+        if (absPath === denied || absPath.startsWith(denied + sep))
+            return true;
+    }
+    // Refuse exact home + filesystem root to prevent ~/ as external root
+    if (absPath === home)
+        return true;
+    return false;
+}
+function extOf(name) {
+    const idx = name.lastIndexOf(".");
+    return idx === -1 ? "" : name.slice(idx).toLowerCase();
+}
+// Exposed for tests
+export const _internal = { isHardDenied, VAULT_ALLOWED_PREFIXES, DEFAULT_SKIP_EXTENSIONS, MAX_FILE_SIZE };
+export { relative as _rel };

package/dist/brain/search/bm25.d.ts

@@ -0,0 +1,6 @@
+import type { SearchHit } from "../types.js";
+export interface SearchOptions {
+    limit?: number;
+    rootFilter?: string;
+}
+export declare function search(clientId: string, query: string, opts?: SearchOptions): SearchHit[];

package/dist/brain/search/bm25.js

@@ -0,0 +1,55 @@
+import { openDb } from "../db/connection.js";
+export function search(clientId, query, opts = {}) {
+    const trimmed = query.trim();
+    if (trimmed.length === 0)
+        return [];
+    const limit = opts.limit ?? 10;
+    const db = openDb(clientId);
+    const ftsQuery = toFtsQuery(trimmed);
+    if (!ftsQuery)
+        return [];
+    const rows = db.prepare(`SELECT
+       c.id            AS chunkId,
+       c.ord           AS chunkOrd,
+       c.text          AS chunkText,
+       d.id            AS docId,
+       d.source_uri    AS sourceUri,
+       d.root_id       AS rootId,
+       bm25(chunks_fts) AS score
+     FROM chunks_fts
+     JOIN chunks c    ON c.id = chunks_fts.rowid
+     JOIN documents d ON d.id = c.doc_id
+     WHERE chunks_fts MATCH ?
+       AND d.client_id = ?
+       ${opts.rootFilter ? "AND d.root_id = ?" : ""}
+     ORDER BY score ASC
+     LIMIT ?`).all(ftsQuery, clientId, ...(opts.rootFilter ? [opts.rootFilter] : []), limit);
+    return rows.map((r) => ({
+        docId: r.docId,
+        sourceUri: r.sourceUri,
+        rootId: r.rootId,
+        chunkOrd: r.chunkOrd,
+        snippet: snippetOf(r.chunkText, trimmed),
+        score: -r.score, // bm25 returns negative; flip to positive for sensible sort
+    }));
+}
+function toFtsQuery(raw) {
+    // Strip FTS5 syntax characters and quote each token so user input
+    // can't inject FTS operators (NEAR, MATCH chains, etc.).
+    const tokens = raw
+        .toLowerCase()
+        .split(/[^a-z0-9_]+/u)
+        .filter((t) => t.length >= 2);
+    if (tokens.length === 0)
+        return "";
+    return tokens.map((t) => `"${t}"`).join(" ");
+}
+function snippetOf(chunk, query) {
+    const lower = chunk.toLowerCase();
+    const term = query.toLowerCase().split(/\s+/)[0] ?? "";
+    const idx = term ? lower.indexOf(term) : 0;
+    const start = Math.max(0, idx - 60);
+    const end = Math.min(chunk.length, (idx === -1 ? 0 : idx) + 120);
+    const slice = chunk.slice(start, end).replace(/\s+/g, " ").trim();
+    return (start > 0 ? "… " : "") + slice + (end < chunk.length ? " …" : "");
+}

package/dist/brain/types.d.ts

@@ -0,0 +1,53 @@
+export type RootKind = "vault" | "external";
+export interface Root {
+    id: string;
+    clientId: string;
+    kind: RootKind;
+    uri: string;
+    addedAt: number;
+    excludesFile?: string;
+}
+export type SkippedReason = "oversize" | "binary" | "denied" | "unsupported" | "parse-error";
+export interface IndexedDoc {
+    id: number;
+    clientId: string;
+    rootId: string;
+    sourceUri: string;
+    mime: string | null;
+    size: number | null;
+    mtime: number | null;
+    contentHash: string | null;
+    parserId: string | null;
+    parserVersion: number | null;
+    lastIngested: number;
+    parseError: string | null;
+    skippedReason: SkippedReason | null;
+}
+export interface Chunk {
+    ord: number;
+    text: string;
+    structuralHint?: string;
+}
+export interface ParsedDoc {
+    chunks: Chunk[];
+    parserId: string;
+    parserVersion: number;
+}
+export interface SearchHit {
+    docId: number;
+    sourceUri: string;
+    rootId: string;
+    chunkOrd: number;
+    snippet: string;
+    score: number;
+}
+export interface ScanStats {
+    rootsScanned: number;
+    filesSeen: number;
+    filesIndexed: number;
+    filesSkipped: number;
+    filesUnchanged: number;
+    filesDeleted: number;
+    errors: number;
+    durationMs: number;
+}

package/dist/brain/types.js

@@ -0,0 +1 @@
+export {};

package/dist/license/entitlements.d.ts

@@ -0,0 +1,12 @@
+export type LicenseTier = "starter" | "pro" | "enterprise";
+export type BrainParser = "text" | "spreadsheet" | "document" | "email";
+export interface BrainEntitlement {
+    parsers: BrainParser[];
+    embedder: "local" | "cloud";
+    cloudEmbedderAllowed: boolean;
+    maxSuggestions: number;
+    draftedSuggestions: boolean;
+    perAbAcl: boolean;
+    suggestionsApi: boolean;
+}
+export declare function brainEntitlement(tier: string): BrainEntitlement;

package/dist/license/entitlements.js

@@ -0,0 +1,37 @@
+import { readFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+const FIXTURE_PATH = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "_schema", "entitlements.fixture.json");
+let cached = null;
+function loadFixture() {
+    if (cached)
+        return cached;
+    const raw = JSON.parse(readFileSync(FIXTURE_PATH, "utf-8"));
+    const out = {};
+    for (const [tier, value] of Object.entries(raw)) {
+        if (tier.startsWith("_"))
+            continue;
+        out[tier] = value;
+    }
+    cached = out;
+    return out;
+}
+export function brainEntitlement(tier) {
+    const fixture = loadFixture();
+    const key = normalizeTier(tier);
+    const found = fixture[key];
+    if (!found) {
+        throw new Error(`Unknown license tier: ${tier} (no entry in entitlements.fixture.json)`);
+    }
+    return found;
+}
+function normalizeTier(tier) {
+    const lower = tier.toLowerCase();
+    if (lower === "starter" || lower === "pro" || lower === "enterprise")
+        return lower;
+    if (lower === "trial")
+        return "starter";
+    if (lower === "business")
+        return "pro";
+    return "starter";
+}

package/dist/paths.d.ts

@@ -9,3 +9,15 @@ export declare const STATE_DIR: string;
  * cwd-relative) so customer installs don't drift between directories.
  */
 export declare const AGENT_WORKSPACE_DIR: string;
+/**
+ * Root of the search-index cache. Each customer gets a per-clientId
+ * subdirectory under this root. The cache is regeneratable from source
+ * (the markdown vault at ~/leedab-brains/<clientId>/ + any registered
+ * external folders) — deleting it is non-destructive. See
+ * docs/plans/brain-bootstrap.md §4.
+ *
+ * LEEDAB_BRAIN_INDEX_ROOT env overrides for tests + alternative layouts.
+ */
+export declare function brainIndexRoot(): string;
+/** Per-client index directory. */
+export declare function brainIndexDir(clientId: string): string;

package/dist/paths.js

@@ -11,3 +11,21 @@ export const STATE_DIR = resolve(homedir(), ".leedab");
  * cwd-relative) so customer installs don't drift between directories.
  */
 export const AGENT_WORKSPACE_DIR = resolve(STATE_DIR, "agent-workspace");
+/**
+ * Root of the search-index cache. Each customer gets a per-clientId
+ * subdirectory under this root. The cache is regeneratable from source
+ * (the markdown vault at ~/leedab-brains/<clientId>/ + any registered
+ * external folders) — deleting it is non-destructive. See
+ * docs/plans/brain-bootstrap.md §4.
+ *
+ * LEEDAB_BRAIN_INDEX_ROOT env overrides for tests + alternative layouts.
+ */
+export function brainIndexRoot() {
+    return process.env.LEEDAB_BRAIN_INDEX_ROOT
+        ? resolve(process.env.LEEDAB_BRAIN_INDEX_ROOT)
+        : resolve(STATE_DIR, "brain-index");
+}
+/** Per-client index directory. */
+export function brainIndexDir(clientId) {
+    return resolve(brainIndexRoot(), clientId);
+}

package/dist/templates/workspace/COO.md

@@ -14,6 +14,18 @@ channel message
   → you synthesise one final reply (Remember + Listen for the next signal)
 ```
 
+## Check the vault first
+
+The operator's notes (Obsidian or any markdown folder they've connected through Admin > Vault) are indexed locally. Before delegating, search the vault — the answer may already be written down. Cheap, no LLM cost, sub-second.
+
+```bash
+curl -s -X POST http://localhost:3000/api/brain/search \
+  -H "Content-Type: application/json" \
+  -d '{ "query": "<short keyword-ish query>", "limit": 6 }'
+```
+
+If a hit nails it, cite the `sourceUri` in your reply so the operator can trace the answer back to their own note. If hits is empty, proceed with the routing protocol below.
+
 ## Your routing protocol
 
 For every inbound message, decide ONE of three responses:

package/dist/templates/workspace/SOUL.md

@@ -14,6 +14,18 @@ channel message
   -> you synthesise one final reply (Remember + Listen for the next signal)
 ```
 
+## Brain skill (check the vault before you reason from scratch)
+
+The operator's notes — Obsidian vaults or any other markdown folder they've connected via Admin > Brain — are indexed locally. Before you delegate or fall back to general knowledge, search the vault for relevant context. Cheap, no LLM call, runs in milliseconds.
+
+```bash
+curl -s -X POST http://localhost:3000/api/brain/search \
+  -H "Content-Type: application/json" \
+  -d '{ "query": "<short keyword-ish query>", "limit": 6 }'
+```
+
+The response shape: `{ hits: [{ sourceUri, rootId, chunkOrd, score, snippet }] }`. Cite the `sourceUri` when you lean on a hit so the operator can trace your reasoning back to the note. If `hits` is empty, fall through to delegation or your own knowledge.
+
 ## Your routing protocol
 
 For every inbound message, decide ONE of three responses: