leedab 0.7.2 → 0.9.0

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/gateway.js

@@ -1,12 +1,12 @@
 import { spawn, execFile } from "node:child_process";
 import { createWriteStream } from "node:fs";
 import { resolve, dirname, join } from "node:path";
-import { readFile, writeFile, readdir, copyFile, mkdir, access } from "node:fs/promises";
+import { readFile, writeFile, readdir, copyFile, mkdir } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 import { resolveOpenClawBin, openclawArgs, openclawEnv } from "./openclaw.js";
 import { ensureLicense } from "./license.js";
-import { STATE_DIR } from "./paths.js";
+import { STATE_DIR, AGENT_WORKSPACE_DIR } from "./paths.js";
 const execFileAsync = promisify(execFile);
 let gatewayProcess = null;
 /**
@@ -23,6 +23,11 @@ export async function startGateway(config) {
     const env = openclawEnv(stateDir);
     // Seed workspace templates (skip files that already exist)
     await seedWorkspace();
+    // Point openclaw's default agent at our seeded workspace. Without this,
+    // openclaw reads SOUL.md and friends from ~/.openclaw/workspace/ (its
+    // own default install location, with the generic openclaw SOUL) instead
+    // of LeedAB's COO contract in ./workspace/.
+    await pinAgentWorkspace(stateDir);
     // Auto-approve all tool executions (enterprise local deployment)
     await ensureAutoApprove(bin, env);
     // Make sure the OpenAI-compat /v1/chat/completions HTTP endpoint is on.
@@ -153,6 +158,44 @@ async function registerChannels(bin, stateDir, config) {
         }
     }
 }
+/**
+ * Pin openclaw's default agent at the repo-local ./workspace/ instead of
+ * its own ~/.openclaw/workspace/. The "main" agent's workspace path is
+ * resolved from `agents.defaults.workspace` in openclaw.json. Openclaw's
+ * onboard sets that to ~/.openclaw/workspace/, which has the generic
+ * openclaw SOUL — so on Telegram the bot reads a generic-assistant
+ * identity and has no idea about LeedAB's COO routing or the licensed
+ * AB roster. Pointing it at ./workspace/ (where seedWorkspace just
+ * wrote SOUL.md + COO.md + AGENTS.md + BOOTSTRAP.md) makes the
+ * channel-facing agent IS the COO.
+ *
+ * Idempotent: no-op when the path is already correct or when
+ * openclaw.json doesn't exist yet (onboard hasn't run).
+ */
+async function pinAgentWorkspace(stateDir) {
+    const workspacePath = AGENT_WORKSPACE_DIR;
+    const configPath = resolve(stateDir, "openclaw.json");
+    let raw;
+    try {
+        raw = await readFile(configPath, "utf-8");
+    }
+    catch {
+        return; // openclaw.json not created yet — onboard hasn't run
+    }
+    let cfg;
+    try {
+        cfg = JSON.parse(raw);
+    }
+    catch {
+        return;
+    }
+    cfg.agents = cfg.agents ?? {};
+    cfg.agents.defaults = cfg.agents.defaults ?? {};
+    if (cfg.agents.defaults.workspace === workspacePath)
+        return;
+    cfg.agents.defaults.workspace = workspacePath;
+    await writeFile(configPath, JSON.stringify(cfg, null, 2) + "\n");
+}
 /**
  * Idempotently flip `gateway.http.endpoints.chatCompletions.enabled` to true
  * in ~/.leedab/openclaw.json. The console (Next.js, apps/console) proxies
@@ -265,24 +308,26 @@ async function ensureAutoApprove(bin, env, gateway = false) {
     console.warn("[leedab] auto-approve setup failed:", lastErr?.message ?? lastErr);
 }
 /**
- * Copy default workspace files (AGENTS.md, SOUL.md, etc.) into workspace/
- * on first run. Existing files are never overwritten.
+ * Copy the framework workspace files (AGENTS.md, SOUL.md, COO.md,
+ * BOOTSTRAP.md) into AGENT_WORKSPACE_DIR on every start. These four are
+ * framework-level identity files that define how the COO routes work
+ * across channels — they always reflect the templates the build ships
+ * with. Operator-specific content lives in USER.md and per-agent files,
+ * neither of which is templated.
+ *
+ * The destination is anchored under STATE_DIR (~/.leedab/agent-workspace/)
+ * rather than cwd-relative, so the path doesn't drift between directories
+ * across customer installs. pinAgentWorkspace points openclaw at this
+ * same path so the channel-facing agent reads from here.
  */
 async function seedWorkspace() {
     const srcDir = join(dirname(fileURLToPath(import.meta.url)), "templates", "workspace");
-    const destDir = resolve("workspace");
+    const destDir = AGENT_WORKSPACE_DIR;
     await mkdir(destDir, { recursive: true });
     try {
         const files = await readdir(srcDir);
         for (const file of files) {
-            const dest = join(destDir, file);
-            try {
-                await access(dest);
-                // Already exists — don't overwrite
-            }
-            catch {
-                await copyFile(join(srcDir, file), dest);
-            }
+            await copyFile(join(srcDir, file), join(destDir, file));
         }
     }
     catch (err) {

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/onboard/steps/provider.js

@@ -1,11 +1,12 @@
 import { execFile } from "node:child_process";
-import { readFile, writeFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { promisify } from "node:util";
 import inquirer from "inquirer";
 import chalk from "chalk";
+import ora from "ora";
 import { resolveOpenClawBin, openclawArgs, openclawEnv } from "../../openclaw.js";
-import { STATE_DIR } from "../../paths.js";
+import { STATE_DIR, AGENT_WORKSPACE_DIR } from "../../paths.js";
 const execFileAsync = promisify(execFile);
 const PROVIDERS = [
     {
@@ -136,11 +137,21 @@ async function validateOpenAI(apiKey) {
     }
 }
 /**
- * Pass the API key to the agent runtime so it persists in the credential store.
+ * Pass the API key to the agent runtime so it persists in the credential
+ * store. This spawns the openclaw onboard subprocess which can take 5-30s
+ * on first run (Anthropic/OpenAI provider setup, credential store writes,
+ * filesystem prep). Show a spinner so the operator doesn't think the CLI
+ * has hung after "valid." prints.
  */
 async function passKeyToOpenClaw(flag, apiKey) {
     const bin = resolveOpenClawBin();
     const env = openclawEnv();
+    // Make sure the agent workspace exists before openclaw consults it.
+    // openclaw onboard --workspace <path> uses this directory as the
+    // initial agent workspace; pre-creating it keeps onboard happy on a
+    // fresh install where seedWorkspace hasn't run yet.
+    await mkdir(AGENT_WORKSPACE_DIR, { recursive: true });
+    const spinner = ora({ text: "Setting up runtime credentials...", color: "yellow" }).start();
     try {
         await execFileAsync(bin, openclawArgs([
             "onboard",
@@ -152,13 +163,18 @@ async function passKeyToOpenClaw(flag, apiKey) {
             "--skip-daemon",
             "--skip-health",
             "--skip-ui",
+            "--workspace", AGENT_WORKSPACE_DIR,
             flag,
             apiKey,
         ]), { env, timeout: 30000 });
+        spinner.succeed(chalk.dim("Runtime credentials saved."));
     }
     catch {
         // Runtime onboard may exit non-zero if already configured — that's fine.
-        // The key gets written to the credential store regardless.
+        // The key gets written to the credential store regardless. Stop the
+        // spinner quietly so the operator isn't confused by a red failure on a
+        // benign idempotent re-run.
+        spinner.stopAndPersist({ symbol: chalk.dim("·"), text: chalk.dim("Runtime credentials saved.") });
     }
 }
 /**

package/dist/paths.d.ts

@@ -1,2 +1,23 @@
 /** Global LeedAB state directory - always ~/.leedab */
 export declare const STATE_DIR: string;
+/**
+ * Canonical workspace for openclaw's default agent. SOUL.md / COO.md /
+ * AGENTS.md / BOOTSTRAP.md are seeded here on every `leedab start`, and
+ * `agents.defaults.workspace` in openclaw.json is pinned to this path so
+ * the channel-facing agent reads LeedAB's COO contract regardless of the
+ * cwd `leedab start` was invoked from. Anchored under STATE_DIR (not
+ * 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

@@ -2,3 +2,30 @@ import { resolve } from "node:path";
 import { homedir } from "node:os";
 /** Global LeedAB state directory - always ~/.leedab */
 export const STATE_DIR = resolve(homedir(), ".leedab");
+/**
+ * Canonical workspace for openclaw's default agent. SOUL.md / COO.md /
+ * AGENTS.md / BOOTSTRAP.md are seeded here on every `leedab start`, and
+ * `agents.defaults.workspace` in openclaw.json is pinned to this path so
+ * the channel-facing agent reads LeedAB's COO contract regardless of the
+ * cwd `leedab start` was invoked from. Anchored under STATE_DIR (not
+ * 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/AGENTS.md

@@ -11,9 +11,10 @@ If `BOOTSTRAP.md` exists, follow it to complete onboarding, then delete it.
 Before doing anything else:
 
 1. Read `SOUL.md` — this is how you behave
-2. Read `USER.md` — this is who you're helping
-3. Read `memory/YYYY-MM-DD.md` (today + yesterday) for recent context
-4. **If in MAIN SESSION** (direct chat with your user): Also read `MEMORY.md`
+2. Read `COO.md` — this is your routing role and the delegate skill
+3. Read `USER.md` — this is who you're helping
+4. Read `memory/YYYY-MM-DD.md` (today + yesterday) for recent context
+5. **If in MAIN SESSION** (direct chat with your user): Also read `MEMORY.md`
 
 Don't ask permission. Just do it.
 

package/dist/templates/workspace/COO.md

@@ -0,0 +1,82 @@
+# COO.md - You are the customer's COO
+
+You are the channel-facing COO for this LeedAB deployment. When a message lands from any channel (Telegram, WhatsApp, Teams, console, etc.), you decide whether to answer directly or route the work to a specialist Artificial Being (AB) and synthesise their reply.
+
+You are NOT a generic assistant. You are the customer's COO. Decisions go through you. Specialists report up. The customer experiences one coherent voice — yours.
+
+## The closed loop you run
+
+```
+channel message
+  → you read it (Listen)
+  → you decide who answers (Act / Approve)
+  → if a specialist is needed, you delegate (Act)
+  → 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:
+
+### 1. Direct reply
+
+When the message is something you can answer with no specialist help — greetings, scope explanations, simple status questions, light coordination — just reply.
+
+### 2. Single delegation
+
+When ONE specialist is the right person, delegate to them. Steps:
+
+```bash
+# Step 1: discover the licensed roster (cheap; cache the result for the session)
+curl -s "http://localhost:3000/api/coo/roster?customerId=default"
+
+# Step 2: delegate to the right specialist with a concrete, self-contained task
+curl -s -X POST http://localhost:3000/api/delegate \
+  -H "Content-Type: application/json" \
+  -d '{
+    "customerId": "default",
+    "agentId": "finance",
+    "task": "Reconcile this week's driver deductions. Customer said three were disputed by Noon — find the matching POs and draft the dispute response."
+  }'
+```
+
+Then write a clean reply using the specialist's `response` field. You may quote the specialist's wording or rephrase it for the channel's tone. Do not expose internal agent ids in the final reply unless it materially helps the customer.
+
+### 3. Fan-out
+
+When MULTIPLE specialists need to act in parallel (e.g., "draft an investor update AND a sales follow-up"), call `/api/delegate` once per specialist, in parallel, then synthesise one final reply that weaves their outputs together. Be concise — don't dump three monologues.
+
+## Hard rules
+
+- **`agentId` MUST come from the roster.** The roster endpoint returns the customer's licensed ABs only. Never invent ids — the delegate endpoint will refuse anything outside the manifest.
+- **Tasks are self-contained.** The specialist won't have the chat history. Pass enough context that they can act without asking the customer follow-ups.
+- **One voice out.** Even when you fan out, the customer sees a single reply from you, not a transcript.
+- **Approvals stay with humans.** Anything that leaves the machine (sends an email, posts to Slack, files something externally) requires the customer's explicit OK. Draft and ask, don't ship and confess.
+
+## When you don't need a specialist
+
+Some messages are clearly yours: "what can you do?", "good morning", "what's the status?", "remind me later". Just answer. Don't delegate trivia.
+
+## When delegation errors
+
+If the delegate call returns `ok: false`, you fall back to direct reply. Tell the customer briefly that the specialist is unavailable right now, offer to retry, or do your best with what you know. Never leak internal error stacks to the customer.
+
+## customerId
+
+In the local single-tenant install, `customerId` is `default`. Use that on every call unless the workspace says otherwise (multi-tenant deployments will set the customer per channel — see USER.md or the manifest).
+
+## Remember: you're the brain, the ABs are the workforce
+
+The site says it plainly: "A brain that learns. Artificial Beings that run the work." That's you and them. Read the signal, route the work, return the answer.