@tpsdev-ai/flair 0.14.0 → 0.16.0

package/dist/cli.js

@@ -4,14 +4,15 @@ import nacl from "tweetnacl";
 import { load as parseYaml } from "js-yaml";
 import * as render from "./render.js";
 import { existsSync, mkdirSync, writeFileSync, readFileSync, chmodSync, renameSync, cpSync, rmSync, mkdtempSync, readdirSync, statSync, } from "node:fs";
-import { homedir, hostname, tmpdir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { join, resolve, sep, dirname } from "node:path";
 import { spawn } from "node:child_process";
 import { createPrivateKey, sign as nodeCryptoSign, randomUUID, randomBytes } from "node:crypto";
 import { create as tarCreate, extract as tarExtract, list as tarList } from "tar";
 import { keystore } from "./keystore.js";
 import { deploy as deployToFabric, validateOptions as validateDeployOptions, buildTargetUrl as buildDeployUrl } from "./deploy.js";
-import { detectClients, wireClaudeCode, wireCodex, wireGemini, wireCursor } from "./install/clients.js";
+import { fabricUpgrade } from "./fabric-upgrade.js";
+import { detectClients, wireCodex, wireGemini, wireCursor } from "./install/clients.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).
@@ -446,6 +447,117 @@ async function waitForHealth(httpPort, adminUser, adminPass, timeoutMs) {
     }
     throw new Error(`Harper at port ${httpPort} did not respond within ${timeoutMs}ms (${attempt} attempts)`);
 }
+/**
+ * Verify that semantic search ACTUALLY works by storing a memory with a
+ * distinctive phrase and searching for a PARAPHRASE (different words, same
+ * meaning). If embeddings are loaded, the paraphrase recovers the memory by
+ * meaning with a genuine semantic score. If embeddings are NOT loaded,
+ * SemanticSearch falls back to keyword-only scan: the paraphrase shares no
+ * keywords with the stored content, so the memory is NOT recovered (or only via
+ * the `_warning` keyword-fallback marker) → "degraded".
+ *
+ * The probe is authenticated as a real agent (Ed25519) because SemanticSearch
+ * rejects anonymous callers (401) and per-agent scoping requires it. We pick the
+ * given agentId, else FLAIR_AGENT_ID, else the first `.key` in keysDir.
+ *
+ * Exported so the init smoke test and unit tests can reuse the exact same gate.
+ */
+export async function verifySemanticSearch(baseUrl, agentIdOpt, keysDir) {
+    // Resolve an agent + key to sign with.
+    let agentId = agentIdOpt || process.env.FLAIR_AGENT_ID || undefined;
+    if (!agentId) {
+        try {
+            const keyFiles = readdirSync(keysDir).filter((f) => f.endsWith(".key"));
+            if (keyFiles.length > 0)
+                agentId = keyFiles[0].replace(/\.key$/, "");
+        }
+        catch { /* keysDir missing */ }
+    }
+    if (!agentId) {
+        return { state: "skipped", detail: "no agent id or key found" };
+    }
+    // Find the signing key. Prefer the standard locations (resolveKeyPath), but
+    // fall back to the keysDir we were handed — `flair init` keys live there and
+    // it may not be a standard location (e.g. --keys-dir, tests).
+    let keyPath = resolveKeyPath(agentId);
+    if (!keyPath) {
+        const candidate = join(keysDir, `${agentId}.key`);
+        if (existsSync(candidate))
+            keyPath = candidate;
+    }
+    if (!keyPath) {
+        return { state: "skipped", detail: `no private key for agent '${agentId}'` };
+    }
+    // Distinctive content vs. a PARAPHRASE query with deliberately ZERO shared
+    // content words. If the search recovers the memory it can ONLY be by meaning.
+    //   content: "The feline predator silently stalked its unsuspecting rodent quarry at dusk."
+    //   query:   "a cat hunting a mouse in the evening"
+    // No word in the query appears in the content (cat≠feline, mouse≠rodent,
+    // hunting≠stalked, evening≠dusk), so a keyword scan returns nothing.
+    const marker = `flair-doctor-embed-check-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const id = marker;
+    const content = `The feline predator silently stalked its unsuspecting rodent quarry at dusk. [${marker}]`;
+    const paraphrase = "a cat hunting a mouse in the evening";
+    let stored = false;
+    try {
+        // Write the test memory (ephemeral so it's never durable). PUT /Memory/<id>.
+        const writeRes = await authFetch(baseUrl, agentId, keyPath, "PUT", `/Memory/${id}`, {
+            id, agentId, content, durability: "ephemeral", createdAt: new Date().toISOString(),
+        });
+        if (!writeRes.ok && writeRes.status !== 204) {
+            const text = await writeRes.text().catch(() => "");
+            return { state: "skipped", detail: `could not write probe memory: HTTP ${writeRes.status} ${text.slice(0, 80)}` };
+        }
+        stored = true;
+        // Allow the HNSW index to catch up before searching.
+        await new Promise((r) => setTimeout(r, 1500));
+        // Search by PARAPHRASE. scoring: "raw" so we read the unweighted semantic
+        // similarity (_rawScore) directly, without recency/durability composites
+        // muddying the keyword-vs-semantic distinction.
+        const searchRes = await authFetch(baseUrl, agentId, keyPath, "POST", "/SemanticSearch", {
+            agentId, q: paraphrase, limit: 10, scoring: "raw",
+        });
+        if (!searchRes.ok) {
+            const text = await searchRes.text().catch(() => "");
+            return { state: "skipped", detail: `SemanticSearch failed: HTTP ${searchRes.status} ${text.slice(0, 80)}` };
+        }
+        const data = await searchRes.json();
+        // The server sets _warning ONLY when getMode() === "none" — i.e. the
+        // embedding engine failed to init and the search ran keyword-only. That is
+        // the unambiguous "embeddings not loaded" signal.
+        if (data._warning) {
+            return { state: "degraded", detail: data._warning };
+        }
+        const results = data.results ?? [];
+        const hit = results.find((r) => r.id === id);
+        if (!hit) {
+            // The paraphrase shares no keywords with the content, so a keyword-only
+            // fallback can't find it. Missing the memory == recall-by-meaning is dead.
+            return { state: "degraded", detail: "paraphrase did not recall the probe memory (keyword-only fallback active)" };
+        }
+        // A genuine semantic hit has a positive similarity score. The keyword bonus
+        // is +0.05; since there is no keyword overlap here, any score above that
+        // floor can only come from vector similarity. Require a real semantic score.
+        const score = typeof hit._rawScore === "number" ? hit._rawScore : (hit._score ?? 0);
+        if (score <= 0.05) {
+            return { state: "degraded", detail: `probe recalled with non-semantic score ${score} (keyword/zero)` };
+        }
+        return { state: "ok", score };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { state: "skipped", detail: `probe error: ${message.slice(0, 100)}` };
+    }
+    finally {
+        // Best-effort cleanup of the ephemeral probe memory.
+        if (stored) {
+            try {
+                await authFetch(baseUrl, agentId, keyPath, "DELETE", `/Memory/${id}`);
+            }
+            catch { /* leave the ephemeral row; it'll age out */ }
+        }
+    }
+}
 // 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
@@ -491,11 +603,29 @@ export async function seedAgentViaOpsApi(opsPortOrUrl, agentId, pubKeyB64url, ad
     // Send Basic auth whenever the caller passed an adminPass. The caller decides
     // when to omit it (e.g., local target with authorizeLocal=true).
     const auth = adminPass !== undefined ? Buffer.from(`${adminUser}:${adminPass}`).toString("base64") : undefined;
+    // The ops-API insert bypasses the Agent resource layer, so Agent.post()'s
+    // 1.0 Principal defaults (kind/status/displayName/admin/defaultTrustTier/type)
+    // never run. Without them a remote-seeded agent lands kind=null, status=null
+    // and is invisible to roster/presence/Office-Space queries that filter on
+    // status='active' or kind='agent' (#521). Mirror Agent.post() exactly here.
+    const now = new Date().toISOString();
     const body = {
         operation: "insert",
         database: "flair",
         table: "Agent",
-        records: [{ id: agentId, name: agentId, publicKey: pubKeyB64url, createdAt: new Date().toISOString() }],
+        records: [{
+                id: agentId,
+                name: agentId,
+                type: "agent",
+                kind: "agent",
+                status: "active",
+                displayName: agentId,
+                admin: false,
+                defaultTrustTier: "unverified",
+                publicKey: pubKeyB64url,
+                createdAt: now,
+                updatedAt: now,
+            }],
     };
     const res = await fetch(url, {
         method: "POST",
@@ -1212,8 +1342,9 @@ program.name("flair").version(__pkgVersion, "-v, --version");
 // ─── flair init ──────────────────────────────────────────────────────────────
 program
     .command("init")
-    .description("Bootstrap a Flair (Harper) instance for an agent")
+    .description("One-command Flair setup — bootstrap the instance, register an agent, and wire MCP clients")
     .option("--agent-id <id>", "Agent ID to register (omit to bootstrap instance without agent)")
+    .option("--agent <id>", "Alias for --agent-id")
     .option("--port <port>", "Harper HTTP port", String(DEFAULT_PORT))
     .option("--ops-port <port>", "Harper operations API port")
     .option("--admin-pass <pass>", "Admin password (generated if omitted)")
@@ -1222,6 +1353,9 @@ program
     .option("--data-dir <dir>", "Harper data directory")
     .option("--skip-start", "Skip Harper startup (assume already running)")
     .option("--skip-soul", "Skip interactive personality setup")
+    .option("--client <client>", "MCP client(s) to wire: claude-code, codex, gemini, cursor, all, or none")
+    .option("--no-mcp", "Skip MCP client wiring (instance + agent only)")
+    .option("--skip-smoke", "Skip the MCP smoke test")
     .option("--target <url>", "Remote Flair URL (env: FLAIR_TARGET)")
     .option("--remote", "When used with --target, init as hub for remote federation")
     .option("--ops-target <url>", "Explicit ops API URL (env: FLAIR_OPS_TARGET; bypasses port derivation)")
@@ -1230,7 +1364,7 @@ program
     .option("--cluster-admin-pass <pass>", "Harper cluster admin password (env: FLAIR_CLUSTER_ADMIN_PASS)")
     .option("--flair-admin-pass <pass>", "Password for Flair's admin user (env: FLAIR_ADMIN_PASS; generated if omitted)")
     .action(async (opts) => {
-    const agentId = opts.agentId;
+    const agentId = opts.agentId ?? opts.agent;
     const target = resolveTarget(opts);
     const opsTarget = resolveOpsTarget(opts);
     // ── Remote init: --target and/or --ops-target drive a remote Flair instance ──
@@ -1407,11 +1541,26 @@ program
         }
         return;
     }
-    // ── Local init (original behavior) ──
+    // ── Local init (full one-command setup) ──
     const httpPort = resolveHttpPort(opts);
     const opsPort = resolveOpsPort(opts);
     const keysDir = opts.keysDir ?? defaultKeysDir();
     const dataDir = opts.dataDir ?? defaultDataDir();
+    // Resolve MCP client selection (union of init's auto-wire + the multi-client
+    // detection/wiring that the front-door command provides). `--no-mcp` sets
+    // opts.mcp === false (commander negates the flag). Validate an explicit
+    // --client up front so a typo fails before Harper is touched.
+    const clientOpt = opts.client;
+    const noMcp = opts.mcp === false;
+    const selectedClients = [];
+    if (clientOpt && clientOpt !== "all" && clientOpt !== "none" && !noMcp) {
+        const valid = ["claude-code", "codex", "gemini", "cursor"];
+        if (!valid.includes(clientOpt)) {
+            console.error(`Unknown client: ${clientOpt}. Valid: claude-code, codex, gemini, cursor, all, none`);
+            process.exit(1);
+        }
+        selectedClients.push(clientOpt);
+    }
     // Admin password: determine from opts, env, or generate
     // Priority: 1) --admin-pass-file, 2) env vars, 3) generate new
     let adminPass;
@@ -1669,6 +1818,26 @@ program
         if (!verifyRes.ok)
             throw new Error(`Ed25519 auth verification failed: ${verifyRes.status}`);
         console.log("Ed25519 auth verified ✓");
+        // Verify semantic search ACTUALLY works (real embed→paraphrase-search
+        // round-trip). A clean-VM dogfood found semantic search dead out of the box
+        // (sudo/root-owned install can't write the embeddings models symlink →
+        // EACCES) while init reported success. Never report a clean init when
+        // recall-by-meaning is broken. Skipped paths (no key yet) are non-fatal.
+        console.log("Verifying semantic search...");
+        const embedCheck = await verifySemanticSearch(httpUrl, agentId, keysDir);
+        if (embedCheck.state === "ok") {
+            console.log(`Semantic search operational ✓ ${render.wrap(render.c.dim, `(paraphrase recall verified, score ${embedCheck.score.toFixed(2)})`)}`);
+        }
+        else if (embedCheck.state === "degraded") {
+            // LOUD — embeddings not loaded. Same message class as `flair doctor`.
+            console.log(`\n${render.icons.error} ${render.wrap(render.c.red, "Semantic search DEGRADED")} — embeddings not loaded; recall-by-meaning will NOT work.`);
+            console.log(`   ${render.wrap(render.c.dim, `(${embedCheck.detail})`)}`);
+            console.log(`   ${render.wrap(render.c.dim, "Common cause: the embeddings component lacks write access (sudo/root global installs).")}`);
+            console.log(`   ${render.wrap(render.c.dim, "Fix: install without sudo (see README Quick Start), then:")} flair restart && flair doctor`);
+        }
+        else {
+            console.log(`${render.icons.warn} Semantic search not verified ${render.wrap(render.c.dim, `(${embedCheck.detail})`)}`);
+        }
         // Output — admin password printed once, never written to disk
         console.log("\n✅ Flair initialized successfully");
         console.log(`   Agent ID:    ${agentId}`);
@@ -1728,38 +1897,164 @@ 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.`);
-        // Auto-wire MCP config into ~/.claude.json if Claude Code is installed
-        const claudeJsonPath = join(homedir(), ".claude.json");
+        // ── MCP client wiring ────────────────────────────────────────────────
+        // The full one-command front door: detect installed MCP clients and wire
+        // each to the zero-install `npx -y @tpsdev-ai/flair-mcp` server. Claude
+        // Code is auto-wired into ~/.claude.json (the only client the CLI can
+        // safely modify); other clients get copy-paste snippets. `--no-mcp`
+        // skips wiring entirely; `--client <name>` targets one client; the
+        // default (no flag) wires every detected client.
         const mcpEnv = { FLAIR_AGENT_ID: agentId, FLAIR_URL: httpUrl };
-        const flairMcpConfig = {
-            type: "stdio",
-            command: "flair-mcp",
-            args: [],
-            env: mcpEnv,
-        };
-        try {
-            if (existsSync(claudeJsonPath)) {
-                const claudeJson = JSON.parse(readFileSync(claudeJsonPath, "utf-8"));
-                const existing = claudeJson.mcpServers?.flair;
-                if (existing && existing.env?.FLAIR_URL === httpUrl && existing.env?.FLAIR_AGENT_ID === agentId) {
-                    console.log(`\n   MCP config already set in ~/.claude.json ✓`);
+        const wiringResults = [];
+        if (!noMcp && clientOpt !== "none") {
+            // Determine which clients to wire.
+            let clients = detectClients();
+            if (selectedClients.length > 0) {
+                clients = clients.filter(c => selectedClients.includes(c.id));
+            }
+            const detected = clients.filter(c => c.detected);
+            if (!clientOpt) {
+                if (detected.length === 0) {
+                    console.log("\n   No MCP clients detected. Run with --client <name> to wire a specific client.");
                 }
                 else {
-                    claudeJson.mcpServers = claudeJson.mcpServers || {};
-                    claudeJson.mcpServers.flair = flairMcpConfig;
-                    writeFileSync(claudeJsonPath, JSON.stringify(claudeJson, null, 2));
-                    console.log(`\n   MCP config written to ~/.claude.json ✓`);
-                    console.log(`   Restart Claude Code to pick up the new config.`);
+                    console.log(`\n   Detected MCP clients: ${detected.map(c => c.label).join(", ")}`);
                 }
             }
-            else {
-                console.log(`\n   MCP config (add to ~/.claude.json):`);
-                console.log(`     { "mcpServers": { "flair": ${JSON.stringify(flairMcpConfig)} } }`);
+            const toWire = clientOpt === "all"
+                ? clients.filter(c => c.detected).map(c => c.id)
+                : selectedClients.length > 0
+                    ? selectedClients
+                    : clients.filter(c => c.detected).map(c => c.id);
+            for (const clientId of toWire) {
+                if (clientId === "claude-code") {
+                    // Claude Code gets real auto-wiring into ~/.claude.json (zero-install
+                    // npx form; matches the snippets everywhere else). Other clients only
+                    // get printed instructions — the CLI can't safely edit their configs.
+                    const claudeJsonPath = join(homedir(), ".claude.json");
+                    const flairMcpConfig = {
+                        type: "stdio",
+                        command: "npx",
+                        args: ["-y", "@tpsdev-ai/flair-mcp"],
+                        env: mcpEnv,
+                    };
+                    try {
+                        if (existsSync(claudeJsonPath)) {
+                            const claudeJson = JSON.parse(readFileSync(claudeJsonPath, "utf-8"));
+                            const existing = claudeJson.mcpServers?.flair;
+                            if (existing && existing.env?.FLAIR_URL === httpUrl && existing.env?.FLAIR_AGENT_ID === agentId) {
+                                console.log(`   ✓ Claude Code already wired in ~/.claude.json`);
+                                wiringResults.push({ client: "claude-code", message: "already wired" });
+                            }
+                            else {
+                                claudeJson.mcpServers = claudeJson.mcpServers || {};
+                                claudeJson.mcpServers.flair = flairMcpConfig;
+                                writeFileSync(claudeJsonPath, JSON.stringify(claudeJson, null, 2));
+                                console.log(`   ✓ Claude Code wired in ~/.claude.json (restart Claude Code to pick it up)`);
+                                wiringResults.push({ client: "claude-code", message: "wired ~/.claude.json" });
+                            }
+                        }
+                        else {
+                            console.log(`   MCP config (add to ~/.claude.json):`);
+                            console.log(`     { "mcpServers": { "flair": ${JSON.stringify(flairMcpConfig)} } }`);
+                            wiringResults.push({ client: "claude-code", message: "snippet printed (no ~/.claude.json)" });
+                        }
+                    }
+                    catch {
+                        console.log(`   MCP config (add manually to ~/.claude.json):`);
+                        console.log(`     { "mcpServers": { "flair": ${JSON.stringify(flairMcpConfig)} } }`);
+                        wiringResults.push({ client: "claude-code", message: "snippet printed" });
+                    }
+                }
+                else {
+                    let result;
+                    switch (clientId) {
+                        case "codex":
+                            result = wireCodex(mcpEnv);
+                            break;
+                        case "gemini":
+                            result = wireGemini(mcpEnv);
+                            break;
+                        case "cursor":
+                            result = wireCursor(mcpEnv);
+                            break;
+                        default: result = { ok: false, message: `Unknown client: ${clientId}` };
+                    }
+                    wiringResults.push({ client: clientId, message: result.message });
+                    console.log(`   ${result.ok ? "✓" : "•"} ${result.message}`);
+                }
             }
         }
-        catch {
-            console.log(`\n   MCP config (add manually to ~/.claude.json):`);
-            console.log(`     { "mcpServers": { "flair": ${JSON.stringify(flairMcpConfig)} } }`);
+        // ── Smoke-test the MCP server ────────────────────────────────────────
+        // Launch flair-mcp and confirm it answers a JSON-RPC initialize over
+        // stdio. Best-effort: failures warn but never fail the command. Skipped
+        // with --skip-smoke, --no-mcp, --client none, or when nothing was wired.
+        if (!opts.skipSmoke && !noMcp && clientOpt !== "none" && wiringResults.length > 0) {
+            console.log("\n   Smoke-testing MCP server...");
+            try {
+                const mcpProc = spawn("npx", ["-y", "@tpsdev-ai/flair-mcp"], {
+                    env: { ...process.env, FLAIR_AGENT_ID: agentId, FLAIR_URL: httpUrl },
+                    stdio: ["pipe", "pipe", "pipe"],
+                });
+                const initMsg = JSON.stringify({ jsonrpc: "2.0", id: 1, method: "initialize", params: { protocolVersion: "0.1", capabilities: {}, clientInfo: { name: "flair-init", version: "1.0.0" } } });
+                mcpProc.stdin.write(initMsg + "\n");
+                mcpProc.stdin.end();
+                let stdout = "";
+                mcpProc.stdout.on("data", (d) => { stdout += d.toString(); });
+                // A single timer drives the timeout AND cleanup. It MUST be cleared on
+                // settle — an un-cleared setTimeout is a live handle that keeps Node's
+                // event loop alive (the ~60s phantom hang after `flair init` printed
+                // success: the smoke timer + the lingering npx child both pinned the
+                // loop). We clear it on every exit path below.
+                let smokeTimer = null;
+                await new Promise((resolve, reject) => {
+                    const settle = (fn) => {
+                        if (smokeTimer) {
+                            clearTimeout(smokeTimer);
+                            smokeTimer = null;
+                        }
+                        fn();
+                    };
+                    mcpProc.on("exit", (code) => {
+                        settle(() => {
+                            if (code === 0 && stdout.length > 0)
+                                resolve();
+                            else
+                                reject(new Error(`MCP server exited with code ${code}`));
+                        });
+                    });
+                    mcpProc.on("error", (err) => settle(() => reject(err)));
+                    smokeTimer = setTimeout(() => settle(() => { mcpProc.kill("SIGKILL"); reject(new Error("MCP smoke test timed out")); }), 15_000);
+                });
+                try {
+                    const lines = stdout.split("\n").filter(l => l.trim());
+                    for (const line of lines) {
+                        const parsed = JSON.parse(line);
+                        if (parsed.jsonrpc === "2.0" && parsed.id === 1 && !parsed.error) {
+                            console.log("   ✓ MCP server responded");
+                            break;
+                        }
+                    }
+                }
+                catch {
+                    console.log("   ⚠ MCP server responded but response could not be parsed");
+                }
+                finally {
+                    // Reap the child even on the resolve path: the MCP server exits on
+                    // stdin close, but the `npx` wrapper can linger holding the loop.
+                    // SIGKILL is safe — we already have the response we need.
+                    try {
+                        if (mcpProc.exitCode === null)
+                            mcpProc.kill("SIGKILL");
+                    }
+                    catch { /* already gone */ }
+                }
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                console.log(`   ⚠ MCP smoke test failed: ${message}`);
+                console.log("   Use --skip-smoke to bypass.");
+            }
         }
     }
     else {
@@ -1783,354 +2078,16 @@ program
         }
         console.log(`\n   Export: FLAIR_URL=${httpUrl}`);
     }
-});
-// ─── flair install ───────────────────────────────────────────────────────────
-program
-    .command("install")
-    .description("One-command Flair setup — init, agent, and MCP client wiring")
-    .option("--client <client>", "MCP client(s) to wire: claude-code, codex, gemini, cursor, all, or none")
-    .option("--agent <id>", "Agent ID (defaults to hostname short-form)")
-    .option("--no-mcp", "Skip MCP wiring (init + agent only)")
-    .option("--port <port>", "Harper HTTP port")
-    .option("--ops-port <port>", "Harper operations API port")
-    .option("--data-dir <dir>", "Harper data directory")
-    .option("--keys-dir <dir>", "Directory for Ed25519 keys")
-    .option("--skip-smoke", "Skip MCP smoke test")
-    .action(async (opts) => {
-    const httpPort = resolveHttpPort(opts);
-    const opsPort = resolveOpsPort(opts);
-    const keysDir = opts.keysDir ?? defaultKeysDir();
-    const dataDir = opts.dataDir ?? defaultDataDir();
-    // Resolve client selection
-    const clientOpt = opts.client;
-    const noMcp = opts.noMcp === true;
-    const selectedClients = [];
-    if (clientOpt === "none" || noMcp) {
-        // Skip MCP entirely — just init + agent
-    }
-    else if (clientOpt === "all") {
-        // Wire all detected clients
-    }
-    else if (clientOpt) {
-        // Wire a specific client
-        const valid = ["claude-code", "codex", "gemini", "cursor"];
-        if (!valid.includes(clientOpt)) {
-            console.error(`Unknown client: ${clientOpt}. Valid: claude-code, codex, gemini, cursor, all, none`);
-            process.exit(1);
-        }
-        selectedClients.push(clientOpt);
-    }
-    // If no --client flag: interactive detection later
-    // ── Step 1: Ensure Flair is initialized ──
-    let alreadyInitialized = false;
-    let alreadyRunning = false;
-    let adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? process.env.HDB_ADMIN_PASSWORD ?? "";
-    const adminUser = DEFAULT_ADMIN_USER;
-    // Check if Flair is already initialized (config with port exists)
-    try {
-        const cp = configPath();
-        if (existsSync(cp)) {
-            const yaml = readFileSync(cp, "utf-8");
-            if (yaml.match(/port:\s*\d+/)) {
-                alreadyInitialized = true;
-                console.log("Flair already initialized — skipping init.");
-            }
-        }
-    }
-    catch { /* not initialized */ }
-    if (!alreadyInitialized) {
-        const major = parseInt(process.version.slice(1), 10);
-        if (major < 18)
-            throw new Error(`Node.js >= 18 required (found ${process.version})`);
-        // Only generate a password if none provided via env (fresh install)
-        // If we generate, write it atomically to ~/.flair/admin-pass
-        let adminPassGenerated = false;
-        if (!adminPass) {
-            adminPass = Buffer.from(nacl.randomBytes(18)).toString("base64url");
-            adminPassGenerated = true;
-            // Atomic write: create temp file in same dir, then rename
-            const flairDir = join(homedir(), ".flair");
-            mkdirSync(flairDir, { recursive: true });
-            const adminPassPath = join(flairDir, "admin-pass");
-            const tempPath = mkdtempSync(join(flairDir, ".admin-pass.tmp-"));
-            const finalTempPath = join(tempPath, "admin-pass");
-            try {
-                writeFileSync(finalTempPath, adminPass + "\n", { mode: 0o600 });
-                renameSync(finalTempPath, adminPassPath);
-                rmSync(tempPath, { recursive: true, force: true });
-            }
-            catch (err) {
-                // Clean up temp dir on failure
-                try {
-                    rmSync(tempPath, { recursive: true, force: true });
-                }
-                catch { }
-                throw err;
-            }
-            console.log(`Admin password saved to: ${adminPassPath}`);
-        }
-        // Check if Harper is already running on this port
-        try {
-            const res = await fetch(`http://127.0.0.1:${httpPort}/health`, { signal: AbortSignal.timeout(1000) });
-            if (res.status > 0) {
-                alreadyRunning = true;
-                console.log(`Harper already running on port ${httpPort} — skipping start`);
-            }
-        }
-        catch { /* not running */ }
-        if (!alreadyRunning) {
-            const bin = harperBin();
-            if (!bin)
-                throw new Error("@harperfast/harper not found in node_modules.\nRun: npm install @harperfast/harper");
-            mkdirSync(dataDir, { recursive: true });
-            const alreadyInstalled = existsSync(join(dataDir, "harper-config.yaml"));
-            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: join(dataDir, "operations-server") },
-                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,
-                THREADS_COUNT: "1",
-                NODE_HOSTNAME: "localhost",
-                HTTP_PORT: String(httpPort),
-                OPERATIONSAPI_NETWORK_PORT: String(opsPort),
-                LOCAL_STUDIO: "false",
-            };
-            if (alreadyInstalled) {
-                console.log("Existing Harper installation found — skipping install.");
-            }
-            else {
-                const installEnv = { ...env, HOME: join(dataDir, "..") };
-                console.log("Installing Harper...");
-                console.log("Downloading embedding model (nomic-embed-text-v1.5, ~80MB) — this may take a minute...");
-                await new Promise((resolve, reject) => {
-                    let output = "";
-                    let dotTimer = null;
-                    const install = spawn(process.execPath, [bin, "install"], { cwd: flairPackageDir(), env: installEnv });
-                    dotTimer = setInterval(() => process.stdout.write("."), 3000);
-                    install.stdout?.on("data", (d) => { output += d.toString(); });
-                    install.stderr?.on("data", (d) => { output += d.toString(); });
-                    install.on("exit", (code) => {
-                        if (dotTimer) {
-                            clearInterval(dotTimer);
-                            process.stdout.write("\n");
-                        }
-                        code === 0 ? resolve() : reject(new Error(`Harper install failed (${code}): ${output}`));
-                    });
-                    install.on("error", (err) => {
-                        if (dotTimer) {
-                            clearInterval(dotTimer);
-                            process.stdout.write("\n");
-                        }
-                        reject(err);
-                    });
-                    setTimeout(() => {
-                        install.kill();
-                        if (dotTimer) {
-                            clearInterval(dotTimer);
-                            process.stdout.write("\n");
-                        }
-                        reject(new Error(`Harper install timed out: ${output}`));
-                    }, 60_000);
-                });
-            }
-            // Start Harper
-            console.log(`Starting Harper on port ${httpPort}...`);
-            const proc = spawn(process.execPath, [bin, "run", "."], { cwd: flairPackageDir(), env, detached: true, stdio: "ignore" });
-            proc.unref();
-        }
-        // Wait for health
-        console.log("Waiting for Harper health check...");
-        await waitForHealth(httpPort, adminUser, adminPass, STARTUP_TIMEOUT_MS);
-        console.log("Harper is healthy ✓");
-        // Write config so other commands can find this instance
-        writeConfig(httpPort);
-    }
-    else {
-        // Flair already initialized — resolve admin pass from env, falling back to
-        // the persisted ~/.flair/admin-pass written at first install. Agent
-        // seeding now goes through the ops API (#499), which always requires Basic
-        // admin auth (it does NOT honor authorizeLocal), so a re-run of
-        // `flair install --agent <new-id>` against an already-initialized local
-        // Flair needs a real pass even when no env var is set.
-        adminPass = process.env.FLAIR_ADMIN_PASS ?? process.env.HDB_ADMIN_PASSWORD ?? "";
-        if (!adminPass) {
-            try {
-                const persisted = join(homedir(), ".flair", "admin-pass");
-                if (existsSync(persisted))
-                    adminPass = readFileSync(persisted, "utf-8").trim();
-            }
-            catch { /* fall through with empty pass */ }
-        }
-    }
-    const httpUrl = `http://127.0.0.1:${httpPort}`;
-    // ── Step 2: Detect MCP clients ──
-    let clients = detectClients();
-    if (selectedClients.length > 0) {
-        // Explicit --client flag — override detection
-        if (clientOpt === "all" || clientOpt === "none" || noMcp) {
-            // all/none handled below
-        }
-        else {
-            // Filter to only the selected client (preserving wire function from detectClients)
-            clients = clients.filter(c => selectedClients.includes(c.id));
-        }
-    }
-    if (!clientOpt && !noMcp) {
-        // No --client flag — print detected clients
-        const detected = clients.filter(c => c.detected);
-        if (detected.length === 0) {
-            console.log("No MCP clients detected. Run with --client <name> to wire a specific client.");
-        }
-        else {
-            console.log(`Detected MCP clients: ${detected.map(c => c.label).join(", ")}`);
-        }
-    }
-    // ── Step 3: Resolve agent identity ──
-    const agentId = opts.agent ?? (() => {
-        try {
-            const hn = hostname();
-            return hn.split(".")[0];
-        }
-        catch {
-            return "flair-agent";
-        }
-    })();
-    // Validate agentId to prevent path traversal
-    const VALID_AGENT_ID = /^[a-zA-Z0-9_-]+$/;
-    if (!VALID_AGENT_ID.test(agentId)) {
-        throw new Error(`Invalid agent ID: ${agentId}. Agent ID must contain only letters, numbers, underscores, and hyphens.`);
-    }
-    let agentExists = false;
-    // Check if agent already exists locally
-    const privPath = privKeyPath(agentId, keysDir);
-    if (existsSync(privPath)) {
-        agentExists = true;
-        console.log(`Agent '${agentId}' already exists ✓`);
-    }
-    else {
-        // Create agent
-        mkdirSync(keysDir, { recursive: true });
-        const pubPath = pubKeyPath(agentId, keysDir);
-        console.log("Generating Ed25519 keypair...");
-        const kp = nacl.sign.keyPair();
-        const seed = kp.secretKey.slice(0, 32);
-        writeFileSync(privPath, Buffer.from(seed));
-        chmodSync(privPath, 0o600);
-        writeFileSync(pubPath, Buffer.from(kp.publicKey));
-        const pubKeyB64url = b64url(kp.publicKey);
-        console.log(`Keypair written: ${privPath} ✓`);
-        // Seed agent via the Harper operations API. The Agent table is a REST
-        // resource without a POST handler, so the insert body must go to the ops
-        // API (POST <opsUrl>/ with {operation:"insert",...}), NOT the REST root
-        // (which 405s the body as a collection POST to /Agent). This is the same
-        // path `flair agent add` uses. (#499)
-        const seedOpsTarget = opts.opsTarget ?? opsPort;
-        console.log(opts.opsTarget
-            ? `Seeding agent '${agentId}' via operations API (--ops-target)...`
-            : `Seeding agent '${agentId}' via operations API...`);
-        await seedAgentViaOpsApi(seedOpsTarget, agentId, pubKeyB64url, adminUser, adminPass);
-        console.log(`Agent '${agentId}' registered ✓`);
-    }
-    // ── Step 4: Wire MCP clients ──
-    const mcpEnv = { FLAIR_AGENT_ID: agentId, FLAIR_URL: httpUrl };
-    const wiringResults = [];
-    if (!noMcp && clientOpt !== "none") {
-        const toWire = clientOpt === "all"
-            ? clients.filter(c => c.detected).map(c => c.id)
-            : selectedClients.length > 0
-                ? selectedClients
-                : clients.filter(c => c.detected).map(c => c.id);
-        for (const clientId of toWire) {
-            let result;
-            switch (clientId) {
-                case "claude-code":
-                    result = wireClaudeCode(mcpEnv);
-                    break;
-                case "codex":
-                    result = wireCodex(mcpEnv);
-                    break;
-                case "gemini":
-                    result = wireGemini(mcpEnv);
-                    break;
-                case "cursor":
-                    result = wireCursor(mcpEnv);
-                    break;
-                default: result = { ok: false, message: `Unknown client: ${clientId}` };
-            }
-            wiringResults.push({ client: clientId, message: result.message });
-            console.log(`  ${result.ok ? "✓" : "✗"} ${result.message}`);
-        }
-    }
-    // ── Step 5: Smoke test the MCP server ──
-    if (!opts.skipSmoke && !noMcp && clientOpt !== "none" && wiringResults.length > 0) {
-        console.log("Smoke-testing MCP server...");
-        try {
-            // Launch flair-mcp and send initialize request over stdio
-            const mcpProc = spawn("npx", ["-y", "@tpsdev-ai/flair-mcp"], {
-                env: { ...process.env, FLAIR_AGENT_ID: agentId, FLAIR_URL: httpUrl },
-                stdio: ["pipe", "pipe", "pipe"],
-                timeout: 15_000,
-            });
-            // Send initialize request
-            const initMsg = JSON.stringify({ jsonrpc: "2.0", id: 1, method: "initialize", params: { protocolVersion: "0.1", capabilities: {}, clientInfo: { name: "flair-install", version: "1.0.0" } } });
-            mcpProc.stdin.write(initMsg + "\n");
-            mcpProc.stdin.end();
-            let stdout = "";
-            mcpProc.stdout.on("data", (d) => { stdout += d.toString(); });
-            await new Promise((resolve, reject) => {
-                mcpProc.on("exit", (code) => {
-                    if (code === 0 && stdout.length > 0) {
-                        resolve();
-                    }
-                    else {
-                        reject(new Error(`MCP server exited with code ${code}`));
-                    }
-                });
-                mcpProc.on("error", reject);
-                setTimeout(() => { mcpProc.kill(); reject(new Error("MCP smoke test timed out")); }, 15_000);
-            });
-            // Check for a valid JSON-RPC response
-            try {
-                const lines = stdout.split("\n").filter(l => l.trim());
-                for (const line of lines) {
-                    const parsed = JSON.parse(line);
-                    if (parsed.jsonrpc === "2.0" && parsed.id === 1 && !parsed.error) {
-                        console.log("  ✓ MCP server responded");
-                        break;
-                    }
-                }
-            }
-            catch {
-                console.log("  ⚠ MCP server responded but response could not be parsed");
-            }
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            console.log(`  ⚠ MCP smoke test failed: ${message}`);
-            console.log("  Use --skip-smoke to bypass.");
-        }
-    }
-    // ── Step 6: Summary ──
-    console.log("");
-    console.log("✓ Flair installed.");
-    console.log(`   Agent: ${agentId}`);
-    if (existsSync(privKeyPath(agentId, keysDir))) {
-        console.log(`   Private key: ${privKeyPath(agentId, keysDir)}`);
-    }
-    console.log(`   Local: ${httpUrl}`);
-    console.log(`   MCP: ${wiringResults.length > 0 ? wiringResults.map(r => r.client).join(", ") + " ✓ wired" : "none wired"}`);
-    console.log("");
-    console.log(`   Try it: in Claude Code, ask the agent "what do you remember about me?"`);
+    // All init work is genuinely done at this point: Harper is installed +
+    // running (detached, unref'd — survives this process exiting), the agent is
+    // registered, semantic search is verified, MCP clients are wired, and the
+    // smoke test ran. The MCP smoke subprocess can leave a lingering npx handle
+    // that pins Node's event loop for ~60s after success ("rc=0 but doesn't
+    // return"). We've cleared/unref'd the known timers above; exit explicitly so
+    // the prompt returns in a couple seconds regardless of any stray handle. The
+    // running Harper instance is unaffected.
+    await new Promise((r) => process.stdout.write("", () => r()));
+    process.exit(0);
 });
 // ─── flair agent ─────────────────────────────────────────────────────────────
 const agent = program.command("agent").description("Manage Flair agents");
@@ -2142,6 +2099,8 @@ agent
     .option("--admin-pass <pass>", "Admin password for registration")
     .option("--keys-dir <dir>", "Directory for Ed25519 keys")
     .option("--ops-port <port>", "Harper operations API port")
+    .option("--target <url>", "Remote Flair REST URL; derives the ops API URL (port-1) to seed the Agent there (env: FLAIR_TARGET)")
+    .option("--ops-target <url>", "Explicit ops API URL to seed the Agent on (env: FLAIR_OPS_TARGET; bypasses port derivation)")
     .action(async (id, opts) => {
     const httpPort = resolveHttpPort(opts);
     const opsPort = resolveOpsPort(opts);
@@ -2149,6 +2108,11 @@ agent
     const adminPass = opts.adminPass;
     const adminUser = DEFAULT_ADMIN_USER;
     const name = opts.name ?? id;
+    // Where to seed the Agent record. Default is localhost (opsPort). When
+    // --ops-target or --target is given, seed on the remote instead of localhost
+    // (#514 — agent add could only ever hit localhost ops). Precedence matches
+    // `flair import`: explicit --ops-target > derive from --target > localhost.
+    const seedOpsTarget = resolveEffectiveOpsUrl({ target: opts.target, opsTarget: opts.opsTarget }) ?? opsPort;
     if (!adminPass) {
         console.error("Error: --admin-pass is required for agent add (needed to insert into Agent table)");
         process.exit(1);
@@ -2172,8 +2136,10 @@ agent
         pubKeyB64url = b64url(kp.publicKey);
         console.log(`Keypair written: ${privPath}`);
     }
-    await seedAgentViaOpsApi(opsPort, id, pubKeyB64url, adminUser, adminPass);
-    console.log(`✅ Agent '${id}' (${name}) registered`);
+    await seedAgentViaOpsApi(seedOpsTarget, id, pubKeyB64url, adminUser, adminPass);
+    console.log(typeof seedOpsTarget === "string"
+        ? `✅ Agent '${id}' (${name}) registered (ops: ${seedOpsTarget})`
+        : `✅ Agent '${id}' (${name}) registered`);
     console.log(`   Private key: ${privPath}`);
     console.log(`   Public key:  ${pubKeyB64url}`);
 });
@@ -2181,6 +2147,8 @@ agent
     .command("list")
     .description("List all agents")
     .option("--admin-pass <pass>", "Admin password (or set FLAIR_ADMIN_PASS env)")
+    .option("--agent <id>", "Agent ID to authenticate as via Ed25519 (or FLAIR_AGENT_ID env) when no admin pass")
+    .option("--keys-dir <dir>", "Directory holding the agent's Ed25519 key")
     .option("--port <port>", "Harper HTTP port")
     .option("--json", "Emit raw JSON array (also: pipe + FLAIR_OUTPUT=json)")
     .action(async (opts) => {
@@ -2216,13 +2184,39 @@ agent
         agents = await res.json();
     }
     else {
+        // No admin pass → authenticate as the AGENT via Ed25519. The Agent table's
+        // allowRead() is allowVerified — a bare unauthenticated GET /Agent returns
+        // 403 AccessViolation (the dogfood symptom: the natural "did my agent
+        // register?" check errored on a healthy install). A verified agent reads
+        // the principal table for discovery, so sign the request with its key.
         const baseUrl = `http://127.0.0.1:${port}`;
-        const res = await fetch(`${baseUrl}/Agent`, {
-            headers: { "Content-Type": "application/json" },
-        });
+        const agentId = opts.agent ?? process.env.FLAIR_AGENT_ID;
+        const keysDir = opts.keysDir ?? process.env.FLAIR_KEY_DIR ?? defaultKeysDir();
+        let res;
+        if (agentId) {
+            const keyPath = resolveKeyPath(agentId) ?? join(keysDir, `${agentId}.key`);
+            if (!existsSync(keyPath)) {
+                console.error(`${render.icons.error} no key for agent '${agentId}' (looked in ${keysDir}). Pass --admin-pass, --keys-dir, or a registered --agent.`);
+                process.exit(1);
+            }
+            res = await authFetch(baseUrl, agentId, keyPath, "GET", "/Agent");
+        }
+        else {
+            // No agent identity available either. Try anonymously, but if it 403s
+            // (the common case), tell the user exactly how to authenticate rather
+            // than dumping a raw AccessViolation.
+            res = await fetch(`${baseUrl}/Agent`, { headers: { "Content-Type": "application/json" } });
+        }
         if (!res.ok) {
             const text = await res.text().catch(() => "");
-            console.error(`${render.icons.error} ${res.status} ${text}`);
+            if (res.status === 403 && !agentId) {
+                console.error(`${render.icons.error} 403 — listing agents requires authentication.`);
+                console.error(`   Use ${render.wrap(render.c.cyan, "--agent <id>")} (or set FLAIR_AGENT_ID) to authenticate as a registered agent,`);
+                console.error(`   or ${render.wrap(render.c.cyan, "--admin-pass")} / FLAIR_ADMIN_PASS for the admin view.`);
+            }
+            else {
+                console.error(`${render.icons.error} ${res.status} ${text}`);
+            }
             process.exit(1);
         }
         const data = await res.json();
@@ -5766,14 +5760,104 @@ statusCmd
         console.log("\n✅ no warnings");
     }
 });
+// ─── flair upgrade --target <fabric> ────────────────────────────────────────
+//
+// One-command upgrade of a Flair instance DEPLOYED to a Harper Fabric cluster.
+// Mirrors `flair deploy`'s credential handling (FABRIC_USER/FABRIC_PASSWORD env
+// fallbacks, password-via-flag warning) and NEVER prints credentials. The
+// version-resolution + @harperfast/harper pin + reuse of deploy() lives in
+// src/fabric-upgrade.ts; this wrapper only does CLI plumbing + the confirm.
+async function runFabricUpgrade(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 fabricUser = opts.fabricUser ?? process.env.FABRIC_USER;
+    const fabricPassword = opts.fabricPassword ?? process.env.FABRIC_PASSWORD;
+    const check = opts.check ?? false;
+    // Creds are not required for --check (read-only registry + best-effort GET),
+    // but ARE required to actually deploy.
+    if (!check && !(fabricUser && fabricPassword)) {
+        console.error(red("flair upgrade --target: credentials required to deploy"));
+        console.error("  pass --fabric-user + --fabric-password (or FABRIC_USER / FABRIC_PASSWORD env)");
+        console.error("  or use --check to preview the plan without credentials");
+        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 upgradeOpts = {
+        target: opts.target,
+        project: opts.project,
+        version: opts.version,
+        harperVersion: opts.harperVersion,
+        fabricUser,
+        fabricPassword,
+        check,
+        restart: opts.restart !== false,
+        replicated: opts.replicated !== false,
+    };
+    console.log(`${green("→")} Upgrading Fabric Flair at ${upgradeOpts.target}`);
+    if (check)
+        console.log(dim("  (--check: plan only, no deploy)"));
+    try {
+        // For a real (non-check) run, confirm first unless --yes. Building the plan
+        // up front would double the registry round-trips; the plan prints inside
+        // fabricUpgrade. We confirm BEFORE invoking when interactive and not --yes.
+        if (!check && !opts.yes && process.stdin.isTTY) {
+            const { createInterface } = await import("node:readline");
+            const rl = createInterface({ input: process.stdin, output: process.stdout });
+            const answer = await new Promise((res) => rl.question(`Deploy a fresh ${green("@tpsdev-ai/flair")} to ${upgradeOpts.target}? [y/N] `, (a) => { rl.close(); res(a); }));
+            if (!/^y(es)?$/i.test(answer.trim())) {
+                console.log("Aborted.");
+                return;
+            }
+        }
+        const result = await fabricUpgrade(upgradeOpts);
+        if (check) {
+            console.log(`\n${green("✓")} check complete — run without --check to deploy.`);
+            return;
+        }
+        if (result.plan.upToDate && !result.deployed) {
+            console.log(`\n${green("✓")} already up to date.`);
+            return;
+        }
+        console.log(`\n${green("✓")} Fabric upgrade complete.`);
+    }
+    catch (err) {
+        console.error(red(`\n✗ fabric upgrade 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 upgrade ────────────────────────────────────────────────────────────
 program
     .command("upgrade")
-    .description("Upgrade Flair and related packages to latest versions")
-    .option("--check", "Only check for updates, don't install")
+    .description("Upgrade Flair — local packages by default, or a deployed Fabric with --target")
+    .option("--check", "Only check for updates / show the plan, don't install or deploy")
     .option("--restart", "Restart Flair after upgrade")
     .option("--all", "Show transitive packages (e.g. flair-client) in the listing — verbose mode for debugging dep versions")
+    // ── Fabric upgrade (--target) ────────────────────────────────────────────
+    // When --target is passed, upgrade the Flair component DEPLOYED to that
+    // Harper Fabric URL instead of the local npm install. Reuses `flair deploy`
+    // under the hood with the @harperfast/harper pin baked in (flair#513).
+    .option("--target <url>", "Upgrade the Flair deployed to this Fabric URL (not the local install)")
+    .option("--fabric-user <user>", "Fabric admin username (env: FABRIC_USER) — for --target")
+    .option("--fabric-password <pass>", "Fabric admin password (env: FABRIC_PASSWORD) — for --target")
+    .option("--version <semver>", "Flair version to deploy with --target (default: latest published @tpsdev-ai/flair)")
+    .option("--harper-version <semver>", "Pin @harperfast/harper to this version for --target (default: registry latest, floored at the flair#513 fix)")
+    .option("--project <name>", "Fabric component name for --target", "flair")
+    .option("--no-replicated", "Disable cluster-wide replication for --target (default: replicated=true)")
+    .option("--yes", "Skip the confirmation prompt for --target")
     .action(async (opts) => {
+    // ── Fabric-upgrade branch ───────────────────────────────────────────────
+    if (opts.target) {
+        await runFabricUpgrade(opts);
+        return;
+    }
     const { execSync, execFileSync } = await import("node:child_process");
     const checkOnly = opts.check ?? false;
     const showAll = opts.all ?? false;
@@ -6600,6 +6684,7 @@ program
     .command("doctor")
     .description("Diagnose common Flair problems and suggest fixes")
     .option("--port <port>", "Harper HTTP port")
+    .option("--agent <id>", "Agent ID to use for the semantic-search round-trip (or FLAIR_AGENT_ID env)")
     .option("--fix", "Automatically fix issues where possible")
     .option("--dry-run", "Show what --fix would do without making changes")
     .action(async (opts) => {
@@ -6762,32 +6847,38 @@ program
     else {
         console.log(`  ${render.icons.warn} No config file at ${render.wrap(render.c.dim, cfgPath)} — using defaults`);
     }
-    // 4. Embeddings check (only if Harper is responding)
+    // 4. Embeddings check — REAL semantic round-trip (only if Harper is responding).
+    //
+    // The dead-simple `{ q: "test" }` probe used to pass even when embeddings were
+    // not loaded: SemanticSearch falls back to keyword-only scan, and an
+    // unauthenticated probe 401s → "cannot verify" → no issue counted. A clean-VM
+    // dogfood found semantic search DEAD out of the box (sudo/root-owned install
+    // can't write the models symlink → EACCES) while `flair doctor` reported
+    // "no issues found". This now stores a memory with a distinctive phrase and
+    // searches for a PARAPHRASE (no shared keywords). If the top result isn't
+    // recovered by MEANING, recall-by-meaning is broken and doctor FAILS LOUDLY.
     if (harperResponding) {
-        try {
-            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(`  ${render.icons.warn} Embeddings: keyword-only ${render.wrap(render.c.dim, `(${data._warning})`)}`);
-                    console.log(`     ${render.wrap(render.c.dim, "Semantic search quality is degraded")}`);
-                    console.log(`     ${render.wrap(render.c.dim, "Check:")} ls ~/.npm-global/lib/node_modules/@tpsdev-ai/flair/models/`);
-                    issues++;
-                }
-                else {
-                    console.log(`  ${render.icons.ok} Embeddings: semantic search operational`);
-                }
-            }
-            else if (testRes.status === 401) {
-                console.log(`  ${render.icons.warn} Embeddings: cannot verify ${render.wrap(render.c.dim, "(auth required for SemanticSearch)")}`);
-            }
+        const semanticStatus = await verifySemanticSearch(baseUrl, opts.agent, defaultKeysDir());
+        switch (semanticStatus.state) {
+            case "ok":
+                console.log(`  ${render.icons.ok} Embeddings: semantic search operational ${render.wrap(render.c.dim, `(paraphrase recall verified, score ${semanticStatus.score.toFixed(2)})`)}`);
+                break;
+            case "degraded":
+                // LOUD failure — never report all-clear when recall-by-meaning is dead.
+                console.log(`  ${render.icons.error} Semantic search DEGRADED ${render.wrap(render.c.dim, `— ${semanticStatus.detail}`)}`);
+                console.log(`     ${render.wrap(render.c.red, "Embeddings are not loaded; recall-by-meaning will NOT work.")}`);
+                console.log(`     ${render.wrap(render.c.dim, "Common cause: the embeddings component lacks write access (sudo/root global installs).")}`);
+                console.log(`     ${render.wrap(render.c.dim, "See:")} docs/troubleshooting.md ${render.wrap(render.c.dim, "→ \"Semantic search DEGRADED\"")}`);
+                issues++;
+                break;
+            case "skipped":
+                // Could not run the round-trip (no agent / no key). Don't claim
+                // all-clear — surface that the check was skipped, but don't count it
+                // as a hard issue since the user may simply not have an agent yet.
+                console.log(`  ${render.icons.warn} Embeddings: not verified ${render.wrap(render.c.dim, `(${semanticStatus.detail})`)}`);
+                console.log(`     ${render.wrap(render.c.dim, "Pass --agent <id> (or set FLAIR_AGENT_ID) so doctor can run a real semantic round-trip.")}`);
+                break;
         }
-        catch { /* fetch error, already flagged */ }
     }
     // 5. Stale PID file (skip if already reported in port check)
     const dataDir = defaultDataDir();
@@ -8657,11 +8748,20 @@ program
     .option("--port <port>", "Harper HTTP port")
     .option("--ops-port <port>", "Harper operations API port")
     .option("--url <url>", "Flair base URL (overrides --port)")
+    .option("--ops-target <url>", "Explicit ops API URL for the Agent seed (env: FLAIR_OPS_TARGET; bypasses port derivation). Use when --url is remote and the ops port isn't HTTP-1.")
     .option("--admin-pass <pass>", "Admin password (or set FLAIR_ADMIN_PASS env)")
     .option("--keys-dir <dir>", "Keys directory", defaultKeysDir())
     .action(async (importPath, opts) => {
     const baseUrl = opts.url ?? `http://127.0.0.1:${resolveHttpPort(opts)}`;
     const opsPort = resolveOpsPort(opts);
+    // Resolve where the Agent record is seeded. The Agent goes through the ops
+    // API (the REST surface has no Agent POST handler), so a remote --url import
+    // must NOT silently seed on localhost (#514 — split import). Precedence:
+    //   1. --ops-target / FLAIR_OPS_TARGET → use directly
+    //   2. --url given → derive ops URL from it (port-1 convention)
+    //   3. neither → localhost opsPort (preserves local default)
+    // The remote REST base (--url) is mapped to `target` for derivation.
+    const seedOpsTarget = resolveEffectiveOpsUrl({ target: opts.url, opsTarget: opts.opsTarget }) ?? opsPort;
     const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
     if (!adminPass) {
         console.error("Error: --admin-pass or FLAIR_ADMIN_PASS required");
@@ -8709,9 +8809,11 @@ program
         ? nacl.sign.keyPair.fromSeed(new Uint8Array(decodedSeed)).publicKey
         : nacl.sign.keyPair.fromSeed(new Uint8Array(decodedSeed.subarray(0, 32))).publicKey;
     const pubKeyB64url = b64url(pubKey);
-    // Register agent via ops API
-    await seedAgentViaOpsApi(opsPort, agentId, pubKeyB64url, DEFAULT_ADMIN_USER, adminPass);
-    console.log(`  Agent registered`);
+    // Register agent via ops API (remote when --url/--ops-target points off-box)
+    await seedAgentViaOpsApi(seedOpsTarget, agentId, pubKeyB64url, DEFAULT_ADMIN_USER, adminPass);
+    console.log(typeof seedOpsTarget === "string"
+        ? `  Agent registered (ops: ${seedOpsTarget})`
+        : `  Agent registered`);
     // Restore memories
     const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
     let memCount = 0;
@@ -9105,9 +9207,159 @@ presence
         console.log(`  Status: ${data.presenceStatus}`);
     }
 });
-// Run CLI only when this is the entry point (not when imported for testing)
-if (import.meta.main) {
+// ─── flair workspace ─────────────────────────────────────────────────────────
+//
+// Coordination write surface (ops-wmgx / Kris #510). `workspace set` writes the
+// agent's OWN WorkspaceState via a signed POST /WorkspaceState. Identity comes
+// from the Ed25519 signature — the body carries NO agentId, so an agent can only
+// write as itself (the WorkspaceState.post() handler overwrites agentId from the
+// signature regardless of body content). Mirrors `presence set`'s signed-POST shape.
+const MAX_WORKSPACE_FIELD_LENGTH = 2000;
+const workspace = program.command("workspace").description("Manage agent workspace state (The Office Space)");
+workspace
+    .command("set")
+    .description("Set your agent's current workspace state (POST /WorkspaceState)")
+    .requiredOption("--ref <ref>", "Workspace ref (branch, worktree, or task ref)")
+    .option("--label <text>", "Human-readable label for this workspace")
+    .option("--provider <name>", "Provider/runtime (e.g. claude-code, openclaw)", "cli")
+    .option("--task <id>", "Task/issue id this workspace is attached to")
+    .option("--phase <phase>", "Current phase (e.g. design, implement, review)")
+    .option("--summary <text>", "Short summary of current workspace state")
+    .option("--agent <id>", "Agent ID (env: FLAIR_AGENT_ID)")
+    .option("--port <port>", "Harper HTTP port")
+    .option("--target <url>", "Remote Flair URL (env: FLAIR_TARGET)")
+    .action(async (opts) => {
+    const agentId = resolveAgentIdOrEnv(opts);
+    if (!agentId) {
+        console.error("Error: agent ID required. Pass --agent <id> or set FLAIR_AGENT_ID environment variable.");
+        process.exit(1);
+    }
+    // Validate field lengths (free text → cap to bound the write).
+    for (const [name, val] of [["ref", opts.ref], ["label", opts.label], ["summary", opts.summary]]) {
+        if (val && String(val).length > MAX_WORKSPACE_FIELD_LENGTH) {
+            console.error(`Error: --${name} exceeds ${MAX_WORKSPACE_FIELD_LENGTH} character limit (got ${String(val).length}).`);
+            process.exit(1);
+        }
+    }
+    const keyPath = resolveKeyPath(agentId);
+    if (!keyPath) {
+        console.error(`Error: private key not found for agent '${agentId}'. Check ~/.flair/keys/ or set FLAIR_KEY_DIR.`);
+        process.exit(1);
+    }
+    const baseUrl = resolveBaseUrl(opts).replace(/\/$/, "");
+    const auth = buildEd25519Auth(agentId, "POST", "/WorkspaceState", keyPath);
+    // NOTE: agentId is intentionally NOT included in the body — the handler
+    // attributes the record from the Ed25519 signature (no forging).
+    const now = new Date().toISOString();
+    const body = {
+        id: `${agentId}:${opts.ref}`,
+        ref: opts.ref,
+        provider: opts.provider ?? "cli",
+        timestamp: now,
+    };
+    if (opts.label)
+        body.label = opts.label;
+    if (opts.task)
+        body.taskId = opts.task;
+    if (opts.phase)
+        body.phase = opts.phase;
+    if (opts.summary)
+        body.summary = opts.summary;
+    const res = await fetch(`${baseUrl}/WorkspaceState`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: auth },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        console.error(`Error: POST /WorkspaceState failed (${res.status}): ${text}`);
+        process.exit(1);
+    }
+    console.log(`✓ Workspace state updated for '${agentId}': ref=${opts.ref}${opts.phase ? `, phase=${opts.phase}` : ""}`);
+});
+// ─── flair orgevent ──────────────────────────────────────────────────────────
+//
+// Coordination write surface (ops-wmgx / Kris #510). `orgevent` publishes an
+// OrgEvent ATTRIBUTED to the authenticated agent via a signed POST /OrgEvent.
+// The event's authorId comes from the Ed25519 signature — the body carries NO
+// authorId, so an agent CANNOT forge another agent's events (the OrgEvent.post()
+// handler overwrites authorId from the signature). Mirrors `presence set`'s shape.
+const MAX_ORGEVENT_SUMMARY_LENGTH = 500;
+const MAX_ORGEVENT_DETAIL_LENGTH = 8000;
+program
+    .command("orgevent")
+    .description("Publish an org-wide coordination event attributed to your agent (POST /OrgEvent)")
+    .requiredOption("--kind <kind>", "Event kind (e.g. coord.claim, coord.release, status)")
+    .requiredOption("--summary <text>", "Short summary of the event")
+    .option("--detail <text>", "Longer detail payload")
+    .option("--scope <scope>", "Scope of the event (e.g. an agent id, repo, or 'org')")
+    .option("--target <agentId>", "Recipient agent id (repeatable)", (val, acc) => { acc.push(val); return acc; }, [])
+    .option("--agent <id>", "Agent ID (env: FLAIR_AGENT_ID)")
+    .option("--port <port>", "Harper HTTP port")
+    .option("--target-url <url>", "Remote Flair URL (env: FLAIR_TARGET)")
+    .action(async (opts) => {
+    const agentId = resolveAgentIdOrEnv(opts);
+    if (!agentId) {
+        console.error("Error: agent ID required. Pass --agent <id> or set FLAIR_AGENT_ID environment variable.");
+        process.exit(1);
+    }
+    if (opts.summary && String(opts.summary).length > MAX_ORGEVENT_SUMMARY_LENGTH) {
+        console.error(`Error: --summary exceeds ${MAX_ORGEVENT_SUMMARY_LENGTH} character limit (got ${String(opts.summary).length}).`);
+        process.exit(1);
+    }
+    if (opts.detail && String(opts.detail).length > MAX_ORGEVENT_DETAIL_LENGTH) {
+        console.error(`Error: --detail exceeds ${MAX_ORGEVENT_DETAIL_LENGTH} character limit (got ${String(opts.detail).length}).`);
+        process.exit(1);
+    }
+    const keyPath = resolveKeyPath(agentId);
+    if (!keyPath) {
+        console.error(`Error: private key not found for agent '${agentId}'. Check ~/.flair/keys/ or set FLAIR_KEY_DIR.`);
+        process.exit(1);
+    }
+    // orgevent reuses --target for recipients, so the remote-URL override is
+    // --target-url here (env FLAIR_TARGET still honored via resolveBaseUrl).
+    const baseUrl = resolveBaseUrl({ target: opts.targetUrl, port: opts.port }).replace(/\/$/, "");
+    const auth = buildEd25519Auth(agentId, "POST", "/OrgEvent", keyPath);
+    // NOTE: authorId is intentionally NOT included in the body — the handler
+    // attributes the event from the Ed25519 signature (no forging).
+    const body = {
+        kind: opts.kind,
+        summary: opts.summary,
+    };
+    if (opts.detail)
+        body.detail = opts.detail;
+    if (opts.scope)
+        body.scope = opts.scope;
+    if (Array.isArray(opts.target) && opts.target.length > 0)
+        body.targetIds = opts.target;
+    const res = await fetch(`${baseUrl}/OrgEvent`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: auth },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        console.error(`Error: POST /OrgEvent failed (${res.status}): ${text}`);
+        process.exit(1);
+    }
+    const data = await res.json().catch(() => null);
+    const targets = Array.isArray(opts.target) && opts.target.length > 0 ? ` → ${opts.target.join(", ")}` : "";
+    console.log(`✓ OrgEvent published as '${agentId}': kind=${opts.kind}${targets}`);
+    if (data?.id)
+        console.log(`  id: ${data.id}`);
+});
+// Parse argv and run the CLI. Exported so the CommonJS preflight shim
+// (cli-shim.cts → dist/cli-shim.cjs, the real bin entry) can invoke it after
+// its Node-version check passes. The shim imports this module, so import.meta.main
+// is false there — without this explicit entry point the CLI would load but never run.
+async function runCli() {
     await program.parseAsync();
 }
+// Run CLI directly when this file is the entry point — covers `node dist/cli.js`,
+// `bun src/cli.ts`, and the test harness (which spawns src/cli.ts under bun).
+// The packaged bin goes through cli-shim.cjs → runCli() instead.
+if (import.meta.main) {
+    await runCli();
+}
 // ─── Exported for testing ─────────────────────────────────────────────────────
-export { resolveKeyPath, buildEd25519Auth, readPortFromConfig, resolveHttpPort, resolveOpsPort, resolveTarget, resolveOpsTarget, resolveEffectiveOpsUrl, resolveOpsUrlFromTarget, signRequestBody, b64, b64url, program, api, VALID_PRESENCE_ACTIVITIES, MAX_TASK_LENGTH, isLocalBase, isLikelyRealSecret, shouldShowInlineSecretWarning, parseTokenFromFile, };
+export { runCli, resolveKeyPath, buildEd25519Auth, readPortFromConfig, resolveHttpPort, resolveOpsPort, resolveTarget, resolveOpsTarget, resolveEffectiveOpsUrl, resolveOpsUrlFromTarget, signRequestBody, b64, b64url, program, api, VALID_PRESENCE_ACTIVITIES, MAX_TASK_LENGTH, MAX_WORKSPACE_FIELD_LENGTH, MAX_ORGEVENT_SUMMARY_LENGTH, MAX_ORGEVENT_DETAIL_LENGTH, isLocalBase, isLikelyRealSecret, shouldShowInlineSecretWarning, parseTokenFromFile, };