@tpsdev-ai/flair 0.3.19 → 0.4.1

package/dist/cli.js

@@ -7,8 +7,8 @@ import { join, resolve as resolvePath } from "node:path";
 import { spawn } from "node:child_process";
 import { createPrivateKey, sign as nodeCryptoSign, randomUUID } from "node:crypto";
 // ─── Defaults ────────────────────────────────────────────────────────────────
-const DEFAULT_PORT = 9926;
-const DEFAULT_OPS_PORT = 9925;
+const DEFAULT_PORT = 19926;
+const DEFAULT_OPS_PORT = 19925;
 const DEFAULT_ADMIN_USER = "admin";
 const STARTUP_TIMEOUT_MS = 60_000;
 const HEALTH_POLL_INTERVAL_MS = 500;
@@ -18,6 +18,27 @@ function defaultKeysDir() {
 function defaultDataDir() {
     return join(homedir(), ".flair", "data");
 }
+function configPath() {
+    return join(homedir(), ".flair", "config.yaml");
+}
+function readPortFromConfig() {
+    try {
+        const p = configPath();
+        if (existsSync(p)) {
+            const yaml = readFileSync(p, "utf-8");
+            const m = yaml.match(/port:\s*(\d+)/);
+            if (m)
+                return Number(m[1]);
+        }
+    }
+    catch { /* ignore */ }
+    return null;
+}
+function writeConfig(port) {
+    const p = configPath();
+    mkdirSync(join(homedir(), ".flair"), { recursive: true });
+    writeFileSync(p, `# Flair configuration\nport: ${port}\n`);
+}
 function privKeyPath(agentId, keysDir) {
     return join(keysDir, `${agentId}.key`);
 }
@@ -48,17 +69,8 @@ function b64url(bytes) {
 }
 async function api(method, path, body) {
     // Resolve port: FLAIR_URL env > ~/.flair/config.yaml > default 9926
-    let defaultUrl = "http://127.0.0.1:9926";
-    try {
-        const configPath = join(homedir(), ".flair", "config.yaml");
-        if (existsSync(configPath)) {
-            const yaml = readFileSync(configPath, "utf-8");
-            const portMatch = yaml.match(/port:\s*(\d+)/);
-            if (portMatch)
-                defaultUrl = `http://127.0.0.1:${portMatch[1]}`;
-        }
-    }
-    catch { /* ignore config read errors */ }
+    const savedPort = readPortFromConfig();
+    const defaultUrl = savedPort ? `http://127.0.0.1:${savedPort}` : `http://127.0.0.1:${DEFAULT_PORT}`;
     const base = process.env.FLAIR_URL || defaultUrl;
     // Auth resolution order:
     // 1. FLAIR_TOKEN env → Bearer token (backward compat)
@@ -261,9 +273,19 @@ program
             if (!bin)
                 throw new Error("@harperfast/harper not found in node_modules.\nRun: npm install @harperfast/harper");
             mkdirSync(dataDir, { recursive: true });
+            const opsSocket = join(dataDir, "operations-server");
+            const harperSetConfig = JSON.stringify({
+                rootPath: dataDir,
+                http: { port: httpPort, cors: true, corsAccessList: [`http://127.0.0.1:${httpPort}`, `http://localhost:${httpPort}`] },
+                operationsApi: { network: { port: opsPort, cors: true }, domainSocket: opsSocket },
+                mqtt: { network: { port: null }, webSocket: false },
+                localStudio: { enabled: false },
+                authentication: { authorizeLocal: true, enableSessions: true },
+            });
             const env = {
                 ...process.env,
                 ROOTPATH: dataDir,
+                HARPER_SET_CONFIG: harperSetConfig,
                 DEFAULTS_MODE: "dev",
                 HDB_ADMIN_USERNAME: adminUser,
                 HDB_ADMIN_PASSWORD: adminPass,
@@ -273,7 +295,10 @@ program
                 OPERATIONSAPI_NETWORK_PORT: String(opsPort),
                 LOCAL_STUDIO: "false",
             };
-            // Install
+            // Install Harper (creates system database, admin user, config file).
+            // IMPORTANT: Do NOT pre-create harper-config.yaml — Harper's install checks
+            // for its existence to detect existing installations. If found, it skips
+            // install and tries to read the (empty) database, causing a crash.
             console.log("Installing Harper...");
             await new Promise((resolve, reject) => {
                 let output = "";
@@ -282,17 +307,21 @@ program
                 install.stderr?.on("data", (d) => { output += d.toString(); });
                 install.on("exit", (code) => code === 0 ? resolve() : reject(new Error(`Harper install failed (${code}): ${output}`)));
                 install.on("error", reject);
-                setTimeout(() => { install.kill(); reject(new Error(`Harper install timed out: ${output}`)); }, 20_000);
+                setTimeout(() => { install.kill(); reject(new Error(`Harper install timed out: ${output}`)); }, 60_000);
             });
-            // Start (detached)
+            // Start Harper in dev mode (detached). Dev mode sets authorizeLocal=true
+            // which allows our Ed25519 middleware to handle auth while internal
+            // cross-resource calls (e.g. SemanticSearch → Memory) pass through.
             console.log(`Starting Harper on port ${httpPort}...`);
-            const proc = spawn(process.execPath, [bin, "run", "."], { cwd: flairPackageDir(), env, detached: true, stdio: "ignore" });
+            const proc = spawn(process.execPath, [bin, "dev", "."], { cwd: flairPackageDir(), env, detached: true, stdio: "ignore" });
             proc.unref();
         }
         console.log("Waiting for Harper health check...");
         await waitForHealth(httpPort, adminUser, adminPass, STARTUP_TIMEOUT_MS);
         console.log("Harper is healthy ✓");
     }
+    // Persist port to config so other commands can find this instance
+    writeConfig(httpPort);
     // Generate or reuse keypair
     mkdirSync(keysDir, { recursive: true });
     const privPath = privKeyPath(agentId, keysDir);
@@ -375,8 +404,10 @@ program
     }
     console.log(`\n   Claude Code: Add to your CLAUDE.md:`);
     console.log(`     At the start of every session, run mcp__flair__bootstrap before responding.`);
+    const mcpEnv = { FLAIR_AGENT_ID: agentId };
+    mcpEnv.FLAIR_URL = httpUrl;
     console.log(`\n   MCP config (.mcp.json):`);
-    console.log(`     { "mcpServers": { "flair": { "command": "npx", "args": ["@tpsdev-ai/flair-mcp"], "env": { "FLAIR_AGENT_ID": "${agentId}" } } } }`);
+    console.log(`     { "mcpServers": { "flair": { "command": "npx", "args": ["@tpsdev-ai/flair-mcp"], "env": ${JSON.stringify(mcpEnv)} } } }`);
 });
 // ─── flair agent ─────────────────────────────────────────────────────────────
 const agent = program.command("agent").description("Manage Flair agents");
@@ -384,7 +415,7 @@ agent
     .command("add <id>")
     .description("Register a new agent in a running Flair instance")
     .option("--name <name>", "Display name (defaults to id)")
-    .option("--port <port>", "Harper HTTP port", String(DEFAULT_PORT))
+    .option("--port <port>", "Harper HTTP port")
     .option("--admin-pass <pass>", "Admin password for registration")
     .option("--keys-dir <dir>", "Directory for Ed25519 keys")
     .option("--ops-port <port>", "Harper operations API port")
@@ -434,7 +465,7 @@ agent
 agent
     .command("rotate-key <id>")
     .description("Rotate an agent's Ed25519 keypair")
-    .option("--port <port>", "Harper HTTP port", String(DEFAULT_PORT))
+    .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)")
     .option("--keys-dir <dir>", "Directory for Ed25519 keys")
@@ -512,7 +543,7 @@ agent
     .command("remove <id>")
     .description("Remove an agent and all its data from Flair")
     .option("--keep-keys", "Do not delete key files from disk")
-    .option("--port <port>", "Harper HTTP port", String(DEFAULT_PORT))
+    .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)")
     .option("--keys-dir <dir>", "Directory for Ed25519 keys")
@@ -624,7 +655,7 @@ program
     .command("grant <from-agent> <to-agent>")
     .description("Grant an agent read access to another agent's memories")
     .option("--scope <scope>", "Grant scope: read or search", "read")
-    .option("--port <port>", "Harper HTTP port", String(DEFAULT_PORT))
+    .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)")
     .option("--keys-dir <dir>", "Directory for Ed25519 keys (for from-agent Ed25519 auth)")
@@ -673,7 +704,7 @@ program
 program
     .command("revoke <from-agent> <to-agent>")
     .description("Revoke a memory grant between two agents")
-    .option("--port <port>", "Harper HTTP port", String(DEFAULT_PORT))
+    .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 (fromAgent, toAgent, opts) => {
@@ -714,10 +745,11 @@ program
 program
     .command("status")
     .description("Check Flair (Harper) instance health and agent count")
-    .option("--port <port>", "Harper HTTP port", String(DEFAULT_PORT))
+    .option("--port <port>", "Harper HTTP port")
     .option("--url <url>", "Flair base URL (overrides --port)")
     .action(async (opts) => {
-    const baseUrl = opts.url ?? `http://127.0.0.1:${opts.port}`;
+    const port = opts.port ? Number(opts.port) : (readPortFromConfig() ?? DEFAULT_PORT);
+    const baseUrl = opts.url ?? `http://127.0.0.1:${port}`;
     let healthy = false;
     let agentCount = null;
     let version = null;
@@ -788,36 +820,511 @@ program
     }
     console.log("\nTo upgrade: npm install -g @tpsdev-ai/flair@latest");
 });
-// ─── Legacy identity/memory/soul commands (preserved) ────────────────────────
-const identity = program.command("identity").description("Legacy identity commands");
-identity.command("register")
-    .requiredOption("--id <id>")
-    .requiredOption("--name <name>")
-    .option("--role <role>")
+// ─── flair stop ───────────────────────────────────────────────────────────────
+program
+    .command("stop")
+    .description("Stop the running Flair (Harper) instance")
+    .option("--port <port>", "Harper HTTP port")
     .action(async (opts) => {
-    const kp = nacl.sign.keyPair();
-    const now = new Date().toISOString();
-    const agentRecord = await api("POST", "/Agent", {
-        id: opts.id, name: opts.name, role: opts.role,
-        publicKey: b64(kp.publicKey), createdAt: now, updatedAt: now,
+    const port = opts.port ? Number(opts.port) : (readPortFromConfig() ?? DEFAULT_PORT);
+    const platform = process.platform;
+    if (platform === "darwin") {
+        // macOS: try launchd first
+        const label = "ai.tpsdev.flair";
+        const plistPath = join(homedir(), "Library", "LaunchAgents", `${label}.plist`);
+        if (existsSync(plistPath)) {
+            try {
+                const { execSync } = await import("node:child_process");
+                execSync(`launchctl unload "${plistPath}"`, { stdio: "pipe" });
+                console.log("✅ Flair stopped (launchd service unloaded)");
+                return;
+            }
+            catch {
+                // launchd unload failed, try PID fallback
+            }
+        }
+    }
+    // Fallback: find process by port
+    try {
+        const { execSync } = await import("node:child_process");
+        const lsof = execSync(`lsof -ti :${port}`, { encoding: "utf-8" }).trim();
+        if (lsof) {
+            const pids = lsof.split("\n").map(p => p.trim()).filter(Boolean);
+            for (const pid of pids) {
+                process.kill(Number(pid), "SIGTERM");
+            }
+            console.log(`✅ Flair stopped (killed PID${pids.length > 1 ? "s" : ""}: ${pids.join(", ")})`);
+        }
+        else {
+            console.log("Flair is not running.");
+        }
+    }
+    catch {
+        console.log("Flair is not running (nothing found on port " + port + ").");
+    }
+});
+// ─── flair restart ────────────────────────────────────────────────────────────
+program
+    .command("restart")
+    .description("Restart the Flair (Harper) instance")
+    .option("--port <port>", "Harper HTTP port")
+    .action(async (opts) => {
+    const port = opts.port ? Number(opts.port) : (readPortFromConfig() ?? DEFAULT_PORT);
+    const platform = process.platform;
+    if (platform === "darwin") {
+        const label = "ai.tpsdev.flair";
+        const plistPath = join(homedir(), "Library", "LaunchAgents", `${label}.plist`);
+        if (existsSync(plistPath)) {
+            try {
+                const { execSync } = await import("node:child_process");
+                const uid = process.getuid?.() ?? 501;
+                execSync(`launchctl kickstart -k user/${uid}/${label}`, { stdio: "pipe" });
+                console.log("✅ Flair restarted (launchd kickstart)");
+                return;
+            }
+            catch (err) {
+                console.error(`launchd restart failed: ${err.message}`);
+            }
+        }
+        else {
+            console.error("❌ No launchd service found. Run 'flair init' first.");
+            process.exit(1);
+        }
+    }
+    else {
+        // Linux: stop + start via init
+        console.log("Stopping...");
+        try {
+            const { execSync } = await import("node:child_process");
+            const lsof = execSync(`lsof -ti :${port}`, { encoding: "utf-8" }).trim();
+            if (lsof) {
+                for (const pid of lsof.split("\n")) {
+                    try {
+                        process.kill(Number(pid.trim()), "SIGTERM");
+                    }
+                    catch { }
+                }
+                // Wait briefly for shutdown
+                await new Promise(r => setTimeout(r, 2000));
+            }
+        }
+        catch { /* not running */ }
+        console.log("Starting...");
+        const bin = harperBin();
+        if (!bin) {
+            console.error("❌ Harper binary not found. Run 'flair init' first.");
+            process.exit(1);
+        }
+        const dataDir = defaultDataDir();
+        const adminPass = process.env.HDB_ADMIN_PASSWORD ?? "";
+        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",
+        };
+        const proc = spawn(process.execPath, [bin, "run", "."], {
+            cwd: flairPackageDir(), env, detached: true, stdio: "ignore",
+        });
+        proc.unref();
+        try {
+            await waitForHealth(port, DEFAULT_ADMIN_USER, adminPass, STARTUP_TIMEOUT_MS);
+            console.log("✅ Flair restarted");
+        }
+        catch {
+            console.error("❌ Flair failed to restart within timeout");
+            process.exit(1);
+        }
+    }
+});
+// ─── flair uninstall ──────────────────────────────────────────────────────────
+program
+    .command("uninstall")
+    .description("Stop Flair and remove the launchd/systemd service")
+    .option("--purge", "Also remove data and keys (destructive)")
+    .action(async (opts) => {
+    const platform = process.platform;
+    const port = readPortFromConfig() ?? DEFAULT_PORT;
+    // Stop first
+    if (platform === "darwin") {
+        const label = "ai.tpsdev.flair";
+        const plistPath = join(homedir(), "Library", "LaunchAgents", `${label}.plist`);
+        if (existsSync(plistPath)) {
+            try {
+                const { execSync } = await import("node:child_process");
+                execSync(`launchctl unload "${plistPath}"`, { stdio: "pipe" });
+            }
+            catch { /* best effort */ }
+            const { unlinkSync } = await import("node:fs");
+            unlinkSync(plistPath);
+            console.log("✅ Launchd service removed");
+        }
+        else {
+            console.log("No launchd service found — skipping");
+        }
+    }
+    else {
+        // Linux: kill by port
+        try {
+            const { execSync } = await import("node:child_process");
+            const lsof = execSync(`lsof -ti :${port}`, { encoding: "utf-8" }).trim();
+            if (lsof) {
+                for (const pid of lsof.split("\n")) {
+                    try {
+                        process.kill(Number(pid.trim()), "SIGTERM");
+                    }
+                    catch { }
+                }
+            }
+        }
+        catch { /* not running */ }
+        console.log("✅ Flair process stopped");
+    }
+    // Remove config
+    const cfgPath = configPath();
+    if (existsSync(cfgPath)) {
+        const { unlinkSync } = await import("node:fs");
+        unlinkSync(cfgPath);
+        console.log("✅ Config removed");
+    }
+    if (opts.purge) {
+        const { rmSync } = await import("node:fs");
+        const dataDir = defaultDataDir();
+        const keysDir = defaultKeysDir();
+        const flairDir = join(homedir(), ".flair");
+        if (existsSync(dataDir)) {
+            rmSync(dataDir, { recursive: true, force: true });
+            console.log("✅ Data removed: " + dataDir);
+        }
+        if (existsSync(keysDir)) {
+            rmSync(keysDir, { recursive: true, force: true });
+            console.log("✅ Keys removed: " + keysDir);
+        }
+        // Remove .flair dir if empty
+        try {
+            const { readdirSync, rmdirSync } = await import("node:fs");
+            if (existsSync(flairDir) && readdirSync(flairDir).length === 0) {
+                rmdirSync(flairDir);
+            }
+        }
+        catch { /* non-empty, that's fine */ }
+        console.log("\n🗑️  Flair fully purged");
+    }
+    else {
+        console.log("\nData and keys preserved at ~/.flair/");
+        console.log("To remove everything: flair uninstall --purge");
+    }
+});
+// ─── flair reembed ────────────────────────────────────────────────────────────
+program
+    .command("reembed")
+    .description("Re-generate embeddings for memories with stale or missing model tags")
+    .requiredOption("--agent <id>", "Agent ID to re-embed memories for")
+    .option("--stale-only", "Only re-embed memories with mismatched model tag")
+    .option("--dry-run", "Show count without modifying")
+    .option("--port <port>", "Harper HTTP port")
+    .option("--batch-size <n>", "Records per batch", "50")
+    .option("--delay-ms <ms>", "Delay between batches (ms)", "100")
+    .action(async (opts) => {
+    const port = opts.port ? Number(opts.port) : (readPortFromConfig() ?? DEFAULT_PORT);
+    const baseUrl = `http://127.0.0.1:${port}`;
+    const agentId = opts.agent;
+    const staleOnly = opts.staleOnly ?? false;
+    const dryRun = opts.dryRun ?? false;
+    const batchSize = Number(opts.batchSize);
+    const delayMs = Number(opts.delayMs);
+    const currentModel = process.env.FLAIR_EMBEDDING_MODEL ?? "nomic-embed-text-v1.5-Q4_K_M";
+    console.log(`Re-embedding memories for agent: ${agentId}`);
+    console.log(`Current model: ${currentModel}`);
+    if (staleOnly)
+        console.log("Mode: stale-only (skipping up-to-date memories)");
+    if (dryRun)
+        console.log("Mode: dry-run (no modifications)");
+    console.log("");
+    const keysDir = defaultKeysDir();
+    const privPath = privKeyPath(agentId, keysDir);
+    if (!existsSync(privPath)) {
+        console.error(`❌ Key not found: ${privPath}`);
+        process.exit(1);
+    }
+    const searchRes = await authFetch(baseUrl, agentId, privPath, "POST", "/SemanticSearch", {
+        agentId, limit: 10000,
+    });
+    if (!searchRes.ok) {
+        console.error(`❌ Failed to fetch memories: ${searchRes.status}`);
+        process.exit(1);
+    }
+    const data = await searchRes.json();
+    const allMemories = data.results ?? [];
+    const candidates = allMemories.filter((m) => {
+        if (!m.content)
+            return false;
+        if (staleOnly)
+            return !m.embeddingModel || m.embeddingModel !== currentModel;
+        return true;
     });
-    console.log(JSON.stringify({ agent: agentRecord, privateKey: b64(kp.secretKey) }, null, 2));
+    const total = candidates.length;
+    const skipped = allMemories.length - total;
+    console.log(`Total memories: ${allMemories.length}`);
+    console.log(`Candidates for re-embedding: ${total}`);
+    if (skipped > 0)
+        console.log(`Skipped (up-to-date): ${skipped}`);
+    if (dryRun || total === 0) {
+        if (total === 0)
+            console.log("\n✅ All memories are up-to-date!");
+        return;
+    }
+    console.log("");
+    let processed = 0;
+    let errors = 0;
+    for (let i = 0; i < candidates.length; i += batchSize) {
+        const batch = candidates.slice(i, i + batchSize);
+        for (const memory of batch) {
+            try {
+                const updateRes = await authFetch(baseUrl, agentId, privPath, "PUT", `/Memory/${memory.id}`, {
+                    id: memory.id, content: memory.content, embedding: undefined, embeddingModel: undefined,
+                });
+                if (updateRes.ok)
+                    processed++;
+                else
+                    errors++;
+            }
+            catch {
+                errors++;
+            }
+        }
+        const pct = Math.round(((i + batch.length) / total) * 100);
+        process.stdout.write(`\rRe-embedded ${processed}/${total} (${pct}%)${errors > 0 ? ` [${errors} errors]` : ""}`);
+        if (i + batchSize < candidates.length)
+            await new Promise(r => setTimeout(r, delayMs));
+    }
+    console.log(`\n\n✅ Re-embedding complete: ${processed} updated, ${errors} errors`);
 });
-identity.command("show").argument("<id>").action(async (id) => console.log(JSON.stringify(await api("GET", `/Agent/${id}`), null, 2)));
-identity.command("list").action(async () => console.log(JSON.stringify(await api("GET", "/Agent"), null, 2)));
-identity.command("add-integration")
-    .requiredOption("--agent <agentId>")
-    .requiredOption("--platform <platform>")
-    .requiredOption("--encrypted-credential <ciphertext>")
+// ─── flair test ───────────────────────────────────────────────────────────────
+program
+    .command("test")
+    .description("Verify Flair is working: store, search, bootstrap, cleanup")
+    .requiredOption("--agent <id>", "Agent ID to test with")
+    .option("--port <port>", "Harper HTTP port")
     .action(async (opts) => {
-    const now = new Date().toISOString();
-    const out = await api("POST", "/Integration", {
-        id: `${opts.agent}:${opts.platform}`, agentId: opts.agent,
-        platform: opts.platform, encryptedCredential: opts.encryptedCredential,
-        createdAt: now, updatedAt: now,
+    const port = opts.port ? Number(opts.port) : (readPortFromConfig() ?? DEFAULT_PORT);
+    const baseUrl = `http://127.0.0.1:${port}`;
+    const agentId = opts.agent;
+    const keysDir = defaultKeysDir();
+    const privPath = privKeyPath(agentId, keysDir);
+    if (!existsSync(privPath)) {
+        console.error(`❌ Key not found: ${privPath}`);
+        console.error(`   Run: flair init --agent-id ${agentId}`);
+        process.exit(1);
+    }
+    const testId = `test-${agentId}-${Date.now()}`;
+    const testContent = `Flair test memory (${new Date().toISOString()})`;
+    let passed = 0;
+    let failed = 0;
+    const check = async (name, fn) => {
+        try {
+            const ok = await fn();
+            if (ok) {
+                console.log(`  ✅ ${name}`);
+                passed++;
+            }
+            else {
+                console.log(`  ❌ ${name}`);
+                failed++;
+            }
+        }
+        catch (e) {
+            console.log(`  ❌ ${name}: ${e.message?.slice(0, 100)}`);
+            failed++;
+        }
+    };
+    console.log(`\nFlair test (agent: ${agentId}, url: ${baseUrl})\n`);
+    // 1. Health
+    await check("Health check", async () => {
+        const res = await fetch(`${baseUrl}/Health`, { signal: AbortSignal.timeout(5000) });
+        return res.status > 0;
     });
-    console.log(JSON.stringify(out, null, 2));
+    // 2. Store
+    await check("Memory store", async () => {
+        const res = await authFetch(baseUrl, agentId, privPath, "PUT", `/Memory/${testId}`, {
+            id: testId, agentId, content: testContent, durability: "ephemeral",
+            createdAt: new Date().toISOString(), archived: false,
+        });
+        return res.ok;
+    });
+    // 3. Search
+    await check("Semantic search", async () => {
+        await new Promise(r => setTimeout(r, 2000)); // wait for indexing
+        const res = await authFetch(baseUrl, agentId, privPath, "POST", "/SemanticSearch", {
+            agentId, q: "flair test memory", limit: 5,
+        });
+        if (!res.ok)
+            return false;
+        const data = await res.json();
+        return (data.results?.length ?? 0) > 0;
+    });
+    // 4. Bootstrap
+    await check("Bootstrap context", async () => {
+        const res = await authFetch(baseUrl, agentId, privPath, "POST", "/BootstrapMemories", {
+            agentId, maxTokens: 1000,
+        });
+        if (!res.ok)
+            return false;
+        const data = await res.json();
+        return (data.context?.length ?? 0) > 0;
+    });
+    // 5. Cleanup
+    await check("Memory delete", async () => {
+        const res = await authFetch(baseUrl, agentId, privPath, "DELETE", `/Memory/${testId}`);
+        return res.ok || res.status === 204;
+    });
+    console.log(`\n${passed} passed, ${failed} failed`);
+    if (failed > 0)
+        process.exit(1);
+});
+// ─── flair doctor ─────────────────────────────────────────────────────────────
+program
+    .command("doctor")
+    .description("Diagnose common Flair problems and suggest fixes")
+    .option("--port <port>", "Harper HTTP port")
+    .action(async (opts) => {
+    const port = opts.port ? Number(opts.port) : (readPortFromConfig() ?? DEFAULT_PORT);
+    const baseUrl = `http://127.0.0.1:${port}`;
+    let issues = 0;
+    console.log("\n🩺 Flair Doctor\n");
+    // 1. Port check — is something listening?
+    try {
+        const res = await fetch(`${baseUrl}/Health`, { signal: AbortSignal.timeout(3000) });
+        if (res.status > 0) {
+            console.log(`  ✅ Harper responding on port ${port}`);
+        }
+    }
+    catch {
+        console.log(`  ❌ Nothing responding on port ${port}`);
+        // Check if port is in use by something else
+        try {
+            const { execSync } = await import("node:child_process");
+            const lsof = execSync(`lsof -ti :${port}`, { encoding: "utf-8" }).trim();
+            if (lsof) {
+                console.log(`     Port ${port} is in use by PID ${lsof} — might be a stale process`);
+                console.log(`     Fix: kill ${lsof} && flair restart`);
+            }
+            else {
+                console.log(`     Harper is not running`);
+                console.log(`     Fix: flair init --agent-id <your-agent>`);
+            }
+        }
+        catch {
+            console.log(`     Harper is not running`);
+            console.log(`     Fix: flair init --agent-id <your-agent>`);
+        }
+        issues++;
+    }
+    // 2. Keys directory
+    const keysDir = defaultKeysDir();
+    if (existsSync(keysDir)) {
+        const keyFiles = (await import("node:fs")).readdirSync(keysDir).filter((f) => f.endsWith(".key"));
+        if (keyFiles.length > 0) {
+            console.log(`  ✅ Keys found: ${keyFiles.length} agent(s) in ${keysDir}`);
+        }
+        else {
+            console.log(`  ❌ Keys directory exists but no .key files found`);
+            console.log(`     Fix: flair init --agent-id <your-agent>`);
+            issues++;
+        }
+    }
+    else {
+        console.log(`  ❌ Keys directory missing: ${keysDir}`);
+        console.log(`     Fix: flair init --agent-id <your-agent>`);
+        issues++;
+    }
+    // 3. Config file
+    const cfgPath = join(homedir(), ".flair", "config.yaml");
+    if (existsSync(cfgPath)) {
+        const savedPort = readPortFromConfig();
+        console.log(`  ✅ Config: ${cfgPath} (port: ${savedPort ?? "default"})`);
+    }
+    else {
+        console.log(`  ⚠️  No config file at ${cfgPath} — using defaults`);
+    }
+    // 4. Embeddings check (only if Harper is running)
+    try {
+        const res = await fetch(`${baseUrl}/Health`, { signal: AbortSignal.timeout(3000) });
+        if (res.status > 0) {
+            // Try a test embedding via SemanticSearch with a dummy query
+            // If embedding mode is "none", search will include _warning
+            const testRes = await fetch(`${baseUrl}/SemanticSearch`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ q: "test", limit: 1 }),
+                signal: AbortSignal.timeout(10000),
+            });
+            if (testRes.ok) {
+                const data = await testRes.json();
+                if (data._warning) {
+                    console.log(`  ⚠️  Embeddings: keyword-only (${data._warning})`);
+                    console.log(`     Semantic search quality is degraded`);
+                    console.log(`     Check: ls ~/.npm-global/lib/node_modules/@tpsdev-ai/flair/models/`);
+                    issues++;
+                }
+                else {
+                    console.log(`  ✅ Embeddings: semantic search operational`);
+                }
+            }
+            else if (testRes.status === 401) {
+                // Auth required — can't test embeddings without an agent key
+                console.log(`  ⚠️  Embeddings: cannot verify (auth required for SemanticSearch)`);
+            }
+        }
+    }
+    catch { /* Harper not running, already flagged above */ }
+    // 5. Stale PID file
+    const dataDir = defaultDataDir();
+    const pidFile = join(dataDir, "hdb.pid");
+    if (existsSync(pidFile)) {
+        const pidContent = (await import("node:fs")).readFileSync(pidFile, "utf-8").trim();
+        try {
+            process.kill(Number(pidContent), 0); // check if process exists
+            console.log(`  ✅ PID file: ${pidFile} (process ${pidContent} is alive)`);
+        }
+        catch {
+            console.log(`  ❌ Stale PID file: ${pidFile} (process ${pidContent} is dead)`);
+            console.log(`     Fix: rm ${pidFile} && flair restart`);
+            issues++;
+        }
+    }
+    // 6. Data directory
+    if (existsSync(dataDir)) {
+        console.log(`  ✅ Data directory: ${dataDir}`);
+    }
+    else {
+        // Check ~/harper/ (common alternative)
+        const altDir = join(homedir(), "harper");
+        if (existsSync(altDir)) {
+            console.log(`  ⚠️  Data at ~/harper/ (not ~/.flair/data) — old install location`);
+        }
+        else {
+            console.log(`  ❌ No data directory found`);
+            console.log(`     Fix: flair init --agent-id <your-agent>`);
+            issues++;
+        }
+    }
+    // Summary
+    console.log("");
+    if (issues === 0) {
+        console.log("  🟢 No issues found");
+    }
+    else {
+        console.log(`  🔴 ${issues} issue${issues > 1 ? "s" : ""} found — see fixes above`);
+    }
+    console.log("");
+    if (issues > 0)
+        process.exit(1);
 });
+// ─── Memory and Soul commands ────────────────────────────────────────────────
 const memory = program.command("memory").description("Manage agent memories");
 memory.command("add").requiredOption("--agent <id>").requiredOption("--content <text>")
     .option("--durability <d>", "standard").option("--tags <csv>")
@@ -843,7 +1350,7 @@ program
     .description("Search memories by meaning (shortcut for memory search)")
     .requiredOption("--agent <id>", "Agent ID")
     .option("--limit <n>", "Max results", "5")
-    .option("--port <port>", "Harper HTTP port", String(DEFAULT_PORT))
+    .option("--port <port>", "Harper HTTP port")
     .option("--url <url>", "Flair base URL (overrides --port)")
     .option("--key <path>", "Ed25519 private key path")
     .action(async (query, opts) => {
@@ -888,7 +1395,7 @@ program
     .description("Cold-start context: get soul + recent memories as formatted text")
     .requiredOption("--agent <id>", "Agent ID")
     .option("--max-tokens <n>", "Maximum tokens in output", "4000")
-    .option("--port <port>", "Harper HTTP port", String(DEFAULT_PORT))
+    .option("--port <port>", "Harper HTTP port")
     .option("--url <url>", "Flair base URL (overrides --port)")
     .option("--key <path>", "Ed25519 private key path")
     .action(async (opts) => {
@@ -938,7 +1445,7 @@ program
     .description("Export agents, memories, and souls to a JSON archive")
     .option("--output <path>", "Output file path (default: ~/.flair/backups/flair-backup-<timestamp>.json)")
     .option("--agents <ids>", "Comma-separated agent IDs to include (default: all)")
-    .option("--port <port>", "Harper HTTP port", String(DEFAULT_PORT))
+    .option("--port <port>", "Harper HTTP port")
     .option("--url <url>", "Flair base URL (overrides --port)")
     .option("--admin-pass <pass>", "Admin password (or set FLAIR_ADMIN_PASS env)")
     .action(async (opts) => {
@@ -1017,7 +1524,7 @@ program
     .description("Import a Flair backup archive")
     .option("--merge", "Add/update records without deleting existing (default)")
     .option("--replace", "Delete all existing data for backed-up agents first, then import")
-    .option("--port <port>", "Harper HTTP port", String(DEFAULT_PORT))
+    .option("--port <port>", "Harper HTTP port")
     .option("--url <url>", "Flair base URL (overrides --port)")
     .option("--admin-pass <pass>", "Admin password (or set FLAIR_ADMIN_PASS env)")
     .option("--dry-run", "Show what would be imported without making changes")
@@ -1134,7 +1641,7 @@ program
     .description("Export a single agent's identity (soul + memories) to a portable file")
     .option("--output <path>", "Output file path")
     .option("--include-key", "Include private key in export (UNENCRYPTED — keep the output file secure)")
-    .option("--port <port>", "Harper HTTP port", String(DEFAULT_PORT))
+    .option("--port <port>", "Harper HTTP port")
     .option("--url <url>", "Flair base URL (overrides --port)")
     .option("--admin-pass <pass>", "Admin password (or set FLAIR_ADMIN_PASS env)")
     .option("--keys-dir <dir>", "Keys directory", defaultKeysDir())
@@ -1220,7 +1727,7 @@ program
 program
     .command("import <path>")
     .description("Import an agent from an export file into this Flair instance")
-    .option("--port <port>", "Harper HTTP port", String(DEFAULT_PORT))
+    .option("--port <port>", "Harper HTTP port")
     .option("--ops-port <port>", "Harper operations API port")
     .option("--url <url>", "Flair base URL (overrides --port)")
     .option("--admin-pass <pass>", "Admin password (or set FLAIR_ADMIN_PASS env)")
@@ -1344,11 +1851,11 @@ program
 // ─── flair migrate-keys ───────────────────────────────────────────────────────
 program
     .command("migrate-keys")
-    .description("Migrate agent keys from legacy path (~/.tps/secrets/flair/) to ~/.flair/keys/")
-    .option("--from <dir>", "Legacy keys directory", join(homedir(), ".tps", "secrets", "flair"))
+    .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 (for agent list)", String(DEFAULT_PORT))
+    .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) => {
@@ -1358,7 +1865,7 @@ program
     const opsPort = opts.opsPort ? Number(opts.opsPort) : Number(opts.port) + 1;
     const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
     if (!existsSync(fromDir)) {
-        console.log(`Legacy keys directory not found: ${fromDir}`);
+        console.log(`Old keys directory not found: ${fromDir}`);
         console.log("Nothing to migrate.");
         process.exit(0);
     }
@@ -1400,7 +1907,7 @@ program
     else {
         console.log(`\n✅ Migration complete: ${migrated} migrated, ${skipped} skipped`);
         if (migrated > 0) {
-            console.log(`\nLegacy keys preserved at ${fromDir} (delete manually when confirmed working).`);
+            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...");