@tpsdev-ai/flair 0.6.1 → 0.7.0

package/dist/cli.js

@@ -1,13 +1,16 @@
 #!/usr/bin/env node
 import { Command } from "commander";
 import nacl from "tweetnacl";
-import { existsSync, mkdirSync, writeFileSync, readFileSync, chmodSync, renameSync, } from "node:fs";
-import { homedir } from "node:os";
-import { join, resolve as resolvePath } from "node:path";
+import { load as parseYaml } from "js-yaml";
+import { existsSync, mkdirSync, writeFileSync, readFileSync, chmodSync, renameSync, cpSync, rmSync, mkdtempSync, readdirSync, } from "node:fs";
+import { homedir, hostname, tmpdir } from "node:os";
+import { join, resolve, sep } from "node:path";
 import { spawn } from "node:child_process";
-import { createPrivateKey, sign as nodeCryptoSign, randomUUID } from "node:crypto";
+import { createPrivateKey, sign as nodeCryptoSign, randomUUID, randomBytes } from "node:crypto";
+import { create as tarCreate } 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";
 // 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).
@@ -30,6 +33,50 @@ function signBody(body, secretKey) {
     const sig = nacl.sign.detached(message, secretKey);
     return Buffer.from(sig).toString("base64url");
 }
+// ─── Secret detection helpers ────────────────────────
+/**
+ * Check if a value looks like a real secret/password/token.
+ * Triggers warning when:
+ *   - length >= 8
+ *   - contains only alphanumerics and URL-safe punctuation (._-)
+ *   - NOT a URL (doesn't contain ://)
+ */
+function isLikelyRealSecret(value) {
+    if (!value || value.length < 8)
+        return false;
+    if (value.includes("://"))
+        return false; // exclude URLs
+    // Match typical password/token format: alphanumerics + URL-safe punct
+    const pattern = /^[A-Za-z0-9._-]+$/;
+    return pattern.test(value);
+}
+/**
+ * Determine if we should show an inline-secret warning.
+ *
+ * @param optValue - The value from the command line option
+ * @param fromEnv - Whether the value came from an environment variable (true = no warning)
+ * @param secretFlagNames - Set of flag names that carry secrets
+ * @param flagName - The flag being checked
+ * @returns true if warning should be shown
+ */
+function shouldShowInlineSecretWarning(optValue, fromEnv, secretFlagNames, flagName) {
+    // Skip if no value provided
+    if (!optValue || optValue === "")
+        return false;
+    // Skip URLs (not secrets)
+    if (flagName === "--target" || flagName === "--url")
+        return false;
+    // Only warn for secret-bearing flags
+    if (!secretFlagNames.has(flagName))
+        return false;
+    // Skip if value came from env (not argv)
+    if (fromEnv)
+        return false;
+    // Check if value looks like a real secret
+    if (!isLikelyRealSecret(optValue))
+        return false;
+    return true;
+}
 // ─── Defaults ────────────────────────────────────────────────────────────────
 const DEFAULT_PORT = 19926;
 const DEFAULT_OPS_PORT = 19925;
@@ -103,6 +150,64 @@ function resolveOpsPort(opts) {
     // Default: httpPort - 1
     return resolveHttpPort(opts) - 1;
 }
+// ─── Target resolution (remote Flair instance) ─────────────────────────────────
+// --target <url> (or FLAIR_TARGET env) points all CLI operations at a remote
+// Flair instance instead of localhost. This enables bootstrapping and
+// managing Fabric-deployed Flair instances.
+function resolveTarget(opts) {
+    return opts.target || process.env.FLAIR_TARGET || undefined;
+}
+/** Resolve the ops API target URL from --ops-target flag or FLAIR_OPS_TARGET env.
+ *  Returns undefined if neither is set (caller should fall back to derivation or localhost).
+ */
+function resolveOpsTarget(opts) {
+    return opts.opsTarget || process.env.FLAIR_OPS_TARGET || undefined;
+}
+/** Derive the ops API URL from a Flair base URL.
+ *  Convention: ops port = HTTP port - 1.
+ *  If target has an explicit port, use port-1 (validated: must be 1-65535).
+ *  If no explicit port: https → 442 (443-1), http → 19925 (19926-1), bare host → https://<host>:19925.
+ *  Throws on unparseable URLs.
+ */
+/** Compute the effective ops API URL for remote commands.
+ *  - If --ops-target is set, use it directly (no derivation).
+ *  - Else if --target is set, derive ops URL via resolveOpsUrlFromTarget.
+ *  - Else return undefined (fall back to localhost resolution).
+ */
+function resolveEffectiveOpsUrl(opts) {
+    const opsTarget = resolveOpsTarget(opts);
+    if (opsTarget)
+        return opsTarget.replace(/\/$/, "");
+    const target = resolveTarget(opts);
+    if (target)
+        return resolveOpsUrlFromTarget(target);
+    return undefined;
+}
+function resolveOpsUrlFromTarget(targetUrl) {
+    // Normalise bare hosts: add https:// prefix so URL parser can handle them.
+    const normalised = targetUrl.includes("://") ? targetUrl : `https://${targetUrl}`;
+    const url = new URL(normalised);
+    const port = parseInt(url.port, 10);
+    if (!isNaN(port) && port > 0 && port <= 65535) {
+        const opsPort = port - 1;
+        if (opsPort < 1)
+            throw new Error(`Derived ops port ${opsPort} is out of range; target port must be > 1`);
+        url.port = String(opsPort);
+        return url.toString().replace(/\/$/, "");
+    }
+    // No valid explicit port — reject port 0 or out-of-range
+    if (url.port !== "" && url.port !== undefined) {
+        throw new Error(`Invalid target port: ${url.port} (must be 1-65535)`);
+    }
+    // No explicit port — infer from scheme
+    if (url.protocol === "https:") {
+        url.port = "442";
+    }
+    else {
+        url.port = String(DEFAULT_OPS_PORT);
+    }
+    return url.toString().replace(/\/$/, "");
+}
 function writeConfig(port) {
     const p = configPath();
     mkdirSync(join(homedir(), ".flair"), { recursive: true });
@@ -136,22 +241,40 @@ function b64(bytes) {
 function b64url(bytes) {
     return Buffer.from(bytes).toString("base64url");
 }
-async function api(method, path, body) {
+function isLocalBase(base) {
+    try {
+        const url = new URL(base);
+        return url.hostname === "127.0.0.1" || url.hostname === "localhost" || url.hostname === "::1";
+    }
+    catch {
+        return !base;
+    }
+}
+async function api(method, path, body, options) {
     // Resolve port: FLAIR_URL env > ~/.flair/config.yaml > default 9926
+    // When baseUrl is provided (--target), use it directly.
     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;
+    const base = options?.baseUrl ?? (process.env.FLAIR_URL || defaultUrl);
+    const isLocal = isLocalBase(base);
     // Auth resolution order:
     // 1. FLAIR_TOKEN env → Bearer token (backward compat)
-    // 2. FLAIR_AGENT_ID env + key file → Ed25519 signature (standard)
-    // 3. --agent flag extracted from body.agentId + key file → Ed25519 signature
-    // 4. No auth (will 401 on any authenticated endpoint)
+    // 2. FLAIR_ADMIN_PASS / HDB_ADMIN_PASSWORD env → Basic admin auth (remote targets only).
+    //    For local targets with authorizeLocal=true, skip Basic auth and let Harper handle it.
+    // 3. FLAIR_AGENT_ID env + key file → Ed25519 signature (standard)
+    // 4. No auth (Harper authorizeLocal handles local; remote will 401)
+    //
+    // NOTE: this function is for the Harper HTTP/REST API only. The Harper
+    // operations API (used by seedAgentViaOpsApi / seedFederationInstanceViaOpsApi)
+    // does NOT honor authorizeLocal — it always requires Basic admin auth, and
+    // those helpers send it unconditionally. authorizeLocal=true affects this
+    // path; it does not affect ops-API calls.
     let authHeader;
     const token = process.env.FLAIR_TOKEN;
     if (token) {
         authHeader = `Bearer ${token}`;
     }
-    else if (process.env.FLAIR_ADMIN_PASS || process.env.HDB_ADMIN_PASSWORD) {
+    else if (!isLocal && (process.env.FLAIR_ADMIN_PASS || process.env.HDB_ADMIN_PASSWORD)) {
         // Admin Basic auth — used by federation, backup, and other admin CLI commands
         const adminPass = process.env.FLAIR_ADMIN_PASS ?? process.env.HDB_ADMIN_PASSWORD;
         authHeader = `Basic ${Buffer.from(`admin:${adminPass}`).toString("base64")}`;
@@ -174,7 +297,8 @@ async function api(method, path, body) {
                 }
                 catch (err) {
                     // Key exists but auth build failed — warn and continue without auth
-                    console.error(`Warning: Ed25519 auth failed for agent '${agentId}': ${err.message}`);
+                    const message = err instanceof Error ? err.message : String(err);
+                    console.error(`Warning: Ed25519 auth failed for agent '${agentId}': ${message}`);
                 }
             }
         }
@@ -303,9 +427,22 @@ function readHarperPid(dataDir) {
         return null;
     }
 }
-async function seedAgentViaOpsApi(opsPort, agentId, pubKeyB64url, adminUser, adminPass) {
-    const url = `http://127.0.0.1:${opsPort}/`;
-    const auth = Buffer.from(`${adminUser}:${adminPass}`).toString("base64");
+/**
+ * Seed an agent record via the Harper operations API.
+ * Accepts either a port number (localhost) or a full URL string (--target).
+ *
+ * `adminPass` is typed as optional but in practice the Harper operations API
+ * always requires Basic admin auth — every existing call site passes one.
+ * The optional signature leaves headroom for a future Harper that honors
+ * `authorizeLocal` on its ops endpoint; until then, callers must pass it.
+ */
+export async function seedAgentViaOpsApi(opsPortOrUrl, agentId, pubKeyB64url, adminUser, adminPass) {
+    const url = typeof opsPortOrUrl === "number"
+        ? `http://127.0.0.1:${opsPortOrUrl}/`
+        : `${opsPortOrUrl.replace(/\/$/, "")}/`;
+    // 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;
     const body = {
         operation: "insert",
         database: "flair",
@@ -314,8 +451,9 @@ async function seedAgentViaOpsApi(opsPort, agentId, pubKeyB64url, adminUser, adm
     };
     const res = await fetch(url, {
         method: "POST",
-        headers: { "Content-Type": "application/json", Authorization: `Basic ${auth}` },
+        headers: { "Content-Type": "application/json", ...(auth ? { Authorization: `Basic ${auth}` } : {}) },
         body: JSON.stringify(body),
+        signal: AbortSignal.timeout(10_000),
     });
     if (!res.ok) {
         const text = await res.text().catch(() => "");
@@ -324,6 +462,225 @@ async function seedAgentViaOpsApi(opsPort, agentId, pubKeyB64url, adminUser, adm
         throw new Error(`Operations API insert failed (${res.status}): ${text}`);
     }
 }
+// Seed an agent record via the Harper REST API.
+// Uses localhost and the given HTTP port.
+export async function seedAgentViaRestApi(httpPort, agentId, pubKeyB64url, adminPass) {
+    const baseUrl = `http://127.0.0.1:${httpPort}`;
+    const body = {
+        operation: "insert",
+        database: "flair",
+        table: "Agent",
+        records: [{ id: agentId, name: agentId, publicKey: pubKeyB64url, createdAt: new Date().toISOString() }],
+    };
+    // Only send Authorization header if adminPass is provided.
+    // Matches the auth pattern in api() which respects authorizeLocal=true.
+    const headers = { "Content-Type": "application/json" };
+    if (adminPass) {
+        headers.Authorization = `Basic ${Buffer.from(`admin:${adminPass}`).toString("base64")}`;
+    }
+    const res = await fetch(`${baseUrl}/Agent`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        if (res.status === 409 || text.includes("duplicate") || text.includes("already exists"))
+            return;
+        throw new Error(`REST API insert failed (${res.status}): ${text}`);
+    }
+}
+// ─── FederationInstance seed via ops API ──────────────────────────────────────
+//
+// Remote init writes FederationInstance through the ops API (Basic auth with
+// admin:admin-pass), not the REST API (which needs server-side HDB_ADMIN_PASSWORD
+// — unavailable on Fabric).  Same pattern as seedAgentViaOpsApi above.
+//
+// `adminPass` is optional in the signature for symmetry with seedAgentViaOpsApi
+// and to keep the door open for a future Harper that honors authorizeLocal on
+// its ops endpoint. Today the Harper operations API always requires Basic admin
+// auth; every current caller passes it.
+export async function seedFederationInstanceViaOpsApi(opsPortOrUrl, instanceId, publicKey, role, adminUser, adminPass) {
+    const url = typeof opsPortOrUrl === "number"
+        ? `http://127.0.0.1:${opsPortOrUrl}/`
+        : `${opsPortOrUrl.replace(/\/$/, "")}/`;
+    // 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;
+    const now = new Date().toISOString();
+    const body = {
+        operation: "insert",
+        database: "flair",
+        table: "Instance",
+        records: [{
+                id: instanceId,
+                publicKey,
+                role,
+                status: "active",
+                createdAt: now,
+                updatedAt: now,
+            }],
+    };
+    const res = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...(auth ? { Authorization: `Basic ${auth}` } : {}) },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        if (res.status === 409 || text.includes("duplicate") || text.includes("already exists"))
+            return;
+        throw new Error(`Federation Instance insert via ops API failed (${res.status}): ${text}`);
+    }
+}
+// ─── Provision Flair on Harper Fabric (ops-2kyi) ───────────────────────────
+//
+// Atomic provisioning for a fresh Harper Fabric cluster: builds a deploy
+// tarball with .env baked in, deploys via ops API, waits for restart, and
+// creates the super_user admin account.
+export async function callOpsApi(opsUrl, body, user, pass) {
+    const url = `${opsUrl.replace(/\/$/, "")}/`;
+    const auth = Buffer.from(`${user}:${pass}`).toString("base64");
+    const res = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...(auth ? { Authorization: `Basic ${auth}` } : {}) },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(30_000),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(`Ops API call failed (${res.status}): ${text}`);
+    }
+    return res.json();
+}
+export async function buildDeployTarball(projectRoot, flairAdminPass) {
+    const tmpDir = mkdtempSync(join(tmpdir(), "flair-deploy-"));
+    try {
+        // Copy deployment files into temp directory
+        const entries = ["dist", "schemas", "config.yaml", "package.json", "LICENSE", "README.md", "SECURITY.md"];
+        if (existsSync(join(projectRoot, "ui")))
+            entries.push("ui");
+        for (const entry of entries) {
+            const src = join(projectRoot, entry);
+            const dst = join(tmpDir, entry);
+            if (existsSync(src)) {
+                cpSync(src, dst, { recursive: true });
+            }
+        }
+        // Write .env with 600 permissions
+        const envContent = [
+            `HDB_ADMIN_PASSWORD=${flairAdminPass}`,
+            `FLAIR_ADMIN_PASSWORD=${flairAdminPass}`,
+            "",
+        ].join("\n");
+        writeFileSync(join(tmpDir, ".env"), envContent, { mode: 0o600 });
+        // Build compressed tarball
+        const tarballPath = join(tmpDir, "deploy.tar.gz");
+        await tarCreate({ gzip: true, cwd: tmpDir, file: tarballPath, portable: true }, entries);
+        const buf = readFileSync(tarballPath);
+        return { tarballB64: buf.toString("base64") };
+    }
+    finally {
+        rmSync(tmpDir, { recursive: true, force: true });
+    }
+}
+export async function waitForFlairRestart(targetUrl, maxWaitMs = 30_000) {
+    const url = `${targetUrl.replace(/\/$/, "")}/FederationPair`;
+    const intervalMs = 1_000;
+    const deadline = Date.now() + maxWaitMs;
+    while (Date.now() < deadline) {
+        try {
+            const res = await fetch(url, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({}),
+                signal: AbortSignal.timeout(5_000),
+            });
+            const text = await res.text().catch(() => "");
+            // The resource handler responds with "instanceId and publicKey required"
+            // when the deployment is live and Flair is serving requests.
+            if (text.includes("instanceId and publicKey required"))
+                return;
+        }
+        catch {
+            // Not ready yet — keep polling
+        }
+        await new Promise((r) => setTimeout(r, intervalMs));
+    }
+    throw new Error(`Flair did not respond within ${maxWaitMs / 1000}s`);
+}
+export async function provisionFabric(target, opsTarget, clusterAdminUser, clusterAdminPass, flairAdminPass) {
+    const projectRoot = process.cwd();
+    // 1. Build and deploy component tarball
+    console.log("Building deploy tarball...");
+    const { tarballB64 } = await buildDeployTarball(projectRoot, flairAdminPass);
+    console.log("Deploying via ops API...");
+    await callOpsApi(opsTarget, {
+        operation: "deploy_component",
+        project: "flair",
+        payload: tarballB64,
+        restart: "rolling",
+    }, clusterAdminUser, clusterAdminPass);
+    // 2. Wait for restart
+    console.log("Waiting for Flair to restart...");
+    await waitForFlairRestart(target);
+    console.log("Flair is running ✓");
+    // 3. Provision Harper super_user
+    // Since ops-lzmg is merged, the username doesn't have to be "admin".
+    // We can use the cluster-admin user directly if it's already a super_user.
+    // Check if cluster admin is already a super_user first:
+    let clusterAdminIsSuperUser = false;
+    try {
+        const userInfo = await callOpsApi(opsTarget, {
+            operation: "list_users",
+        }, clusterAdminUser, clusterAdminPass);
+        // list_users returns an array of user objects with role/permission info
+        const users = Array.isArray(userInfo) ? userInfo : [];
+        const adminRecord = users.find((u) => u.username === clusterAdminUser || u.user?.username === clusterAdminUser);
+        clusterAdminIsSuperUser = !!(adminRecord?.role?.permission?.super_user ??
+            adminRecord?.permission?.super_user ??
+            false);
+    }
+    catch {
+        // If we can't check, assume not and proceed with add_user
+    }
+    if (clusterAdminIsSuperUser) {
+        console.log(`Cluster admin '${clusterAdminUser}' is already a super_user — skipping user provisioning`);
+    }
+    else {
+        console.log(`Provisioning Harper user 'admin' as super_user...`);
+        try {
+            await callOpsApi(opsTarget, {
+                operation: "add_user",
+                username: "admin",
+                password: flairAdminPass,
+                role: "super_user",
+                active: true,
+            }, clusterAdminUser, clusterAdminPass);
+            console.log("User 'admin' created ✓");
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (msg.includes("already exists") || msg.includes("duplicate")) {
+                // Idempotent: fall back to alter_user
+                console.log("User 'admin' already exists — updating password...");
+                await callOpsApi(opsTarget, {
+                    operation: "alter_user",
+                    username: "admin",
+                    password: flairAdminPass,
+                    role: "super_user",
+                    active: true,
+                }, clusterAdminUser, clusterAdminPass);
+                console.log("User 'admin' updated ✓");
+            }
+            else {
+                throw err;
+            }
+        }
+    }
+}
 // ─── Upgrade presence probes ──────────────────────────────────────────────────
 //
 // `flair upgrade` previously called `npm list -g <pkg>` to detect the installed
@@ -515,7 +872,8 @@ async function runSoulWizard(agentId) {
             }
         }
         catch (err) {
-            console.log(`\n   Couldn't parse JSON (${err.message}). Falling back to custom prompts.`);
+            const message = err instanceof Error ? err.message : String(err);
+            console.log(`\n   Couldn't parse JSON (${message}). Falling back to custom prompts.`);
             entries = await customSoulPrompts(ask);
         }
     }
@@ -542,24 +900,257 @@ program.name("flair").version(__pkgVersion, "-v, --version");
 // ─── flair init ──────────────────────────────────────────────────────────────
 program
     .command("init")
-    .description("Bootstrap a local Flair (Harper) instance for an agent")
-    .option("--agent-id <id>", "Agent ID to register", "local")
+    .description("Bootstrap a Flair (Harper) instance for an agent")
+    .option("--agent-id <id>", "Agent ID to register (omit to bootstrap instance without agent)")
     .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)")
+    .option("--admin-pass-file <path>", "Read admin password from file (chmod 600 recommended)")
     .option("--keys-dir <dir>", "Directory for Ed25519 keys")
     .option("--data-dir <dir>", "Harper data directory")
     .option("--skip-start", "Skip Harper startup (assume already running)")
     .option("--skip-soul", "Skip interactive personality setup")
+    .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)")
+    .option("--force", "Skip confirmation prompt for remote writes (required with --target)")
+    .option("--cluster-admin-user <user>", "Harper cluster admin username (env: FLAIR_CLUSTER_ADMIN_USER)")
+    .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 target = resolveTarget(opts);
+    const opsTarget = resolveOpsTarget(opts);
+    // ── Remote init: --target and/or --ops-target drive a remote Flair instance ──
+    if (target || opsTarget) {
+        // When -only- --ops-target is provided, attempt to derive REST URL
+        if (!target && opsTarget) {
+            console.error("Error: --ops-target requires --target as well. Pass --target <rest-url> for the REST API surface.");
+            console.error("  Currently only explicit --ops-target + --target combination is supported.");
+            process.exit(1);
+        }
+        const baseUrl = target.replace(/\/$/, "");
+        // --ops-target overrides derivation; otherwise derive from --target
+        const opsUrl = opsTarget ? opsTarget.replace(/\/$/, "") : resolveOpsUrlFromTarget(baseUrl);
+        // Check for cluster-admin provisioning (new atomic flow)
+        const clusterAdminUser = opts.clusterAdminUser || process.env.FLAIR_CLUSTER_ADMIN_USER;
+        const clusterAdminPass = opts.clusterAdminPass || process.env.FLAIR_CLUSTER_ADMIN_PASS;
+        let flairAdminPass = opts.flairAdminPass || process.env.FLAIR_ADMIN_PASS;
+        let didProvision = false;
+        if (clusterAdminUser && clusterAdminPass) {
+            // ── New provisioning path: deploy Flair to Fabric, wait, provision super_user ──
+            if (!opts.force) {
+                console.error("Error: --force is required with --target/--ops-target (remote init provisions a live Fabric instance)");
+                console.error("  Pass --force to confirm this is intended.");
+                process.exit(1);
+            }
+            // Generate flair admin pass if not provided
+            if (!flairAdminPass) {
+                flairAdminPass = randomBytes(24).toString("base64url");
+            }
+            // Write the flair admin pass to secrets directory
+            const secretsDir = join(homedir(), ".tps", "secrets");
+            mkdirSync(secretsDir, { recursive: true });
+            const secretPath = join(secretsDir, "flair-fabric-hdb");
+            writeFileSync(secretPath, flairAdminPass + "\n", { mode: 0o600 });
+            console.log(`Admin password written to ${secretPath}`);
+            // Atomic provisioning: deploy + wait + provision user
+            await provisionFabric(baseUrl, opsUrl, clusterAdminUser, clusterAdminPass, flairAdminPass);
+            didProvision = true;
+        }
+        else {
+            // ── Existing behavior: --admin-pass required for already-running Flair ──
+            if (!opts.adminPass) {
+                console.error("Error: --admin-pass is required with --target/--ops-target (remote init without --cluster-admin-user/--cluster-admin-pass)");
+                console.error("  Use --cluster-admin-user and --cluster-admin-pass for automated Fabric provisioning.");
+                process.exit(1);
+            }
+            if (!opts.force) {
+                const displayTarget = target || opsTarget;
+                console.error(`Error: --force is required with --target/--ops-target. Remote init writes to a live Flair instance at ${displayTarget}.`);
+                console.error("  Pass --force to confirm this is intended.");
+                process.exit(1);
+            }
+            flairAdminPass = opts.adminPass;
+        }
+        const adminUser = DEFAULT_ADMIN_USER;
+        const auth = `Basic ${Buffer.from(`${adminUser}:${flairAdminPass}`).toString("base64")}`;
+        const role = opts.remote ? "hub" : undefined;
+        // Generate or reuse keypair (only if --agent-id provided, or --remote needs
+        // a public key for the FederationInstance row)
+        let pubKeyB64url;
+        let privPath;
+        let instanceId;
+        if (agentId || role) {
+            const keysDir = opts.keysDir ?? defaultKeysDir();
+            mkdirSync(keysDir, { recursive: true });
+            if (agentId) {
+                privPath = privKeyPath(agentId, keysDir);
+                const pubPath = pubKeyPath(agentId, keysDir);
+                if (existsSync(privPath)) {
+                    console.log(`Reusing existing key: ${privPath}`);
+                    const seed = new Uint8Array(readFileSync(privPath));
+                    const kp = nacl.sign.keyPair.fromSeed(seed);
+                    pubKeyB64url = b64url(kp.publicKey);
+                }
+                else {
+                    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));
+                    pubKeyB64url = b64url(kp.publicKey);
+                    console.log(`Keypair written: ${privPath} ✓`);
+                }
+                // Seed agent via remote ops API
+                console.log(`Seeding agent '${agentId}' on ${baseUrl}...`);
+                await seedAgentViaOpsApi(opsUrl, agentId, pubKeyB64url, adminUser, flairAdminPass);
+                console.log(`Agent '${agentId}' registered on remote instance ✓`);
+            }
+            else {
+                // No agentId -- generate throwaway keypair for FederationInstance row
+                console.log("Generating federation instance keypair...");
+                const kp = nacl.sign.keyPair();
+                pubKeyB64url = b64url(kp.publicKey);
+            }
+        }
+        else {
+            console.log("No --agent-id provided -- skipping agent registration");
+        }
+        // Write FederationInstance row if --remote (hub role)
+        if (role) {
+            if (!pubKeyB64url) {
+                const kp = nacl.sign.keyPair();
+                pubKeyB64url = b64url(kp.publicKey);
+            }
+            instanceId = randomUUID();
+            console.log(`Writing federation Instance (role=${role}) via ops API...`);
+            await seedFederationInstanceViaOpsApi(opsUrl, instanceId, pubKeyB64url, role, adminUser, flairAdminPass);
+            console.log(`Federation Instance created: ${instanceId} (${role}) ✓`);
+        }
+        // Verify connectivity
+        if (didProvision) {
+            // Use /FederationInstance with Basic auth (not /Health which false-401s on Fabric)
+            console.log("Verifying remote connectivity...");
+            const verifyRes = await fetch(`${baseUrl}/FederationInstance`, {
+                headers: { Authorization: auth },
+                signal: AbortSignal.timeout(5000),
+            });
+            if (!verifyRes.ok) {
+                const body = await verifyRes.text().catch(() => "");
+                console.error(`Remote verification failed (${verifyRes.status}): ${body}`);
+                process.exit(1);
+            }
+            console.log("✓ Hub ready at " + baseUrl);
+        }
+        else {
+            // Existing behavior: /Health check (already-running Flair)
+            console.log("Verifying remote connectivity...");
+            const verifyRes = await fetch(`${baseUrl}/Health`, { signal: AbortSignal.timeout(5000) });
+            if (!verifyRes.ok) {
+                console.error(`Remote health check failed: ${verifyRes.status}`);
+                process.exit(1);
+            }
+            console.log("Remote Flair instance healthy ✓");
+        }
+        // Print summary
+        if (didProvision) {
+            const pkg = JSON.parse(readFileSync(join(process.cwd(), "package.json"), "utf-8"));
+            const flavor = pkg.version || "(unknown)";
+            const displayTarget = target || opsTarget;
+            console.log(`\n✓ Flair hub deployed to ${displayTarget}`);
+            console.log(`  Component: flair@${flavor}`);
+            console.log(`  Admin user: ${adminUser} (pass written to ${join(homedir(), ".tps", "secrets", "flair-fabric-hdb")})`);
+            if (instanceId)
+                console.log(`  Instance: ${instanceId} (role=${role})`);
+            console.log(`  Federation: ready — run \`flair federation token\` to mint a pairing token`);
+        }
+        else {
+            console.log(`\n✅ Remote Flair initialized`);
+            if (agentId)
+                console.log(`   Agent ID:    ${agentId}`);
+            console.log(`   Target:      ${baseUrl}`);
+            if (agentId)
+                console.log(`   Private key: ${privPath}`);
+            if (role)
+                console.log(`   Role:         ${role}`);
+            console.log(`\n   Export: FLAIR_URL=${baseUrl}`);
+        }
+        return;
+    }
+    // ── Local init (original behavior) ──
     const httpPort = resolveHttpPort(opts);
     const opsPort = resolveOpsPort(opts);
     const keysDir = opts.keysDir ?? defaultKeysDir();
     const dataDir = opts.dataDir ?? defaultDataDir();
-    // Admin password: generate if not provided, NEVER written to disk
-    const adminPass = opts.adminPass ?? Buffer.from(nacl.randomBytes(18)).toString("base64url");
+    // Admin password: determine from opts, env, or generate
+    // Priority: 1) --admin-pass-file, 2) env vars, 3) generate new
+    let adminPass;
+    let passwordSource = "generated";
+    // Warn if --admin-pass is passed inline (not from env)
+    if (shouldShowInlineSecretWarning(opts.adminPass, false, new Set(["--admin-pass"]), "--admin-pass")) {
+        console.error("warning: --admin-pass passed inline. Consider --admin-pass-file <path> or FLAIR_ADMIN_PASS env " +
+            "to keep secrets out of shell history.");
+    }
+    // Read from file if provided
+    if (opts.adminPassFile) {
+        if (!existsSync(opts.adminPassFile)) {
+            console.error(`Error: --admin-pass-file path does not exist: ${opts.adminPassFile}`);
+            process.exit(1);
+        }
+        const fileContent = readFileSync(opts.adminPassFile, "utf-8");
+        adminPass = fileContent.trim();
+        if (!adminPass) {
+            console.error(`Error: admin password file is empty or contains only whitespace: ${opts.adminPassFile}`);
+            process.exit(1);
+        }
+        passwordSource = "file";
+    }
+    else if (process.env.FLAIR_ADMIN_PASS) {
+        adminPass = process.env.FLAIR_ADMIN_PASS;
+        passwordSource = "env";
+    }
+    else if (process.env.HDB_ADMIN_PASSWORD) {
+        adminPass = process.env.HDB_ADMIN_PASSWORD;
+        passwordSource = "env";
+    }
+    else if (opts.adminPass) {
+        // Inline admin pass (deprecated)
+        adminPass = opts.adminPass;
+        // Don't generate - don't write to file
+        passwordSource = "env"; // Treat same as env for display purposes
+    }
+    else {
+        // Generate new password and write to file atomically
+        adminPass = Buffer.from(nacl.randomBytes(18)).toString("base64url");
+        passwordSource = "generated";
+        // 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;
+        }
+    }
     const adminUser = DEFAULT_ADMIN_USER;
+    // If we generated the password, report where it was saved
+    if (passwordSource === "generated") {
+        const adminPassPath = join(homedir(), ".flair", "admin-pass");
+        console.log(`Admin password saved to: ${adminPassPath}`);
+    }
     // Check Node.js version
     const major = parseInt(process.version.slice(1), 10);
     if (major < 18)
@@ -719,125 +1310,490 @@ program
     }
     // 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);
-    const pubPath = pubKeyPath(agentId, keysDir);
-    let pubKeyB64url;
-    if (existsSync(privPath)) {
-        console.log(`Reusing existing key: ${privPath}`);
-        const seed = new Uint8Array(readFileSync(privPath));
-        const kp = nacl.sign.keyPair.fromSeed(seed);
-        pubKeyB64url = b64url(kp.publicKey);
+    if (agentId) {
+        // Generate or reuse keypair
+        mkdirSync(keysDir, { recursive: true });
+        const privPath = privKeyPath(agentId, keysDir);
+        const pubPath = pubKeyPath(agentId, keysDir);
+        let pubKeyB64url;
+        if (existsSync(privPath)) {
+            console.log(`Reusing existing key: ${privPath}`);
+            const seed = new Uint8Array(readFileSync(privPath));
+            const kp = nacl.sign.keyPair.fromSeed(seed);
+            pubKeyB64url = b64url(kp.publicKey);
+        }
+        else {
+            console.log("Generating Ed25519 keypair...");
+            const kp = nacl.sign.keyPair();
+            // Store only the 32-byte seed (first 32 bytes of secretKey)
+            const seed = kp.secretKey.slice(0, 32);
+            writeFileSync(privPath, Buffer.from(seed));
+            chmodSync(privPath, 0o600);
+            writeFileSync(pubPath, Buffer.from(kp.publicKey));
+            pubKeyB64url = b64url(kp.publicKey);
+            console.log(`Keypair written: ${privPath} ✓`);
+        }
+        // Seed agent via operations API
+        console.log(`Seeding agent '${agentId}' via operations API...`);
+        await seedAgentViaOpsApi(opsPort, agentId, pubKeyB64url, adminUser, adminPass);
+        console.log(`Agent '${agentId}' registered ✓`);
+        // Verify Ed25519 auth
+        console.log("Verifying Ed25519 auth...");
+        const httpUrl = `http://127.0.0.1:${httpPort}`;
+        const verifyRes = await authFetch(httpUrl, agentId, privPath, "GET", `/Agent/${agentId}`);
+        if (!verifyRes.ok)
+            throw new Error(`Ed25519 auth verification failed: ${verifyRes.status}`);
+        console.log("Ed25519 auth verified ✓");
+        // Output — admin password printed once, never written to disk
+        console.log("\n✅ Flair initialized successfully");
+        console.log(`   Agent ID:    ${agentId}`);
+        console.log(`   Flair URL:   ${httpUrl}`);
+        console.log(`   Private key: ${privPath}`);
+        // Display admin credentials when password was generated or from a file
+        // Do NOT display when from env (to avoid showing the env var value)
+        if (passwordSource !== "env" && !alreadyRunning) {
+            const passDisplay = passwordSource === "file"
+                ? opts.adminPassFile ?? "(file path)"
+                : "~/.flair/admin-pass";
+            console.log(`\n   ┌─────────────────────────────────────────────────┐`);
+            console.log(`   │  Harper admin credentials (save these now):     │`);
+            console.log(`   │                                                 │`);
+            console.log(`   │  Username: ${DEFAULT_ADMIN_USER.padEnd(37)}│`);
+            console.log(`   │  Password: ${passDisplay.padEnd(37)}│`);
+            console.log(`   │                                                 │`);
+            console.log(`   │  ⚠️  The password won't be shown again.         │`);
+            console.log(`   └─────────────────────────────────────────────────┘`);
+        }
+        console.log(`\n   Export: FLAIR_URL=${httpUrl}`);
+        // ── First-run soul setup ──────────────────────────────────────────────
+        // Interactive wizard to set initial personality (see runSoulWizard).
+        // Skipped with --skip-soul or when stdin is not a TTY (CI, scripts, pipe).
+        //
+        // Non-TTY / --skip-soul used to seed placeholder text like
+        // "AI assistant [default]" — it leaked into bootstrap output and
+        // confused users. Now those paths leave the soul empty and nudge the
+        // user toward `flair soul set` / `flair doctor` instead.
+        if (!opts.skipSoul && process.stdin.isTTY) {
+            const soulEntries = await runSoulWizard(agentId);
+            if (soulEntries.length > 0) {
+                console.log("");
+                for (const [key, value] of soulEntries) {
+                    try {
+                        await authFetch(httpUrl, agentId, privPath, "PUT", `/Soul/${agentId}:${key}`, { id: `${agentId}:${key}`, agentId, key, value, createdAt: new Date().toISOString() });
+                        console.log(`   ✓ soul:${key} set`);
+                    }
+                    catch (err) {
+                        const message = err instanceof Error ? err.message : String(err);
+                        console.warn(`   ⚠ soul:${key} failed: ${message}`);
+                    }
+                }
+                console.log(`\n   ${soulEntries.length} soul entries saved.`);
+                console.log(`   Preview what an agent will see: flair bootstrap --agent ${agentId}`);
+            }
+            else {
+                console.log(`\n   No soul entries saved. Add later with:`);
+                console.log(`     flair soul set --agent ${agentId} --key role --value "..."`);
+                console.log(`   Or run \`flair doctor\` anytime for a nudge.`);
+            }
+        }
+        else {
+            const reason = opts.skipSoul ? "--skip-soul" : "non-interactive";
+            console.log(`\n   Soul prompts skipped (${reason}). Add entries with:`);
+            console.log(`     flair soul set --agent ${agentId} --key role --value "..."`);
+        }
+        console.log(`\n   Claude Code: Add to your CLAUDE.md:`);
+        console.log(`     At the start of every session, run mcp__flair__bootstrap before responding.`);
+        // Auto-wire MCP config into ~/.claude.json if Claude Code is installed
+        const claudeJsonPath = join(homedir(), ".claude.json");
+        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 ✓`);
+                }
+                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.`);
+                }
+            }
+            else {
+                console.log(`\n   MCP config (add to ~/.claude.json):`);
+                console.log(`     { "mcpServers": { "flair": ${JSON.stringify(flairMcpConfig)} } }`);
+            }
+        }
+        catch {
+            console.log(`\n   MCP config (add manually to ~/.claude.json):`);
+            console.log(`     { "mcpServers": { "flair": ${JSON.stringify(flairMcpConfig)} } }`);
+        }
+    }
+    else {
+        const httpUrl = `http://127.0.0.1:${httpPort}`;
+        console.log("\n✅ Flair initialized (no agent registered)");
+        console.log(`   Flair URL:   ${httpUrl}`);
+        // Display admin credentials when password was generated or from a file
+        // Do NOT display when from env (to avoid showing the env var value)
+        if (passwordSource !== "env" && !alreadyRunning) {
+            const passDisplay = passwordSource === "file"
+                ? opts.adminPassFile ?? "(file path)"
+                : "~/.flair/admin-pass";
+            console.log(`\n   ┌─────────────────────────────────────────────────┐`);
+            console.log(`   │  Harper admin credentials (save these now):     │`);
+            console.log(`   │                                                 │`);
+            console.log(`   │  Username: ${DEFAULT_ADMIN_USER.padEnd(37)}│`);
+            console.log(`   │  Password: ${passDisplay.padEnd(37)}│`);
+            console.log(`   │                                                 │`);
+            console.log(`   │  ⚠️  The password won't be shown again.         │`);
+            console.log(`   └─────────────────────────────────────────────────┘`);
+        }
+        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 or running instance
+        adminPass = process.env.FLAIR_ADMIN_PASS ?? process.env.HDB_ADMIN_PASSWORD ?? "";
+    }
+    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
+            clients = [{ id: selectedClients[0], label: selectedClients[0], detected: true }];
+        }
+    }
+    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();
-        // Store only the 32-byte seed (first 32 bytes of secretKey)
         const seed = kp.secretKey.slice(0, 32);
         writeFileSync(privPath, Buffer.from(seed));
         chmodSync(privPath, 0o600);
         writeFileSync(pubPath, Buffer.from(kp.publicKey));
-        pubKeyB64url = b64url(kp.publicKey);
+        const pubKeyB64url = b64url(kp.publicKey);
         console.log(`Keypair written: ${privPath} ✓`);
-    }
-    // Seed agent via operations API
-    console.log(`Seeding agent '${agentId}' via operations API...`);
-    await seedAgentViaOpsApi(opsPort, agentId, pubKeyB64url, adminUser, adminPass);
-    console.log(`Agent '${agentId}' registered ✓`);
-    // Verify Ed25519 auth
-    console.log("Verifying Ed25519 auth...");
-    const httpUrl = `http://127.0.0.1:${httpPort}`;
-    const verifyRes = await authFetch(httpUrl, agentId, privPath, "GET", `/Agent/${agentId}`);
-    if (!verifyRes.ok)
-        throw new Error(`Ed25519 auth verification failed: ${verifyRes.status}`);
-    console.log("Ed25519 auth verified ✓");
-    // Output — admin password printed once, never written to disk
-    console.log("\n✅ Flair initialized successfully");
-    console.log(`   Agent ID:    ${agentId}`);
-    console.log(`   Flair URL:   ${httpUrl}`);
-    console.log(`   Private key: ${privPath}`);
-    if (!opts.adminPass && !alreadyRunning) {
-        console.log(`\n   ┌─────────────────────────────────────────────────┐`);
-        console.log(`   │  Harper admin credentials (save these now):     │`);
-        console.log(`   │                                                 │`);
-        console.log(`   │  Username: ${DEFAULT_ADMIN_USER.padEnd(37)}│`);
-        console.log(`   │  Password: ${adminPass.padEnd(37)}│`);
-        console.log(`   │                                                 │`);
-        console.log(`   │  ⚠️  The password won't be shown again.         │`);
-        console.log(`   └─────────────────────────────────────────────────┘`);
-    }
-    console.log(`\n   Export: FLAIR_URL=${httpUrl}`);
-    // ── First-run soul setup ──────────────────────────────────────────────
-    // Interactive wizard to set initial personality (see runSoulWizard).
-    // Skipped with --skip-soul or when stdin is not a TTY (CI, scripts, pipe).
-    //
-    // Non-TTY / --skip-soul used to seed placeholder text like
-    // "AI assistant [default]" — it leaked into bootstrap output and
-    // confused users. Now those paths leave the soul empty and nudge the
-    // user toward `flair soul set` / `flair doctor` instead.
-    if (!opts.skipSoul && process.stdin.isTTY) {
-        const soulEntries = await runSoulWizard(agentId);
-        if (soulEntries.length > 0) {
-            console.log("");
-            for (const [key, value] of soulEntries) {
-                try {
-                    await authFetch(httpUrl, agentId, privPath, "PUT", `/Soul/${agentId}:${key}`, { id: `${agentId}:${key}`, agentId, key, value, createdAt: new Date().toISOString() });
-                    console.log(`   ✓ soul:${key} set`);
-                }
-                catch (err) {
-                    console.warn(`   ⚠ soul:${key} failed: ${err.message}`);
-                }
-            }
-            console.log(`\n   ${soulEntries.length} soul entries saved.`);
-            console.log(`   Preview what an agent will see: flair bootstrap --agent ${agentId}`);
+        // Seed agent - use REST API for local Harper, Ops API only when --ops-target is specified
+        if (opts.opsTarget) {
+            // Remote Harper via explicit ops target
+            console.log(`Seeding agent '${agentId}' via operations API (--ops-target)...`);
+            await seedAgentViaOpsApi(opts.opsTarget, agentId, pubKeyB64url, adminUser, adminPass);
         }
         else {
-            console.log(`\n   No soul entries saved. Add later with:`);
-            console.log(`     flair soul set --agent ${agentId} --key role --value "..."`);
-            console.log(`   Or run \`flair doctor\` anytime for a nudge.`);
+            // Local Harper - use REST API
+            console.log(`Seeding agent '${agentId}' via REST API...`);
+            await seedAgentViaRestApi(httpPort, agentId, pubKeyB64url, adminPass);
         }
+        console.log(`Agent '${agentId}' registered ✓`);
     }
-    else {
-        const reason = opts.skipSoul ? "--skip-soul" : "non-interactive";
-        console.log(`\n   Soul prompts skipped (${reason}). Add entries with:`);
-        console.log(`     flair soul set --agent ${agentId} --key role --value "..."`);
-    }
-    console.log(`\n   Claude Code: Add to your CLAUDE.md:`);
-    console.log(`     At the start of every session, run mcp__flair__bootstrap before responding.`);
-    // Auto-wire MCP config into ~/.claude.json if Claude Code is installed
-    const claudeJsonPath = join(homedir(), ".claude.json");
+    // ── Step 4: Wire MCP clients ──
     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") {
+        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, httpUrl);
+                    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}` };
             }
-            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.`);
+            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");
             }
         }
-        else {
-            console.log(`\n   MCP config (add to ~/.claude.json):`);
-            console.log(`     { "mcpServers": { "flair": ${JSON.stringify(flairMcpConfig)} } }`);
+        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.");
         }
     }
-    catch {
-        console.log(`\n   MCP config (add manually to ~/.claude.json):`);
-        console.log(`     { "mcpServers": { "flair": ${JSON.stringify(flairMcpConfig)} } }`);
+    // ── 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?"`);
 });
 // ─── flair agent ─────────────────────────────────────────────────────────────
 const agent = program.command("agent").description("Manage Flair agents");
@@ -891,7 +1847,13 @@ agent
     .option("--port <port>", "Harper HTTP port")
     .action(async (opts) => {
     const port = resolveHttpPort(opts);
-    const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
+    // fromEnv is true ONLY when the resolved value came from env (no inline override).
+    const adminPassFromEnv = !opts.adminPass && (!!process.env.FLAIR_ADMIN_PASS || !!process.env.HDB_ADMIN_PASSWORD);
+    if (shouldShowInlineSecretWarning(opts.adminPass, adminPassFromEnv, new Set(["--admin-pass"]), "--admin-pass")) {
+        console.error("warning: --admin-pass passed inline. Consider --admin-pass-from <file> or FLAIR_ADMIN_PASS env " +
+            "to keep secrets out of shell history.");
+    }
+    const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? process.env.HDB_ADMIN_PASSWORD ?? "";
     if (adminPass) {
         // Use admin basic auth against ops API to list agents directly
         const opsPort = resolveOpsPort(opts);
@@ -899,18 +1861,37 @@ agent
         const res = await fetch(`http://127.0.0.1:${opsPort}/`, {
             method: "POST",
             headers: { "Content-Type": "application/json", Authorization: `Basic ${auth}` },
-            body: JSON.stringify({ operation: "sql", sql: "SELECT id, name, createdAt FROM flair.Agent ORDER BY createdAt" }),
+            body: JSON.stringify({ operation: "search_by_value", schema: "flair", table: "Agent", search_attribute: "id", search_type: "starts_with", search_value: "", get_attributes: ["id", "name", "createdAt"] }),
         });
         if (!res.ok) {
             const text = await res.text().catch(() => "");
             console.error(`Error: ${res.status} ${text}`);
             process.exit(1);
         }
-        console.log(JSON.stringify(await res.json(), null, 2));
+        const agents = await res.json();
+        agents.sort((a, b) => (a.createdAt ?? "").localeCompare(b.createdAt ?? ""));
+        console.log(JSON.stringify(agents, null, 2));
     }
     else {
-        // Try agent-authed API (requires FLAIR_AGENT_ID to be set)
-        console.log(JSON.stringify(await api("GET", "/Agent"), null, 2));
+        // Localhost operator path: allow IDs-only enumeration without per-agent auth
+        // This treats localhost as a trusted boundary for read-only public metadata
+        const baseUrl = `http://127.0.0.1:${port}`;
+        const res = await fetch(`${baseUrl}/Agent`, {
+            headers: { "Content-Type": "application/json" },
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            console.error(`Error: ${res.status} ${text}`);
+            process.exit(1);
+        }
+        const data = await res.json();
+        // Filter to IDs-only to respect the localhost trust boundary
+        if (Array.isArray(data)) {
+            console.log(JSON.stringify(data.map((a) => ({ id: a.id, name: a.name, createdAt: a.createdAt })), null, 2));
+        }
+        else {
+            console.log(JSON.stringify(data, null, 2));
+        }
     }
 });
 agent
@@ -927,6 +1908,12 @@ agent
     .action(async (id, opts) => {
     const httpPort = resolveHttpPort(opts);
     const opsPort = resolveOpsPort(opts);
+    // fromEnv is true ONLY when the resolved value came from env (no inline override).
+    const adminPassFromEnv = !opts.adminPass && !!process.env.FLAIR_ADMIN_PASS;
+    if (shouldShowInlineSecretWarning(opts.adminPass, adminPassFromEnv, new Set(["--admin-pass"]), "--admin-pass")) {
+        console.error("warning: --admin-pass passed inline. Consider --admin-pass-from <file> or FLAIR_ADMIN_PASS env " +
+            "to keep secrets out of shell history.");
+    }
     const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
     const adminUser = DEFAULT_ADMIN_USER;
     const keysDir = opts.keysDir ?? defaultKeysDir();
@@ -1204,14 +2191,20 @@ principal
         console.error("Error: --admin-pass or FLAIR_ADMIN_PASS required");
         process.exit(1);
     }
-    const kindFilter = opts.kind ? ` WHERE kind = '${opts.kind}'` : "";
     const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
+    const conditions = opts.kind
+        ? [{ search_attribute: "kind", search_type: "equals", search_value: opts.kind }]
+        : [{ search_attribute: "id", search_type: "starts_with", search_value: "" }];
     const res = await fetch(`http://127.0.0.1:${opsPort}/`, {
         method: "POST",
         headers: { "Content-Type": "application/json", Authorization: auth },
         body: JSON.stringify({
-            operation: "sql",
-            sql: `SELECT id, name, kind, status, defaultTrustTier, admin, runtime, createdAt FROM flair.Agent${kindFilter} ORDER BY createdAt`,
+            operation: "search_by_conditions",
+            schema: "flair",
+            table: "Agent",
+            operator: "and",
+            conditions,
+            get_attributes: ["id", "name", "kind", "status", "defaultTrustTier", "admin", "runtime", "createdAt"],
         }),
     });
     if (!res.ok) {
@@ -1220,6 +2213,7 @@ principal
         process.exit(1);
     }
     const records = await res.json();
+    records.sort((a, b) => (a.createdAt ?? "").localeCompare(b.createdAt ?? ""));
     if (records.length === 0) {
         console.log("No principals found.");
         return;
@@ -1382,8 +2376,13 @@ idp
         method: "POST",
         headers: { "Content-Type": "application/json", Authorization: auth },
         body: JSON.stringify({
-            operation: "sql",
-            sql: "SELECT id, name, issuer, requiredDomain, jitProvision, enabled, createdAt FROM flair.IdpConfig ORDER BY createdAt",
+            operation: "search_by_value",
+            schema: "flair",
+            table: "IdpConfig",
+            search_attribute: "id",
+            search_type: "starts_with",
+            search_value: "",
+            get_attributes: ["id", "name", "issuer", "requiredDomain", "jitProvision", "enabled", "createdAt"],
         }),
     });
     if (!res.ok) {
@@ -1392,6 +2391,7 @@ idp
         process.exit(1);
     }
     const records = await res.json();
+    records.sort((a, b) => (a.createdAt ?? "").localeCompare(b.createdAt ?? ""));
     if (records.length === 0) {
         console.log("No IdPs configured.");
         return;
@@ -1443,18 +2443,14 @@ idp
         console.error("Error: --admin-pass or FLAIR_ADMIN_PASS required");
         process.exit(1);
     }
-    const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
-    const res = await fetch(`http://127.0.0.1:${opsPort}/`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json", Authorization: auth },
-        body: JSON.stringify({ operation: "sql", sql: `SELECT * FROM flair.IdpConfig WHERE id = '${id}'` }),
-    });
-    const records = await res.json();
-    if (records.length === 0) {
+    let cfg;
+    try {
+        cfg = await api("GET", `/IdpConfig/${id}`);
+    }
+    catch {
         console.error(`IdP '${id}' not found`);
         process.exit(1);
     }
-    const cfg = records[0];
     console.log(`Testing IdP: ${cfg.name} (${cfg.issuer})`);
     console.log(`  JWKS endpoint: ${cfg.jwksUri}`);
     try {
@@ -1468,7 +2464,8 @@ idp
         console.log(`  ✅ JWKS reachable — ${keyCount} key(s) found`);
     }
     catch (err) {
-        console.error(`  ❌ JWKS fetch error: ${err.message}`);
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`  ❌ JWKS fetch error: ${message}`);
         process.exit(1);
     }
 });
@@ -1581,7 +2578,7 @@ async function loadInstanceSecretKey(instanceId, opts) {
     const res = await fetch(`http://127.0.0.1:${opsPort}/`, {
         method: "POST",
         headers: { "Content-Type": "application/json", Authorization: auth },
-        body: JSON.stringify({ operation: "sql", sql: `SELECT * FROM flair.Instance WHERE id = '${instanceId}'` }),
+        body: JSON.stringify({ operation: "search_by_value", schema: "flair", table: "Instance", search_attribute: "id", search_type: "equals", search_value: instanceId, get_attributes: ["*"] }),
     });
     if (res.ok) {
         const rows = await res.json();
@@ -1607,14 +2604,18 @@ federation
     .command("status")
     .description("Show federation status and peer connections")
     .option("--port <port>", "Harper HTTP port")
+    .option("--target <url>", "Remote Flair URL (env: FLAIR_TARGET)")
+    .option("--ops-target <url>", "Explicit ops API URL (env: FLAIR_OPS_TARGET; bypasses port derivation)")
     .action(async (opts) => {
+    const target = resolveTarget(opts);
+    const baseUrl = target ? target.replace(/\/$/, "") : undefined;
     try {
-        const instance = await api("GET", "/FederationInstance");
+        const instance = await api("GET", "/FederationInstance", undefined, baseUrl ? { baseUrl } : undefined);
         console.log(`Instance: ${instance.id} (${instance.role})`);
         console.log(`Public key: ${instance.publicKey}`);
         console.log(`Status: ${instance.status}`);
         console.log();
-        const { peers } = await api("GET", "/FederationPeers");
+        const { peers } = await api("GET", "/FederationPeers", undefined, baseUrl ? { baseUrl } : undefined);
         if (peers.length === 0) {
             console.log("No peers configured. Use 'flair federation pair' to connect to a hub.");
         }
@@ -1638,22 +2639,38 @@ federation
     .option("--port <port>", "Harper HTTP port")
     .option("--admin-pass <pass>", "Admin password")
     .option("--ops-port <port>", "Harper operations API port")
-    .option("--token <token>", "One-time pairing token from hub admin")
+    .option("--token <token>", "One-time pairing token from hub admin (env: FLAIR_PAIRING_TOKEN)")
+    .option("--target <url>", "Remote Flair URL (env: FLAIR_TARGET)")
+    .option("--ops-target <url>", "Explicit ops API URL (env: FLAIR_OPS_TARGET; bypasses port derivation)")
     .action(async (hubUrl, opts) => {
+    const target = resolveTarget(opts);
+    const baseUrl = target ? target.replace(/\/$/, "") : undefined;
     try {
-        const instance = await api("GET", "/FederationInstance");
-        console.log(`Local instance: ${instance.id} (${instance.role})`);
+        const instance = await api("GET", "/FederationInstance", undefined, baseUrl ? { baseUrl } : undefined);
+        console.log(`${target ? "Remote" : "Local"} instance: ${instance.id} (${instance.role})`);
         if (!opts.token) {
             console.error("Error: --token is required. Ask the hub admin to run 'flair federation token' and provide the token.");
             process.exit(1);
         }
-        // Load secret key and sign the pairing request
+        // Warning: inline token may leak to shell history.
+        // fromEnv is true ONLY when the resolved value came from env (no inline override).
+        const tokenFromEnv = !opts.token && !!process.env.FLAIR_PAIRING_TOKEN;
+        if (shouldShowInlineSecretWarning(opts.token, tokenFromEnv, new Set(["--token"]), "--token")) {
+            console.error("warning: --token passed inline. Consider --token-from <file> or FLAIR_PAIRING_TOKEN env " +
+                "to keep secrets out of shell history.");
+        }
+        // Load secret key and sign the pairing request. The pairing token is
+        // included in the signed body (not in an Authorization header) because
+        // Harper's auth layer claims any "Bearer X" Authorization header for
+        // itself and 401s before our resource ever runs.
         const secretKey = await loadInstanceSecretKey(instance.id, opts);
+        // Env var fallback for --token: FLAIR_PAIRING_TOKEN
+        const pairingToken = opts.token || process.env.FLAIR_PAIRING_TOKEN;
         const pairBody = {
             instanceId: instance.id,
             publicKey: instance.publicKey,
             role: "spoke",
-            pairingToken: opts.token,
+            pairingToken,
         };
         const signedBody = signRequestBody(pairBody, secretKey);
         const res = await fetch(`${hubUrl}/FederationPair`, {
@@ -1668,12 +2685,12 @@ federation
         }
         const result = await res.json();
         console.log(`✅ Paired with hub: ${result.instance?.id ?? hubUrl}`);
-        // Record the hub as our peer locally
-        const opsPort = resolveOpsPort(opts);
+        // Record the hub as our peer — locally or remotely depending on --target
         const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
         if (adminPass) {
             const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
-            await fetch(`http://127.0.0.1:${opsPort}/`, {
+            const opsEndpoint = resolveEffectiveOpsUrl(opts) ?? `http://127.0.0.1:${resolveOpsPort(opts)}`;
+            await fetch(`${opsEndpoint}/`, {
                 method: "POST",
                 headers: { "Content-Type": "application/json", Authorization: auth },
                 body: JSON.stringify({
@@ -1687,6 +2704,7 @@ federation
                             updatedAt: new Date().toISOString(),
                         }],
                 }),
+                signal: AbortSignal.timeout(10_000),
             });
         }
     }
@@ -1702,16 +2720,20 @@ federation
     .option("--admin-pass <pass>", "Admin password")
     .option("--ops-port <port>", "Harper operations API port")
     .option("--ttl <minutes>", "Token TTL in minutes (default: 60)", "60")
+    .option("--target <url>", "Remote Flair URL (env: FLAIR_TARGET)")
+    .option("--ops-target <url>", "Explicit ops API URL (env: FLAIR_OPS_TARGET; bypasses port derivation)")
     .action(async (opts) => {
+    const target = resolveTarget(opts);
+    const baseUrl = target ? target.replace(/\/$/, "") : undefined;
     try {
         const { randomBytes } = await import("node:crypto");
         const token = randomBytes(24).toString("base64url");
         const ttlMinutes = parseInt(opts.ttl, 10) || 60;
         const expiresAt = new Date(Date.now() + ttlMinutes * 60 * 1000).toISOString();
-        const opsPort = resolveOpsPort(opts);
+        const opsEndpoint = resolveEffectiveOpsUrl(opts) ?? `http://127.0.0.1:${resolveOpsPort(opts)}`;
         const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
         const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
-        await fetch(`http://127.0.0.1:${opsPort}/`, {
+        const opsRes = await fetch(`${opsEndpoint}/`, {
             method: "POST",
             headers: { "Content-Type": "application/json", Authorization: auth },
             body: JSON.stringify({
@@ -1722,7 +2744,12 @@ federation
                         expiresAt,
                     }],
             }),
+            signal: AbortSignal.timeout(10_000),
         });
+        if (!opsRes.ok) {
+            const detail = await opsRes.text().catch(() => "");
+            throw new Error(`Failed to persist pairing token (${opsRes.status}): ${detail || "no body"}`);
+        }
         console.log(`Pairing token (expires in ${ttlMinutes}m):`);
         console.log(`  ${token}`);
         console.log(`\nGive this to the spoke admin to run:`);
@@ -1733,46 +2760,48 @@ federation
         process.exit(1);
     }
 });
-federation
-    .command("sync")
-    .description("Push local changes to the hub")
-    .option("--port <port>", "Harper HTTP port")
-    .option("--admin-pass <pass>", "Admin password")
-    .option("--ops-port <port>", "Harper operations API port")
-    .action(async (opts) => {
+export async function runFederationSyncOnce(opts) {
+    const target = resolveTarget(opts);
+    const baseUrl = target ? target.replace(/\/$/, "") : undefined;
+    const apiOpts = baseUrl ? { baseUrl } : undefined;
     try {
-        const { peers } = await api("GET", "/FederationPeers");
+        const { peers } = await api("GET", "/FederationPeers", undefined, apiOpts);
         const hub = peers.find((p) => p.role === "hub" && p.status !== "revoked");
         if (!hub) {
-            console.error("No hub peer configured. Use 'flair federation pair' first.");
-            process.exit(1);
+            return { pushed: 0, skipped: 0, error: new Error("No hub peer configured. Use 'flair federation pair' first.") };
         }
         console.log(`Syncing to hub: ${hub.id}...`);
         const since = hub.lastSyncAt ?? new Date(0).toISOString();
-        const opsPort = resolveOpsPort(opts);
+        const opsEndpoint = resolveEffectiveOpsUrl(opts) ?? `http://127.0.0.1:${resolveOpsPort(opts)}`;
         const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
         const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
         const tables = ["Memory", "Soul", "Agent", "Relationship"];
         const records = [];
-        const instance = await api("GET", "/FederationInstance");
+        const instance = await api("GET", "/FederationInstance", undefined, apiOpts);
         for (const table of tables) {
+            let res;
             try {
-                const res = await fetch(`http://127.0.0.1:${opsPort}/`, {
+                res = await fetch(`${opsEndpoint}/`, {
                     method: "POST",
                     headers: { "Content-Type": "application/json", Authorization: auth },
-                    body: JSON.stringify({ operation: "sql", sql: `SELECT * FROM flair.${table} WHERE updatedAt > '${since}'` }),
+                    body: JSON.stringify({ operation: "search_by_conditions", schema: "flair", table, operator: "and", conditions: [{ search_attribute: "updatedAt", search_type: "greater_than", search_value: since }], get_attributes: ["*"] }),
+                    signal: AbortSignal.timeout(15_000),
                 });
-                if (res.ok) {
-                    for (const row of await res.json()) {
-                        records.push({ table, id: row.id, data: row, updatedAt: row.updatedAt ?? row.createdAt, originatorInstanceId: instance.id });
-                    }
-                }
             }
-            catch { }
+            catch (err) {
+                return { pushed: 0, skipped: 0, error: err instanceof Error ? err : new Error(String(err)) };
+            }
+            if (!res.ok) {
+                const text = await res.text().catch(() => "");
+                return { pushed: 0, skipped: 0, error: new Error(`SQL query failed (${res.status}): ${text}`) };
+            }
+            for (const row of await res.json()) {
+                records.push({ table, id: row.id, data: row, updatedAt: row.updatedAt ?? row.createdAt, originatorInstanceId: instance.id });
+            }
         }
         if (records.length === 0) {
             console.log("No changes since last sync.");
-            return;
+            return { pushed: 0, skipped: 0 };
         }
         // Sign the sync request with our instance key
         const secretKey = await loadInstanceSecretKey(instance.id, opts);
@@ -1784,17 +2813,78 @@ federation
             body: JSON.stringify(signedSyncBody),
         });
         if (!syncRes.ok) {
-            console.error(`Sync failed: ${syncRes.status} ${await syncRes.text().catch(() => "")}`);
-            process.exit(1);
+            const text = await syncRes.text().catch(() => "");
+            return { pushed: 0, skipped: 0, error: new Error(`Sync failed: ${syncRes.status} ${text}`) };
         }
         const result = await syncRes.json();
         console.log(`✅ Synced ${result.merged} records (${result.skipped} skipped) in ${result.durationMs}ms`);
+        return { pushed: result.merged ?? 0, skipped: result.skipped ?? 0 };
     }
     catch (err) {
-        console.error(`Error: ${err.message}`);
+        return { pushed: 0, skipped: 0, error: err instanceof Error ? err : new Error(String(err)) };
+    }
+}
+federation
+    .command("sync")
+    .description("Push local changes to the hub")
+    .option("--port <port>", "Harper HTTP port")
+    .option("--admin-pass <pass>", "Admin password")
+    .option("--ops-port <port>", "Harper operations API port")
+    .option("--target <url>", "Remote Flair URL (env: FLAIR_TARGET)")
+    .option("--ops-target <url>", "Explicit ops API URL (env: FLAIR_OPS_TARGET; bypasses port derivation)")
+    .action(async (opts) => {
+    const r = await runFederationSyncOnce(opts);
+    if (r.error) {
+        console.error(`Error: ${r.error.message}`);
         process.exit(1);
     }
 });
+export async function runFederationWatch(opts) {
+    const intervalMs = Math.max(5, parseFloat(opts.interval) || 30) * 1000;
+    let stopped = false;
+    const stop = () => { stopped = true; };
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+    console.log(`flair federation watch — interval ${intervalMs / 1000}s. Ctrl-C to stop.`);
+    try {
+        while (!stopped) {
+            try {
+                const r = await runFederationSyncOnce(opts);
+                const ts = new Date().toISOString();
+                if (r.error)
+                    console.error(`[${ts}] sync error: ${r.error.message}`);
+                else
+                    console.log(`[${ts}] sync ok — pushed ${r.pushed}, skipped ${r.skipped}`);
+            }
+            catch (err) {
+                console.error(`[${new Date().toISOString()}] watch loop error: ${err.message}`);
+            }
+            // Sleep but exit early on signal
+            const t = Date.now();
+            while (!stopped && Date.now() - t < intervalMs) {
+                const remaining = intervalMs - (Date.now() - t);
+                await new Promise((r) => setTimeout(r, Math.min(250, remaining)));
+            }
+        }
+    }
+    finally {
+        process.removeListener("SIGINT", stop);
+        process.removeListener("SIGTERM", stop);
+    }
+    console.log("flair federation watch — stopped.");
+}
+federation
+    .command("watch")
+    .description("Run federation sync in a loop (foreground daemon)")
+    .option("--interval <seconds>", "Seconds between syncs", "30")
+    .option("--port <port>", "Harper HTTP port")
+    .option("--admin-pass <pass>", "Admin password")
+    .option("--ops-port <port>", "Harper operations API port")
+    .option("--target <url>", "Remote Flair URL")
+    .option("--ops-target <url>", "Explicit ops API URL")
+    .action(async (opts) => {
+    await runFederationWatch(opts);
+});
 // ─── flair rem ───────────────────────────────────────────────────────────────
 // Memory hygiene and reflection: light (NREM), rapid (REM), restorative (deep).
 const rem = program.command("rem").description("Memory hygiene and reflection");
@@ -2057,7 +3147,8 @@ function oauthDetailLines(o) {
 }
 async function fetchHealthDetail(opts) {
     const port = resolveHttpPort(opts);
-    const baseUrl = opts.url ?? `http://127.0.0.1:${port}`;
+    // --target takes precedence, then --url, then FLAIR_TARGET, then FLAIR_URL, then localhost
+    const baseUrl = opts.target || opts.url || process.env.FLAIR_TARGET || (process.env.FLAIR_URL ?? `http://127.0.0.1:${port}`);
     let healthy = false;
     let healthData = null;
     try {
@@ -2114,6 +3205,7 @@ const statusCmd = program
     .description("Show Flair instance status, memory stats, and agent info")
     .option("--port <port>", "Harper HTTP port")
     .option("--url <url>", "Flair base URL (overrides --port)")
+    .option("--target <url>", "Remote Flair URL (env: FLAIR_TARGET; alias for --url)")
     .option("--json", "Output as JSON")
     .option("--agent <id>", "Agent ID for authenticated detail (or set FLAIR_AGENT_ID)")
     .action(async (opts) => {
@@ -2142,17 +3234,42 @@ const statusCmd = program
     const agents = healthData?.agents;
     const memories = healthData?.memories;
     const warnings = Array.isArray(healthData?.warnings) ? healthData.warnings : [];
-    const hasWarn = warnings.some((w) => w.level === "warn");
-    // Header state-word stays "running" whenever the process is alive; the
-    // icon conveys health (🟢 clean / 🟡 warnings). 🔴 unreachable is already
-    // handled above by the `!healthy` early-exit. Decoupling state from
-    // health keeps the smoke-test `grep -q "running"` stable across tiers.
+    // Scope warnings to the filtered agent if --agent is set
+    const scopedWarnings = opts.agent && healthData?.agents?.perAgent
+        ? warnings.filter((w) => {
+            // Hash-fallback warnings contain agent-specific counts
+            if (w.message.includes("hash-fallback")) {
+                const match = w.message.match(/\b(\d+)\/(\d+) \((\d+)%\)/);
+                if (match) {
+                    const hashCount = parseInt(match[1]);
+                    const totalCount = parseInt(match[2]);
+                    const agentRow = healthData.agents.perAgent.find((r) => r.id === opts.agent);
+                    if (agentRow && agentRow.hashFallback === hashCount && agentRow.memoryCount === totalCount) {
+                        return true;
+                    }
+                    return false;
+                }
+            }
+            // Mixed-model warnings are fleet-wide; keep them
+            if (w.message.includes("multiple embedding models"))
+                return true;
+            // Federation warnings are fleet-wide; keep them
+            if (w.message.includes("federation"))
+                return true;
+            // REM warnings are fleet-wide; keep them
+            if (w.message.includes("REM") || w.message.includes("nightly"))
+                return true;
+            // Default: keep fleet-wide warnings
+            return !w.message.includes(opts.agent);
+        })
+        : warnings;
+    const hasWarn = scopedWarnings.some((w) => w.level === "warn");
     const headerIcon = hasWarn ? "🟡" : "🟢";
     console.log(`Flair v${__pkgVersion} — ${headerIcon} running${pid ? ` (PID ${pid}` : ""}${uptimeStr ? `, uptime ${uptimeStr})` : pid ? ")" : ""}`);
     console.log(`  URL:        ${baseUrl}`);
-    if (warnings.length > 0) {
-        console.log(`\n⚠ Warnings:  ${warnings.length}`);
-        for (const w of warnings)
+    if (scopedWarnings.length > 0) {
+        console.log(`\n⚠ Warnings:  ${scopedWarnings.length}`);
+        for (const w of scopedWarnings)
             console.log(`  • ${w.level} ${w.message}`);
     }
     if (memories) {
@@ -2248,6 +3365,9 @@ const statusCmd = program
         if (f.pendingTokens > 0)
             console.log(`  Pairing:     ${f.pendingTokens} unconsumed token(s)`);
     }
+    else {
+        console.log("\nFederation: not configured");
+    }
     if (healthData?.oauth) {
         const lines = oauthSummaryLines(healthData.oauth);
         for (const line of lines)
@@ -2263,6 +3383,9 @@ const statusCmd = program
         if (b.lastExport)
             console.log(`  Last export: ${relativeTime(b.lastExport)}`);
     }
+    else {
+        console.log("\nBridges: none installed");
+    }
     if (healthData?.disk) {
         const d = healthData.disk;
         console.log("\nDisk:");
@@ -2270,8 +3393,8 @@ const statusCmd = program
         console.log(`  Snapshots:   ${d.snapshotDir} — ${humanBytes(d.snapshotBytes ?? 0)}`);
     }
     console.log("");
-    if (warnings.length > 0)
-        console.log(`  Health:     ⚠ ${warnings.length} warning(s)`);
+    if (scopedWarnings.length > 0)
+        console.log(`  Health:     ⚠ ${scopedWarnings.length} warning(s)`);
     else
         console.log(`  Health:     ✅ all checks passing`);
 });
@@ -2806,7 +3929,7 @@ program
 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("--agent <id>", "Agent ID to re-embed memories for (defaults to all agents with stale rows)")
     .option("--stale-only", "Only re-embed memories with mismatched model tag")
     .option("--dry-run", "Show count without modifying")
     .option("--port <port>", "Harper HTTP port")
@@ -2821,13 +3944,100 @@ program
     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}`);
+    if (agentId) {
+        console.log(`Re-embedding memories for agent: ${agentId}`);
+    }
+    else {
+        console.log("Re-embedding memories for all agents with stale rows");
+    }
     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("");
+    // When no agent specified, use admin auth to fetch all memories
+    if (!agentId) {
+        const adminPass = process.env.FLAIR_ADMIN_PASS ?? process.env.HDB_ADMIN_PASSWORD;
+        if (!adminPass) {
+            console.error("❌ Admin password required when --agent is not specified (set FLAIR_ADMIN_PASS or HDB_ADMIN_PASSWORD)");
+            process.exit(1);
+        }
+        // Fetch all memories with admin auth
+        const searchRes = await fetch(`${baseUrl}/SemanticSearch`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Basic ${Buffer.from(`admin:${adminPass}`).toString("base64")}`,
+            },
+            body: JSON.stringify({ 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 ?? [];
+        // Group by agentId
+        const byAgent = new Map();
+        for (const m of allMemories) {
+            if (!m.content)
+                continue;
+            if (staleOnly && m.embeddingModel === currentModel)
+                continue;
+            const agent = m.agentId || "unknown";
+            if (!byAgent.has(agent))
+                byAgent.set(agent, []);
+            byAgent.get(agent).push(m);
+        }
+        // Process each agent
+        let totalProcessed = 0;
+        let totalErrors = 0;
+        const agentCount = byAgent.size;
+        let agentIndex = 0;
+        for (const [agent, memories] of byAgent) {
+            agentIndex++;
+            console.log(`\nAgent ${agentIndex}/${agentCount}: ${agent}`);
+            console.log(`  Memories to re-embed: ${memories.length}`);
+            const keysDir = defaultKeysDir();
+            const privPath = privKeyPath(agent, keysDir);
+            if (!existsSync(privPath)) {
+                console.error(`  ❌ Key not found: ${privPath} — skipping`);
+                continue;
+            }
+            if (dryRun)
+                continue;
+            let processed = 0;
+            let errors = 0;
+            for (let i = 0; i < memories.length; i += batchSize) {
+                const batch = memories.slice(i, i + batchSize);
+                for (const memory of batch) {
+                    try {
+                        const updateRes = await authFetch(baseUrl, agent, privPath, "PUT", `/Memory/${memory.id}`, {
+                            id: memory.id, content: memory.content, embedding: undefined, embeddingModel: undefined, agentId: memory.agentId || agent,
+                        });
+                        if (updateRes.ok)
+                            processed++;
+                        else
+                            errors++;
+                    }
+                    catch {
+                        errors++;
+                    }
+                }
+                const pct = Math.round(((i + batch.length) / memories.length) * 100);
+                process.stdout.write(`  \r  Re-embedded ${processed}/${memories.length} (${pct}%)${errors > 0 ? ` [${errors} errors]` : ""}`);
+                if (i + batchSize < memories.length)
+                    await new Promise(r => setTimeout(r, delayMs));
+            }
+            console.log(`\n  ✅ Agent ${agent}: ${processed} updated, ${errors} errors`);
+            totalProcessed += processed;
+            totalErrors += errors;
+        }
+        console.log(`\n\n✅ Re-embedding complete: ${totalProcessed} updated, ${totalErrors} errors`);
+        return;
+    }
+    // Original single-agent path
     const keysDir = defaultKeysDir();
     const privPath = privKeyPath(agentId, keysDir);
     if (!existsSync(privPath)) {
@@ -2869,7 +4079,7 @@ program
         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,
+                    id: memory.id, content: memory.content, embedding: undefined, embeddingModel: undefined, agentId: memory.agentId || opts.agent,
                 });
                 if (updateRes.ok)
                     processed++;
@@ -2919,7 +4129,8 @@ program
             }
         }
         catch (e) {
-            console.log(`  ${red("FAIL")} ${name}: ${e.message?.slice(0, 120)}`);
+            const message = e instanceof Error ? e.message : String(e);
+            console.log(`  ${red("FAIL")} ${name}: ${message?.slice(0, 120)}`);
             failed++;
         }
     };
@@ -2963,6 +4174,13 @@ program
         process.exit(1);
 });
 // ─── flair deploy ─────────────────────────────────────────────────────────────
+// NOTE on env-var naming for `flair deploy`: the FABRIC_* env vars below intentionally
+// do NOT carry the FLAIR_ prefix that the rest of the CLI uses (FLAIR_ADMIN_PASS,
+// FLAIR_TARGET, FLAIR_PAIRING_TOKEN, etc.). FABRIC_* credentials are shared with
+// the broader TPS tooling stack — multiple tools deploy to the same Harper Fabric
+// org/cluster with the same auth, and demanding a tool-specific prefix would force
+// operators to maintain duplicated env vars. Per Kern review on PR #306: the
+// inconsistency is deliberate, document it here so the next agent doesn't "fix" it.
 program
     .command("deploy")
     .description("Deploy Flair as a component to a remote Harper Fabric cluster")
@@ -3544,7 +4762,7 @@ bridge
     const cwd = opts.cwd ?? srcArg ?? process.cwd();
     const { discover } = await import("./bridges/discover.js");
     const { builtinDiscoveryRecords } = await import("./bridges/builtins/index.js");
-    const { loadDescriptor } = await import("./bridges/runtime/load-descriptor.js");
+    const { loadBridge } = await import("./bridges/runtime/load-bridge.js");
     const { runImport } = await import("./bridges/runtime/import-runner.js");
     const { makeContext } = await import("./bridges/runtime/context.js");
     const { BridgeRuntimeError } = await import("./bridges/types.js");
@@ -3554,9 +4772,9 @@ bridge
         console.error(`No bridge named "${name}" — run \`flair bridge list\` to see installed bridges.`);
         process.exit(1);
     }
-    let descriptor;
+    let loaded;
     try {
-        descriptor = await loadDescriptor(target);
+        loaded = await loadBridge(target);
     }
     catch (err) {
         printBridgeError(err);
@@ -3591,10 +4809,10 @@ bridge
         if (ev.type === "done") {
             const noun = (n) => `${n} ${n === 1 ? "memory" : "memories"}`;
             if (opts.dryRun) {
-                console.log(`\n${descriptor.name}: would import ${noun(ev.total)}. Re-run without --dry-run to write to Flair.`);
+                console.log(`\n${target.name}: would import ${noun(ev.total)}. Re-run without --dry-run to write to Flair.`);
             }
             else {
-                console.log(`\n${descriptor.name}: imported ${ev.imported}/${ev.total} memories${ev.skipped > 0 ? ` (${ev.skipped} skipped)` : ""}.`);
+                console.log(`\n${target.name}: imported ${ev.imported}/${ev.total} memories${ev.skipped > 0 ? ` (${ev.skipped} skipped)` : ""}.`);
             }
             return;
         }
@@ -3611,15 +4829,40 @@ bridge
         }
     };
     try {
-        await runImport({
-            descriptor,
-            cwd,
-            agentId,
-            dryRun: !!opts.dryRun,
-            putMemory,
-            onProgress,
-            ctx,
-        });
+        if (loaded.kind === "yaml") {
+            await runImport({
+                bridgeName: target.name,
+                descriptor: loaded.descriptor,
+                cwd,
+                agentId,
+                dryRun: !!opts.dryRun,
+                putMemory,
+                onProgress,
+                ctx,
+            });
+        }
+        else {
+            // Code plugin: invoke bridge.import(opts, ctx) directly; the plugin
+            // returns an AsyncIterable of BridgeMemory that runImport processes.
+            if (!loaded.plugin.import) {
+                console.error(`Bridge "${name}" is a code plugin without an import() function — can only export through it.`);
+                process.exit(1);
+            }
+            // Code-plugin options: pass through all --X flags as a single object.
+            // The plugin's declared `options` descriptor validates what it actually cares about.
+            const pluginOpts = { ...opts };
+            const source = loaded.plugin.import(pluginOpts, ctx);
+            await runImport({
+                bridgeName: target.name,
+                source,
+                cwd,
+                agentId,
+                dryRun: !!opts.dryRun,
+                putMemory,
+                onProgress,
+                ctx,
+            });
+        }
     }
     catch (err) {
         if (err instanceof BridgeRuntimeError) {
@@ -3651,7 +4894,7 @@ bridge
     const cwd = opts.cwd ?? dst;
     const { discover } = await import("./bridges/discover.js");
     const { builtinDiscoveryRecords } = await import("./bridges/builtins/index.js");
-    const { loadDescriptor } = await import("./bridges/runtime/load-descriptor.js");
+    const { loadBridge } = await import("./bridges/runtime/load-bridge.js");
     const { runExport } = await import("./bridges/runtime/export-runner.js");
     const { makeContext } = await import("./bridges/runtime/context.js");
     const { BridgeRuntimeError } = await import("./bridges/types.js");
@@ -3661,18 +4904,22 @@ bridge
         console.error(`No bridge named "${name}" — run \`flair bridge list\` to see installed bridges.`);
         process.exit(1);
     }
-    let descriptor;
+    let loaded;
     try {
-        descriptor = await loadDescriptor(target);
+        loaded = await loadBridge(target);
     }
     catch (err) {
         printBridgeError(err);
         process.exit(1);
     }
-    if (!descriptor.export) {
+    if (loaded.kind === "yaml" && !loaded.descriptor.export) {
         console.error(`Bridge "${name}" has no export block — cannot export through it.`);
         process.exit(1);
     }
+    if (loaded.kind === "code" && !loaded.plugin.export) {
+        console.error(`Bridge "${name}" is a code plugin without an export() function — can only import through it.`);
+        process.exit(1);
+    }
     const baseUrl = opts.url ?? `http://127.0.0.1:${resolveHttpPort(opts)}`;
     const ctx = makeContext({ bridge: name });
     // Memory fetcher — paginates GET /Memory?agentId=... applying any
@@ -3710,10 +4957,10 @@ bridge
     const onProgress = (ev) => {
         if (ev.type === "done") {
             if (opts.dryRun) {
-                console.log(`\n${descriptor.name}: would export ${ev.exported} memor${ev.exported === 1 ? "y" : "ies"} from ${ev.total} total. Re-run without --dry-run to write.`);
+                console.log(`\n${target.name}: would export ${ev.exported} memor${ev.exported === 1 ? "y" : "ies"} from ${ev.total} total. Re-run without --dry-run to write.`);
             }
             else {
-                console.log(`\n${descriptor.name}: exported ${ev.exported} memor${ev.exported === 1 ? "y" : "ies"} from ${ev.total} total.`);
+                console.log(`\n${target.name}: exported ${ev.exported} memor${ev.exported === 1 ? "y" : "ies"} from ${ev.total} total.`);
             }
             return;
         }
@@ -3733,15 +4980,28 @@ bridge
         process.stdout.write(`\r  filtering memory ${ev.ordinal}...`.padEnd(60));
     };
     try {
-        await runExport({
-            descriptor,
-            cwd,
-            fetchMemories,
-            filters: { agentId, subject: opts.subject, source: opts.source, since: opts.since },
-            dryRun: !!opts.dryRun,
-            ctx,
-            onProgress,
-        });
+        if (loaded.kind === "yaml") {
+            await runExport({
+                descriptor: loaded.descriptor,
+                cwd,
+                fetchMemories,
+                filters: { agentId, subject: opts.subject, source: opts.source, since: opts.since },
+                dryRun: !!opts.dryRun,
+                ctx,
+                onProgress,
+            });
+        }
+        else {
+            // Code plugin export: invoke plugin.export(memoryStream, opts, ctx) directly.
+            // Plugin writes to its target however it likes (HTTP, file, etc.).
+            if (opts.dryRun) {
+                console.log(`${target.name}: dry-run not supported for code-plugin exports; aborting before invoking plugin.export().`);
+                process.exit(2);
+            }
+            const pluginOpts = { ...opts };
+            await loaded.plugin.export(fetchMemories({ agentId, subject: opts.subject, source: opts.source, since: opts.since }), pluginOpts, ctx);
+            console.log(`${target.name}: code-plugin export completed. Record count not reported by the plugin.`);
+        }
     }
     catch (err) {
         if (err instanceof BridgeRuntimeError) {
@@ -3762,7 +5022,7 @@ bridge
     const cwd = opts.cwd ?? process.cwd();
     const { discover } = await import("./bridges/discover.js");
     const { builtinDiscoveryRecords } = await import("./bridges/builtins/index.js");
-    const { loadDescriptor } = await import("./bridges/runtime/load-descriptor.js");
+    const { loadBridge } = await import("./bridges/runtime/load-bridge.js");
     const { runRoundTrip } = await import("./bridges/runtime/roundtrip.js");
     const { BridgeRuntimeError } = await import("./bridges/types.js");
     const found = await discover({ builtins: builtinDiscoveryRecords() });
@@ -3771,25 +5031,30 @@ bridge
         console.error(`No bridge named "${name}" — run \`flair bridge list\` to see installed bridges.`);
         process.exit(1);
     }
-    let descriptor;
+    let loaded;
     try {
-        descriptor = await loadDescriptor(target);
+        loaded = await loadBridge(target);
     }
     catch (err) {
         printBridgeError(err);
         process.exit(1);
     }
+    if (loaded.kind === "code") {
+        console.error(`Bridge "${name}" is a code plugin — round-trip testing for code plugins lands in slice 3d (requires mocked fetch transport).`);
+        console.error(`For now, code plugins should ship their own tests alongside the npm package.`);
+        process.exit(2);
+    }
     try {
-        const result = await runRoundTrip({ descriptor, cwd, fixturePath: opts.fixture });
+        const result = await runRoundTrip({ descriptor: loaded.descriptor, cwd, fixturePath: opts.fixture });
         if (opts.json) {
             console.log(JSON.stringify(result, null, 2));
             process.exit(result.passed ? 0 : 1);
         }
         if (result.passed) {
-            console.log(`✅ ${descriptor.name} round-trip passed (${result.expectedCount} record${result.expectedCount === 1 ? "" : "s"}).`);
+            console.log(`✅ ${target.name} round-trip passed (${result.expectedCount} record${result.expectedCount === 1 ? "" : "s"}).`);
             process.exit(0);
         }
-        console.log(`❌ ${descriptor.name} round-trip failed.`);
+        console.log(`❌ ${target.name} round-trip failed.`);
         console.log(`   expected ${result.expectedCount} records, got ${result.actualCount} back.`);
         if (result.missingInPass2.length > 0) {
             console.log(`   missing from re-import (${result.missingInPass2.length}):`);
@@ -3825,11 +5090,92 @@ bridge
         process.exit(1);
     }
 });
+bridge
+    .command("allow <name>")
+    .description("Approve an npm code-plugin bridge for execution. Approval is pinned to the package's location and package.json contents — a malicious package squatting on the same name in a different node_modules tree will be refused at load-time.")
+    .action(async (name) => {
+    const { discover } = await import("./bridges/discover.js");
+    const { builtinDiscoveryRecords } = await import("./bridges/builtins/index.js");
+    const { allow } = await import("./bridges/runtime/allow-list.js");
+    const found = await discover({ builtins: builtinDiscoveryRecords() });
+    const target = found.find((b) => b.name === name);
+    if (!target) {
+        console.error(`No bridge named "${name}" — run \`flair bridge list\` to see installed bridges.`);
+        process.exit(1);
+    }
+    if (target.source !== "npm-package") {
+        console.error(`"${name}" is a ${target.source} bridge; only npm code plugins require allow-list approval.`);
+        console.error(`YAML and built-in bridges run via the descriptor runtime and don't execute arbitrary JS.`);
+        process.exit(1);
+    }
+    try {
+        const result = await allow(name, target.path);
+        if (result.alreadyAllowed) {
+            console.log(`${name} was already allowed at ${result.entry.packageDir} — no change.`);
+            return;
+        }
+        const verb = result.updated ? "re-approved" : "allowed";
+        console.log(`✓ ${name} ${verb}.`);
+        console.log(`  location: ${result.entry.packageDir}`);
+        console.log(`  version:  ${result.entry.version ?? "(not declared)"}`);
+        console.log(`  digest:   ${result.entry.packageJsonSha256.slice(0, 16)}…`);
+        console.log(`  If the package later moves or its package.json content changes, execution is refused until you re-run this command.`);
+        console.log(`  Revoke anytime with: flair bridge revoke ${name}`);
+    }
+    catch (err) {
+        console.error(`Failed to approve "${name}": ${err?.message ?? err}`);
+        process.exit(1);
+    }
+});
+bridge
+    .command("revoke <name>")
+    .description("Revoke approval for an npm code-plugin bridge (future invocations will require `flair bridge allow <name>` again)")
+    .action(async (name) => {
+    const { revoke } = await import("./bridges/runtime/allow-list.js");
+    const result = await revoke(name);
+    if (!result.wasAllowed) {
+        console.log(`${name} was not on the allow-list — no change.`);
+        return;
+    }
+    console.log(`✓ ${name} revoked. Future invocations require \`flair bridge allow ${name}\` again.`);
+});
+bridge
+    .command("allow-list")
+    .description("Show the allow-listed code-plugin bridges")
+    .option("--json", "Emit raw JSON")
+    .action(async (opts) => {
+    const { list: listAllowed } = await import("./bridges/runtime/allow-list.js");
+    const entries = await listAllowed();
+    if (opts.json) {
+        console.log(JSON.stringify(entries, null, 2));
+        return;
+    }
+    if (entries.length === 0) {
+        console.log("No code-plugin bridges are allow-listed yet.");
+        console.log("Allow one with: flair bridge allow <name>");
+        return;
+    }
+    const nameW = Math.max(4, ...entries.map((e) => e.name.length));
+    const verW = Math.max(7, ...entries.map((e) => (e.version ?? "—").length));
+    console.log(`  ${"name".padEnd(nameW)}  ${"version".padEnd(verW)}  allowed-at               location / digest`);
+    for (const e of entries) {
+        console.log(`  ${e.name.padEnd(nameW)}  ${(e.version ?? "—").padEnd(verW)}  ${e.allowedAt}  ${e.packageDir}`);
+        console.log(`  ${" ".repeat(nameW)}  ${" ".repeat(verW)}  ${" ".repeat(24)}  sha256:${e.packageJsonSha256.slice(0, 16)}…`);
+    }
+});
 function printBridgeError(err) {
     // Pretty-print BridgeRuntimeError as the structured shape from §10 of the
     // spec, plus a one-line human summary so the operator gets both.
     const detail = err?.detail;
     if (detail && typeof detail === "object") {
+        // Trust-check failures get a dedicated, operator-facing rendering.
+        // Dumping the full spec-§10 JSON is useful when an operator is
+        // debugging a broken YAML descriptor; for trust errors it buries the
+        // one thing that matters — the command to re-approve.
+        if (detail.field === "(trust)") {
+            printTrustError(detail);
+            return;
+        }
         console.error(`Bridge error: ${detail.hint ?? err.message}`);
         console.error(JSON.stringify(detail, null, 2));
     }
@@ -3837,6 +5183,73 @@ function printBridgeError(err) {
         console.error(`Bridge error: ${err.message ?? String(err)}`);
     }
 }
+function printTrustError(detail) {
+    const name = detail.bridge ?? "(unknown)";
+    const ctx = detail.context ?? {};
+    const reapprove = `  flair bridge allow ${name}`;
+    const bar = "─".repeat(60);
+    const header = (title) => {
+        console.error("");
+        console.error(`⚠ ${title} — ${name}`);
+        console.error(bar);
+    };
+    const footer = (label) => {
+        console.error("");
+        console.error(`${label}:`);
+        console.error(reapprove);
+        console.error("");
+    };
+    switch (detail.got) {
+        case "not-allowed":
+            header("Approval required");
+            console.error("This bridge is an npm code plugin — it runs arbitrary JavaScript.");
+            console.error("First-use approval is required before Flair will execute it.");
+            footer("Approve it with");
+            return;
+        case "path-mismatch":
+            header("Trust check failed: package location changed");
+            console.error("A different package with the same name was discovered. This is how");
+            console.error("local squatting attacks present — a planted `node_modules/flair-bridge-*`");
+            console.error("in an unrelated project tree.");
+            console.error("");
+            console.error(`  approved: ${ctx.approvedPath ?? "(unknown)"}`);
+            console.error(`            version ${ctx.approvedVersion ?? "?"} at ${ctx.approvedAt ?? "?"}`);
+            console.error(`  now:      ${ctx.observedPath ?? "(unknown)"}`);
+            footer("If the new location is intentional, re-approve");
+            return;
+        case "digest-mismatch":
+            header("Trust check failed: package contents changed");
+            console.error("The package.json at the approved location has changed since you");
+            console.error("approved this bridge. This fires on every upgrade — it's a trust");
+            console.error("event, not an error. If the update is intentional, re-approve.");
+            console.error("");
+            console.error(`  location:          ${ctx.packagePath ?? "(unknown)"}`);
+            console.error(`  approved version:  ${ctx.approvedVersion ?? "?"}   (at ${ctx.approvedAt ?? "?"})`);
+            console.error(`  approved digest:   sha256:${(ctx.approvedDigest ?? "").slice(0, 16)}…`);
+            console.error(`  observed digest:   sha256:${(ctx.observedDigest ?? "").slice(0, 16)}…`);
+            footer("Re-approve");
+            return;
+        case "entry-incomplete":
+            header("Trust check failed: approval record is incomplete");
+            console.error("The allow-list entry for this bridge is missing a location or digest.");
+            console.error("This usually means the record was created by a pre-fix Flair version");
+            console.error("(0.6.0 / 0.6.1) that only stored the name. Re-approve to upgrade.");
+            footer("Re-approve");
+            return;
+        case "package-missing":
+            header("Trust check failed: approved package missing on disk");
+            console.error("The package location recorded at allow-time is no longer readable.");
+            console.error("");
+            console.error(`  approved at:  ${ctx.approvedPath ?? "(unknown)"}`);
+            console.error(`  discovered:   ${ctx.discoveredPath ?? "(unknown)"}`);
+            footer("Reinstall the package, then re-approve");
+            return;
+        default:
+            // Unknown trust sub-reason — fall back to the raw structured print.
+            console.error(`Bridge error (trust): ${detail.hint ?? detail.got ?? "unknown"}`);
+            console.error(JSON.stringify(detail, null, 2));
+    }
+}
 // ─── flair backup ────────────────────────────────────────────────────────────
 program
     .command("backup")
@@ -4246,9 +5659,264 @@ program
         console.log(`Souls: ${(data.souls ?? []).length}`);
     }
 });
+// ─── flair migrate-harness-memory ───────────────────────────────────────────
+/** Resolve the memory directory path for a target harness. */
+function resolveMemoryDir(target, agentId) {
+    switch (target) {
+        case "claude-code": {
+            const cwd = process.cwd();
+            const encodedCwd = encodeURIComponent(cwd).replace(/%2F/g, "/");
+            const memoryDir = join(homedir(), ".claude", "projects", encodedCwd, "memory");
+            const resolved = resolve(memoryDir);
+            const expectedRoot = join(homedir(), ".claude", "projects");
+            if (!resolved.startsWith(expectedRoot + sep)) {
+                throw new Error(`Memory dir must be within ${expectedRoot}, got ${resolved}`);
+            }
+            return resolved;
+        }
+        case "openclaw": {
+            const cwd = process.cwd();
+            const encodedCwd = encodeURIComponent(cwd).replace(/%2F/g, "/");
+            const memoryDir = join(homedir(), ".openclaw", "projects", encodedCwd, "memory");
+            const resolved = resolve(memoryDir);
+            const expectedRoot = join(homedir(), ".openclaw", "projects");
+            if (!resolved.startsWith(expectedRoot + sep)) {
+                throw new Error(`Memory dir must be within ${expectedRoot}, got ${resolved}`);
+            }
+            return resolved;
+        }
+        case "pi": {
+            const cwd = process.cwd();
+            const encodedCwd = encodeURIComponent(cwd).replace(/%2F/g, "/");
+            const memoryDir = join(homedir(), ".pi", "projects", encodedCwd, "memory");
+            const resolved = resolve(memoryDir);
+            const expectedRoot = join(homedir(), ".pi", "projects");
+            if (!resolved.startsWith(expectedRoot + sep)) {
+                throw new Error(`Memory dir must be within ${expectedRoot}, got ${resolved}`);
+            }
+            return resolved;
+        }
+        default:
+            throw new Error(`Unknown target: ${target}. Valid: claude-code, openclaw, pi`);
+    }
+}
+/** Parse a memory file with YAML frontmatter. */
+function parseMemoryFile(filePath) {
+    const raw = readFileSync(filePath, "utf-8");
+    const lines = raw.split("\n");
+    if (!lines[0].startsWith("---")) {
+        return { meta: {}, body: raw };
+    }
+    let endIdx = 1;
+    while (endIdx < lines.length && !lines[endIdx].startsWith("---")) {
+        endIdx++;
+    }
+    const frontmatterLines = lines.slice(1, endIdx);
+    const bodyLines = lines.slice(endIdx + 1);
+    const yamlContent = frontmatterLines.join("\n");
+    const meta = parseYaml(yamlContent) || {};
+    return {
+        meta: {
+            name: meta.name,
+            description: meta.description,
+            type: meta.type,
+            tags: Array.isArray(meta.tags) ? meta.tags : (meta.tags ? [meta.tags] : []),
+        },
+        body: bodyLines.join("\n").trim(),
+    };
+}
+/** Map memory type to durability. */
+function mapDurability(type) {
+    switch (type) {
+        case "feedback":
+        case "reference":
+            return "permanent";
+        case "project":
+        case "user":
+            return "persistent";
+        default:
+            return "standard";
+    }
+}
+/** Extract keywords from filename for tags. */
+function extractKeywordsFromFilename(filename) {
+    const base = filename.replace(/\.md$/, "");
+    const withoutType = base.replace(/^(feedback|project|reference|user)_/, "");
+    const parts = withoutType.split(/[_-]+/).map(p => p.toLowerCase());
+    const stopwords = new Set(["the", "and", "for", "with", "about", "on", "in", "to", "of", "a", "an"]);
+    return parts.filter(p => p.length > 2 && !stopwords.has(p));
+}
+program
+    .command("migrate-harness-memory")
+    .description("Migrate harness-local memories to Flair")
+    .requiredOption("--target <target>", "Target harness: claude-code, openclaw, pi")
+    .requiredOption("--agent <id>", "Agent ID to write memories under")
+    .option("--dry-run", "Show what would be migrated without writing")
+    .action(async (opts) => {
+    const target = opts.target;
+    const agentId = opts.agent;
+    const dryRun = !!opts.dryRun;
+    let memoryDir;
+    try {
+        memoryDir = resolveMemoryDir(target, agentId);
+    }
+    catch (e) {
+        console.error(`Error resolving memory directory: ${e.message}`);
+        process.exit(1);
+    }
+    if (!existsSync(memoryDir)) {
+        console.error(`Error: Memory directory not found: ${memoryDir}`);
+        process.exit(1);
+    }
+    const migratedDir = join(memoryDir, ".migrated");
+    if (!dryRun) {
+        mkdirSync(migratedDir, { recursive: true, mode: 0o700 });
+    }
+    console.log(`Migrating memories from ${memoryDir} to Flair (agentId=${agentId})`);
+    if (dryRun)
+        console.log("  (DRY RUN - no files will be modified)");
+    const files = readdirSync(memoryDir, { withFileTypes: true })
+        .filter(d => d.isFile() && d.name.endsWith(".md") && d.name !== "MEMORY.md")
+        .map(d => d.name)
+        .sort();
+    if (files.length === 0) {
+        console.log("No memory files found.");
+        return;
+    }
+    console.log(`Found ${files.length} memory file(s) to migrate.`);
+    let successCount = 0;
+    let skipCount = 0;
+    let failCount = 0;
+    for (const filename of files) {
+        const sourcePath = join(memoryDir, filename);
+        const migratedPath = join(migratedDir, filename);
+        if (existsSync(migratedPath)) {
+            console.log(`  ${filename}: already migrated, skipping`);
+            skipCount++;
+            continue;
+        }
+        console.log(`  Processing: ${filename}...`);
+        let parsed;
+        try {
+            parsed = parseMemoryFile(sourcePath);
+        }
+        catch (e) {
+            console.error(`    Failed to parse: ${e.message}`);
+            failCount++;
+            continue;
+        }
+        let type = parsed.meta.type;
+        if (!type) {
+            if (filename.startsWith("feedback_"))
+                type = "feedback";
+            else if (filename.startsWith("project_"))
+                type = "project";
+            else if (filename.startsWith("reference_"))
+                type = "reference";
+            else
+                type = "session";
+        }
+        const durability = mapDurability(type);
+        const tags = [...(parsed.meta.tags || [])];
+        const filenameTags = extractKeywordsFromFilename(filename);
+        for (const t of filenameTags) {
+            if (!tags.includes(t))
+                tags.push(t);
+        }
+        tags.push(type);
+        const content = parsed.body;
+        console.log(`    Type: ${type}, Durability: ${durability}`);
+        console.log(`    Tags: ${tags.join(", ")}`);
+        console.log(`    Content preview: ${content.slice(0, 100)}${content.length > 100 ? "..." : ""}`);
+        if (!dryRun) {
+            console.log(`    Writing to Flair...`);
+            try {
+                const DEFAULT_PORT = 19926;
+                const httpUrl = `http://127.0.0.1:${DEFAULT_PORT}`;
+                const agentKeyId = `${agentId}.key`;
+                const keysDir = join(homedir(), ".flair", "keys");
+                const keyPath = join(keysDir, agentKeyId);
+                let authSuccess = false;
+                if (existsSync(keyPath)) {
+                    const memoryId = `${agentId}-${randomUUID()}`;
+                    const body = {
+                        id: memoryId,
+                        agentId: agentId,
+                        content: content,
+                        type: type,
+                        durability: durability,
+                        tags: tags,
+                        createdAt: new Date().toISOString(),
+                    };
+                    const memoryPath = `/Memory/${memoryId}`;
+                    const res = await authFetch(httpUrl, agentId, keyPath, "PUT", memoryPath, body);
+                    if (res.ok) {
+                        authSuccess = true;
+                        console.log(`    Write to Flair successful (Ed25519 auth)`);
+                    }
+                }
+                if (!authSuccess) {
+                    const adminPass = process.env.FLAIR_ADMIN_PASS || process.env.HDB_ADMIN_PASSWORD || "";
+                    if (adminPass) {
+                        const memoryId = `${agentId}-${randomUUID()}`;
+                        const body = {
+                            id: memoryId,
+                            agentId: agentId,
+                            content: content,
+                            type: type,
+                            durability: durability,
+                            tags: tags,
+                            createdAt: new Date().toISOString(),
+                        };
+                        const memoryPath = `/Memory/${memoryId}`;
+                        const auth = `Basic ${Buffer.from(`admin:${adminPass}`).toString("base64")}`;
+                        const res = await fetch(`${httpUrl}${memoryPath}`, {
+                            method: "PUT",
+                            headers: {
+                                Authorization: auth,
+                                "Content-Type": "application/json",
+                            },
+                            body: JSON.stringify(body),
+                            signal: AbortSignal.timeout(10000),
+                        });
+                        if (res.ok) {
+                            console.log(`    Write to Flair successful (Basic auth)`);
+                        }
+                        else {
+                            const text = await res.text();
+                            throw new Error(`HTTP ${res.status}: ${text}`);
+                        }
+                    }
+                    else {
+                        throw new Error("No authentication method available");
+                    }
+                }
+                renameSync(sourcePath, migratedPath);
+                console.log(`    Moved to .migrated/${filename}`);
+            }
+            catch (e) {
+                console.error(`    Failed: ${e.message}`);
+                failCount++;
+                continue;
+            }
+        }
+        else {
+            console.log(`    [dry-run] Would write to Flair and move to .migrated/${filename}`);
+        }
+        successCount++;
+    }
+    console.log(`\nMigration complete:`);
+    console.log(`  Processed: ${files.length}`);
+    console.log(`  Successful: ${successCount}`);
+    console.log(`  Skipped: ${skipCount}`);
+    console.log(`  Failed: ${failCount}`);
+    if (failCount > 0) {
+        process.exit(1);
+    }
+});
 // Run CLI only when this is the entry point (not when imported for testing)
 if (import.meta.main) {
     await program.parseAsync();
 }
 // ─── Exported for testing ─────────────────────────────────────────────────────
-export { resolveKeyPath, buildEd25519Auth, readPortFromConfig, resolveHttpPort, resolveOpsPort, signRequestBody, b64, b64url, program, };
+export { resolveKeyPath, buildEd25519Auth, readPortFromConfig, resolveHttpPort, resolveOpsPort, resolveTarget, resolveOpsTarget, resolveEffectiveOpsUrl, resolveOpsUrlFromTarget, signRequestBody, b64, b64url, program, api, isLocalBase, isLikelyRealSecret, shouldShowInlineSecretWarning, };