@tpsdev-ai/flair 0.5.3 → 0.6.0

package/dist/cli.js

@@ -7,6 +7,7 @@ import { join, resolve as resolvePath } from "node:path";
 import { spawn } from "node:child_process";
 import { createPrivateKey, sign as nodeCryptoSign, randomUUID } from "node:crypto";
 import { keystore } from "./keystore.js";
+import { deploy as deployToFabric, validateOptions as validateDeployOptions, buildTargetUrl as buildDeployUrl } from "./deploy.js";
 // Federation crypto helpers — inlined to avoid cross-boundary imports from
 // src/ into resources/, which don't survive npm packaging (see also
 // resources/federation-crypto.ts; the two must stay in sync).
@@ -253,7 +254,7 @@ async function authFetch(baseUrl, agentId, keyPath, method, path, body) {
     });
 }
 async function waitForHealth(httpPort, adminUser, adminPass, timeoutMs) {
-    const url = `http://127.0.0.1:${httpPort}/health`;
+    const url = `http://127.0.0.1:${httpPort}/Health`;
     const deadline = Date.now() + timeoutMs;
     let attempt = 0;
     while (Date.now() < deadline) {
@@ -263,7 +264,9 @@ async function waitForHealth(httpPort, adminUser, adminPass, timeoutMs) {
                 headers: { Authorization: `Basic ${Buffer.from(`${adminUser}:${adminPass}`).toString("base64")}` },
                 signal: AbortSignal.timeout(2000),
             });
-            if (res.status > 0)
+            // 2xx = healthy; 401 = Harper up but credentials wrong — still "reachable"
+            // enough for restart success. Anything else (5xx, 502 during shutdown) keeps polling.
+            if (res.ok || res.status === 401)
                 return;
         }
         catch { /* not ready yet */ }
@@ -271,6 +274,35 @@ async function waitForHealth(httpPort, adminUser, adminPass, timeoutMs) {
     }
     throw new Error(`Harper at port ${httpPort} did not respond within ${timeoutMs}ms (${attempt} attempts)`);
 }
+// Blocks until the given PID is gone (ESRCH from signal 0), or timeout.
+// Used during restart to confirm the old Harper process actually exited before
+// we start polling /Health — otherwise the still-shutting-down old process can
+// answer and we'd declare restart success while a gap is still ahead.
+async function waitForProcessExit(pid, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            process.kill(pid, 0);
+        }
+        catch {
+            return;
+        }
+        await new Promise((r) => setTimeout(r, HEALTH_POLL_INTERVAL_MS));
+    }
+    throw new Error(`Process ${pid} did not exit within ${timeoutMs}ms`);
+}
+function readHarperPid(dataDir) {
+    const pidFile = join(dataDir, "hdb.pid");
+    if (!existsSync(pidFile))
+        return null;
+    try {
+        const n = Number(readFileSync(pidFile, "utf-8").trim());
+        return Number.isInteger(n) && n > 0 ? n : null;
+    }
+    catch {
+        return null;
+    }
+}
 async function seedAgentViaOpsApi(opsPort, agentId, pubKeyB64url, adminUser, adminPass) {
     const url = `http://127.0.0.1:${opsPort}/`;
     const auth = Buffer.from(`${adminUser}:${adminPass}`).toString("base64");
@@ -292,6 +324,163 @@ async function seedAgentViaOpsApi(opsPort, agentId, pubKeyB64url, adminUser, adm
         throw new Error(`Operations API insert failed (${res.status}): ${text}`);
     }
 }
+export function templateSoul(choice) {
+    const templates = {
+        "1": [
+            ["role", "Pair programmer on this machine. Concise, direct, proactive about flagging risks before I hit them."],
+            ["project", "(fill in: the main project or repo I'm helping with — shapes what bootstrap prioritizes)"],
+            ["standards", "Match existing codebase style. Prefer editing over rewriting. Surface tradeoffs on ambiguous decisions instead of making unilateral calls."],
+        ],
+        "2": [
+            ["role", "Team agent — operates in a shared repo and coordinates with other agents. Communicate through structured channels (PRs, issues, mail), not free-form chat."],
+            ["project", "(fill in: the repo or ops flow this agent runs in)"],
+            ["standards", "Keep changes minimal and reviewable. Always open PRs, never push to main. Document decisions in the issue tracker, not in agent memory."],
+        ],
+        "3": [
+            ["role", "Research assistant. Survey sources, extract findings, write structured notes. Flag uncertainty explicitly; separate evidence from inference."],
+            ["project", "(fill in: the research area or question being tracked)"],
+            ["standards", "Cite sources inline. When sources disagree, surface the disagreement rather than picking a side silently. Prefer primary sources."],
+        ],
+    };
+    return templates[choice] ?? [];
+}
+async function customSoulPrompts(ask) {
+    const entries = [];
+    console.log("\n   Three fields. Press Enter on any to skip it.\n");
+    console.log("   role — how the agent identifies itself and acts");
+    console.log("     \"Senior dev, concise and direct\"");
+    console.log("     \"Data-engineering sidekick, SQL-first\"");
+    console.log("     \"PM assistant — asks clarifying questions before writing specs\"");
+    const role = await ask("   > ");
+    if (role.trim())
+        entries.push(["role", role.trim()]);
+    console.log("\n   project — what the agent is currently focused on");
+    console.log("     \"LifestyleLab — building Flair and TPS\"");
+    console.log("     \"Legal discovery review, Q2 contracts\"");
+    console.log("     \"Personal automation scripts in Bash + Python\"");
+    const project = await ask("   > ");
+    if (project.trim())
+        entries.push(["project", project.trim()]);
+    console.log("\n   standards — communication or coding preferences that should persist");
+    console.log("     \"No emojis. Match existing style. Ask before risky ops.\"");
+    console.log("     \"Always cite sources. Flag uncertainty explicitly.\"");
+    console.log("     \"Typescript strict mode. Prefer composition over inheritance.\"");
+    const standards = await ask("   > ");
+    if (standards.trim())
+        entries.push(["standards", standards.trim()]);
+    return entries;
+}
+async function editEntries(ask, entries) {
+    console.log("\n   Press Enter to keep each default, or type a replacement:");
+    const result = [];
+    for (const [key, def] of entries) {
+        const preview = def.length > 60 ? def.slice(0, 57) + "..." : def;
+        console.log(`\n   ${key} [keep: ${preview}]`);
+        const input = (await ask("   > ")).trim();
+        result.push([key, input || def]);
+    }
+    return result;
+}
+export function parseSoulJson(raw) {
+    const jsonMatch = raw.match(/\{[\s\S]*\}/);
+    if (!jsonMatch)
+        throw new Error("no JSON object found in input");
+    const parsed = JSON.parse(jsonMatch[0]);
+    const entries = [];
+    if (parsed.role)
+        entries.push(["role", String(parsed.role).trim()]);
+    if (parsed.project)
+        entries.push(["project", String(parsed.project).trim()]);
+    if (parsed.standards)
+        entries.push(["standards", String(parsed.standards).trim()]);
+    if (entries.length === 0)
+        throw new Error("JSON had no role/project/standards keys");
+    return entries;
+}
+async function runSoulWizard(agentId) {
+    const { createInterface } = await import("node:readline");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    // Buffered ask: collects rapid input (pasted text) into one answer.
+    // Waits 200ms after last line before resolving, so pasted multiline
+    // blocks are captured as a single answer instead of spilling across prompts.
+    const ask = (q) => new Promise(resolve => {
+        let buffer = "";
+        let timer = null;
+        let done = false;
+        const finish = () => {
+            if (done)
+                return;
+            done = true;
+            rl.removeListener("line", onLine);
+            resolve(buffer.trim());
+        };
+        const onLine = (line) => {
+            buffer += (buffer ? "\n" : "") + line;
+            if (timer)
+                clearTimeout(timer);
+            timer = setTimeout(finish, 200);
+        };
+        process.stdout.write(q);
+        rl.on("line", onLine);
+    });
+    console.log("\n🎭 Agent personality setup");
+    console.log("   Soul entries shape what every future session starts with.\n");
+    console.log("   What best describes this agent?");
+    console.log("     (1) Solo developer — helps you with code on this machine");
+    console.log("     (2) Team agent — runs in a shared repo / ops flow");
+    console.log("     (3) Research assistant — surveys sources, writes notes");
+    console.log("     (4) Draft from Claude — paste a Claude-generated JSON draft");
+    console.log("     (5) Custom — I'll prompt for each field with examples");
+    console.log("     (s) Skip — set up later; `flair doctor` will nudge\n");
+    const choice = (await ask("   Choice [1-5/s]: ")).trim().toLowerCase();
+    let entries = [];
+    if (choice === "s" || choice === "skip") {
+        rl.close();
+        return [];
+    }
+    else if (choice === "1" || choice === "2" || choice === "3") {
+        entries = templateSoul(choice);
+        console.log("\n   Template draft:");
+        for (const [k, v] of entries)
+            console.log(`     ${k}: ${v}`);
+        const edit = (await ask("\n   Edit before saving? [y/N]: ")).trim().toLowerCase();
+        if (edit === "y" || edit === "yes") {
+            entries = await editEntries(ask, entries);
+        }
+    }
+    else if (choice === "4") {
+        console.log("\n   Paste this prompt into your Claude session:");
+        console.log("   ─────────────────────────────────────────────────────────────");
+        console.log(`   Generate a JSON object with keys "role", "project", and`);
+        console.log(`   "standards" suitable as Flair soul entries for an agent with`);
+        console.log(`   id "${agentId}" operating in my current context. Each value`);
+        console.log(`   should be 1-2 specific sentences that shape behavior. Output`);
+        console.log(`   only the JSON object, no prose.`);
+        console.log("   ─────────────────────────────────────────────────────────────\n");
+        console.log("   Paste the resulting JSON below:");
+        const raw = await ask("   > ");
+        try {
+            entries = parseSoulJson(raw);
+            console.log("\n   Parsed draft:");
+            for (const [k, v] of entries)
+                console.log(`     ${k}: ${v}`);
+            const edit = (await ask("\n   Edit before saving? [y/N]: ")).trim().toLowerCase();
+            if (edit === "y" || edit === "yes") {
+                entries = await editEntries(ask, entries);
+            }
+        }
+        catch (err) {
+            console.log(`\n   Couldn't parse JSON (${err.message}). Falling back to custom prompts.`);
+            entries = await customSoulPrompts(ask);
+        }
+    }
+    else {
+        // Custom (5) or unrecognized input — route to custom prompts
+        entries = await customSoulPrompts(ask);
+    }
+    rl.close();
+    return entries.filter(([, v]) => v.trim().length > 0);
+}
 // ─── Program ─────────────────────────────────────────────────────────────────
 // Read version from package.json at the package root
 const __pkgDir = join(import.meta.dirname ?? __dirname, "..");
@@ -535,43 +724,15 @@ program
     }
     console.log(`\n   Export: FLAIR_URL=${httpUrl}`);
     // ── First-run soul setup ──────────────────────────────────────────────
-    // Interactive prompts to set initial personality. Skipped with --skip-soul
-    // or when stdin is not a TTY (CI, scripts, piped input).
+    // Interactive wizard to set initial personality (see runSoulWizard).
+    // Skipped with --skip-soul or when stdin is not a TTY (CI, scripts, pipe).
+    //
+    // Non-TTY / --skip-soul used to seed placeholder text like
+    // "AI assistant [default]" — it leaked into bootstrap output and
+    // confused users. Now those paths leave the soul empty and nudge the
+    // user toward `flair soul set` / `flair doctor` instead.
     if (!opts.skipSoul && process.stdin.isTTY) {
-        console.log("\n🎭 Set up agent personality (press Enter to skip any):\n");
-        const { createInterface } = await import("node:readline");
-        const rl = createInterface({ input: process.stdin, output: process.stdout });
-        // Buffered ask: collects rapid input (pasted text) into one answer.
-        // Waits 200ms after last line before resolving, so pasted multiline
-        // blocks are captured as a single answer instead of spilling across prompts.
-        const ask = (q) => new Promise(resolve => {
-            let buffer = "";
-            let timer = null;
-            const finish = () => {
-                rl.removeListener("line", onLine);
-                resolve(buffer.trim());
-            };
-            const onLine = (line) => {
-                buffer += (buffer ? "\n" : "") + line;
-                if (timer)
-                    clearTimeout(timer);
-                timer = setTimeout(finish, 200);
-            };
-            process.stdout.write(q);
-            rl.on("line", onLine);
-        });
-        const role = await ask("   What's this agent's role? (e.g., \"Senior dev, concise and direct\")\n   > ");
-        const project = await ask("   What project is it working on?\n   > ");
-        const standards = await ask("   Any coding standards or preferences?\n   > ");
-        rl.close();
-        // Write non-empty answers as soul entries
-        const soulEntries = [];
-        if (role.trim())
-            soulEntries.push(["role", role.trim()]);
-        if (project.trim())
-            soulEntries.push(["project", project.trim()]);
-        if (standards.trim())
-            soulEntries.push(["standards", standards.trim()]);
+        const soulEntries = await runSoulWizard(agentId);
         if (soulEntries.length > 0) {
             console.log("");
             for (const [key, value] of soulEntries) {
@@ -583,30 +744,19 @@ program
                     console.warn(`   ⚠ soul:${key} failed: ${err.message}`);
                 }
             }
-            console.log(`\n   ${soulEntries.length} soul entries saved. Bootstrap will include them.`);
+            console.log(`\n   ${soulEntries.length} soul entries saved.`);
+            console.log(`   Preview what an agent will see: flair bootstrap --agent ${agentId}`);
         }
         else {
-            console.log("\n   No soul entries — you can add them later with: flair soul set --agent " + agentId + " --key role --value \"...\"");
+            console.log(`\n   No soul entries saved. Add later with:`);
+            console.log(`     flair soul set --agent ${agentId} --key role --value "..."`);
+            console.log(`   Or run \`flair doctor\` anytime for a nudge.`);
         }
     }
     else {
-        // --skip-soul or non-interactive: seed sensible defaults so bootstrap returns useful context
-        const defaultSoulEntries = [
-            ["role", "AI assistant [default — customize with 'flair soul set']"],
-            ["personality", "Helpful, precise, and proactive [default — customize with 'flair soul set']"],
-            ["constraints", "Respect user privacy. Be concise. [default — customize with 'flair soul set']"],
-        ];
-        console.log("\nSeeding default soul entries...");
-        for (const [key, value] of defaultSoulEntries) {
-            try {
-                await authFetch(httpUrl, agentId, privPath, "PUT", `/Soul/${agentId}:${key}`, { id: `${agentId}:${key}`, agentId, key, value, createdAt: new Date().toISOString() });
-                console.log(`   ✓ soul:${key} set (default)`);
-            }
-            catch (err) {
-                console.warn(`   ⚠ soul:${key} failed: ${err.message}`);
-            }
-        }
-        console.log(`   Customize with: flair soul set --agent ${agentId} --key role --value "..."`);
+        const reason = opts.skipSoul ? "--skip-soul" : "non-interactive";
+        console.log(`\n   Soul prompts skipped (${reason}). Add entries with:`);
+        console.log(`     flair soul set --agent ${agentId} --key role --value "..."`);
     }
     console.log(`\n   Claude Code: Add to your CLAUDE.md:`);
     console.log(`     At the start of every session, run mcp__flair__bootstrap before responding.`);
@@ -1304,8 +1454,8 @@ program
         table: "MemoryGrant",
         records: [{
                 id: grantId,
-                fromAgentId: fromAgent,
-                toAgentId: toAgent,
+                ownerId: fromAgent,
+                granteeId: toAgent,
                 scope,
                 createdAt: new Date().toISOString(),
             }],
@@ -1793,23 +1943,81 @@ rem
     }
 });
 // ─── flair status ─────────────────────────────────────────────────────────────
-program
-    .command("status")
-    .description("Show Flair instance status, memory stats, and agent info")
-    .option("--port <port>", "Harper HTTP port")
-    .option("--url <url>", "Flair base URL (overrides --port)")
-    .option("--json", "Output as JSON")
-    .option("--agent <id>", "Agent ID for authenticated detail (or set FLAIR_AGENT_ID)")
-    .action(async (opts) => {
+function humanBytes(n) {
+    if (!Number.isFinite(n) || n < 0)
+        return "—";
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    if (n < 1024 * 1024 * 1024)
+        return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+    return `${(n / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+}
+function relativeTime(iso) {
+    if (!iso)
+        return "—";
+    const ago = Date.now() - new Date(iso).getTime();
+    if (!Number.isFinite(ago) || ago < 0)
+        return "—";
+    const mins = Math.floor(ago / 60000);
+    const hrs = Math.floor(ago / 3600000);
+    const days = Math.floor(ago / 86400000);
+    return days > 0 ? `${days}d ago` : hrs > 0 ? `${hrs}h ago` : mins > 0 ? `${mins}m ago` : "just now";
+}
+// Renders OAuth status lines from non-secret metadata. /HealthDetail never
+// returns clientSecret — only counts and identifying fields (id, name,
+// registeredBy, createdAt, issuer). Inputs are coerced to scalar primitives
+// before formatting to keep the display values clearly separated from the
+// source record.
+function oauthSummaryLines(o) {
+    const clients = Number(o?.clients ?? 0);
+    const idps = Number(o?.idpConfigs ?? 0);
+    const tokens = Number(o?.activeTokens ?? 0);
+    return [
+        "\nOAuth:",
+        `  Clients:     ${clients}   IdPs: ${idps}   Active tokens: ${tokens}`,
+    ];
+}
+function oauthDetailLines(o) {
+    const clients = Number(o?.clients ?? 0);
+    const idps = Number(o?.idpConfigs ?? 0);
+    const tokens = Number(o?.activeTokens ?? 0);
+    const out = [
+        "OAuth:",
+        `  Clients:       ${clients}`,
+        `  IdP configs:   ${idps}`,
+        `  Active tokens: ${tokens}`,
+    ];
+    if (Array.isArray(o?.clientList) && o.clientList.length > 0) {
+        out.push("", "  Clients:");
+        for (const c of o.clientList) {
+            const id = String(c?.id ?? "");
+            const name = String(c?.name ?? "—");
+            const registeredBy = String(c?.registeredBy ?? "—");
+            const createdAt = String(c?.createdAt ?? "—");
+            out.push(`    ${id}  ${name}  ${registeredBy}  ${createdAt}`);
+        }
+    }
+    if (Array.isArray(o?.idpList) && o.idpList.length > 0) {
+        out.push("", "  IdPs:");
+        for (const i of o.idpList) {
+            const id = String(i?.id ?? "");
+            const name = String(i?.name ?? "—");
+            const issuer = String(i?.issuer ?? "—");
+            out.push(`    ${id}  ${name}  ${issuer}`);
+        }
+    }
+    return out;
+}
+async function fetchHealthDetail(opts) {
     const port = resolveHttpPort(opts);
     const baseUrl = opts.url ?? `http://127.0.0.1:${port}`;
     let healthy = false;
     let healthData = null;
-    // 1. Basic health check — try unauthenticated first, then with admin auth
     try {
         let res = await fetch(`${baseUrl}/Health`, { signal: AbortSignal.timeout(5000) });
         if (!res.ok && res.status === 401) {
-            // Harper requires auth (authorizeLocal: true) — retry with admin credentials
             const adminPass = process.env.FLAIR_ADMIN_PASS ?? process.env.HDB_ADMIN_PASSWORD;
             if (adminPass) {
                 res = await fetch(`${baseUrl}/Health`, {
@@ -1821,7 +2029,6 @@ program
         healthy = res.ok;
     }
     catch { /* unreachable */ }
-    // 2. Try authenticated /HealthDetail for rich stats
     if (healthy) {
         const agentId = opts.agent || process.env.FLAIR_AGENT_ID;
         if (agentId) {
@@ -1833,14 +2040,12 @@ program
                         headers: { Authorization: authHeader },
                         signal: AbortSignal.timeout(5000),
                     });
-                    if (res.ok) {
+                    if (res.ok)
                         healthData = await res.json().catch(() => null);
-                    }
                 }
-                catch { /* fall through to basic output */ }
+                catch { /* fall through */ }
             }
         }
-        // Fallback: try admin basic auth if available
         if (!healthData) {
             const adminPass = process.env.HDB_ADMIN_PASSWORD || process.env.FLAIR_ADMIN_PASS;
             if (adminPass) {
@@ -1850,14 +2055,24 @@ program
                         headers: { Authorization: auth },
                         signal: AbortSignal.timeout(5000),
                     });
-                    if (res.ok) {
+                    if (res.ok)
                         healthData = await res.json().catch(() => null);
-                    }
                 }
-                catch { /* fall through to basic output */ }
+                catch { /* fall through */ }
             }
         }
     }
+    return { healthy, baseUrl, healthData };
+}
+const statusCmd = program
+    .command("status")
+    .description("Show Flair instance status, memory stats, and agent info")
+    .option("--port <port>", "Harper HTTP port")
+    .option("--url <url>", "Flair base URL (overrides --port)")
+    .option("--json", "Output as JSON")
+    .option("--agent <id>", "Agent ID for authenticated detail (or set FLAIR_AGENT_ID)")
+    .action(async (opts) => {
+    const { healthy, baseUrl, healthData } = await fetchHealthDetail(opts);
     if (opts.json) {
         console.log(JSON.stringify({ healthy, url: baseUrl, flairVersion: __pkgVersion, ...healthData }, null, 2));
         if (!healthy)
@@ -1870,7 +2085,6 @@ program
         console.log(`\n  Run: flair start  or  flair doctor`);
         process.exit(1);
     }
-    // Format uptime
     const uptimeSec = healthData?.uptimeSeconds;
     let uptimeStr = "";
     if (uptimeSec != null) {
@@ -1879,41 +2093,268 @@ program
         const m = Math.floor((uptimeSec % 3600) / 60);
         uptimeStr = d > 0 ? `${d}d ${h}h` : h > 0 ? `${h}h ${m}m` : `${m}m`;
     }
-    // Format last write as relative time
-    let lastWriteStr = "";
-    if (healthData?.lastWrite) {
-        const ago = Date.now() - new Date(healthData.lastWrite).getTime();
-        const mins = Math.floor(ago / 60000);
-        const hrs = Math.floor(ago / 3600000);
-        const days = Math.floor(ago / 86400000);
-        lastWriteStr = days > 0 ? `${days}d ago` : hrs > 0 ? `${hrs}h ago` : mins > 0 ? `${mins}m ago` : "just now";
-    }
     const pid = healthData?.pid ?? "";
     const agents = healthData?.agents;
     const memories = healthData?.memories;
-    console.log(`Flair v${__pkgVersion} — 🟢 running${pid ? ` (PID ${pid}` : ""}${uptimeStr ? `, uptime ${uptimeStr})` : pid ? ")" : ""}`);
+    const warnings = Array.isArray(healthData?.warnings) ? healthData.warnings : [];
+    const hasWarn = warnings.some((w) => w.level === "warn");
+    // Header state-word stays "running" whenever the process is alive; the
+    // icon conveys health (🟢 clean / 🟡 warnings). 🔴 unreachable is already
+    // handled above by the `!healthy` early-exit. Decoupling state from
+    // health keeps the smoke-test `grep -q "running"` stable across tiers.
+    const headerIcon = hasWarn ? "🟡" : "🟢";
+    console.log(`Flair v${__pkgVersion} — ${headerIcon} running${pid ? ` (PID ${pid}` : ""}${uptimeStr ? `, uptime ${uptimeStr})` : pid ? ")" : ""}`);
     console.log(`  URL:        ${baseUrl}`);
+    if (warnings.length > 0) {
+        console.log(`\n⚠ Warnings:  ${warnings.length}`);
+        for (const w of warnings)
+            console.log(`  • ${w.level} ${w.message}`);
+    }
     if (memories) {
-        const embStr = memories.withEmbeddings > 0
-            ? `${memories.withEmbeddings} with embeddings`
-            : "";
-        const hashStr = memories.hashFallback > 0
-            ? `${memories.hashFallback} hash-fallback`
-            : "";
+        console.log("\nMemory:");
+        const embStr = memories.withEmbeddings > 0 ? `${memories.withEmbeddings} embedded` : "";
+        const hashStr = memories.hashFallback > 0 ? `${memories.hashFallback} hash` : "";
         const detail = [embStr, hashStr].filter(Boolean).join(", ");
-        console.log(`  Memories:   ${memories.total}${detail ? ` (${detail})` : ""}`);
+        console.log(`  Total:       ${memories.total}${detail ? ` (${detail})` : ""}`);
+        if (memories.modelCounts && typeof memories.modelCounts === "object") {
+            const entries = Object.entries(memories.modelCounts)
+                .filter(([, n]) => n > 0)
+                .sort((a, b) => b[1] - a[1]);
+            if (entries.length > 0) {
+                const formatted = entries.map(([k, n]) => `${k}: ${n}`).join(", ");
+                console.log(`  Embeddings:  ${formatted}`);
+            }
+        }
+        if (memories.byDurability) {
+            const d = memories.byDurability;
+            console.log(`  Durability:  ${d.permanent ?? 0} permanent / ${d.persistent ?? 0} persistent / ${d.standard ?? 0} standard / ${d.ephemeral ?? 0} ephemeral`);
+        }
+        if (typeof memories.archived === "number")
+            console.log(`  Archived:    ${memories.archived}`);
+        if (typeof memories.expired === "number" && memories.expired > 0)
+            console.log(`  Expired:     ${memories.expired}`);
+        if (healthData?.lastWrite)
+            console.log(`  Last write:  ${relativeTime(healthData.lastWrite)}`);
+    }
+    if (agents && agents.count > 0) {
+        console.log("\nAgents:");
+        const nameStr = agents.names?.length > 0 ? ` — ${agents.names.join(", ")}` : "";
+        console.log(`  ${agents.count} total${nameStr}`);
+        if (agents.count > 1 && Array.isArray(agents.perAgent) && agents.perAgent.length > 0) {
+            const idW = Math.max(2, ...agents.perAgent.map((r) => (r.id ?? "").length));
+            // Older HealthDetail responses only carry id / memoryCount / lastWriteAt.
+            // Only print the richer columns if at least one row supplies them.
+            const hasDeep = agents.perAgent.some((r) => typeof r.hashFallback === "number" || typeof r.writes24h === "number");
+            if (hasDeep) {
+                console.log(`  ${"id".padEnd(idW)}  memories  hash_fb  24h  last_write`);
+                for (const r of agents.perAgent) {
+                    const fb = typeof r.hashFallback === "number" ? String(r.hashFallback) : "—";
+                    const w24 = typeof r.writes24h === "number" ? String(r.writes24h) : "—";
+                    console.log(`  ${(r.id ?? "").padEnd(idW)}  ${String(r.memoryCount).padStart(8)}  ${fb.padStart(7)}  ${w24.padStart(3)}  ${relativeTime(r.lastWriteAt)}`);
+                }
+            }
+            else {
+                console.log(`  ${"id".padEnd(idW)}  memories  last_write`);
+                for (const r of agents.perAgent) {
+                    console.log(`  ${(r.id ?? "").padEnd(idW)}  ${String(r.memoryCount).padStart(8)}  ${relativeTime(r.lastWriteAt)}`);
+                }
+            }
+        }
+    }
+    if (healthData?.relationships) {
+        const r = healthData.relationships;
+        console.log("\nRelationships:");
+        console.log(`  ${r.total} total (${r.active} active)`);
+    }
+    if (healthData?.soul && healthData.soul.total > 0) {
+        const s = healthData.soul;
+        const bp = s.byPriority ?? {};
+        console.log("\nSoul:");
+        console.log(`  ${s.total} entries — ${bp.critical ?? 0} critical / ${bp.high ?? 0} high / ${bp.standard ?? 0} standard / ${bp.low ?? 0} low`);
+    }
+    else if (typeof healthData?.soulEntries === "number" && healthData.soulEntries > 0) {
+        console.log("\nSoul:");
+        console.log(`  ${healthData.soulEntries} entries`);
+    }
+    if (healthData?.rem) {
+        const r = healthData.rem;
+        console.log("\nREM:");
+        if (r.lastLightAt)
+            console.log(`  Last light:        ${relativeTime(r.lastLightAt)}`);
+        if (r.lastRapidAt)
+            console.log(`  Last rapid:        ${relativeTime(r.lastRapidAt)}`);
+        if (r.lastRestorativeAt)
+            console.log(`  Last restorative:  ${relativeTime(r.lastRestorativeAt)}`);
+        const nightly = r.nightlyEnabled === true ? "enabled" : r.nightlyEnabled === false ? "disabled" : "unknown";
+        console.log(`  Nightly:           ${nightly}`);
+        if (r.nightlyEnabled && r.lastNightlyAt)
+            console.log(`  Last nightly:      ${relativeTime(r.lastNightlyAt)}`);
+        if (typeof r.pendingCandidates === "number" && r.pendingCandidates > 0) {
+            console.log(`  Pending candidates: ${r.pendingCandidates}`);
+        }
+    }
+    if (healthData?.federation) {
+        const f = healthData.federation;
+        console.log("\nFederation:");
+        if (f.instance)
+            console.log(`  Instance:    ${f.instance.id} (${f.instance.role ?? "—"}, ${f.instance.status ?? "—"})`);
+        if (f.peers)
+            console.log(`  Peers:       ${f.peers.total} (${f.peers.connected} connected / ${f.peers.disconnected} down / ${f.peers.revoked} revoked)`);
+        if (f.pendingTokens > 0)
+            console.log(`  Pairing:     ${f.pendingTokens} unconsumed token(s)`);
+    }
+    if (healthData?.oauth) {
+        const lines = oauthSummaryLines(healthData.oauth);
+        for (const line of lines)
+            console.log(line);
+    }
+    if (healthData?.bridges) {
+        const b = healthData.bridges;
+        console.log("\nBridges:");
+        if (Array.isArray(b.installed) && b.installed.length > 0)
+            console.log(`  Installed:   ${b.installed.join(", ")}`);
+        if (b.lastImport)
+            console.log(`  Last import: ${relativeTime(b.lastImport)}`);
+        if (b.lastExport)
+            console.log(`  Last export: ${relativeTime(b.lastExport)}`);
+    }
+    if (healthData?.disk) {
+        const d = healthData.disk;
+        console.log("\nDisk:");
+        console.log(`  Data:        ${d.dataDir} — ${humanBytes(d.dataBytes ?? 0)}`);
+        console.log(`  Snapshots:   ${d.snapshotDir} — ${humanBytes(d.snapshotBytes ?? 0)}`);
+    }
+    console.log("");
+    if (warnings.length > 0)
+        console.log(`  Health:     ⚠ ${warnings.length} warning(s)`);
+    else
+        console.log(`  Health:     ✅ all checks passing`);
+});
+statusCmd
+    .command("rem")
+    .description("Show REM (memory hygiene) subsystem status")
+    .action(async function () {
+    const opts = this.optsWithGlobals();
+    const { healthy, healthData } = await fetchHealthDetail(opts);
+    if (opts.json) {
+        console.log(JSON.stringify({ healthy, rem: healthData?.rem ?? null }, null, 2));
+        if (!healthy)
+            process.exit(1);
+        return;
     }
-    if (agents) {
-        const nameStr = agents.names?.length > 0 ? ` (${agents.names.join(", ")})` : "";
-        console.log(`  Agents:     ${agents.count}${nameStr}`);
+    if (!healthy) {
+        console.log("🔴 unreachable");
+        process.exit(1);
     }
-    if (healthData?.soulEntries != null) {
-        console.log(`  Soul:       ${healthData.soulEntries} entries`);
+    const r = healthData?.rem;
+    if (!r) {
+        console.log("REM: not configured (no log entries or platform timers found)");
+        return;
     }
-    if (lastWriteStr) {
-        console.log(`  Last write: ${lastWriteStr}`);
+    console.log("REM:");
+    console.log(`  Last light:        ${relativeTime(r.lastLightAt)}`);
+    console.log(`  Last rapid:        ${relativeTime(r.lastRapidAt)}`);
+    console.log(`  Last restorative:  ${relativeTime(r.lastRestorativeAt)}`);
+    const nightly = r.nightlyEnabled === true ? "enabled" : r.nightlyEnabled === false ? "disabled" : "unknown";
+    console.log(`  Nightly:           ${nightly}`);
+    if (r.lastNightlyAt)
+        console.log(`  Last nightly:      ${relativeTime(r.lastNightlyAt)} (${r.lastNightlyAt})`);
+    if (typeof r.pendingCandidates === "number")
+        console.log(`  Pending candidates: ${r.pendingCandidates}`);
+    else
+        console.log(`  Pending candidates: — (schema not available)`);
+});
+statusCmd
+    .command("federation")
+    .description("Show federation subsystem status")
+    .action(async function () {
+    const opts = this.optsWithGlobals();
+    const { healthy, healthData } = await fetchHealthDetail(opts);
+    if (opts.json) {
+        console.log(JSON.stringify({ healthy, federation: healthData?.federation ?? null }, null, 2));
+        if (!healthy)
+            process.exit(1);
+        return;
+    }
+    if (!healthy) {
+        console.log("🔴 unreachable");
+        process.exit(1);
+    }
+    const f = healthData?.federation;
+    if (!f) {
+        console.log("Federation: not configured");
+        return;
+    }
+    console.log("Federation:");
+    if (f.instance)
+        console.log(`  Instance:    ${f.instance.id} (${f.instance.role ?? "—"}, ${f.instance.status ?? "—"})`);
+    else
+        console.log("  Instance:    —");
+    if (f.peers)
+        console.log(`  Peers:       ${f.peers.total} (${f.peers.connected} connected / ${f.peers.disconnected} down / ${f.peers.revoked} revoked)`);
+    if (typeof f.pendingTokens === "number" && f.pendingTokens > 0)
+        console.log(`  Pairing:     ${f.pendingTokens} unconsumed token(s)`);
+    if (Array.isArray(f.peerList) && f.peerList.length > 0) {
+        const idW = Math.max(4, ...f.peerList.map((p) => (p.id ?? "").length));
+        console.log(`\n  ${"peer".padEnd(idW)}  ${"role".padEnd(5)}  ${"status".padEnd(13)}  last_sync`);
+        for (const p of f.peerList) {
+            console.log(`  ${(p.id ?? "").padEnd(idW)}  ${(p.role ?? "—").padEnd(5)}  ${(p.status ?? "—").padEnd(13)}  ${p.lastSyncAt ? `${relativeTime(p.lastSyncAt)} (${p.lastSyncAt})` : "never"}`);
+        }
     }
-    console.log(`  Health:     ✅ all checks passing`);
+});
+statusCmd
+    .command("auth")
+    .description("Show OAuth / IdP subsystem status")
+    .action(async function () {
+    const opts = this.optsWithGlobals();
+    const { healthy, healthData } = await fetchHealthDetail(opts);
+    if (opts.json) {
+        console.log(JSON.stringify({ healthy, oauth: healthData?.oauth ?? null }, null, 2));
+        if (!healthy)
+            process.exit(1);
+        return;
+    }
+    if (!healthy) {
+        console.log("🔴 unreachable");
+        process.exit(1);
+    }
+    const o = healthData?.oauth;
+    if (!o) {
+        console.log("OAuth: not configured");
+        return;
+    }
+    const lines = oauthDetailLines(o);
+    for (const line of lines)
+        console.log(line);
+});
+statusCmd
+    .command("bridges")
+    .description("Show memory bridges subsystem status")
+    .action(async function () {
+    const opts = this.optsWithGlobals();
+    const { healthy, healthData } = await fetchHealthDetail(opts);
+    if (opts.json) {
+        console.log(JSON.stringify({ healthy, bridges: healthData?.bridges ?? null }, null, 2));
+        if (!healthy)
+            process.exit(1);
+        return;
+    }
+    if (!healthy) {
+        console.log("🔴 unreachable");
+        process.exit(1);
+    }
+    const b = healthData?.bridges;
+    if (!b) {
+        console.log("Bridges: none installed (no flair-bridge-* packages found)");
+        return;
+    }
+    console.log("Bridges:");
+    if (Array.isArray(b.installed) && b.installed.length > 0)
+        console.log(`  Installed:   ${b.installed.join(", ")}`);
+    if (b.lastImport)
+        console.log(`  Last import: ${relativeTime(b.lastImport)}`);
+    if (b.lastExport)
+        console.log(`  Last export: ${relativeTime(b.lastExport)}`);
 });
 // ─── flair upgrade ────────────────────────────────────────────────────────────
 program
@@ -2139,11 +2580,16 @@ program
                     execSync(`launchctl load "${plistPath}"`, { stdio: "pipe" });
                 }
                 catch { }
-                // Stop the service — KeepAlive=true in the plist auto-restarts it
+                // Capture the current PID *before* stopping so we can verify exit. Without
+                // this, waitForHealth can race against the still-shutting-down old process
+                // and return success before KeepAlive brings the new one up.
+                const oldPid = readHarperPid(defaultDataDir());
                 try {
                     execSync(`launchctl stop ${label}`, { stdio: "pipe" });
                 }
                 catch { }
+                if (oldPid)
+                    await waitForProcessExit(oldPid, STARTUP_TIMEOUT_MS);
                 await waitForHealth(port, DEFAULT_ADMIN_USER, process.env.HDB_ADMIN_PASSWORD ?? "", STARTUP_TIMEOUT_MS);
                 console.log("✅ Flair restarted");
                 return;
@@ -2178,16 +2624,22 @@ program
             process.exit(1);
         }
         const dataDir = defaultDataDir();
-        const adminPass = process.env.HDB_ADMIN_PASSWORD ?? "";
+        // Match `flair start`: accept either HDB_ADMIN_PASSWORD or FLAIR_ADMIN_PASS.
+        // Without this, `flair init --admin-pass X` (which only exports HDB_*
+        // to the initial Harper spawn) followed by `flair restart` would silently
+        // drop admin credentials — any subsequent auth'd call returns 401.
+        const adminPass = process.env.HDB_ADMIN_PASSWORD || process.env.FLAIR_ADMIN_PASS || "";
         const env = {
             ...process.env,
             ROOTPATH: dataDir,
             DEFAULTS_MODE: "dev",
             HDB_ADMIN_USERNAME: DEFAULT_ADMIN_USER,
-            HDB_ADMIN_PASSWORD: adminPass,
             HTTP_PORT: String(port),
             LOCAL_STUDIO: "false",
         };
+        if (adminPass) {
+            env.HDB_ADMIN_PASSWORD = adminPass;
+        }
         const proc = spawn(process.execPath, [bin, "run", "."], {
             cwd: flairPackageDir(), env, detached: true, stdio: "ignore",
         });
@@ -2398,19 +2850,21 @@ program
             failed++;
         }
     };
-    // 1. Write a test memory via POST /Memory
-    await check("Write test memory (POST /Memory)", async () => {
+    // 1. Write a test memory via PUT /Memory/<id>.
+    // Schema only exposes PUT — POST returns 'Memory does not have a post method implemented'.
+    await check("Write test memory (PUT /Memory/<id>)", async () => {
+        const id = `flair-test-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
         const body = {
+            id,
             content: "flair test \u2014 this will be deleted",
             durability: "ephemeral",
             createdAt: new Date().toISOString(),
         };
         if (agentId)
             body.agentId = agentId;
-        const result = await api("POST", "/Memory", body);
-        // id may be returned directly or nested
-        memoryId = result?.id ?? result?.[0]?.id ?? null;
-        return !!memoryId || result?.ok === true;
+        await api("PUT", `/Memory/${id}`, body);
+        memoryId = id;
+        return true;
     });
     // 2. Search for the test memory via POST /SemanticSearch
     await check("Search for test memory (POST /SemanticSearch)", async () => {
@@ -2435,6 +2889,80 @@ program
     if (failed > 0)
         process.exit(1);
 });
+// ─── flair deploy ─────────────────────────────────────────────────────────────
+program
+    .command("deploy")
+    .description("Deploy Flair as a component to a remote Harper Fabric cluster")
+    .option("--fabric-org <org>", "Fabric org (env: FABRIC_ORG)")
+    .option("--fabric-cluster <cluster>", "Fabric cluster within the org (env: FABRIC_CLUSTER)")
+    .option("--fabric-user <user>", "Fabric admin username (env: FABRIC_USER)")
+    .option("--fabric-password <pass>", "Fabric admin password (env: FABRIC_PASSWORD)")
+    .option("--fabric-token <token>", "OAuth bearer token (env: FABRIC_TOKEN) — reserved for future Fabric bearer support")
+    .option("--target <url>", "Override the Fabric URL template (https://<cluster>.<org>.harperfabric.com)")
+    .option("--project <name>", "Component name in Fabric", "flair")
+    .option("--pkg-version <semver>", "Override version label (default: installed package version)")
+    .option("--no-replicated", "Disable cluster-wide replication (default: replicated=true)")
+    .option("--no-restart", "Do not restart the component after deploy (default: restart=true)")
+    .option("--dry-run", "Resolve package, validate args, skip the deploy call")
+    .option("--package-root <dir>", "Override package root (mainly for testing)")
+    .action(async (opts) => {
+    const green = (s) => `\x1b[32m${s}\x1b[0m`;
+    const red = (s) => `\x1b[31m${s}\x1b[0m`;
+    const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+    const deployOpts = {
+        fabricOrg: opts.fabricOrg ?? process.env.FABRIC_ORG,
+        fabricCluster: opts.fabricCluster ?? process.env.FABRIC_CLUSTER,
+        fabricUser: opts.fabricUser ?? process.env.FABRIC_USER,
+        fabricPassword: opts.fabricPassword ?? process.env.FABRIC_PASSWORD,
+        fabricToken: opts.fabricToken ?? process.env.FABRIC_TOKEN,
+        target: opts.target,
+        project: opts.project,
+        version: opts.pkgVersion,
+        replicated: opts.replicated !== false,
+        restart: opts.restart !== false,
+        dryRun: opts.dryRun ?? false,
+        packageRoot: opts.packageRoot,
+    };
+    const errors = validateDeployOptions(deployOpts);
+    if (errors.length) {
+        console.error(red("flair deploy: missing required options"));
+        for (const e of errors)
+            console.error(`  - ${e}`);
+        process.exit(1);
+    }
+    // Warn on password-via-flag (leaks to shell history). Env is preferred.
+    if (opts.fabricPassword && !process.env.FABRIC_PASSWORD) {
+        console.error(dim("warning: --fabric-password leaks to shell history. " +
+            "Prefer FABRIC_PASSWORD env."));
+    }
+    const url = buildDeployUrl(deployOpts);
+    console.log(`${green("→")} Deploying ${deployOpts.project} to ${url}`);
+    if (deployOpts.dryRun)
+        console.log(dim("  (dry-run: skipping API call)"));
+    try {
+        const result = await deployToFabric(deployOpts);
+        if (result.dryRun) {
+            console.log(`${green("✓")} dry-run OK: ${result.project} ${result.version} ready to deploy to ${result.url}`);
+            console.log(dim(`  package root: ${result.packageRoot}`));
+            return;
+        }
+        console.log(`\n${green("✓")} Flair ${result.version} deployed`);
+        console.log(`\n  URL:     ${result.url}`);
+        console.log(`  Project: ${result.project}`);
+        console.log(`\nNext steps:`);
+        console.log(dim(`  1. Set an admin password in Fabric Studio (Cluster Settings → Admin)`));
+        console.log(dim(`  2. Seed your first agent:`));
+        console.log(`     flair agent add --remote ${result.url} --name my-agent`);
+    }
+    catch (err) {
+        console.error(red(`\n✗ deploy failed: ${err.message}`));
+        const hint = err.message?.toLowerCase();
+        if (hint?.includes("401") || hint?.includes("unauthoriz")) {
+            console.error(dim("  hint: check Fabric Studio → Cluster Settings → Admin for the admin password"));
+        }
+        process.exit(1);
+    }
+});
 // ─── flair doctor ─────────────────────────────────────────────────────────────
 program
     .command("doctor")
@@ -2688,23 +3216,81 @@ program
 });
 // ─── Memory and Soul commands ────────────────────────────────────────────────
 const memory = program.command("memory").description("Manage agent memories");
-memory.command("add").requiredOption("--agent <id>").requiredOption("--content <text>")
+memory.command("add [content]").requiredOption("--agent <id>")
+    .option("--content <text>", "memory content (alias for positional arg)")
     .option("--durability <d>", "standard").option("--tags <csv>")
-    .action(async (opts) => {
+    .action(async (contentArg, opts) => {
+    const content = contentArg ?? opts.content;
+    if (!content) {
+        console.error("error: content required (positional arg or --content)");
+        process.exit(1);
+    }
     const memId = `${opts.agent}-${Date.now()}`;
     const out = await api("PUT", `/Memory/${memId}`, {
-        id: memId, agentId: opts.agent, content: opts.content, durability: opts.durability || "standard",
+        id: memId, agentId: opts.agent, content, durability: opts.durability || "standard",
         tags: opts.tags ? String(opts.tags).split(",").map((x) => x.trim()).filter(Boolean) : undefined,
         type: "memory", createdAt: new Date().toISOString(),
     });
     console.log(JSON.stringify(out, null, 2));
 });
-memory.command("search").requiredOption("--agent <id>").requiredOption("--q <query>").option("--tag <tag>")
-    .action(async (opts) => console.log(JSON.stringify(await api("POST", "/SemanticSearch", { agentId: opts.agent, q: opts.q, tag: opts.tag }), null, 2)));
-memory.command("list").requiredOption("--agent <id>").option("--tag <tag>")
+memory.command("search [query]").requiredOption("--agent <id>")
+    .option("--q <query>", "search query (alias for positional arg)")
+    .option("--limit <n>", "Max results", "5")
+    .option("--tag <tag>")
+    .action(async (queryArg, opts) => {
+    const q = queryArg ?? opts.q;
+    if (!q) {
+        console.error("error: query required (positional arg or --q)");
+        process.exit(1);
+    }
+    const body = { agentId: opts.agent, q, limit: parseInt(opts.limit, 10) || 5 };
+    if (opts.tag)
+        body.tag = opts.tag;
+    console.log(JSON.stringify(await api("POST", "/SemanticSearch", body), null, 2));
+});
+memory.command("list")
+    .requiredOption("--agent <id>")
+    .option("--tag <tag>")
+    .option("--hash-fallback", "Only memories with missing or hash-fallback embeddings (for backfill triage)")
+    .option("--limit <n>", "Max rows when using --hash-fallback", "50")
     .action(async (opts) => {
     const q = new URLSearchParams({ agentId: opts.agent, ...(opts.tag ? { tag: opts.tag } : {}) }).toString();
-    console.log(JSON.stringify(await api("GET", `/Memory?${q}`), null, 2));
+    const raw = await api("GET", `/Memory?${q}`);
+    if (!opts.hashFallback) {
+        console.log(JSON.stringify(raw, null, 2));
+        return;
+    }
+    // --hash-fallback: filter to entries without a real embedding and print as a table.
+    // Same predicate HealthDetail uses: missing model or the "hash-512d" marker.
+    const all = Array.isArray(raw) ? raw : (raw?.results ?? raw?.items ?? []);
+    const fallback = all.filter((m) => !m.embeddingModel || m.embeddingModel === "hash-512d");
+    if (fallback.length === 0) {
+        console.log(`No hash-fallback memories for agent ${opts.agent}. All embedded.`);
+        return;
+    }
+    const limit = Math.max(1, parseInt(opts.limit, 10) || 50);
+    const rows = fallback
+        .slice()
+        .sort((a, b) => {
+        const ta = a.createdAt ? new Date(a.createdAt).getTime() : 0;
+        const tb = b.createdAt ? new Date(b.createdAt).getTime() : 0;
+        return tb - ta;
+    })
+        .slice(0, limit);
+    const idW = Math.max(2, ...rows.map((r) => String(r.id ?? "").length));
+    console.log(`${fallback.length} hash-fallback memories for agent ${opts.agent} (showing ${rows.length}):\n`);
+    console.log(`  ${"id".padEnd(idW)}  created_at            preview`);
+    for (const r of rows) {
+        const created = r.createdAt ? String(r.createdAt).slice(0, 19).replace("T", " ") : "—".padEnd(19);
+        const preview = String(r.content ?? "").replace(/\s+/g, " ").slice(0, 80);
+        console.log(`  ${String(r.id ?? "").padEnd(idW)}  ${created}  ${preview}`);
+    }
+    if (fallback.length > rows.length) {
+        console.log(`\n... ${fallback.length - rows.length} more (raise with --limit). To backfill: flair reembed --agent ${opts.agent} --stale-only`);
+    }
+    else {
+        console.log(`\nTo backfill: flair reembed --agent ${opts.agent} --stale-only`);
+    }
 });
 // ─── flair search (top-level shortcut) ───────────────────────────────────────
 program
@@ -2801,6 +3387,320 @@ soul.command("set").requiredOption("--agent <id>").requiredOption("--key <key>")
 soul.command("get").argument("<id>").action(async (id) => console.log(JSON.stringify(await api("GET", `/Soul/${id}`), null, 2)));
 soul.command("list").requiredOption("--agent <id>")
     .action(async (opts) => console.log(JSON.stringify(await api("GET", `/Soul?agentId=${encodeURIComponent(opts.agent)}`), null, 2)));
+// ─── flair bridge ────────────────────────────────────────────────────────────
+// Slice 1: discovery + scaffold. Slice 2: YAML runtime + `import` for Shape A
+// + agentic-stack reference adapter as a built-in.
+// `test` and `export` are still stubbed; Shape B (npm code plugins) too.
+// See specs/FLAIR-BRIDGES.md.
+const bridge = program.command("bridge").description("Manage memory bridges (import/export between Flair and foreign systems)");
+bridge
+    .command("list")
+    .description("List installed bridges across project YAML, user YAML, npm packages, and built-ins")
+    .option("--json", "Output as JSON")
+    .action(async (opts) => {
+    const { discover } = await import("./bridges/discover.js");
+    const { builtinDiscoveryRecords } = await import("./bridges/builtins/index.js");
+    const found = await discover({ builtins: builtinDiscoveryRecords() });
+    if (opts.json) {
+        console.log(JSON.stringify(found, null, 2));
+        return;
+    }
+    if (found.length === 0) {
+        console.log("No bridges installed.");
+        console.log("Add one with:  flair bridge scaffold <name> --file");
+        console.log("Or install from npm:  npm install flair-bridge-<name>");
+        return;
+    }
+    const nameW = Math.max(4, ...found.map((b) => b.name.length));
+    const kindW = Math.max(4, ...found.map((b) => b.kind.length));
+    const srcW = Math.max(6, ...found.map((b) => b.source.length));
+    console.log(`  ${"name".padEnd(nameW)}  ${"kind".padEnd(kindW)}  ${"source".padEnd(srcW)}  description`);
+    for (const b of found) {
+        const desc = b.description ?? "";
+        console.log(`  ${b.name.padEnd(nameW)}  ${b.kind.padEnd(kindW)}  ${b.source.padEnd(srcW)}  ${desc}`);
+    }
+});
+bridge
+    .command("scaffold <name>")
+    .description("Emit starter files for a new bridge. Choose --file (YAML, declarative) or --api (TS code plugin)")
+    .option("--file", "YAML file-format bridge (shape A)")
+    .option("--api", "TypeScript API bridge (shape B)")
+    .option("--force", "Overwrite existing files")
+    .action(async (name, opts) => {
+    if (opts.file && opts.api) {
+        console.error("Pick one: --file or --api.");
+        process.exit(1);
+    }
+    const { BUILTIN_BY_NAME } = await import("./bridges/builtins/index.js");
+    if (BUILTIN_BY_NAME.has(name)) {
+        console.error(`"${name}" is a built-in bridge name and can't be scaffolded — pick a different name.`);
+        process.exit(1);
+    }
+    const kind = opts.api ? "api" : "file"; // --file is default
+    const { scaffold } = await import("./bridges/scaffold.js");
+    try {
+        const result = await scaffold({ name, kind, force: !!opts.force });
+        if (result.createdFiles.length > 0) {
+            console.log(`Created ${result.createdFiles.length} file(s):`);
+            for (const p of result.createdFiles)
+                console.log(`  + ${p}`);
+        }
+        if (result.skippedFiles.length > 0) {
+            console.log(`Skipped ${result.skippedFiles.length} existing file(s) (pass --force to overwrite):`);
+            for (const p of result.skippedFiles)
+                console.log(`  · ${p}`);
+        }
+        console.log(`\n${result.summary}`);
+    }
+    catch (err) {
+        console.error(`Scaffold failed: ${err.message}`);
+        process.exit(1);
+    }
+});
+bridge
+    .command("import <name> [src]")
+    .description("Import memories from a foreign system into Flair via a bridge (Shape A YAML / built-in)")
+    .option("--agent <id>", "Default agent ID for memories that don't carry one (or set FLAIR_AGENT_ID)")
+    .option("--cwd <dir>", "Filesystem root the descriptor's relative paths resolve against (default: cwd)")
+    .option("--dry-run", "Validate + count, don't write to Flair")
+    .option("--port <port>", "Harper HTTP port")
+    .option("--url <url>", "Flair base URL (overrides --port)")
+    .option("--key <path>", "Ed25519 private key path (default: resolved from agent)")
+    .action(async (name, srcArg, opts) => {
+    const agentId = opts.agent ?? process.env.FLAIR_AGENT_ID;
+    const cwd = opts.cwd ?? srcArg ?? process.cwd();
+    const { discover } = await import("./bridges/discover.js");
+    const { builtinDiscoveryRecords } = await import("./bridges/builtins/index.js");
+    const { loadDescriptor } = await import("./bridges/runtime/load-descriptor.js");
+    const { runImport } = await import("./bridges/runtime/import-runner.js");
+    const { makeContext } = await import("./bridges/runtime/context.js");
+    const { BridgeRuntimeError } = await import("./bridges/types.js");
+    const found = await discover({ builtins: builtinDiscoveryRecords() });
+    const target = found.find((b) => b.name === name);
+    if (!target) {
+        console.error(`No bridge named "${name}" — run \`flair bridge list\` to see installed bridges.`);
+        process.exit(1);
+    }
+    let descriptor;
+    try {
+        descriptor = await loadDescriptor(target);
+    }
+    catch (err) {
+        printBridgeError(err);
+        process.exit(1);
+    }
+    const baseUrl = opts.url ?? `http://127.0.0.1:${resolveHttpPort(opts)}`;
+    const ctx = makeContext({ bridge: name });
+    // Memory POST: Ed25519-signed when an agent key is available, fall back
+    // to the shared `api()` helper otherwise. Mirrors how `flair memory add`
+    // works (see the `memory.command("add")` handler above).
+    const putMemory = async (body) => {
+        const headers = { "content-type": "application/json" };
+        const keyPath = opts.key ?? resolveKeyPath(body.agentId);
+        if (keyPath) {
+            headers["authorization"] = buildEd25519Auth(body.agentId, "PUT", `/Memory/${body.id}`, keyPath);
+        }
+        const res = await fetch(`${baseUrl}/Memory/${encodeURIComponent(body.id)}`, {
+            method: "PUT",
+            headers,
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`PUT /Memory/${body.id} → ${res.status}: ${text || res.statusText}`);
+        }
+    };
+    let lastReportedAt = Date.now();
+    let lastReportedOrdinal = 0;
+    const onProgress = (ev) => {
+        // Throttle in-progress chatter to at most one line every 2s + the
+        // final summary. Avoids flooding stdout for big imports.
+        if (ev.type === "done") {
+            const noun = (n) => `${n} ${n === 1 ? "memory" : "memories"}`;
+            if (opts.dryRun) {
+                console.log(`\n${descriptor.name}: would import ${noun(ev.total)}. Re-run without --dry-run to write to Flair.`);
+            }
+            else {
+                console.log(`\n${descriptor.name}: imported ${ev.imported}/${ev.total} memories${ev.skipped > 0 ? ` (${ev.skipped} skipped)` : ""}.`);
+            }
+            return;
+        }
+        const now = Date.now();
+        if (now - lastReportedAt < 2000 && ev.ordinal - lastReportedOrdinal < 25)
+            return;
+        lastReportedAt = now;
+        lastReportedOrdinal = ev.ordinal;
+        if (ev.type === "memory-imported") {
+            process.stdout.write(`\r  ${ev.ordinal} imported (${ev.foreignId ?? ev.flairId})`.padEnd(80));
+        }
+        else if (ev.type === "memory-skipped") {
+            process.stdout.write(`\r  ${ev.ordinal} skipped (${ev.reason})`.padEnd(80));
+        }
+    };
+    try {
+        await runImport({
+            descriptor,
+            cwd,
+            agentId,
+            dryRun: !!opts.dryRun,
+            putMemory,
+            onProgress,
+            ctx,
+        });
+    }
+    catch (err) {
+        if (err instanceof BridgeRuntimeError) {
+            printBridgeError(err);
+            process.exit(1);
+        }
+        console.error(`Bridge import failed: ${err?.message ?? err}`);
+        process.exit(1);
+    }
+});
+bridge
+    .command("export <name> <dst>")
+    .description("Export memories from Flair to a foreign system via a bridge (Shape A YAML / built-in)")
+    .requiredOption("--agent <id>", "Agent ID to export memories for (or set FLAIR_AGENT_ID)")
+    .option("--source <tag>", "Filter to memories with a matching `source:` tag (typical for round-tripping a single bridge's data)")
+    .option("--subject <subj>", "Filter to memories with a matching `subject:` tag")
+    .option("--since <iso>", "Only memories with createdAt >= this ISO-8601 timestamp")
+    .option("--cwd <dir>", "Filesystem root the descriptor's relative target paths resolve against (default: cwd)")
+    .option("--dry-run", "Validate + count + apply maps, don't write to the target")
+    .option("--port <port>", "Harper HTTP port")
+    .option("--url <url>", "Flair base URL (overrides --port)")
+    .option("--key <path>", "Ed25519 private key path (default: resolved from agent)")
+    .action(async (name, dst, opts) => {
+    const agentId = opts.agent ?? process.env.FLAIR_AGENT_ID;
+    if (!agentId) {
+        console.error("error: --agent <id> required (or set FLAIR_AGENT_ID)");
+        process.exit(1);
+    }
+    const cwd = opts.cwd ?? dst;
+    const { discover } = await import("./bridges/discover.js");
+    const { builtinDiscoveryRecords } = await import("./bridges/builtins/index.js");
+    const { loadDescriptor } = await import("./bridges/runtime/load-descriptor.js");
+    const { runExport } = await import("./bridges/runtime/export-runner.js");
+    const { makeContext } = await import("./bridges/runtime/context.js");
+    const { BridgeRuntimeError } = await import("./bridges/types.js");
+    const found = await discover({ builtins: builtinDiscoveryRecords() });
+    const target = found.find((b) => b.name === name);
+    if (!target) {
+        console.error(`No bridge named "${name}" — run \`flair bridge list\` to see installed bridges.`);
+        process.exit(1);
+    }
+    let descriptor;
+    try {
+        descriptor = await loadDescriptor(target);
+    }
+    catch (err) {
+        printBridgeError(err);
+        process.exit(1);
+    }
+    if (!descriptor.export) {
+        console.error(`Bridge "${name}" has no export block — cannot export through it.`);
+        process.exit(1);
+    }
+    const baseUrl = opts.url ?? `http://127.0.0.1:${resolveHttpPort(opts)}`;
+    const ctx = makeContext({ bridge: name });
+    // Memory fetcher — paginates GET /Memory?agentId=... applying any
+    // descriptor + caller-side filters in memory. Slice 3a does the
+    // simplest thing: one round trip, no streaming. Slice 3b can move
+    // to cursor-paginated streaming if real corpora warrant it.
+    const fetchMemories = async function* (filters) {
+        const params = new URLSearchParams({ agentId });
+        if (opts.subject)
+            params.set("subject", opts.subject);
+        const headers = { "content-type": "application/json" };
+        const keyPath = opts.key ?? resolveKeyPath(agentId);
+        const path = `/Memory?${params.toString()}`;
+        if (keyPath)
+            headers["authorization"] = buildEd25519Auth(agentId, "GET", path, keyPath);
+        const res = await fetch(`${baseUrl}${path}`, { headers });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`GET /Memory → ${res.status}: ${text || res.statusText}`);
+        }
+        const raw = await res.json();
+        const all = Array.isArray(raw) ? raw : (raw?.results ?? raw?.items ?? []);
+        const sourceFilter = opts.source;
+        const sinceMs = opts.since ? new Date(opts.since).getTime() : null;
+        for (const m of all) {
+            if (sourceFilter && m.source !== sourceFilter)
+                continue;
+            if (sinceMs !== null && m.createdAt && new Date(m.createdAt).getTime() < sinceMs)
+                continue;
+            yield m;
+        }
+        void filters;
+    };
+    let lastReportedAt = Date.now();
+    const onProgress = (ev) => {
+        if (ev.type === "done") {
+            if (opts.dryRun) {
+                console.log(`\n${descriptor.name}: would export ${ev.exported} memor${ev.exported === 1 ? "y" : "ies"} from ${ev.total} total. Re-run without --dry-run to write.`);
+            }
+            else {
+                console.log(`\n${descriptor.name}: exported ${ev.exported} memor${ev.exported === 1 ? "y" : "ies"} from ${ev.total} total.`);
+            }
+            return;
+        }
+        if (ev.type === "target-write") {
+            console.log(`  ✓ ${ev.path} (${ev.written} record${ev.written === 1 ? "" : "s"})`);
+            return;
+        }
+        if (ev.type === "target-skipped") {
+            console.log(`  · ${ev.path} skipped (${ev.reason})`);
+            return;
+        }
+        // memory-skipped events throttled to one line every 2s
+        const now = Date.now();
+        if (now - lastReportedAt < 2000)
+            return;
+        lastReportedAt = now;
+        process.stdout.write(`\r  filtering memory ${ev.ordinal}...`.padEnd(60));
+    };
+    try {
+        await runExport({
+            descriptor,
+            cwd,
+            fetchMemories,
+            filters: { agentId, subject: opts.subject, source: opts.source, since: opts.since },
+            dryRun: !!opts.dryRun,
+            ctx,
+            onProgress,
+        });
+    }
+    catch (err) {
+        if (err instanceof BridgeRuntimeError) {
+            printBridgeError(err);
+            process.exit(1);
+        }
+        console.error(`Bridge export failed: ${err?.message ?? err}`);
+        process.exit(1);
+    }
+});
+// `test` still stubbed — round-trip harness lands in slice 3b.
+bridge
+    .command("test <name> [args...]")
+    .description("test a bridge — not yet implemented (slice 3b of FLAIR-BRIDGES)")
+    .allowUnknownOption()
+    .action(() => {
+    console.error(`\`flair bridge test\` is not yet implemented — landing in slice 3b of FLAIR-BRIDGES.`);
+    console.error(`Slice 3a ships export (Shape A YAML); the round-trip test harness pairs with it.`);
+    process.exit(2);
+});
+function printBridgeError(err) {
+    // Pretty-print BridgeRuntimeError as the structured shape from §10 of the
+    // spec, plus a one-line human summary so the operator gets both.
+    const detail = err?.detail;
+    if (detail && typeof detail === "object") {
+        console.error(`Bridge error: ${detail.hint ?? err.message}`);
+        console.error(JSON.stringify(detail, null, 2));
+    }
+    else {
+        console.error(`Bridge error: ${err.message ?? String(err)}`);
+    }
+}
 // ─── flair backup ────────────────────────────────────────────────────────────
 program
     .command("backup")
@@ -3210,110 +4110,6 @@ program
         console.log(`Souls: ${(data.souls ?? []).length}`);
     }
 });
-// ─── flair migrate-keys ───────────────────────────────────────────────────────
-program
-    .command("migrate-keys")
-    .description("Migrate agent keys from old path (~/.tps/secrets/flair/) to ~/.flair/keys/")
-    .option("--from <dir>", "Old keys directory", join(homedir(), ".tps", "secrets", "flair"))
-    .option("--to <dir>", "New keys directory", defaultKeysDir())
-    .option("--dry-run", "Show what would be migrated without copying")
-    .option("--port <port>", "Harper HTTP port")
-    .option("--ops-port <port>", "Harper operations API port")
-    .option("--admin-pass <pass>", "Admin password (or set FLAIR_ADMIN_PASS env)")
-    .action(async (opts) => {
-    const fromDir = opts.from;
-    const toDir = opts.to;
-    const dryRun = opts.dryRun ?? false;
-    const opsPort = resolveOpsPort(opts);
-    const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
-    if (!existsSync(fromDir)) {
-        console.log(`Old keys directory not found: ${fromDir}`);
-        console.log("Nothing to migrate.");
-        process.exit(0);
-    }
-    // Discover legacy keys: <id>-priv.key pattern
-    const { readdirSync, unlinkSync } = await import("node:fs");
-    const files = readdirSync(fromDir);
-    const keyFiles = files.filter((f) => f.endsWith("-priv.key"));
-    if (keyFiles.length === 0) {
-        console.log(`No legacy key files found in ${fromDir}`);
-        process.exit(0);
-    }
-    console.log(`Found ${keyFiles.length} legacy key file(s) in ${fromDir}:`);
-    let migrated = 0;
-    let skipped = 0;
-    for (const file of keyFiles) {
-        const agentId = file.replace("-priv.key", "");
-        const srcPath = join(fromDir, file);
-        const destPath = join(toDir, `${agentId}.key`);
-        if (existsSync(destPath)) {
-            console.log(`  skip: ${agentId} — already exists at ${destPath}`);
-            skipped++;
-            continue;
-        }
-        if (dryRun) {
-            console.log(`  would migrate: ${srcPath} → ${destPath}`);
-            migrated++;
-            continue;
-        }
-        mkdirSync(toDir, { recursive: true });
-        const keyData = readFileSync(srcPath);
-        writeFileSync(destPath, keyData);
-        chmodSync(destPath, 0o600);
-        console.log(`  migrated: ${agentId} → ${destPath}`);
-        migrated++;
-    }
-    if (dryRun) {
-        console.log(`\n🔍 Dry run: ${migrated} key(s) would be migrated, ${skipped} skipped`);
-    }
-    else {
-        console.log(`\n✅ Migration complete: ${migrated} migrated, ${skipped} skipped`);
-        if (migrated > 0) {
-            console.log(`\nOld keys preserved at ${fromDir} (delete manually when confirmed working).`);
-            // Optionally verify keys match Flair records
-            if (adminPass) {
-                console.log("\nVerifying migrated keys against Flair...");
-                const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
-                for (const file of keyFiles) {
-                    const agentId = file.replace("-priv.key", "");
-                    const destPath = join(toDir, `${agentId}.key`);
-                    if (!existsSync(destPath))
-                        continue;
-                    try {
-                        const keyB64 = readFileSync(destPath, "utf-8").trim();
-                        const seed = Buffer.from(keyB64, "base64");
-                        const kp = nacl.sign.keyPair.fromSeed(new Uint8Array(seed));
-                        const localPub = b64url(kp.publicKey);
-                        const res = await fetch(`http://127.0.0.1:${opsPort}/`, {
-                            method: "POST",
-                            headers: { "Content-Type": "application/json", Authorization: auth },
-                            body: JSON.stringify({ operation: "search_by_value", database: "flair", table: "Agent", search_attribute: "id", search_value: agentId, get_attributes: ["id", "publicKey"] }),
-                            signal: AbortSignal.timeout(10_000),
-                        });
-                        if (res.ok) {
-                            const agents = await res.json();
-                            if (Array.isArray(agents) && agents.length > 0) {
-                                const remotePub = agents[0].publicKey;
-                                if (remotePub === localPub) {
-                                    console.log(`  ✅ ${agentId}: key matches Flair`);
-                                }
-                                else {
-                                    console.log(`  ⚠️  ${agentId}: key MISMATCH — local key doesn't match Flair record`);
-                                }
-                            }
-                            else {
-                                console.log(`  ⚠️  ${agentId}: not found in Flair`);
-                            }
-                        }
-                    }
-                    catch (err) {
-                        console.log(`  ⚠️  ${agentId}: verification failed — ${err.message}`);
-                    }
-                }
-            }
-        }
-    }
-});
 // Run CLI only when this is the entry point (not when imported for testing)
 if (import.meta.main) {
     await program.parseAsync();