@tpsdev-ai/flair 0.9.0 → 0.10.1

package/dist/cli.js

@@ -2,6 +2,7 @@
 import { Command } from "commander";
 import nacl from "tweetnacl";
 import { load as parseYaml } from "js-yaml";
+import * as render from "./render.js";
 import { existsSync, mkdirSync, writeFileSync, readFileSync, chmodSync, renameSync, cpSync, rmSync, mkdtempSync, readdirSync, statSync, } from "node:fs";
 import { homedir, hostname, tmpdir } from "node:os";
 import { join, resolve, sep, dirname } from "node:path";
@@ -83,6 +84,34 @@ const DEFAULT_OPS_PORT = 19925;
 const DEFAULT_ADMIN_USER = "admin";
 const STARTUP_TIMEOUT_MS = 60_000;
 const HEALTH_POLL_INTERVAL_MS = 500;
+/**
+ * Read an admin password from a file, refusing if the file is world/group readable.
+ *
+ * Admin pass files (default ~/.flair/admin-pass) are short-lived secrets generated
+ * by `openssl rand` — mode 0600 keeps them out of reach of other local users + most
+ * backup tooling. A 0644 file silently leaks the secret to anyone with read access
+ * to the user's home (multi-user hosts, NFS, time-machine snapshots, etc.).
+ *
+ * Throws with an actionable error if the file isn't owner-only, otherwise returns
+ * the trimmed file content (admin-pass files generated by `openssl rand -base64`
+ * conventionally end in a newline).
+ */
+export function readAdminPassFileSecure(path) {
+    if (!existsSync(path)) {
+        throw new Error(`--admin-pass-file path does not exist: ${path}`);
+    }
+    const st = statSync(path);
+    if (st.mode & 0o077) {
+        const modeOctal = (st.mode & 0o777).toString(8).padStart(3, "0");
+        throw new Error(`Refusing to read --admin-pass-file at ${path}: permissions ${modeOctal} are too open. ` +
+            `Run \`chmod 600 ${path}\` to restrict to owner-only.`);
+    }
+    const content = readFileSync(path, "utf-8").replace(/\s+$/, "");
+    if (!content) {
+        throw new Error(`admin password file is empty or contains only whitespace: ${path}`);
+    }
+    return content;
+}
 function defaultKeysDir() {
     return join(homedir(), ".flair", "keys");
 }
@@ -126,6 +155,25 @@ function resolveHttpPort(opts) {
     }
     return readPortFromConfig() ?? DEFAULT_PORT;
 }
+// Unified base URL resolution. Precedence:
+//   --target > --url > FLAIR_TARGET env > FLAIR_URL env > http://127.0.0.1:<resolveHttpPort>
+//
+// Every user-facing command that talks to a Flair instance should call this
+// instead of hand-rolling the precedence. Keeps remote-target switching
+// (e.g. CI hitting Fabric) consistent across `flair status`, `flair search`,
+// `flair bootstrap`, etc.
+function resolveBaseUrl(opts) {
+    return (opts.target
+        || opts.url
+        || process.env.FLAIR_TARGET
+        || process.env.FLAIR_URL
+        || `http://127.0.0.1:${resolveHttpPort(opts)}`);
+}
+// Resolve agent id from --agent flag or FLAIR_AGENT_ID env.
+// Returns null if neither is set; caller decides whether that's fatal.
+function resolveAgentIdOrEnv(opts) {
+    return opts.agent || process.env.FLAIR_AGENT_ID || null;
+}
 // Ops port resolution: --ops-port flag > FLAIR_OPS_PORT env > config opsPort > httpPort - 1
 function resolveOpsPort(opts) {
     if (opts.opsPort !== undefined && opts.opsPort !== null) {
@@ -831,6 +879,16 @@ export function probeOpenclawPluginVersion(extensionName) {
         return null;
     }
 }
+/**
+ * Order a soul key→count map for display: highest count first, ties broken
+ * alphabetically for stable output. Soul entries are keyed identity facts
+ * (role / project / standards / …) — this is the honest breakdown dimension.
+ * (Replaced a priority breakdown that was dead telemetry — see flair#453:
+ * nothing ever writes Soul.priority to anything but "standard".)
+ */
+export function sortSoulKeyEntries(byKey) {
+    return Object.entries(byKey ?? {}).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+}
 export function templateSoul(choice) {
     const templates = {
         "1": [
@@ -1206,14 +1264,11 @@ program
     }
     // 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);
+        try {
+            adminPass = readAdminPassFileSecure(opts.adminPassFile);
         }
-        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}`);
+        catch (err) {
+            console.error(`Error: ${err.message}`);
             process.exit(1);
         }
         passwordSource = "file";
@@ -1956,6 +2011,7 @@ agent
     .description("List all agents")
     .option("--admin-pass <pass>", "Admin password (or set FLAIR_ADMIN_PASS env)")
     .option("--port <port>", "Harper HTTP port")
+    .option("--json", "Emit raw JSON array (also: pipe + FLAIR_OUTPUT=json)")
     .action(async (opts) => {
     const port = resolveHttpPort(opts);
     // fromEnv is true ONLY when the resolved value came from env (no inline override).
@@ -1965,8 +2021,9 @@ agent
             "to keep secrets out of shell history.");
     }
     const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? process.env.HDB_ADMIN_PASSWORD ?? "";
+    const mode = render.resolveOutputMode(opts);
+    let agents;
     if (adminPass) {
-        // Use admin basic auth against ops API to list agents directly
         const opsPort = resolveOpsPort(opts);
         const auth = Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64");
         const res = await fetch(`http://127.0.0.1:${opsPort}/`, {
@@ -1976,39 +2033,79 @@ agent
         });
         if (!res.ok) {
             const text = await res.text().catch(() => "");
-            console.error(`Error: ${res.status} ${text}`);
+            console.error(`${render.icons.error} ${res.status} ${text}`);
             process.exit(1);
         }
-        const agents = await res.json();
-        agents.sort((a, b) => (a.createdAt ?? "").localeCompare(b.createdAt ?? ""));
-        console.log(JSON.stringify(agents, null, 2));
+        agents = await res.json();
     }
     else {
-        // 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}`);
+            console.error(`${render.icons.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));
-        }
+        agents = Array.isArray(data) ? data.map((a) => ({ id: a.id, name: a.name, createdAt: a.createdAt })) : [];
+    }
+    agents.sort((a, b) => (a.createdAt ?? "").localeCompare(b.createdAt ?? ""));
+    if (mode === "json") {
+        console.log(render.asJSON(agents));
+        return;
     }
+    if (agents.length === 0) {
+        console.log(`${render.icons.info} ${render.wrap(render.c.dim, "no agents")}`);
+        return;
+    }
+    console.log(`${render.wrap(render.c.bold, String(agents.length))} agents\n`);
+    const cols = [
+        { label: "id", key: "id", format: (v) => render.wrap(render.c.bold, String(v ?? "—")) },
+        { label: "name", key: "name", format: (v) => String(v ?? "—") },
+        { label: "created", key: "createdAt", format: (v) => render.wrap(render.c.dim, v ? String(v).slice(0, 10) : "—") },
+    ];
+    console.log(render.table(cols, agents));
 });
 agent
     .command("show <id>")
     .description("Show agent details")
-    .action(async (id) => console.log(JSON.stringify(await api("GET", `/Agent/${id}`), null, 2)));
+    .option("--json", "Emit raw JSON response (also: pipe + FLAIR_OUTPUT=json)")
+    .action(async (id, opts) => {
+    const out = await api("GET", `/Agent/${id}`);
+    const mode = render.resolveOutputMode(opts);
+    if (mode === "json") {
+        console.log(render.asJSON(out));
+        return;
+    }
+    if (!out || (typeof out === "object" && !out.id)) {
+        console.log(`${render.icons.info} ${render.wrap(render.c.dim, `no agent ${id}`)}`);
+        return;
+    }
+    console.log(render.wrap(render.c.bold, String(out.id)));
+    if (out.name)
+        console.log(render.kv("name", String(out.name)));
+    if (out.kind)
+        console.log(render.kv("kind", render.wrap(render.c.cyan, String(out.kind))));
+    if (out.status) {
+        const statusColor = out.status === "active" ? render.c.green : out.status === "disabled" ? render.c.red : render.c.yellow;
+        console.log(render.kv("status", render.wrap(statusColor, String(out.status))));
+    }
+    if (out.defaultTrustTier)
+        console.log(render.kv("trust tier", String(out.defaultTrustTier)));
+    if (out.admin)
+        console.log(render.kv("admin", render.wrap(render.c.magenta, "yes")));
+    if (out.runtime)
+        console.log(render.kv("runtime", String(out.runtime)));
+    if (out.publicKey)
+        console.log(render.kv("publicKey", render.wrap(render.c.dim, String(out.publicKey))));
+    if (out.createdAt)
+        console.log(render.kv("created", `${render.relativeTime(out.createdAt)} ${render.wrap(render.c.dim, `(${out.createdAt})`)}`));
+    if (out.updatedAt && out.updatedAt !== out.createdAt) {
+        console.log(render.kv("updated", `${render.relativeTime(out.updatedAt)} ${render.wrap(render.c.dim, `(${out.updatedAt})`)}`));
+    }
+});
 agent
     .command("rotate-key <id>")
     .description("Rotate an agent's Ed25519 keypair")
@@ -2295,11 +2392,12 @@ principal
     .option("--admin-pass <pass>", "Admin password (or set FLAIR_ADMIN_PASS)")
     .option("--port <port>", "Harper HTTP port")
     .option("--ops-port <port>", "Harper operations API port")
+    .option("--json", "Emit raw JSON array (also: pipe + FLAIR_OUTPUT=json)")
     .action(async (opts) => {
     const opsPort = resolveOpsPort(opts);
     const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
     if (!adminPass) {
-        console.error("Error: --admin-pass or FLAIR_ADMIN_PASS required");
+        console.error(`${render.icons.error} --admin-pass or FLAIR_ADMIN_PASS required`);
         process.exit(1);
     }
     const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
@@ -2320,34 +2418,90 @@ principal
     });
     if (!res.ok) {
         const text = await res.text().catch(() => "");
-        console.error(`Error: ${res.status} ${text}`);
+        console.error(`${render.icons.error} ${res.status} ${text}`);
         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.");
+    const mode = render.resolveOutputMode(opts);
+    if (mode === "json") {
+        console.log(render.asJSON(records));
         return;
     }
-    // Table format
-    console.log(`${"ID".padEnd(20)} ${"Kind".padEnd(7)} ${"Trust".padEnd(14)} ${"Admin".padEnd(6)} ${"Status".padEnd(12)} ${"Runtime".padEnd(12)} Created`);
-    console.log("─".repeat(95));
-    for (const r of records) {
-        const kind = r.kind ?? "agent";
-        const trust = r.defaultTrustTier ?? "—";
-        const admin = r.admin ? "yes" : "no";
-        const status = r.status ?? "active";
-        const runtime = r.runtime ?? "—";
-        const created = r.createdAt?.slice(0, 10) ?? "—";
-        console.log(`${String(r.id).padEnd(20)} ${kind.padEnd(7)} ${trust.padEnd(14)} ${admin.padEnd(6)} ${status.padEnd(12)} ${runtime.padEnd(12)} ${created}`);
+    if (records.length === 0) {
+        console.log(`${render.icons.info} ${render.wrap(render.c.dim, "no principals")}`);
+        return;
     }
+    console.log(`${render.wrap(render.c.bold, String(records.length))} principals${opts.kind ? ` ${render.wrap(render.c.dim, `(kind=${opts.kind})`)}` : ""}\n`);
+    const cols = [
+        { label: "id", key: "id", format: (v) => render.wrap(render.c.bold, String(v ?? "—")) },
+        {
+            label: "kind",
+            key: "kind",
+            format: (v) => {
+                const k = String(v ?? "agent");
+                return render.wrap(k === "human" ? render.c.cyan : render.c.magenta, k);
+            },
+        },
+        { label: "trust", key: "defaultTrustTier", format: (v) => String(v ?? "—") },
+        {
+            label: "admin",
+            key: "admin",
+            format: (v) => (v ? render.wrap(render.c.red, "yes") : render.wrap(render.c.dim, "no")),
+        },
+        {
+            label: "status",
+            key: "status",
+            format: (v) => {
+                const s = String(v ?? "active");
+                const color = s === "active" ? render.c.green : s === "disabled" ? render.c.red : render.c.yellow;
+                return render.wrap(color, s);
+            },
+        },
+        { label: "runtime", key: "runtime", format: (v) => String(v ?? "—") },
+        { label: "created", key: "createdAt", format: (v) => render.wrap(render.c.dim, v ? String(v).slice(0, 10) : "—") },
+    ];
+    console.log(render.table(cols, records));
 });
 principal
     .command("show <id>")
     .description("Show principal details")
-    .action(async (id) => {
+    .option("--json", "Emit raw JSON response (also: pipe + FLAIR_OUTPUT=json)")
+    .action(async (id, opts) => {
     const result = await api("GET", `/Agent/${id}`);
-    console.log(JSON.stringify(result, null, 2));
+    const mode = render.resolveOutputMode(opts);
+    if (mode === "json") {
+        console.log(render.asJSON(result));
+        return;
+    }
+    if (!result || (typeof result === "object" && !result.id)) {
+        console.log(`${render.icons.info} ${render.wrap(render.c.dim, `no principal ${id}`)}`);
+        return;
+    }
+    console.log(render.wrap(render.c.bold, String(result.id)));
+    if (result.name)
+        console.log(render.kv("name", String(result.name)));
+    if (result.kind)
+        console.log(render.kv("kind", render.wrap(result.kind === "human" ? render.c.cyan : render.c.magenta, String(result.kind))));
+    if (result.status) {
+        const statusColor = result.status === "active" ? render.c.green : result.status === "disabled" ? render.c.red : render.c.yellow;
+        console.log(render.kv("status", render.wrap(statusColor, String(result.status))));
+    }
+    if (result.defaultTrustTier)
+        console.log(render.kv("trust tier", String(result.defaultTrustTier)));
+    if (result.admin)
+        console.log(render.kv("admin", render.wrap(render.c.red, "yes")));
+    if (result.runtime)
+        console.log(render.kv("runtime", String(result.runtime)));
+    if (result.email)
+        console.log(render.kv("email", String(result.email)));
+    if (result.publicKey)
+        console.log(render.kv("publicKey", render.wrap(render.c.dim, String(result.publicKey))));
+    if (result.createdAt)
+        console.log(render.kv("created", `${render.relativeTime(result.createdAt)} ${render.wrap(render.c.dim, `(${result.createdAt})`)}`));
+    if (result.updatedAt && result.updatedAt !== result.createdAt) {
+        console.log(render.kv("updated", `${render.relativeTime(result.updatedAt)} ${render.wrap(render.c.dim, `(${result.updatedAt})`)}`));
+    }
 });
 principal
     .command("disable <id>")
@@ -2475,11 +2629,12 @@ idp
     .description("List configured IdPs")
     .option("--admin-pass <pass>", "Admin password")
     .option("--ops-port <port>", "Harper operations API port")
+    .option("--json", "Emit raw JSON array (also: pipe + FLAIR_OUTPUT=json)")
     .action(async (opts) => {
     const opsPort = resolveOpsPort(opts);
     const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
     if (!adminPass) {
-        console.error("Error: --admin-pass or FLAIR_ADMIN_PASS required");
+        console.error(`${render.icons.error} --admin-pass or FLAIR_ADMIN_PASS required`);
         process.exit(1);
     }
     const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
@@ -2498,22 +2653,28 @@ idp
     });
     if (!res.ok) {
         const text = await res.text().catch(() => "");
-        console.error(`Error: ${res.status} ${text}`);
+        console.error(`${render.icons.error} ${res.status} ${text}`);
         process.exit(1);
     }
     const records = await res.json();
     records.sort((a, b) => (a.createdAt ?? "").localeCompare(b.createdAt ?? ""));
+    const mode = render.resolveOutputMode(opts);
+    if (mode === "json") {
+        console.log(render.asJSON(records));
+        return;
+    }
     if (records.length === 0) {
-        console.log("No IdPs configured.");
+        console.log(`${render.icons.info} ${render.wrap(render.c.dim, "no IdPs configured")}`);
         return;
     }
+    console.log(`${render.wrap(render.c.bold, String(records.length))} IdP${records.length === 1 ? "" : "s"}\n`);
     for (const r of records) {
-        const status = r.enabled ? "enabled" : "disabled";
-        console.log(`${r.name} (${r.id}) — ${status}`);
-        console.log(`  Issuer: ${r.issuer}`);
+        const enabled = r.enabled ? render.wrap(render.c.green, "enabled") : render.wrap(render.c.dim, "disabled");
+        console.log(`${render.wrap(render.c.bold, r.name ?? "?")}  ${render.wrap(render.c.dim, `(${r.id})`)}  ${render.wrap(render.c.dim, "—")}  ${enabled}`);
+        console.log(render.kv("issuer", String(r.issuer ?? "—")));
         if (r.requiredDomain)
-            console.log(`  Domain: ${r.requiredDomain}`);
-        console.log(`  JIT: ${r.jitProvision ?? true}`);
+            console.log(render.kv("domain", String(r.requiredDomain)));
+        console.log(render.kv("JIT", String(r.jitProvision ?? true)));
         console.log();
     }
 });
@@ -2727,65 +2888,117 @@ federation
     .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)")
+    .option("--json", "Emit JSON {instance, peers} (also: pipe + FLAIR_OUTPUT=json)")
     .action(async (opts) => {
     const target = resolveTarget(opts);
     const baseUrl = target ? target.replace(/\/$/, "") : undefined;
+    const mode = render.resolveOutputMode(opts);
     try {
         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", undefined, baseUrl ? { baseUrl } : undefined);
+        if (mode === "json") {
+            console.log(render.asJSON({ instance, peers }));
+            return;
+        }
+        const statusColor = instance.status === "active" ? render.c.green : render.c.yellow;
+        console.log(render.wrap(render.c.bold, "Federation"));
+        console.log(render.kv("Instance", `${instance.id}  ${render.wrap(render.c.dim, `(${instance.role})`)}`));
+        console.log(render.kv("Public key", render.wrap(render.c.dim, instance.publicKey)));
+        console.log(render.kv("Status", render.wrap(statusColor, instance.status)));
         if (peers.length === 0) {
-            console.log("No peers configured. Use 'flair federation pair' to connect to a hub.");
+            console.log(`\n${render.icons.info} ${render.wrap(render.c.dim, "No peers configured. Use 'flair federation pair' to connect to a hub.")}`);
+            return;
         }
-        else {
-            // Compute lastSync staleness so an operator can tell at a glance whether sync is current.
-            const now = Date.now();
-            const stale = (iso) => {
-                if (!iso)
-                    return "never";
-                const t = Date.parse(iso);
-                if (!Number.isFinite(t))
-                    return "never";
-                const ageMs = now - t;
-                if (ageMs < 60_000)
-                    return "<1m ago";
-                if (ageMs < 3_600_000)
-                    return `${Math.floor(ageMs / 60_000)}m ago`;
-                if (ageMs < 86_400_000)
-                    return `${Math.floor(ageMs / 3_600_000)}h ago`;
-                return `${Math.floor(ageMs / 86_400_000)}d ago`;
-            };
-            console.log(`${"Peer".padEnd(20)} ${"Role".padEnd(8)} ${"Status".padEnd(14)} ${"Last Sync".padEnd(14)} Relay`);
-            console.log("─".repeat(80));
-            for (const p of peers) {
-                console.log(`${p.id.padEnd(20)} ${(p.role ?? "—").padEnd(8)} ${(p.status ?? "—").padEnd(14)} ${stale(p.lastSyncAt).padEnd(14)} ${p.relayOnly ? "yes" : "no"}`);
-            }
-            const haveStale = peers.some((p) => {
-                if (!p.lastSyncAt)
-                    return true;
-                return now - Date.parse(p.lastSyncAt) > 86_400_000;
-            });
-            if (haveStale) {
-                console.log();
-                console.log("⚠  One or more peers haven't synced in >24h. Run 'flair federation sync' or check the launchd watchdog.");
-            }
+        const now = Date.now();
+        const formatPeerAge = (iso, refNow, staleAfterMs) => {
+            if (!iso)
+                return render.wrap(render.c.red, "never");
+            const t = Date.parse(iso);
+            if (!Number.isFinite(t))
+                return render.wrap(render.c.red, "never");
+            const ageMs = refNow - t;
+            const ageStr = ageMs < 60_000 ? "<1m ago"
+                : ageMs < 3_600_000 ? `${Math.floor(ageMs / 60_000)}m ago`
+                    : ageMs < 86_400_000 ? `${Math.floor(ageMs / 3_600_000)}h ago`
+                        : `${Math.floor(ageMs / 86_400_000)}d ago`;
+            const stale = ageMs > staleAfterMs;
+            return render.wrap(stale ? render.c.yellow : render.c.dim, ageStr);
+        };
+        console.log();
+        const cols = [
+            { label: "peer", key: "id" },
+            { label: "role", key: "role", format: (v) => String(v ?? "—") },
+            {
+                label: "status",
+                key: "status",
+                format: (v) => {
+                    const s = String(v ?? "—");
+                    const color = s === "paired" || s === "connected" || s === "active" ? render.c.green : s === "revoked" ? render.c.red : render.c.yellow;
+                    return render.wrap(color, s);
+                },
+            },
+            {
+                // Liveness: "did we hear from this peer recently?" Updates on every
+                // contact, even when 100% of records were skipped. See flair#444.
+                label: "last_sync",
+                key: "lastSyncAt",
+                format: (v) => formatPeerAge(v, now, 86_400_000),
+            },
+            {
+                // Progress: "did data actually flow in?" Updates only when merged>0.
+                // Diverging from last_sync means contact-yes but data-no — investigate.
+                label: "last_merge",
+                key: "lastMergeAt",
+                format: (v) => formatPeerAge(v, now, 86_400_000),
+            },
+            {
+                label: "relay",
+                key: "relayOnly",
+                format: (v) => (v ? render.wrap(render.c.cyan, "yes") : render.wrap(render.c.dim, "no")),
+            },
+        ];
+        console.log(render.table(cols, peers));
+        // Stale warning is gated on lastMergeAt (real progress), not lastSyncAt.
+        // A peer that "syncs" every 5min but hasn't merged a record in 24h is
+        // exactly the failure mode we want surfaced.
+        const haveStale = peers.some((p) => {
+            const cursor = p.lastMergeAt ?? p.lastSyncAt;
+            if (!cursor)
+                return true;
+            const t = Date.parse(cursor);
+            return !Number.isFinite(t) || (now - t) > 86_400_000;
+        });
+        if (haveStale) {
+            console.log();
+            console.log(`${render.icons.warn} ${render.wrap(render.c.yellow, "One or more peers haven't merged a record in >24h.")} ${render.wrap(render.c.dim, "Check skippedReasons in SyncLog or run 'flair federation sync'.")}`);
+        }
+        const haveContactButNoMerge = peers.some((p) => {
+            if (!p.lastSyncAt || !Number.isFinite(Date.parse(p.lastSyncAt)))
+                return false;
+            if ((now - Date.parse(p.lastSyncAt)) > 3_600_000)
+                return false; // only recent contact
+            // Contact within the last hour, but no merge ever (or stale by >1h)
+            if (!p.lastMergeAt)
+                return true;
+            const tm = Date.parse(p.lastMergeAt);
+            return !Number.isFinite(tm) || (now - tm) > 3_600_000;
+        });
+        if (haveContactButNoMerge && !haveStale) {
+            console.log();
+            console.log(`${render.icons.warn} ${render.wrap(render.c.yellow, "Peer contact is fresh but no records merged in the last hour.")} ${render.wrap(render.c.dim, "Possible silent-skip scenario — check SyncLog.skippedReasons.")}`);
         }
     }
     catch (err) {
-        // Better UX on the common auth failure: tell the user what to set.
         const msg = String(err.message ?? err);
         if (msg.includes("missing_or_invalid_authorization") || msg.includes("401")) {
-            console.error("Error: federation status requires auth.");
-            console.error("  Set one of:");
-            console.error("    FLAIR_AGENT_ID=<your-agent-id>     (Ed25519 — uses ~/.flair/keys/<id>.key)");
-            console.error("    FLAIR_ADMIN_PASS=<admin-password>  (admin Basic auth, remote targets)");
-            console.error("    FLAIR_TOKEN=<bearer>               (legacy)");
+            console.error(`${render.icons.error} federation status requires auth.`);
+            console.error(`  ${render.wrap(render.c.dim, "Set one of:")}`);
+            console.error(`    ${render.wrap(render.c.cyan, "FLAIR_AGENT_ID=<your-agent-id>")}     ${render.wrap(render.c.dim, "(Ed25519 — uses ~/.flair/keys/<id>.key)")}`);
+            console.error(`    ${render.wrap(render.c.cyan, "FLAIR_ADMIN_PASS=<admin-password>")}  ${render.wrap(render.c.dim, "(admin Basic auth, remote targets)")}`);
+            console.error(`    ${render.wrap(render.c.cyan, "FLAIR_TOKEN=<bearer>")}               ${render.wrap(render.c.dim, "(legacy)")}`);
             process.exit(1);
         }
-        console.error(`Error: ${msg}`);
+        console.error(`${render.icons.error} ${msg}`);
         process.exit(1);
     }
 });
@@ -3002,28 +3215,45 @@ federation
         }
         const result = await res.json();
         console.log(`✅ Paired with hub: ${result.instance?.id ?? hubUrl}`);
-        // 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")}`;
-            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({
-                    operation: "upsert", database: "flair", table: "Peer",
-                    records: [{
-                            id: result.instance?.id ?? "hub",
-                            publicKey: result.instance?.publicKey ?? "",
-                            role: "hub", endpoint: hubUrl, status: "paired",
-                            pairedAt: new Date().toISOString(),
-                            createdAt: new Date().toISOString(),
-                            updatedAt: new Date().toISOString(),
-                        }],
-                }),
-                signal: AbortSignal.timeout(10_000),
-            });
+        // Record the hub as our local peer. This is REQUIRED, not optional:
+        // `flair federation sync` reads the Peer table to find the hub, so
+        // without this record sync reports "No hub peer configured" and silently
+        // never runs. Previously this was gated on `if (adminPass)` and the write
+        // result was never checked — pairing with only an agent key (or a failed
+        // upsert) left no peer behind a misleadingly green "✅ Paired".
+        const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? process.env.HDB_ADMIN_PASSWORD ?? "";
+        if (!adminPass) {
+            console.error("Error: paired on the hub, but the local hub-peer record needs admin auth to write — " +
+                "pass --admin-pass, or set FLAIR_ADMIN_PASS / HDB_ADMIN_PASSWORD, then re-run pair. " +
+                "Without it, 'flair federation sync' will report 'No hub peer configured'.");
+            process.exit(1);
+        }
+        const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
+        const opsEndpoint = resolveEffectiveOpsUrl(opts) ?? `http://127.0.0.1:${resolveOpsPort(opts)}`;
+        const peerRes = await fetch(`${opsEndpoint}/`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Authorization: auth },
+            body: JSON.stringify({
+                operation: "upsert", database: "flair", table: "Peer",
+                records: [{
+                        id: result.instance?.id ?? "hub",
+                        publicKey: result.instance?.publicKey ?? "",
+                        role: "hub", endpoint: hubUrl, status: "paired",
+                        pairedAt: new Date().toISOString(),
+                        createdAt: new Date().toISOString(),
+                        updatedAt: new Date().toISOString(),
+                    }],
+            }),
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!peerRes.ok) {
+            const text = await peerRes.text().catch(() => "");
+            console.error(`Error: paired with the hub but failed to write the local hub-peer record ` +
+                `(${peerRes.status} ${text.slice(0, 200)}). Ops endpoint: ${opsEndpoint}. ` +
+                `'flair federation sync' will not find the hub until this succeeds — check --admin-pass and the ops port.`);
+            process.exit(1);
         }
+        console.log(`✅ Recorded hub as local peer: ${result.instance?.id ?? "hub"} → ${hubUrl}`);
     }
     catch (err) {
         console.error(`Error: ${err.message}`);
@@ -3146,6 +3376,12 @@ export async function runFederationSyncOnce(opts) {
         }
         console.log(`Syncing to hub: ${hub.id}...`);
         const since = hub.lastSyncAt ?? new Date(0).toISOString();
+        // Capture sync start time BEFORE we query records. We advance the local
+        // hub peer's lastSyncAt to this value after success so the next poll's
+        // `since` cursor moves forward — fixes task #146 (federation peer
+        // .lastSyncAt update bug). Records updated DURING this sync will have
+        // updatedAt > syncStartedAt and be picked up next cycle, not missed.
+        const syncStartedAt = new Date().toISOString();
         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")}`;
@@ -3154,25 +3390,63 @@ export async function runFederationSyncOnce(opts) {
         const hubUrl = hub.endpoint ?? hub.id;
         // ── Batching constants ──────────────────────────────────────────────
         // 2MB JSON budget (server cap is 10MB; 2MB leaves headroom for headers
-        // and signature metadata) + 200 records max per batch.
+        // and signature metadata) + 50 records max per batch. The hub merge itself
+        // is fast (~1.7s/50 records, per its SyncLog), but the Fabric ingress was
+        // observed to intermittently stall on larger POSTs — a 50-record batch hung
+        // ~2 min while the same records split into 2×25 went through immediately.
+        // 50 keeps batches in the reliable range, and sendBatch's adaptive split
+        // recovers if a stretch still stalls.
         const BUDGET_BYTES = 2_000_000;
-        const BUDGET_RECORDS = 200;
+        const BUDGET_RECORDS = 50;
         // ── sendBatch helper ────────────────────────────────────────────────
         // Secret key is lazy-loaded: only needed when there are records to send.
         // Loading earlier would cause a spurious error when SQL queries fail
         // (e.g. 401) before we know we have records.
         let secretKey;
+        // Statuses the Fabric ingress returns when a batch POST didn't complete in
+        // time (408) or was too large (413), plus the transient gateway 5xx family.
+        // Splitting the batch and retrying smaller chunks lets the sync converge
+        // instead of aborting the whole run.
+        const TIMEOUT_STATUSES = new Set([408, 413, 502, 503, 504]);
+        // Per-batch wall-clock cap. Without it a stalled connection to the Fabric
+        // ingress hangs the whole sync until the *gateway's* timeout fires (~2 min
+        // observed), which is what stranded the re-pair. A 45s cap is generous —
+        // a healthy 50-record batch merges in <2s — so a trip means a real stall,
+        // and we split-and-retry rather than wait it out.
+        const BATCH_TIMEOUT_MS = 45_000;
         async function sendBatch(batch) {
             if (!secretKey)
                 secretKey = await loadInstanceSecretKey(instance.id, opts);
             const syncBody = { instanceId: instance.id, records: batch, lamportClock: Date.now() };
             const signedSyncBody = signBodyFresh(syncBody, secretKey);
-            const syncRes = await fetch(`${hubUrl}/FederationSync`, {
-                method: "POST",
-                headers: { "Content-Type": "application/json" },
-                body: JSON.stringify(signedSyncBody),
-            });
+            // Halve and retry down to a single record. Covers both an explicit
+            // timeout status AND a client-side abort (stalled socket). The hub
+            // merges idempotently (put-by-id), so retried records are safe.
+            const splittable = (status) => batch.length > 1 && (status === null || TIMEOUT_STATUSES.has(status));
+            const split = async () => {
+                const mid = Math.floor(batch.length / 2);
+                const left = await sendBatch(batch.slice(0, mid));
+                const right = await sendBatch(batch.slice(mid));
+                return { merged: left.merged + right.merged, skipped: left.skipped + right.skipped };
+            };
+            let syncRes;
+            try {
+                syncRes = await fetch(`${hubUrl}/FederationSync`, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify(signedSyncBody),
+                    signal: AbortSignal.timeout(BATCH_TIMEOUT_MS),
+                });
+            }
+            catch (err) {
+                // Timeout/abort or network drop — no status. Split if we can.
+                if (splittable(null))
+                    return await split();
+                throw new Error(`Sync batch (${batch.length} record${batch.length === 1 ? "" : "s"}) failed: ${err?.message ?? err}`);
+            }
             if (!syncRes.ok) {
+                if (splittable(syncRes.status))
+                    return await split();
                 const text = await syncRes.text().catch(() => "");
                 throw new Error(`Sync batch failed: ${syncRes.status} ${text}`);
             }
@@ -3224,6 +3498,35 @@ export async function runFederationSyncOnce(opts) {
                 totalBatches++;
             }
         }
+        // Advance the local hub peer's lastSyncAt cursor. The hub-side
+        // FederationSync handler updates ITS view of the spoke peer, but the
+        // spoke never updated its own view of the hub — so `since` stayed at
+        // whatever value was on the peer record at pair time (often near-epoch),
+        // and every poll re-queried `updatedAt > since` and re-sent every
+        // memory ever written. The receiver-side contentHash gate in
+        // Federation.ts prevents the actual blob re-write, but advancing the
+        // cursor here stops the redundant network traffic + Lambda compute
+        // entirely. Task #146. Even no-change runs should advance.
+        try {
+            const advanceRes = await fetch(`${opsEndpoint}/`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json", Authorization: auth },
+                body: JSON.stringify({
+                    operation: "update",
+                    database: "flair",
+                    table: "Peer",
+                    records: [{ id: hub.id, lastSyncAt: syncStartedAt }],
+                }),
+                signal: AbortSignal.timeout(10_000),
+            });
+            if (!advanceRes.ok) {
+                const txt = await advanceRes.text().catch(() => "");
+                console.warn(`⚠️  Local hub.lastSyncAt advance failed (${advanceRes.status}): ${txt.slice(0, 200)}. Next poll will re-send memories.`);
+            }
+        }
+        catch (advErr) {
+            console.warn(`⚠️  Local hub.lastSyncAt advance error: ${advErr?.message ?? advErr}. Next poll will re-send memories.`);
+        }
         if (totalBatches === 0) {
             console.log("No changes since last sync.");
             return { pushed: 0, skipped: 0 };
@@ -3784,7 +4087,7 @@ rem
         process.exit(1);
     }
     if (!agentId) {
-        console.error("Error: --agent is required (or set FLAIR_AGENT_ID)");
+        console.error(`${render.icons.error} --agent is required (or set FLAIR_AGENT_ID)`);
         process.exit(1);
     }
     try {
@@ -3796,42 +4099,49 @@ rem
             ],
             get_attributes: ["id", "claim", "generatedBy", "generatedAt", "status", "target", "reviewerId", "decidedAt", "supersedes"],
         });
-        // search_by_conditions returns either an array or { error }; tolerate both shapes
         const candidates = Array.isArray(result) ? result : (result?.results ?? []);
-        if (opts.json) {
-            console.log(JSON.stringify({ agentId, status, count: candidates.length, candidates }, null, 2));
+        const mode = render.resolveOutputMode(opts);
+        if (mode === "json") {
+            console.log(render.asJSON({ agentId, status, count: candidates.length, candidates }));
             return;
         }
-        console.log(`\n-- rem candidates (agent=${agentId}, status=${status}) --\n`);
+        const statusColor = status === "promoted" ? render.c.green : status === "rejected" ? render.c.red : render.c.yellow;
+        console.log(`${render.wrap(render.c.bold, "REM candidates")}  ${render.wrap(render.c.dim, "—")} agent ${render.wrap(render.c.bold, agentId)} ${render.wrap(render.c.dim, "·")} ${render.wrap(statusColor, status)}`);
         if (candidates.length === 0) {
-            console.log(`No ${status} candidates.`);
+            console.log(`\n${render.icons.info} ${render.wrap(render.c.dim, `No ${status} candidates.`)}`);
             if (status === "pending") {
-                console.log("\n(Run `flair rem nightly enable` to start the nightly distillation cycle that populates this table.)");
+                console.log(`${render.wrap(render.c.dim, "  Run")} flair rem nightly enable ${render.wrap(render.c.dim, "to start the nightly distillation cycle that populates this table.")}`);
             }
             return;
         }
-        // Sort newest-first by generatedAt
         candidates.sort((a, b) => String(b.generatedAt ?? "").localeCompare(String(a.generatedAt ?? "")));
+        console.log();
         for (const c of candidates) {
-            const tag = c.status === "promoted"
-                ? `[promoted → ${c.target ?? "?"} by ${c.reviewerId ?? "?"} @ ${relativeTime(c.decidedAt)}]`
-                : c.status === "rejected"
-                    ? `[rejected by ${c.reviewerId ?? "?"} @ ${relativeTime(c.decidedAt)}]`
-                    : `[pending — ${c.generatedBy ?? "?"} @ ${relativeTime(c.generatedAt)}]`;
-            console.log(`  ${c.id}  ${tag}`);
+            let tag;
+            if (c.status === "promoted") {
+                tag = `${render.wrap(render.c.green, "✓ promoted")} ${render.wrap(render.c.dim, "→")} ${render.wrap(render.c.bold, c.target ?? "?")} ${render.wrap(render.c.dim, `by ${c.reviewerId ?? "?"} ${render.relativeTime(c.decidedAt)}`)}`;
+            }
+            else if (c.status === "rejected") {
+                tag = `${render.wrap(render.c.red, "✗ rejected")} ${render.wrap(render.c.dim, `by ${c.reviewerId ?? "?"} ${render.relativeTime(c.decidedAt)}`)}`;
+            }
+            else {
+                tag = `${render.wrap(render.c.yellow, "○ pending")} ${render.wrap(render.c.dim, `— ${c.generatedBy ?? "?"} ${render.relativeTime(c.generatedAt)}`)}`;
+            }
+            console.log(`  ${render.wrap(render.c.dim, c.id)}  ${tag}`);
             console.log(`    ${c.claim}`);
-            if (c.supersedes)
-                console.log(`    (supersedes ${c.supersedes} — recurring proposal)`);
+            if (c.supersedes) {
+                console.log(`    ${render.wrap(render.c.dim, `(supersedes ${c.supersedes} — recurring proposal)`)}`);
+            }
             console.log("");
         }
-        console.log(`${candidates.length} candidate${candidates.length > 1 ? "s" : ""}.`);
+        console.log(`${render.wrap(render.c.bold, String(candidates.length))} candidate${candidates.length > 1 ? "s" : ""}.`);
         if (status === "pending") {
-            console.log(`Promote: flair rem promote <id> --rationale "<why>" --to (soul|memory)`);
-            console.log(`Reject:  flair rem reject <id> --reason "<why>"`);
+            console.log(`${render.wrap(render.c.dim, "Promote:")} flair rem promote <id> --rationale "<why>" --to (soul|memory)`);
+            console.log(`${render.wrap(render.c.dim, "Reject: ")} flair rem reject <id> --reason "<why>"`);
         }
     }
     catch (err) {
-        console.error(`Error: ${err.message}`);
+        console.error(`${render.icons.error} ${err.message}`);
         process.exit(1);
     }
 });
@@ -4438,7 +4748,7 @@ function oauthDetailLines(o) {
 // discoverLocalFlairPort when the configured URL is unreachable, to detect
 // config-vs-daemon port drift (ops-mbdi). Order is ad-hoc — first hit wins.
 //
-// 9926: original default (long-running rockit installs predate the bump)
+// 9926: original default (long-running early installs predate the bump)
 // 19926: current default (DEFAULT_PORT)
 // 19925: ops-anvil VM secondary
 const LOCAL_FLAIR_PROBE_PORTS = [9926, 19926, 19925];
@@ -4626,139 +4936,176 @@ const statusCmd = program
         })
         : 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}`);
+    const headerIcon = hasWarn ? render.icons.warn : render.icons.ok;
+    const versionStr = render.wrap(render.c.bold, `Flair v${__pkgVersion}`);
+    const runStatus = `${headerIcon} ${render.wrap(render.c.green, "running")}`;
+    const pidPart = pid ? render.wrap(render.c.dim, `PID ${pid}`) : "";
+    const uptimePart = uptimeStr ? render.wrap(render.c.dim, `uptime ${uptimeStr}`) : "";
+    const metaParts = [pidPart, uptimePart].filter(Boolean).join(render.wrap(render.c.dim, " · "));
+    console.log(`${versionStr} ${render.wrap(render.c.dim, "—")} ${runStatus}${metaParts ? `  ${metaParts}` : ""}`);
+    console.log(render.kv("URL", baseUrl));
     if (scopedWarnings.length > 0) {
-        console.log(`\n⚠ Warnings:  ${scopedWarnings.length}`);
-        for (const w of scopedWarnings)
-            console.log(`  • ${w.level} ${w.message}`);
+        console.log(`\n${render.wrap(render.c.bold, "Warnings")}  ${render.wrap(render.c.dim, `(${scopedWarnings.length})`)}`);
+        for (const w of scopedWarnings) {
+            const icon = w.level === "warn" ? render.icons.warn : render.icons.info;
+            console.log(`  ${icon} ${w.message}`);
+        }
     }
     if (memories) {
-        console.log("\nMemory:");
+        console.log(`\n${render.wrap(render.c.bold, "Memory")}`);
         const embStr = memories.withEmbeddings > 0 ? `${memories.withEmbeddings} embedded` : "";
         const hashStr = memories.hashFallback > 0 ? `${memories.hashFallback} hash` : "";
         const detail = [embStr, hashStr].filter(Boolean).join(", ");
-        console.log(`  Total:       ${memories.total}${detail ? ` (${detail})` : ""}`);
+        console.log(render.kv("Total", `${render.wrap(render.c.bold, String(memories.total))}${detail ? ` ${render.wrap(render.c.dim, `(${detail})`)}` : ""}`));
         if (memories.modelCounts && typeof memories.modelCounts === "object") {
             const entries = Object.entries(memories.modelCounts)
                 .filter(([, n]) => n > 0)
                 .sort((a, b) => b[1] - a[1]);
             if (entries.length > 0) {
-                const formatted = entries.map(([k, n]) => `${k}: ${n}`).join(", ");
-                console.log(`  Embeddings:  ${formatted}`);
+                const formatted = entries.map(([k, n]) => `${render.wrap(render.c.cyan, k)}:${n}`).join(render.wrap(render.c.dim, ", "));
+                console.log(render.kv("Embeddings", formatted));
             }
         }
         if (memories.byDurability) {
             const d = memories.byDurability;
-            console.log(`  Durability:  ${d.permanent ?? 0} permanent / ${d.persistent ?? 0} persistent / ${d.standard ?? 0} standard / ${d.ephemeral ?? 0} ephemeral`);
+            const parts = [
+                `${render.wrap(render.c.magenta, "permanent")}:${d.permanent ?? 0}`,
+                `${render.wrap(render.c.blue, "persistent")}:${d.persistent ?? 0}`,
+                `${render.wrap(render.c.cyan, "standard")}:${d.standard ?? 0}`,
+                `${render.wrap(render.c.gray, "ephemeral")}:${d.ephemeral ?? 0}`,
+            ];
+            console.log(render.kv("Durability", parts.join(render.wrap(render.c.dim, " · "))));
         }
         if (typeof memories.archived === "number")
-            console.log(`  Archived:    ${memories.archived}`);
-        if (typeof memories.expired === "number" && memories.expired > 0)
-            console.log(`  Expired:     ${memories.expired}`);
+            console.log(render.kv("Archived", String(memories.archived)));
+        if (typeof memories.expired === "number" && memories.expired > 0) {
+            console.log(render.kv("Expired", `${render.wrap(render.c.yellow, String(memories.expired))}`));
+        }
         if (healthData?.lastWrite)
-            console.log(`  Last write:  ${relativeTime(healthData.lastWrite)}`);
+            console.log(render.kv("Last write", render.relativeTime(healthData.lastWrite)));
     }
     if (agents && agents.count > 0) {
-        console.log("\nAgents:");
-        const nameStr = agents.names?.length > 0 ? ` — ${agents.names.join(", ")}` : "";
-        console.log(`  ${agents.count} total${nameStr}`);
+        console.log(`\n${render.wrap(render.c.bold, "Agents")}`);
+        const nameStr = agents.names?.length > 0 ? ` ${render.wrap(render.c.dim, "—")} ${agents.names.join(render.wrap(render.c.dim, ", "))}` : "";
+        console.log(render.kv("Total", `${render.wrap(render.c.bold, String(agents.count))}${nameStr}`));
         if (agents.count > 1 && Array.isArray(agents.perAgent) && agents.perAgent.length > 0) {
-            const idW = Math.max(2, ...agents.perAgent.map((r) => (r.id ?? "").length));
-            // Older HealthDetail responses only carry id / memoryCount / lastWriteAt.
-            // Only print the richer columns if at least one row supplies them.
             const hasDeep = agents.perAgent.some((r) => typeof r.hashFallback === "number" || typeof r.writes24h === "number");
-            if (hasDeep) {
-                console.log(`  ${"id".padEnd(idW)}  memories  hash_fb  24h  last_write`);
-                for (const r of agents.perAgent) {
-                    const fb = typeof r.hashFallback === "number" ? String(r.hashFallback) : "—";
-                    const w24 = typeof r.writes24h === "number" ? String(r.writes24h) : "—";
-                    console.log(`  ${(r.id ?? "").padEnd(idW)}  ${String(r.memoryCount).padStart(8)}  ${fb.padStart(7)}  ${w24.padStart(3)}  ${relativeTime(r.lastWriteAt)}`);
-                }
-            }
-            else {
-                console.log(`  ${"id".padEnd(idW)}  memories  last_write`);
-                for (const r of agents.perAgent) {
-                    console.log(`  ${(r.id ?? "").padEnd(idW)}  ${String(r.memoryCount).padStart(8)}  ${relativeTime(r.lastWriteAt)}`);
-                }
-            }
+            const cols = hasDeep
+                ? [
+                    { label: "id", key: "id" },
+                    { label: "memories", key: "memoryCount", align: "right" },
+                    { label: "hash_fb", key: "hashFallback", align: "right", format: (v) => (typeof v === "number" ? String(v) : "—") },
+                    { label: "24h", key: "writes24h", align: "right", format: (v) => (typeof v === "number" ? String(v) : "—") },
+                    { label: "last_write", key: "lastWriteAt", format: (v) => render.relativeTime(v) },
+                ]
+                : [
+                    { label: "id", key: "id" },
+                    { label: "memories", key: "memoryCount", align: "right" },
+                    { label: "last_write", key: "lastWriteAt", format: (v) => render.relativeTime(v) },
+                ];
+            console.log(render.table(cols, agents.perAgent));
         }
     }
     if (healthData?.relationships) {
         const r = healthData.relationships;
-        console.log("\nRelationships:");
-        console.log(`  ${r.total} total (${r.active} active)`);
+        console.log(`\n${render.wrap(render.c.bold, "Relationships")}`);
+        console.log(render.kv("Total", `${r.total}  ${render.wrap(render.c.dim, `(${r.active} active)`)}`));
     }
     if (healthData?.soul && healthData.soul.total > 0) {
         const s = healthData.soul;
-        const bp = s.byPriority ?? {};
-        console.log("\nSoul:");
-        console.log(`  ${s.total} entries — ${bp.critical ?? 0} critical / ${bp.high ?? 0} high / ${bp.standard ?? 0} standard / ${bp.low ?? 0} low`);
+        console.log(`\n${render.wrap(render.c.bold, "Soul")}`);
+        const entries = sortSoulKeyEntries(s.byKey ?? {});
+        const parts = entries.map(([k, n]) => `${render.wrap(render.c.cyan, k)}:${n}`);
+        const suffix = parts.length > 0
+            ? ` ${render.wrap(render.c.dim, "—")} ${parts.join(render.wrap(render.c.dim, " · "))}`
+            : "";
+        console.log(render.kv("Entries", `${render.wrap(render.c.bold, String(s.total))}${suffix}`));
     }
     else if (typeof healthData?.soulEntries === "number" && healthData.soulEntries > 0) {
-        console.log("\nSoul:");
-        console.log(`  ${healthData.soulEntries} entries`);
+        console.log(`\n${render.wrap(render.c.bold, "Soul")}`);
+        console.log(render.kv("Entries", String(healthData.soulEntries)));
     }
     if (healthData?.rem) {
         const r = healthData.rem;
-        console.log("\nREM:");
+        console.log(`\n${render.wrap(render.c.bold, "REM")}`);
         if (r.lastLightAt)
-            console.log(`  Last light:        ${relativeTime(r.lastLightAt)}`);
+            console.log(render.kv("Last light", render.relativeTime(r.lastLightAt)));
         if (r.lastRapidAt)
-            console.log(`  Last rapid:        ${relativeTime(r.lastRapidAt)}`);
+            console.log(render.kv("Last rapid", render.relativeTime(r.lastRapidAt)));
         if (r.lastRestorativeAt)
-            console.log(`  Last restorative:  ${relativeTime(r.lastRestorativeAt)}`);
-        const nightly = r.nightlyEnabled === true ? "enabled" : r.nightlyEnabled === false ? "disabled" : "unknown";
-        console.log(`  Nightly:           ${nightly}`);
+            console.log(render.kv("Last restorative", render.relativeTime(r.lastRestorativeAt)));
+        const nightlyTxt = r.nightlyEnabled === true
+            ? render.wrap(render.c.green, "enabled")
+            : r.nightlyEnabled === false
+                ? render.wrap(render.c.dim, "disabled")
+                : render.wrap(render.c.dim, "unknown");
+        console.log(render.kv("Nightly", nightlyTxt));
         if (r.nightlyEnabled && r.lastNightlyAt)
-            console.log(`  Last nightly:      ${relativeTime(r.lastNightlyAt)}`);
+            console.log(render.kv("Last nightly", render.relativeTime(r.lastNightlyAt)));
         if (typeof r.pendingCandidates === "number" && r.pendingCandidates > 0) {
-            console.log(`  Pending candidates: ${r.pendingCandidates}`);
+            console.log(render.kv("Pending candidates", render.wrap(render.c.yellow, String(r.pendingCandidates))));
         }
     }
     if (healthData?.federation) {
         const f = healthData.federation;
-        console.log("\nFederation:");
-        if (f.instance)
-            console.log(`  Instance:    ${f.instance.id} (${f.instance.role ?? "—"}, ${f.instance.status ?? "—"})`);
-        if (f.peers)
-            console.log(`  Peers:       ${f.peers.total} (${f.peers.connected} connected / ${f.peers.disconnected} down / ${f.peers.revoked} revoked)`);
+        console.log(`\n${render.wrap(render.c.bold, "Federation")}`);
+        if (f.instance) {
+            const statusColor = f.instance.status === "active" ? render.c.green : render.c.yellow;
+            console.log(render.kv("Instance", `${f.instance.id}  ${render.wrap(render.c.dim, "(")}${f.instance.role ?? "—"}${render.wrap(render.c.dim, ", ")}${render.wrap(statusColor, f.instance.status ?? "—")}${render.wrap(render.c.dim, ")")}`));
+        }
+        if (f.peers) {
+            const connColor = f.peers.connected > 0 ? render.c.green : render.c.dim;
+            const downColor = f.peers.disconnected > 0 ? render.c.yellow : render.c.dim;
+            const revColor = f.peers.revoked > 0 ? render.c.red : render.c.dim;
+            const parts = [
+                `${render.wrap(connColor, `${f.peers.connected} connected`)}`,
+                `${render.wrap(downColor, `${f.peers.disconnected} down`)}`,
+                `${render.wrap(revColor, `${f.peers.revoked} revoked`)}`,
+            ];
+            console.log(render.kv("Peers", `${render.wrap(render.c.bold, String(f.peers.total))} ${render.wrap(render.c.dim, "—")} ${parts.join(render.wrap(render.c.dim, " · "))}`));
+        }
         if (f.pendingTokens > 0)
-            console.log(`  Pairing:     ${f.pendingTokens} unconsumed token(s)`);
+            console.log(render.kv("Pairing", `${render.wrap(render.c.yellow, String(f.pendingTokens))} unconsumed token(s)`));
     }
     else {
-        console.log("\nFederation: not configured");
+        console.log(`\n${render.wrap(render.c.bold, "Federation")}  ${render.wrap(render.c.dim, "not configured")}`);
     }
     if (healthData?.oauth) {
         const lines = oauthSummaryLines(healthData.oauth);
-        for (const line of lines)
-            console.log(line);
+        // Tweak the "OAuth:" header to bold; downstream lines are aligned k/v which already look fine
+        for (const line of lines) {
+            if (line.trim() === "OAuth:")
+                console.log(`\n${render.wrap(render.c.bold, "OAuth")}`);
+            else
+                console.log(line);
+        }
     }
     if (healthData?.bridges) {
         const b = healthData.bridges;
-        console.log("\nBridges:");
+        console.log(`\n${render.wrap(render.c.bold, "Bridges")}`);
         if (Array.isArray(b.installed) && b.installed.length > 0)
-            console.log(`  Installed:   ${b.installed.join(", ")}`);
+            console.log(render.kv("Installed", b.installed.join(render.wrap(render.c.dim, ", "))));
         if (b.lastImport)
-            console.log(`  Last import: ${relativeTime(b.lastImport)}`);
+            console.log(render.kv("Last import", render.relativeTime(b.lastImport)));
         if (b.lastExport)
-            console.log(`  Last export: ${relativeTime(b.lastExport)}`);
+            console.log(render.kv("Last export", render.relativeTime(b.lastExport)));
     }
     else {
-        console.log("\nBridges: none installed");
+        console.log(`\n${render.wrap(render.c.bold, "Bridges")}  ${render.wrap(render.c.dim, "none installed")}`);
     }
     if (healthData?.disk) {
         const d = healthData.disk;
-        console.log("\nDisk:");
-        console.log(`  Data:        ${d.dataDir} — ${humanBytes(d.dataBytes ?? 0)}`);
-        console.log(`  Snapshots:   ${d.snapshotDir} — ${humanBytes(d.snapshotBytes ?? 0)}`);
+        console.log(`\n${render.wrap(render.c.bold, "Disk")}`);
+        console.log(render.kv("Data", `${render.wrap(render.c.dim, d.dataDir)} ${render.wrap(render.c.dim, "—")} ${render.wrap(render.c.bold, render.humanBytes(d.dataBytes ?? 0))}`));
+        console.log(render.kv("Snapshots", `${render.wrap(render.c.dim, d.snapshotDir)} ${render.wrap(render.c.dim, "—")} ${render.wrap(render.c.bold, render.humanBytes(d.snapshotBytes ?? 0))}`));
     }
     console.log("");
-    if (scopedWarnings.length > 0)
-        console.log(`  Health:     ⚠ ${scopedWarnings.length} warning(s)`);
-    else
-        console.log(`  Health:     ✅ all checks passing`);
+    if (scopedWarnings.length > 0) {
+        console.log(`  ${render.icons.warn} ${render.wrap(render.c.yellow, `${scopedWarnings.length} warning${scopedWarnings.length === 1 ? "" : "s"}`)}`);
+    }
+    else {
+        console.log(`  ${render.icons.ok} ${render.wrap(render.c.green, "all checks passing")}`);
+    }
 });
 statusCmd
     .command("rem")
@@ -4766,33 +5113,42 @@ statusCmd
     .action(async function () {
     const opts = this.optsWithGlobals();
     const { healthy, healthData } = await fetchHealthDetail(opts);
-    if (opts.json) {
-        console.log(JSON.stringify({ healthy, rem: healthData?.rem ?? null }, null, 2));
+    const mode = render.resolveOutputMode(opts);
+    if (mode === "json") {
+        console.log(render.asJSON({ healthy, rem: healthData?.rem ?? null }));
         if (!healthy)
             process.exit(1);
         return;
     }
     if (!healthy) {
-        console.log("🔴 unreachable");
+        console.log(`${render.icons.error} ${render.wrap(render.c.red, "unreachable")}`);
         process.exit(1);
     }
     const r = healthData?.rem;
     if (!r) {
-        console.log("REM: not configured (no log entries or platform timers found)");
+        console.log(`${render.wrap(render.c.bold, "REM")}  ${render.wrap(render.c.dim, "not configured (no log entries or platform timers found)")}`);
         return;
     }
-    console.log("REM:");
-    console.log(`  Last light:        ${relativeTime(r.lastLightAt)}`);
-    console.log(`  Last rapid:        ${relativeTime(r.lastRapidAt)}`);
-    console.log(`  Last restorative:  ${relativeTime(r.lastRestorativeAt)}`);
-    const nightly = r.nightlyEnabled === true ? "enabled" : r.nightlyEnabled === false ? "disabled" : "unknown";
-    console.log(`  Nightly:           ${nightly}`);
-    if (r.lastNightlyAt)
-        console.log(`  Last nightly:      ${relativeTime(r.lastNightlyAt)} (${r.lastNightlyAt})`);
-    if (typeof r.pendingCandidates === "number")
-        console.log(`  Pending candidates: ${r.pendingCandidates}`);
-    else
-        console.log(`  Pending candidates: — (schema not available)`);
+    console.log(render.wrap(render.c.bold, "REM"));
+    console.log(render.kv("Last light", render.relativeTime(r.lastLightAt), 18));
+    console.log(render.kv("Last rapid", render.relativeTime(r.lastRapidAt), 18));
+    console.log(render.kv("Last restorative", render.relativeTime(r.lastRestorativeAt), 18));
+    const nightlyTxt = r.nightlyEnabled === true
+        ? render.wrap(render.c.green, "enabled")
+        : r.nightlyEnabled === false
+            ? render.wrap(render.c.dim, "disabled")
+            : render.wrap(render.c.dim, "unknown");
+    console.log(render.kv("Nightly", nightlyTxt, 18));
+    if (r.lastNightlyAt) {
+        console.log(render.kv("Last nightly", `${render.relativeTime(r.lastNightlyAt)} ${render.wrap(render.c.dim, `(${r.lastNightlyAt})`)}`, 18));
+    }
+    if (typeof r.pendingCandidates === "number") {
+        const pendingColor = r.pendingCandidates > 0 ? render.c.yellow : render.c.dim;
+        console.log(render.kv("Pending candidates", render.wrap(pendingColor, String(r.pendingCandidates)), 18));
+    }
+    else {
+        console.log(render.kv("Pending candidates", render.wrap(render.c.dim, "— (schema not available)"), 18));
+    }
 });
 statusCmd
     .command("federation")
@@ -4800,36 +5156,70 @@ statusCmd
     .action(async function () {
     const opts = this.optsWithGlobals();
     const { healthy, healthData } = await fetchHealthDetail(opts);
-    if (opts.json) {
-        console.log(JSON.stringify({ healthy, federation: healthData?.federation ?? null }, null, 2));
+    const mode = render.resolveOutputMode(opts);
+    if (mode === "json") {
+        console.log(render.asJSON({ healthy, federation: healthData?.federation ?? null }));
         if (!healthy)
             process.exit(1);
         return;
     }
     if (!healthy) {
-        console.log("🔴 unreachable");
+        console.log(`${render.icons.error} ${render.wrap(render.c.red, "unreachable")}`);
         process.exit(1);
     }
     const f = healthData?.federation;
     if (!f) {
-        console.log("Federation: not configured");
+        console.log(`${render.wrap(render.c.bold, "Federation")}  ${render.wrap(render.c.dim, "not configured")}`);
         return;
     }
-    console.log("Federation:");
-    if (f.instance)
-        console.log(`  Instance:    ${f.instance.id} (${f.instance.role ?? "—"}, ${f.instance.status ?? "—"})`);
-    else
-        console.log("  Instance:    —");
-    if (f.peers)
-        console.log(`  Peers:       ${f.peers.total} (${f.peers.connected} connected / ${f.peers.disconnected} down / ${f.peers.revoked} revoked)`);
-    if (typeof f.pendingTokens === "number" && f.pendingTokens > 0)
-        console.log(`  Pairing:     ${f.pendingTokens} unconsumed token(s)`);
+    console.log(render.wrap(render.c.bold, "Federation"));
+    if (f.instance) {
+        const statusColor = f.instance.status === "active" ? render.c.green : render.c.yellow;
+        console.log(render.kv("Instance", `${f.instance.id}  ${render.wrap(render.c.dim, "(")}${f.instance.role ?? "—"}${render.wrap(render.c.dim, ", ")}${render.wrap(statusColor, f.instance.status ?? "—")}${render.wrap(render.c.dim, ")")}`));
+    }
+    else {
+        console.log(render.kv("Instance", render.wrap(render.c.dim, "—")));
+    }
+    if (f.peers) {
+        const connColor = f.peers.connected > 0 ? render.c.green : render.c.dim;
+        const downColor = f.peers.disconnected > 0 ? render.c.yellow : render.c.dim;
+        const revColor = f.peers.revoked > 0 ? render.c.red : render.c.dim;
+        const parts = [
+            render.wrap(connColor, `${f.peers.connected} connected`),
+            render.wrap(downColor, `${f.peers.disconnected} down`),
+            render.wrap(revColor, `${f.peers.revoked} revoked`),
+        ];
+        console.log(render.kv("Peers", `${render.wrap(render.c.bold, String(f.peers.total))} ${render.wrap(render.c.dim, "—")} ${parts.join(render.wrap(render.c.dim, " · "))}`));
+    }
+    if (typeof f.pendingTokens === "number" && f.pendingTokens > 0) {
+        console.log(render.kv("Pairing", `${render.wrap(render.c.yellow, String(f.pendingTokens))} unconsumed token(s)`));
+    }
     if (Array.isArray(f.peerList) && f.peerList.length > 0) {
-        const idW = Math.max(4, ...f.peerList.map((p) => (p.id ?? "").length));
-        console.log(`\n  ${"peer".padEnd(idW)}  ${"role".padEnd(5)}  ${"status".padEnd(13)}  last_sync`);
-        for (const p of f.peerList) {
-            console.log(`  ${(p.id ?? "").padEnd(idW)}  ${(p.role ?? "—").padEnd(5)}  ${(p.status ?? "—").padEnd(13)}  ${p.lastSyncAt ? `${relativeTime(p.lastSyncAt)} (${p.lastSyncAt})` : "never"}`);
-        }
+        console.log();
+        const cols = [
+            { label: "peer", key: "id" },
+            { label: "role", key: "role", format: (v) => String(v ?? "—") },
+            {
+                label: "status",
+                key: "status",
+                format: (v) => {
+                    const s = String(v ?? "—");
+                    const color = s === "paired" || s === "connected" ? render.c.green : s === "revoked" ? render.c.red : render.c.yellow;
+                    return render.wrap(color, s);
+                },
+            },
+            {
+                label: "last_sync",
+                key: "lastSyncAt",
+                format: (v) => {
+                    const iso = v;
+                    if (!iso)
+                        return render.wrap(render.c.dim, "never");
+                    return `${render.relativeTime(iso)} ${render.wrap(render.c.dim, `(${iso})`)}`;
+                },
+            },
+        ];
+        console.log(render.table(cols, f.peerList));
     }
 });
 statusCmd
@@ -4838,24 +5228,46 @@ statusCmd
     .action(async function () {
     const opts = this.optsWithGlobals();
     const { healthy, healthData } = await fetchHealthDetail(opts);
-    if (opts.json) {
-        console.log(JSON.stringify({ healthy, oauth: healthData?.oauth ?? null }, null, 2));
+    const mode = render.resolveOutputMode(opts);
+    if (mode === "json") {
+        console.log(render.asJSON({ healthy, oauth: healthData?.oauth ?? null }));
         if (!healthy)
             process.exit(1);
         return;
     }
     if (!healthy) {
-        console.log("🔴 unreachable");
+        console.log(`${render.icons.error} ${render.wrap(render.c.red, "unreachable")}`);
         process.exit(1);
     }
     const o = healthData?.oauth;
     if (!o) {
-        console.log("OAuth: not configured");
+        console.log(`${render.wrap(render.c.bold, "OAuth")}  ${render.wrap(render.c.dim, "not configured")}`);
         return;
     }
-    const lines = oauthDetailLines(o);
-    for (const line of lines)
-        console.log(line);
+    console.log(render.wrap(render.c.bold, "OAuth"));
+    console.log(render.kv("Clients", render.wrap(render.c.bold, String(Number(o?.clients ?? 0)))));
+    console.log(render.kv("IdP configs", String(Number(o?.idpConfigs ?? 0))));
+    const tokenColor = Number(o?.activeTokens ?? 0) > 0 ? render.c.green : render.c.dim;
+    console.log(render.kv("Active tokens", render.wrap(tokenColor, String(Number(o?.activeTokens ?? 0)))));
+    if (Array.isArray(o?.clientList) && o.clientList.length > 0) {
+        console.log(`\n  ${render.wrap(render.c.dim, "Clients")}`);
+        const cols = [
+            { label: "id", key: "id" },
+            { label: "name", key: "name", format: (v) => String(v ?? "—") },
+            { label: "registered_by", key: "registeredBy", format: (v) => String(v ?? "—") },
+            { label: "created_at", key: "createdAt", format: (v) => String(v ?? "—") },
+        ];
+        console.log(render.table(cols, o.clientList));
+    }
+    if (Array.isArray(o?.idpList) && o.idpList.length > 0) {
+        console.log(`\n  ${render.wrap(render.c.dim, "IdPs")}`);
+        const cols = [
+            { label: "id", key: "id" },
+            { label: "name", key: "name", format: (v) => String(v ?? "—") },
+            { label: "issuer", key: "issuer", format: (v) => String(v ?? "—") },
+        ];
+        console.log(render.table(cols, o.idpList));
+    }
 });
 statusCmd
     .command("bridges")
@@ -4863,28 +5275,283 @@ statusCmd
     .action(async function () {
     const opts = this.optsWithGlobals();
     const { healthy, healthData } = await fetchHealthDetail(opts);
-    if (opts.json) {
-        console.log(JSON.stringify({ healthy, bridges: healthData?.bridges ?? null }, null, 2));
+    const mode = render.resolveOutputMode(opts);
+    if (mode === "json") {
+        console.log(render.asJSON({ healthy, bridges: healthData?.bridges ?? null }));
         if (!healthy)
             process.exit(1);
         return;
     }
     if (!healthy) {
-        console.log("🔴 unreachable");
+        console.log(`${render.icons.error} ${render.wrap(render.c.red, "unreachable")}`);
         process.exit(1);
     }
     const b = healthData?.bridges;
     if (!b) {
-        console.log("Bridges: none installed (no flair-bridge-* packages found)");
+        console.log(`${render.wrap(render.c.bold, "Bridges")}  ${render.wrap(render.c.dim, "none installed (no flair-bridge-* packages found)")}`);
         return;
     }
-    console.log("Bridges:");
-    if (Array.isArray(b.installed) && b.installed.length > 0)
-        console.log(`  Installed:   ${b.installed.join(", ")}`);
+    console.log(render.wrap(render.c.bold, "Bridges"));
+    if (Array.isArray(b.installed) && b.installed.length > 0) {
+        console.log(render.kv("Installed", b.installed.join(render.wrap(render.c.dim, ", "))));
+    }
     if (b.lastImport)
-        console.log(`  Last import: ${relativeTime(b.lastImport)}`);
+        console.log(render.kv("Last import", render.relativeTime(b.lastImport)));
     if (b.lastExport)
-        console.log(`  Last export: ${relativeTime(b.lastExport)}`);
+        console.log(render.kv("Last export", render.relativeTime(b.lastExport)));
+});
+// ─── flair status --deep ──────────────────────────────────────────────────────
+//
+// Deeper observability than the default `flair status` summary — full
+// per-section detail with no condensing. Optional --bootstrap measures
+// cold-start context bytes per agent (slow; calls /MemoryBootstrap once per
+// agent, admin-auth required).
+//
+// Addresses ops-yph: Nathan's 2026-04-22 ask for "how much storage does my
+// memory take, how much context are bootstraps pulling, what's the real usage
+// pattern" — questions the default `flair status` summarizes but doesn't
+// surface in full. Agents should be able to self-audit via this too.
+statusCmd
+    .command("deep")
+    .description("Verbose status + optional bootstrap context size per agent (ops-yph)")
+    .option("--bootstrap", "Also measure bootstrap context bytes per agent (slow; admin auth required)")
+    .option("--max-tokens <n>", "Bootstrap maxTokens cap when --bootstrap is set", "4000")
+    .action(async function () {
+    const opts = this.optsWithGlobals();
+    const { healthy, baseUrl, healthData } = await fetchHealthDetail(opts);
+    if (!healthy) {
+        if (opts.json) {
+            console.log(JSON.stringify({ healthy: false, url: baseUrl, error: "unreachable" }, null, 2));
+        }
+        else {
+            console.log(`Flair v${__pkgVersion} — 🔴 unreachable`);
+            console.log(`  URL:  ${baseUrl}`);
+            console.log(`\n  Run: flair start  or  flair doctor`);
+        }
+        process.exit(1);
+    }
+    // Optional: per-agent bootstrap context bytes. Calls /MemoryBootstrap with
+    // admin auth (so we can measure on behalf of any agent without holding
+    // their keys). 15s timeout per call — bootstrap can be expensive on cold
+    // caches or large memory sets.
+    const agentList = (Array.isArray(healthData?.agents?.names) && healthData.agents.names.length > 0
+        ? healthData.agents.names
+        : Array.isArray(healthData?.agents?.perAgent)
+            ? healthData.agents.perAgent.map((r) => r.id).filter(Boolean)
+            : []);
+    const bootstrapBytes = {};
+    if (opts.bootstrap && agentList.length > 0) {
+        const adminPass = process.env.HDB_ADMIN_PASSWORD || process.env.FLAIR_ADMIN_PASS;
+        if (!adminPass) {
+            if (!opts.json) {
+                console.log("⚠ --bootstrap requires HDB_ADMIN_PASSWORD or FLAIR_ADMIN_PASS env var");
+            }
+        }
+        else {
+            const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
+            const maxTokens = Number.parseInt(String(opts.maxTokens ?? "4000"), 10);
+            for (const agentId of agentList) {
+                try {
+                    const res = await fetch(`${baseUrl}/BootstrapMemories`, {
+                        method: "POST",
+                        headers: { "Content-Type": "application/json", Authorization: auth },
+                        body: JSON.stringify({ agentId, maxTokens }),
+                        signal: AbortSignal.timeout(15000),
+                    });
+                    const text = await res.text();
+                    const bytes = Buffer.byteLength(text, "utf8");
+                    let tokenEstimate;
+                    let memoriesIncluded;
+                    try {
+                        const json = JSON.parse(text);
+                        tokenEstimate = typeof json.tokenEstimate === "number" ? json.tokenEstimate : undefined;
+                        memoriesIncluded = typeof json.memoriesIncluded === "number" ? json.memoriesIncluded : undefined;
+                    }
+                    catch { /* response wasn't JSON; bytes still valid */ }
+                    if (!res.ok) {
+                        bootstrapBytes[agentId] = { bytes, error: `HTTP ${res.status}` };
+                    }
+                    else {
+                        bootstrapBytes[agentId] = { bytes, tokenEstimate, memoriesIncluded };
+                    }
+                }
+                catch (e) {
+                    bootstrapBytes[agentId] = { bytes: 0, error: e?.message ?? String(e) };
+                }
+            }
+        }
+    }
+    if (opts.json) {
+        const out = { healthy, url: baseUrl, flairVersion: __pkgVersion, ...healthData };
+        if (opts.bootstrap)
+            out.bootstrapBytes = bootstrapBytes;
+        console.log(JSON.stringify(out, null, 2));
+        return;
+    }
+    // Human-readable verbose render.
+    const uptimeSec = healthData?.uptimeSeconds;
+    let uptimeStr = "";
+    if (uptimeSec != null) {
+        const d = Math.floor(uptimeSec / 86400);
+        const h = Math.floor((uptimeSec % 86400) / 3600);
+        const m = Math.floor((uptimeSec % 3600) / 60);
+        uptimeStr = d > 0 ? `${d}d ${h}h` : h > 0 ? `${h}h ${m}m` : `${m}m`;
+    }
+    const pid = healthData?.pid ?? "?";
+    console.log(`Flair v${__pkgVersion} — running (PID ${pid}${uptimeStr ? `, uptime ${uptimeStr}` : ""})`);
+    console.log(`URL: ${baseUrl}`);
+    const memories = healthData?.memories;
+    if (memories) {
+        console.log("\n═══ Memory ═══════════════════════════════════════");
+        console.log(`Total:        ${memories.total}`);
+        console.log(`Breakdown:    ${memories.withEmbeddings ?? 0} embedded, ${memories.hashFallback ?? 0} hash-fallback`);
+        if (memories.modelCounts && memories.total > 0) {
+            const entries = Object.entries(memories.modelCounts)
+                .filter(([, n]) => n > 0)
+                .sort((a, b) => b[1] - a[1]);
+            for (const [k, n] of entries) {
+                const pct = ((n / memories.total) * 100).toFixed(1);
+                console.log(`  ${k.padEnd(28)} ${String(n).padStart(6)}  (${pct}%)`);
+            }
+        }
+        if (memories.byDurability) {
+            const d = memories.byDurability;
+            console.log(`Durability:   ${d.permanent ?? 0} permanent / ${d.persistent ?? 0} persistent / ${d.standard ?? 0} standard / ${d.ephemeral ?? 0} ephemeral`);
+        }
+        console.log(`Archived:     ${memories.archived ?? 0}`);
+        console.log(`Expired:      ${memories.expired ?? 0}`);
+        if (healthData?.lastWrite)
+            console.log(`Last write:   ${relativeTime(healthData.lastWrite)} (${healthData.lastWrite})`);
+    }
+    const agents = healthData?.agents;
+    if (agents && agents.count > 0) {
+        console.log("\n═══ Agents ═══════════════════════════════════════");
+        console.log(`Total:        ${agents.count}`);
+        if (Array.isArray(agents.names) && agents.names.length > 0) {
+            console.log(`Names:        ${agents.names.join(", ")}`);
+        }
+        if (Array.isArray(agents.perAgent) && agents.perAgent.length > 0) {
+            const idW = Math.max(2, ...agents.perAgent.map((r) => (r.id ?? "").length));
+            console.log(`\n  ${"id".padEnd(idW)}  memories  hash_fb  24h  last_write`);
+            for (const r of agents.perAgent) {
+                const fb = typeof r.hashFallback === "number" ? String(r.hashFallback) : "—";
+                const w24 = typeof r.writes24h === "number" ? String(r.writes24h) : "—";
+                console.log(`  ${(r.id ?? "").padEnd(idW)}  ${String(r.memoryCount).padStart(8)}  ${fb.padStart(7)}  ${w24.padStart(3)}  ${relativeTime(r.lastWriteAt)}`);
+            }
+        }
+    }
+    // Bootstrap context section — always printed so users see how to opt in.
+    console.log("\n═══ Bootstrap context ═══════════════════════════");
+    if (!opts.bootstrap) {
+        console.log("  (not measured — pass --bootstrap to fetch per-agent context bytes)");
+    }
+    else if (Object.keys(bootstrapBytes).length === 0) {
+        console.log("  (no agents found, or admin pass missing — see HDB_ADMIN_PASSWORD)");
+    }
+    else {
+        const idW = Math.max(5, ...Object.keys(bootstrapBytes).map((id) => id.length));
+        console.log(`  ${"agent".padEnd(idW)}  ${"bytes".padStart(9)}  ${"~tokens".padStart(7)}  ${"mems".padStart(4)}  status`);
+        // Sort by bytes desc so heaviest bootstraps surface first.
+        const sortedEntries = Object.entries(bootstrapBytes).sort((a, b) => (b[1].bytes ?? 0) - (a[1].bytes ?? 0));
+        for (const [agentId, info] of sortedEntries) {
+            const bytesStr = info.error ? "error" : humanBytes(info.bytes);
+            const tok = info.tokenEstimate != null ? String(info.tokenEstimate) : "—";
+            const mems = info.memoriesIncluded != null ? String(info.memoriesIncluded) : "—";
+            const status = info.error ? info.error.slice(0, 40) : "ok";
+            console.log(`  ${agentId.padEnd(idW)}  ${bytesStr.padStart(9)}  ${tok.padStart(7)}  ${mems.padStart(4)}  ${status}`);
+        }
+    }
+    if (healthData?.relationships) {
+        const r = healthData.relationships;
+        console.log("\n═══ Relationships ═══════════════════════════════");
+        console.log(`Total:        ${r.total} (${r.active} active)`);
+    }
+    if (healthData?.soul && healthData.soul.total > 0) {
+        const s = healthData.soul;
+        console.log("\n═══ Soul ═════════════════════════════════════════");
+        console.log(`Total:        ${s.total} entries`);
+        const entries = sortSoulKeyEntries(s.byKey ?? {});
+        if (entries.length > 0) {
+            console.log(`Keys:         ${entries.map(([k, n]) => `${n} ${k}`).join(" / ")}`);
+        }
+    }
+    else if (typeof healthData?.soulEntries === "number" && healthData.soulEntries > 0) {
+        console.log("\n═══ Soul ═════════════════════════════════════════");
+        console.log(`Total:        ${healthData.soulEntries} entries`);
+    }
+    if (healthData?.rem) {
+        const r = healthData.rem;
+        console.log("\n═══ REM ══════════════════════════════════════════");
+        console.log(`Last light:        ${relativeTime(r.lastLightAt)}`);
+        console.log(`Last rapid:        ${relativeTime(r.lastRapidAt)}`);
+        console.log(`Last restorative:  ${relativeTime(r.lastRestorativeAt)}`);
+        const nightly = r.nightlyEnabled === true ? "enabled" : r.nightlyEnabled === false ? "disabled" : "unknown";
+        console.log(`Nightly:           ${nightly}`);
+        if (r.lastNightlyAt)
+            console.log(`Last nightly:      ${relativeTime(r.lastNightlyAt)} (${r.lastNightlyAt})`);
+        if (typeof r.pendingCandidates === "number")
+            console.log(`Pending candidates: ${r.pendingCandidates}`);
+    }
+    if (healthData?.federation) {
+        const f = healthData.federation;
+        console.log("\n═══ Federation ═══════════════════════════════════");
+        if (f.instance)
+            console.log(`Instance:     ${f.instance.id} (${f.instance.role ?? "—"}, ${f.instance.status ?? "—"})`);
+        if (f.peers)
+            console.log(`Peers:        ${f.peers.total} total (${f.peers.connected} connected, ${f.peers.disconnected} down, ${f.peers.revoked} revoked)`);
+        if (typeof f.pendingTokens === "number" && f.pendingTokens > 0)
+            console.log(`Pairing:      ${f.pendingTokens} unconsumed token(s)`);
+        if (Array.isArray(f.peerList) && f.peerList.length > 0) {
+            const idW = Math.max(4, ...f.peerList.map((p) => (p.id ?? "").length));
+            console.log(`\n  ${"peer".padEnd(idW)}  ${"role".padEnd(5)}  ${"status".padEnd(13)}  last_sync`);
+            for (const p of f.peerList) {
+                console.log(`  ${(p.id ?? "").padEnd(idW)}  ${(p.role ?? "—").padEnd(5)}  ${(p.status ?? "—").padEnd(13)}  ${p.lastSyncAt ? `${relativeTime(p.lastSyncAt)} (${p.lastSyncAt})` : "never"}`);
+            }
+        }
+    }
+    else {
+        console.log("\n═══ Federation ═══════════════════════════════════");
+        console.log("  not configured");
+    }
+    if (healthData?.oauth) {
+        const o = healthData.oauth;
+        console.log("\n═══ OAuth / IdP ══════════════════════════════════");
+        console.log(`Clients:       ${o.clients}`);
+        console.log(`IdP configs:   ${o.idpConfigs}`);
+        console.log(`Active tokens: ${o.activeTokens}`);
+        if (Array.isArray(o.clientList) && o.clientList.length > 0) {
+            console.log(`\n  Clients:`);
+            for (const c of o.clientList) {
+                console.log(`    ${c.id}  ${c.name ?? "—"}  ${c.registeredBy ?? "—"}  ${c.createdAt ?? "—"}`);
+            }
+        }
+    }
+    if (healthData?.bridges) {
+        const b = healthData.bridges;
+        console.log("\n═══ Bridges ══════════════════════════════════════");
+        if (Array.isArray(b.installed) && b.installed.length > 0)
+            console.log(`Installed:    ${b.installed.join(", ")}`);
+        if (b.lastImport)
+            console.log(`Last import:  ${relativeTime(b.lastImport)}`);
+        if (b.lastExport)
+            console.log(`Last export:  ${relativeTime(b.lastExport)}`);
+    }
+    if (healthData?.disk) {
+        const d = healthData.disk;
+        console.log("\n═══ Disk ═════════════════════════════════════════");
+        console.log(`Data:         ${d.dataDir} — ${humanBytes(d.dataBytes ?? 0)}`);
+        console.log(`Snapshots:    ${d.snapshotDir} — ${humanBytes(d.snapshotBytes ?? 0)}`);
+        console.log(`Total:        ${humanBytes((d.dataBytes ?? 0) + (d.snapshotBytes ?? 0))}`);
+    }
+    const warnings = Array.isArray(healthData?.warnings) ? healthData.warnings : [];
+    if (warnings.length > 0) {
+        console.log("\n═══ Warnings ═════════════════════════════════════");
+        for (const w of warnings)
+            console.log(`  ${w.level === "warn" ? "⚠" : "ℹ"} ${w.message}`);
+    }
+    else {
+        console.log("\n✅ no warnings");
+    }
 });
 // ─── flair upgrade ────────────────────────────────────────────────────────────
 program
@@ -5565,15 +6232,13 @@ program
     .option("--agent <id>", "Agent ID (or set FLAIR_AGENT_ID env)")
     .option("--port <port>", "Harper HTTP port")
     .action(async (opts) => {
-    const green = (s) => `\x1b[32m${s}\x1b[0m`;
-    const red = (s) => `\x1b[31m${s}\x1b[0m`;
     const agentId = opts.agent ?? process.env.FLAIR_AGENT_ID;
     if (!agentId && !process.env.FLAIR_ADMIN_PASS) {
-        console.error(red("Error: set --agent / FLAIR_AGENT_ID or FLAIR_ADMIN_PASS"));
+        console.error(`${render.icons.error} ${render.wrap(render.c.red, "set --agent / FLAIR_AGENT_ID or FLAIR_ADMIN_PASS")}`);
         process.exit(1);
     }
     const baseUrl = `http://127.0.0.1:${resolveHttpPort(opts)}`;
-    console.log(`\nFlair test (url: ${baseUrl})\n`);
+    console.log(`\n${render.wrap(render.c.bold, "Flair test")} ${render.wrap(render.c.dim, `(url: ${baseUrl})`)}\n`);
     let passed = 0;
     let failed = 0;
     let memoryId = null;
@@ -5581,17 +6246,17 @@ program
         try {
             const ok = await fn();
             if (ok) {
-                console.log(`  ${green("PASS")} ${name}`);
+                console.log(`  ${render.icons.ok} ${render.wrap(render.c.green, "PASS")} ${name}`);
                 passed++;
             }
             else {
-                console.log(`  ${red("FAIL")} ${name}`);
+                console.log(`  ${render.icons.error} ${render.wrap(render.c.red, "FAIL")} ${name}`);
                 failed++;
             }
         }
         catch (e) {
             const message = e instanceof Error ? e.message : String(e);
-            console.log(`  ${red("FAIL")} ${name}: ${message?.slice(0, 120)}`);
+            console.log(`  ${render.icons.error} ${render.wrap(render.c.red, "FAIL")} ${name}: ${render.wrap(render.c.dim, message?.slice(0, 120))}`);
             failed++;
         }
     };
@@ -5630,7 +6295,9 @@ program
         await api("DELETE", `/Memory/${memoryId}`, agentId ? { agentId } : undefined);
         return true;
     });
-    console.log(`\n${passed} passed, ${failed} failed`);
+    const passColor = passed > 0 ? render.c.green : render.c.dim;
+    const failColor = failed > 0 ? render.c.red : render.c.dim;
+    console.log(`\n  ${render.wrap(passColor, `${passed} passed`)} ${render.wrap(render.c.dim, "·")} ${render.wrap(failColor, `${failed} failed`)}`);
     if (failed > 0)
         process.exit(1);
 });
@@ -5733,7 +6400,7 @@ program
     let baseUrl = `http://127.0.0.1:${port}`;
     let issues = 0;
     let harperResponding = false;
-    console.log("\n🩺 Flair Doctor\n");
+    console.log(`\n${render.wrap(render.c.bold, "🩺 Flair Doctor")}\n`);
     // Helper: try to reach Harper on a given port
     async function probePort(p) {
         try {
@@ -5777,11 +6444,11 @@ program
             catch { /* dead */ }
         }
         else {
-            console.log(`  ⚠️  PID file contains non-numeric value: ${pidFile0} — skipping`);
+            console.log(`  ${render.icons.warn} PID file contains non-numeric value: ${render.wrap(render.c.dim, pidFile0)} — skipping`);
         }
     }
     if (await probePort(port)) {
-        console.log(`  ✅ Harper responding on port ${port}`);
+        console.log(`  ${render.icons.ok} Harper responding on port ${render.wrap(render.c.bold, String(port))}`);
         harperResponding = true;
     }
     else {
@@ -5790,19 +6457,19 @@ program
         if (pidAlive) {
             discoveredPort = await discoverPortFromPid(pidValue);
             if (discoveredPort && discoveredPort !== port && await probePort(discoveredPort)) {
-                console.log(`  ⚠️  Harper not on expected port ${port}, but responding on port ${discoveredPort} (PID ${pidValue})`);
-                console.log(`     Your config says port ${port} but Harper is actually running on ${discoveredPort}`);
+                console.log(`  ${render.icons.warn} Harper not on expected port ${port}, but responding on port ${render.wrap(render.c.bold, String(discoveredPort))} ${render.wrap(render.c.dim, `(PID ${pidValue})`)}`);
+                console.log(`     ${render.wrap(render.c.dim, `Your config says port ${port} but Harper is actually running on ${discoveredPort}`)}`);
                 if (autoFix) {
                     if (dryRun) {
-                        console.log(`     Would update config to port ${discoveredPort}`);
+                        console.log(`     ${render.wrap(render.c.dim, "Would update config to port")} ${discoveredPort}`);
                     }
                     else {
                         writeConfig(discoveredPort);
-                        console.log(`     ✅ Updated config to port ${discoveredPort}`);
+                        console.log(`     ${render.icons.ok} Updated config to port ${discoveredPort}`);
                     }
                 }
                 else {
-                    console.log(`     Fix: flair doctor --fix (updates config to match running port)`);
+                    console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair doctor --fix ${render.wrap(render.c.dim, "(updates config to match running port)")}`);
                 }
                 effectivePort = discoveredPort;
                 baseUrl = `http://127.0.0.1:${discoveredPort}`;
@@ -5810,8 +6477,8 @@ program
                 issues++;
             }
             else {
-                console.log(`  ❌ Harper process alive (PID ${pidValue}) but not responding on any detected port`);
-                console.log(`     Fix: flair restart`);
+                console.log(`  ${render.icons.error} Harper process alive (PID ${pidValue}) but not responding on any detected port`);
+                console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair restart`);
                 issues++;
             }
         }
@@ -5822,34 +6489,34 @@ program
                 const { execSync } = await import("node:child_process");
                 const lsof = execSync(`lsof -ti :${port}`, { encoding: "utf-8" }).trim();
                 if (lsof) {
-                    console.log(`  ❌ Nothing responding on port ${port} (port occupied by PID ${lsof})`);
-                    console.log(`     Fix: kill ${lsof} && flair restart`);
+                    console.log(`  ${render.icons.error} Nothing responding on port ${port} ${render.wrap(render.c.dim, `(port occupied by PID ${lsof})`)}`);
+                    console.log(`     ${render.wrap(render.c.dim, "Fix:")} kill ${lsof} && flair restart`);
                 }
                 else {
-                    console.log(`  ❌ Harper is not running`);
-                    console.log(`     Fix: flair restart`);
+                    console.log(`  ${render.icons.error} Harper is not running`);
+                    console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair restart`);
                 }
             }
             catch {
-                console.log(`  ❌ Harper is not running`);
+                console.log(`  ${render.icons.error} Harper is not running`);
                 if (autoFix) {
                     if (dryRun) {
-                        console.log(`     Would run: flair restart`);
+                        console.log(`     ${render.wrap(render.c.dim, "Would run:")} flair restart`);
                     }
                     else {
-                        console.log(`     Attempting restart...`);
+                        console.log(`     ${render.wrap(render.c.dim, "Attempting restart...")}`);
                         try {
                             const { execSync } = await import("node:child_process");
                             execSync(`${process.argv[0]} ${process.argv[1]} restart --port ${port}`, { stdio: "inherit" });
-                            console.log(`     ✅ Restart attempted`);
+                            console.log(`     ${render.icons.ok} Restart attempted`);
                         }
                         catch {
-                            console.log(`     ❌ Restart failed — try: flair init --agent-id <your-agent>`);
+                            console.log(`     ${render.icons.error} Restart failed — try: flair init --agent-id <your-agent>`);
                         }
                     }
                 }
                 else {
-                    console.log(`     Fix: flair restart`);
+                    console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair restart`);
                 }
             }
             issues++;
@@ -5860,27 +6527,27 @@ program
     if (existsSync(keysDir)) {
         const keyFiles = (await import("node:fs")).readdirSync(keysDir).filter((f) => f.endsWith(".key"));
         if (keyFiles.length > 0) {
-            console.log(`  ✅ Keys found: ${keyFiles.length} agent(s) in ${keysDir}`);
+            console.log(`  ${render.icons.ok} Keys found: ${render.wrap(render.c.bold, String(keyFiles.length))} agent(s) in ${render.wrap(render.c.dim, keysDir)}`);
         }
         else {
-            console.log(`  ❌ Keys directory exists but no .key files found`);
-            console.log(`     Fix: flair init --agent-id <your-agent>`);
+            console.log(`  ${render.icons.error} Keys directory exists but no .key files found`);
+            console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair init --agent-id <your-agent>`);
             issues++;
         }
     }
     else {
-        console.log(`  ❌ Keys directory missing: ${keysDir}`);
-        console.log(`     Fix: flair init --agent-id <your-agent>`);
+        console.log(`  ${render.icons.error} Keys directory missing: ${render.wrap(render.c.dim, keysDir)}`);
+        console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair init --agent-id <your-agent>`);
         issues++;
     }
     // 3. Config file
     const cfgPath = configPath();
     if (existsSync(cfgPath)) {
         const savedPort = readPortFromConfig();
-        console.log(`  ✅ Config: ${cfgPath} (port: ${savedPort ?? "default"})`);
+        console.log(`  ${render.icons.ok} Config: ${render.wrap(render.c.dim, cfgPath)} ${render.wrap(render.c.dim, `(port: ${savedPort ?? "default"})`)}`);
     }
     else {
-        console.log(`  ⚠️  No config file at ${cfgPath} — using defaults`);
+        console.log(`  ${render.icons.warn} No config file at ${render.wrap(render.c.dim, cfgPath)} — using defaults`);
     }
     // 4. Embeddings check (only if Harper is responding)
     if (harperResponding) {
@@ -5894,17 +6561,17 @@ program
             if (testRes.ok) {
                 const data = await testRes.json();
                 if (data._warning) {
-                    console.log(`  ⚠️  Embeddings: keyword-only (${data._warning})`);
-                    console.log(`     Semantic search quality is degraded`);
-                    console.log(`     Check: ls ~/.npm-global/lib/node_modules/@tpsdev-ai/flair/models/`);
+                    console.log(`  ${render.icons.warn} Embeddings: keyword-only ${render.wrap(render.c.dim, `(${data._warning})`)}`);
+                    console.log(`     ${render.wrap(render.c.dim, "Semantic search quality is degraded")}`);
+                    console.log(`     ${render.wrap(render.c.dim, "Check:")} ls ~/.npm-global/lib/node_modules/@tpsdev-ai/flair/models/`);
                     issues++;
                 }
                 else {
-                    console.log(`  ✅ Embeddings: semantic search operational`);
+                    console.log(`  ${render.icons.ok} Embeddings: semantic search operational`);
                 }
             }
             else if (testRes.status === 401) {
-                console.log(`  ⚠️  Embeddings: cannot verify (auth required for SemanticSearch)`);
+                console.log(`  ${render.icons.warn} Embeddings: cannot verify ${render.wrap(render.c.dim, "(auth required for SemanticSearch)")}`);
             }
         }
         catch { /* fetch error, already flagged */ }
@@ -5917,50 +6584,50 @@ program
         try {
             process.kill(Number(pidContent), 0);
             if (harperResponding) {
-                console.log(`  ✅ PID file: ${pidFile} (process ${pidContent} is alive)`);
+                console.log(`  ${render.icons.ok} PID file: ${render.wrap(render.c.dim, pidFile)} ${render.wrap(render.c.dim, `(process ${pidContent} is alive)`)}`);
             }
             // If not responding, we already reported the issue in step 1
         }
         catch {
-            console.log(`  ❌ Stale PID file: ${pidFile} (process ${pidContent} is dead)`);
+            console.log(`  ${render.icons.error} Stale PID file: ${render.wrap(render.c.dim, pidFile)} ${render.wrap(render.c.dim, `(process ${pidContent} is dead)`)}`);
             if (autoFix) {
                 if (dryRun) {
-                    console.log(`     Would remove: ${pidFile}`);
+                    console.log(`     ${render.wrap(render.c.dim, "Would remove:")} ${pidFile}`);
                 }
                 else {
                     (await import("node:fs")).unlinkSync(pidFile);
-                    console.log(`     ✅ Removed stale PID file`);
+                    console.log(`     ${render.icons.ok} Removed stale PID file`);
                 }
             }
             else {
-                console.log(`     Fix: rm ${pidFile} && flair restart`);
+                console.log(`     ${render.wrap(render.c.dim, "Fix:")} rm ${pidFile} && flair restart`);
             }
             issues++;
         }
     }
     // 6. Data directory
     if (existsSync(dataDir)) {
-        console.log(`  ✅ Data directory: ${dataDir}`);
+        console.log(`  ${render.icons.ok} Data directory: ${render.wrap(render.c.dim, dataDir)}`);
     }
     else {
         // Check ~/harper/ (common alternative)
         const altDir = join(homedir(), "harper");
         if (existsSync(altDir)) {
-            console.log(`  ⚠️  Data at ~/harper/ (not ~/.flair/data) — old install location`);
+            console.log(`  ${render.icons.warn} Data at ${render.wrap(render.c.dim, "~/harper/")} (not ${render.wrap(render.c.dim, "~/.flair/data")}) — old install location`);
         }
         else {
-            console.log(`  ❌ No data directory found`);
-            console.log(`     Fix: flair init --agent-id <your-agent>`);
+            console.log(`  ${render.icons.error} No data directory found`);
+            console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair init --agent-id <your-agent>`);
             issues++;
         }
     }
     // Summary
     console.log("");
     if (issues === 0) {
-        console.log("  🟢 No issues found");
+        console.log(`  ${render.icons.ok} ${render.wrap(render.c.green, "No issues found")}`);
     }
     else {
-        console.log(`  🔴 ${issues} issue${issues > 1 ? "s" : ""} found — see fixes above`);
+        console.log(`  ${render.icons.error} ${render.wrap(render.c.red, `${issues} issue${issues > 1 ? "s" : ""} found`)} ${render.wrap(render.c.dim, "— see fixes above")}`);
     }
     console.log("");
     if (issues > 0)
@@ -6220,68 +6887,144 @@ memory.command("write-task-summary")
     // without parsing a JSON blob.
     console.log(memId);
 });
-memory.command("search [query]").requiredOption("--agent <id>")
+memory.command("search [query]")
+    .option("--agent <id>", "Agent ID (or set FLAIR_AGENT_ID env)")
     .option("--q <query>", "search query (alias for positional arg)")
     .option("--limit <n>", "Max results", "5")
     .option("--tag <tag>")
+    .option("--target <url>", "Remote Flair URL (env: FLAIR_TARGET; alias for --url)")
+    .option("--url <url>", "Flair base URL (overrides --port)")
+    .option("--port <port>", "Harper HTTP port")
     .action(async (queryArg, opts) => {
+    const agentId = resolveAgentIdOrEnv(opts);
+    if (!agentId) {
+        console.error("error: --agent <id> required (or set FLAIR_AGENT_ID)");
+        process.exit(2);
+    }
     const q = queryArg ?? opts.q;
     if (!q) {
         console.error("error: query required (positional arg or --q)");
         process.exit(1);
     }
-    const body = { agentId: opts.agent, q, limit: parseInt(opts.limit, 10) || 5 };
+    const body = { agentId, q, limit: parseInt(opts.limit, 10) || 5 };
     if (opts.tag)
         body.tag = opts.tag;
-    console.log(JSON.stringify(await api("POST", "/SemanticSearch", body), null, 2));
+    const baseUrl = resolveBaseUrl(opts);
+    const res = await api("POST", "/SemanticSearch", body, { baseUrl });
+    console.log(JSON.stringify(res, null, 2));
 });
 memory.command("list")
-    .requiredOption("--agent <id>")
+    .option("--agent <id>", "Agent ID (or set FLAIR_AGENT_ID env)")
     .option("--tag <tag>")
     .option("--hash-fallback", "Only memories with missing or hash-fallback embeddings (for backfill triage)")
     .option("--limit <n>", "Max rows when using --hash-fallback", "50")
+    .option("--json", "Emit raw JSON array (also: pipe + FLAIR_OUTPUT=json)")
     .action(async (opts) => {
-    const q = new URLSearchParams({ agentId: opts.agent, ...(opts.tag ? { tag: opts.tag } : {}) }).toString();
+    const agentId = resolveAgentIdOrEnv(opts);
+    if (!agentId) {
+        console.error(`${render.icons.error} --agent <id> required (or set FLAIR_AGENT_ID)`);
+        process.exit(2);
+    }
+    const q = new URLSearchParams({ agentId, ...(opts.tag ? { tag: opts.tag } : {}) }).toString();
     const raw = await api("GET", `/Memory?${q}`);
-    if (!opts.hashFallback) {
-        console.log(JSON.stringify(raw, null, 2));
+    const mode = render.resolveOutputMode(opts);
+    // hashFallback flag changes the lens: instead of all memories, show
+    // only those that need re-embedding. Keep that surface separate.
+    if (opts.hashFallback) {
+        const all = Array.isArray(raw) ? raw : (raw?.results ?? raw?.items ?? []);
+        const fallback = all.filter((m) => !m.embeddingModel || m.embeddingModel === "hash-512d");
+        if (mode === "json") {
+            console.log(render.asJSON(fallback));
+            return;
+        }
+        if (fallback.length === 0) {
+            console.log(`${render.icons.ok} ${render.wrap(render.c.green, "All memories embedded")} ${render.wrap(render.c.dim, `(agent ${agentId})`)}`);
+            return;
+        }
+        const limit = Math.max(1, parseInt(opts.limit, 10) || 50);
+        const rows = fallback
+            .slice()
+            .sort((a, b) => {
+            const ta = a.createdAt ? new Date(a.createdAt).getTime() : 0;
+            const tb = b.createdAt ? new Date(b.createdAt).getTime() : 0;
+            return tb - ta;
+        })
+            .slice(0, limit);
+        console.log(`${render.icons.warn} ${render.wrap(render.c.yellow, String(fallback.length))} hash-fallback memories for agent ${render.wrap(render.c.bold, agentId)} ${render.wrap(render.c.dim, `(showing ${rows.length})`)}\n`);
+        const cols = [
+            { label: "id", key: "id" },
+            {
+                label: "created_at",
+                key: "createdAt",
+                format: (v) => (v ? String(v).slice(0, 19).replace("T", " ") : "—"),
+            },
+            {
+                label: "preview",
+                key: "content",
+                format: (v) => String(v ?? "").replace(/\s+/g, " ").slice(0, 80),
+            },
+        ];
+        console.log(render.table(cols, rows));
+        if (fallback.length > rows.length) {
+            console.log(`\n${render.wrap(render.c.dim, `... ${fallback.length - rows.length} more (raise with --limit). To backfill:`)} flair reembed --agent ${agentId} --stale-only`);
+        }
+        else {
+            console.log(`\n${render.wrap(render.c.dim, "To backfill:")} flair reembed --agent ${agentId} --stale-only`);
+        }
         return;
     }
-    // --hash-fallback: filter to entries without a real embedding and print as a table.
-    // Same predicate HealthDetail uses: missing model or the "hash-512d" marker.
+    // Default lens: all memories for the agent.
     const all = Array.isArray(raw) ? raw : (raw?.results ?? raw?.items ?? []);
-    const fallback = all.filter((m) => !m.embeddingModel || m.embeddingModel === "hash-512d");
-    if (fallback.length === 0) {
-        console.log(`No hash-fallback memories for agent ${opts.agent}. All embedded.`);
+    if (mode === "json") {
+        console.log(render.asJSON(all));
+        return;
+    }
+    if (all.length === 0) {
+        console.log(`${render.icons.info} ${render.wrap(render.c.dim, `No memories for agent ${agentId}`)}`);
         return;
     }
-    const limit = Math.max(1, parseInt(opts.limit, 10) || 50);
-    const rows = fallback
+    console.log(`${render.wrap(render.c.bold, String(all.length))} memories for agent ${render.wrap(render.c.bold, agentId)}${opts.tag ? ` ${render.wrap(render.c.dim, `(tag=${opts.tag})`)}` : ""}\n`);
+    const sorted = all
         .slice()
         .sort((a, b) => {
         const ta = a.createdAt ? new Date(a.createdAt).getTime() : 0;
         const tb = b.createdAt ? new Date(b.createdAt).getTime() : 0;
         return tb - ta;
-    })
-        .slice(0, limit);
-    const idW = Math.max(2, ...rows.map((r) => String(r.id ?? "").length));
-    console.log(`${fallback.length} hash-fallback memories for agent ${opts.agent} (showing ${rows.length}):\n`);
-    console.log(`  ${"id".padEnd(idW)}  created_at            preview`);
-    for (const r of rows) {
-        const created = r.createdAt ? String(r.createdAt).slice(0, 19).replace("T", " ") : "—".padEnd(19);
-        const preview = String(r.content ?? "").replace(/\s+/g, " ").slice(0, 80);
-        console.log(`  ${String(r.id ?? "").padEnd(idW)}  ${created}  ${preview}`);
-    }
-    if (fallback.length > rows.length) {
-        console.log(`\n... ${fallback.length - rows.length} more (raise with --limit). To backfill: flair reembed --agent ${opts.agent} --stale-only`);
-    }
-    else {
-        console.log(`\nTo backfill: flair reembed --agent ${opts.agent} --stale-only`);
-    }
+    });
+    const durabilityColor = (d) => {
+        if (d === "permanent")
+            return render.c.magenta;
+        if (d === "persistent")
+            return render.c.blue;
+        if (d === "ephemeral")
+            return render.c.gray;
+        return render.c.cyan;
+    };
+    const cols = [
+        {
+            label: "created_at",
+            key: "createdAt",
+            format: (v) => (v ? render.wrap(render.c.dim, String(v).slice(0, 10)) : render.wrap(render.c.dim, "—")),
+        },
+        {
+            label: "durability",
+            key: "durability",
+            format: (v) => {
+                const d = String(v ?? "standard");
+                return render.wrap(durabilityColor(d), d);
+            },
+        },
+        {
+            label: "preview",
+            key: "content",
+            format: (v) => String(v ?? "").replace(/\s+/g, " ").slice(0, 80),
+        },
+    ];
+    console.log(render.table(cols, sorted));
 });
 // ─── flair memory hygiene ────────────────────────────────────────────────────
 // Detect + remove junk memory rows that accumulate over time. Surfaced from
-// the 2026-05-07 manual cleanup (ops-ucyy): rockit had 627 records, ~250 of
+// the 2026-05-07 manual cleanup (ops-ucyy): an instance had 627 records, ~250 of
 // them were noise — `*-compact-*` ID fragments from an old pipeline, pangram
 // test content ("the quick brown fox..." / "Flair 251 test ..."), and
 // near-empty rows (<25 chars). We did the cleanup ad-hoc with raw curl + jq;
@@ -6421,47 +7164,184 @@ memory.command("hygiene")
     console.log("hygiene --apply` on each peer to fan out.");
 });
 // ─── flair search (top-level shortcut) ───────────────────────────────────────
+// Parse --since / --as-of: accept ISO 8601 OR relative expressions
+// ("1h", "7d", "30m"). Returns ISO 8601 string or null if input is empty.
+// Returns the original string unchanged if it looks like a date (caller
+// passes through to server, which validates).
+function parseRelativeOrIso(input) {
+    if (!input)
+        return null;
+    const m = input.match(/^(\d+)([smhdw])$/);
+    if (!m)
+        return input;
+    const n = Number.parseInt(m[1], 10);
+    const unit = m[2];
+    const multMs = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000, w: 604_800_000 };
+    return new Date(Date.now() - n * (multMs[unit] ?? 0)).toISOString();
+}
 program
     .command("search <query>")
-    .description("Search memories by meaning (shortcut for memory search)")
-    .requiredOption("--agent <id>", "Agent ID")
+    .description("Search memories by meaning (shortcut for memory search) — filterable, with --explain ranking")
+    .option("--agent <id>", "Agent ID (or set FLAIR_AGENT_ID env)")
     .option("--limit <n>", "Max results", "5")
     .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("--key <path>", "Ed25519 private key path")
+    // Server-side filters (forwarded to /SemanticSearch payload)
+    .option("--tag <tag>", "Filter to memories carrying this tag")
+    .option("--subject <subject>", "Filter to memories carrying this subject (case-insensitive)")
+    .option("--subjects <list>", "Comma-separated list of subjects to OR-filter (case-insensitive)")
+    .option("--since <iso-or-relative>", "Only memories created after this point (ISO 8601 or '7d'/'24h'/'30m')")
+    .option("--as-of <iso>", "Temporal validity: only memories valid at this point (ISO 8601)")
+    .option("--include-superseded", "Include memories that have been superseded")
+    .option("--scoring <mode>", "Scoring mode: composite (default) re-ranks by durability/recency/retrieval; raw uses cosine similarity only", "composite")
+    .option("--min-score <n>", "Drop results below this score (0..1)", "0")
+    // Client-side filters (applied after server response)
+    .option("--durability <level>", "Filter to permanent|persistent|standard|ephemeral (client-side)")
+    .option("--source <name>", "Filter by source/agentId (client-side)")
+    // Output modes
+    .option("--explain", "Show score breakdown (composite, raw, durability, age, retrieval) per hit")
+    .option("--json", "Output raw JSON array")
     .action(async (query, opts) => {
     try {
-        const baseUrl = opts.url || `http://127.0.0.1:${resolveHttpPort(opts)}`;
+        const agentId = resolveAgentIdOrEnv(opts);
+        if (!agentId) {
+            console.error("error: --agent <id> required (or set FLAIR_AGENT_ID)");
+            process.exit(2);
+        }
+        const baseUrl = resolveBaseUrl(opts);
         const headers = { "content-type": "application/json" };
-        const keyPath = opts.key || resolveKeyPath(opts.agent);
+        const keyPath = opts.key || resolveKeyPath(agentId);
         if (keyPath) {
-            headers["authorization"] = buildEd25519Auth(opts.agent, "POST", "/SemanticSearch", keyPath);
+            headers["authorization"] = buildEd25519Auth(agentId, "POST", "/SemanticSearch", keyPath);
         }
+        // Build payload from CLI options. Server validates types.
+        const payload = {
+            agentId,
+            q: query,
+            limit: Number.parseInt(opts.limit, 10) || 5,
+            scoring: opts.scoring === "raw" ? "raw" : "composite",
+        };
+        if (opts.tag)
+            payload.tag = opts.tag;
+        if (opts.subject)
+            payload.subject = opts.subject;
+        if (opts.subjects)
+            payload.subjects = String(opts.subjects).split(",").map((s) => s.trim()).filter(Boolean);
+        const since = parseRelativeOrIso(opts.since);
+        if (since)
+            payload.since = since;
+        if (opts.asOf)
+            payload.asOf = opts.asOf;
+        if (opts.includeSuperseded)
+            payload.includeSuperseded = true;
+        const minScore = Number.parseFloat(opts.minScore ?? "0");
+        if (Number.isFinite(minScore) && minScore > 0)
+            payload.minScore = minScore;
         const res = await fetch(`${baseUrl}/SemanticSearch`, {
             method: "POST",
             headers,
-            body: JSON.stringify({ agentId: opts.agent, q: query, limit: parseInt(opts.limit, 10) }),
+            body: JSON.stringify(payload),
         });
         if (!res.ok)
             throw new Error(await res.text());
-        const result = await res.json();
-        const results = result.results || result || [];
-        if (!Array.isArray(results) || results.length === 0) {
-            console.log("No results found.");
+        const result = (await res.json());
+        let results = result.results || result || [];
+        if (!Array.isArray(results))
+            results = [];
+        // Client-side filters: durability + source. Server doesn't expose these
+        // as conditions, so we filter after fetch.
+        if (opts.durability) {
+            const allowed = new Set(String(opts.durability).split(",").map((d) => d.trim()));
+            results = results.filter((r) => allowed.has(r.durability ?? "standard"));
+        }
+        if (opts.source) {
+            const allowed = new Set(String(opts.source).split(",").map((s) => s.trim()));
+            results = results.filter((r) => allowed.has(r._source ?? r.agentId ?? ""));
+        }
+        const mode = render.resolveOutputMode(opts);
+        if (mode === "json") {
+            console.log(render.asJSON(results));
+            return;
+        }
+        if (results.length === 0) {
+            console.log(`${render.icons.info} ${render.wrap(render.c.dim, "No results found.")}`);
+            const filters = [];
+            if (opts.tag)
+                filters.push(`tag=${opts.tag}`);
+            if (opts.subject)
+                filters.push(`subject=${opts.subject}`);
+            if (opts.subjects)
+                filters.push(`subjects=${opts.subjects}`);
+            if (opts.since)
+                filters.push(`since=${opts.since}`);
+            if (opts.durability)
+                filters.push(`durability=${opts.durability}`);
+            if (opts.source)
+                filters.push(`source=${opts.source}`);
+            if (filters.length > 0) {
+                console.log(`  ${render.wrap(render.c.dim, "Filters:")} ${filters.join(render.wrap(render.c.dim, " · "))}`);
+                console.log(`  ${render.icons.arrow} ${render.wrap(render.c.dim, "Try removing a filter or:")} flair search "${query}" --agent ${agentId}`);
+            }
             return;
         }
+        const durabilityColor = (d) => {
+            if (d === "permanent")
+                return render.c.magenta;
+            if (d === "persistent")
+                return render.c.blue;
+            if (d === "ephemeral")
+                return render.c.gray;
+            return render.c.cyan;
+        };
         for (const r of results) {
-            const date = r.createdAt ? r.createdAt.slice(0, 10) : "";
-            const score = r._score ? `${(r._score * 100).toFixed(0)}%` : "";
-            const meta = [date, r.type, score].filter(Boolean).join(" · ");
+            const date = r.createdAt ? String(r.createdAt).slice(0, 10) : "";
+            const scoreVal = typeof r._score === "number" ? r._score : 0;
+            const scorePct = typeof r._score === "number" ? `${(scoreVal * 100).toFixed(0)}%` : "";
+            const scoreColor = scoreVal >= 0.7 ? render.c.green : scoreVal >= 0.4 ? render.c.yellow : render.c.dim;
+            const durability = r.durability ?? "standard";
+            const metaParts = [];
+            if (date)
+                metaParts.push(render.wrap(render.c.dim, date));
+            metaParts.push(render.wrap(durabilityColor(durability), durability));
+            if (scorePct)
+                metaParts.push(render.wrap(scoreColor, scorePct));
+            if (r._source)
+                metaParts.push(render.wrap(render.c.cyan, `from:${r._source}`));
+            const meta = metaParts.join(render.wrap(render.c.dim, " · "));
             console.log(`  ${r.content}`);
             if (meta)
-                console.log(`  (${meta})`);
+                console.log(`  ${render.wrap(render.c.dim, "(")} ${meta} ${render.wrap(render.c.dim, ")")}`);
+            if (opts.explain) {
+                const parts = [];
+                if (typeof r._rawScore === "number")
+                    parts.push(`raw=${r._rawScore.toFixed(3)}`);
+                if (typeof r._score === "number")
+                    parts.push(`composite=${r._score.toFixed(3)}`);
+                if (typeof r.retrievalCount === "number" && r.retrievalCount > 0)
+                    parts.push(`retrievals=${r.retrievalCount}`);
+                if (r.tags && Array.isArray(r.tags) && r.tags.length > 0)
+                    parts.push(`tags=[${r.tags.join(",")}]`);
+                if (r.subject)
+                    parts.push(`subject=${r.subject}`);
+                if (r.supersedes)
+                    parts.push(`supersedes=${r.supersedes}`);
+                if (parts.length > 0) {
+                    console.log(`    ${render.wrap(render.c.gray, "└─")} ${render.wrap(render.c.dim, parts.join(" · "))}`);
+                }
+            }
             console.log();
         }
+        if (opts.explain) {
+            const formula = payload.scoring === "composite"
+                ? "semantic × durability-weight × recency-decay × retrieval-boost"
+                : "cosine similarity only";
+            console.log(`${render.wrap(render.c.dim, "Scoring:")} ${render.wrap(render.c.bold, payload.scoring)}  ${render.wrap(render.c.dim, `(${formula})`)}`);
+        }
     }
     catch (err) {
-        console.error(`Search failed: ${err.message}`);
+        console.error(`${render.icons.error} Search failed: ${err.message}`);
         process.exit(1);
     }
 });
@@ -6483,58 +7363,179 @@ program
 program
     .command("bootstrap")
     .description("Cold-start context: get soul + recent memories as formatted text")
-    .requiredOption("--agent <id>", "Agent ID")
+    .option("--agent <id>", "Agent ID (or set FLAIR_AGENT_ID env)")
     .option("--max-tokens <n>", "Maximum tokens in output", "4000")
     .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("--key <path>", "Ed25519 private key path")
+    .option("--json", "Emit JSON {context, tokenEstimate, memoriesIncluded, ...} (also: pipe + FLAIR_OUTPUT=json)")
     .action(async (opts) => {
-    const baseUrl = opts.url || `http://127.0.0.1:${resolveHttpPort(opts)}`;
+    const agentId = resolveAgentIdOrEnv(opts);
+    if (!agentId) {
+        console.error(`${render.icons.error} --agent <id> required (or set FLAIR_AGENT_ID)`);
+        process.exit(2);
+    }
+    const baseUrl = resolveBaseUrl(opts);
+    const mode = render.resolveOutputMode(opts);
     try {
         const headers = { "content-type": "application/json" };
-        const keyPath = opts.key || resolveKeyPath(opts.agent);
+        const keyPath = opts.key || resolveKeyPath(agentId);
         if (keyPath) {
-            headers["authorization"] = buildEd25519Auth(opts.agent, "POST", "/BootstrapMemories", keyPath);
+            headers["authorization"] = buildEd25519Auth(agentId, "POST", "/BootstrapMemories", keyPath);
         }
         const res = await fetch(`${baseUrl}/BootstrapMemories`, {
             method: "POST",
             headers,
-            body: JSON.stringify({ agentId: opts.agent, maxTokens: parseInt(opts.maxTokens, 10) }),
+            body: JSON.stringify({ agentId, maxTokens: parseInt(opts.maxTokens, 10) }),
         });
         if (!res.ok) {
             const body = await res.text();
             throw new Error(`${res.status}: ${body}`);
         }
-        const result = await res.json();
+        const result = (await res.json());
+        if (mode === "json") {
+            // Agent-first: emit the full server response, augmented with the cap
+            // that was requested. Includes context, sections, tokenEstimate, etc.
+            console.log(render.asJSON({ ...result, maxTokens: parseInt(opts.maxTokens, 10) }));
+            return;
+        }
+        // Human mode: print context to stdout, budget footer to stderr (parseable).
         if (result.context) {
             console.log(result.context);
         }
         else {
-            console.error("No context available.");
+            console.error(`${render.icons.error} No context available.`);
             process.exit(1);
         }
-        // Print budget footer to stderr (parseable, won't interfere with context output)
         const tokensUsed = result.tokenEstimate ?? 0;
         const maxTokens = parseInt(opts.maxTokens, 10);
         const included = result.memoriesIncluded ?? 0;
         const truncated = result.memoriesTruncated ?? 0;
-        console.error(`[budget: ${tokensUsed}/${maxTokens} tokens, ${included} included, ${truncated} truncated]`);
+        const tokenPct = maxTokens > 0 ? (tokensUsed / maxTokens) * 100 : 0;
+        const tokenIcon = tokenPct >= 90 ? render.icons.warn : tokenPct >= 70 ? render.icons.info : render.icons.ok;
+        const truncIcon = truncated > 0 ? render.icons.warn : render.icons.ok;
+        console.error(`${tokenIcon} budget ${tokensUsed}/${maxTokens} tokens (${tokenPct.toFixed(0)}%) ${render.icons.bullet} ${render.icons.ok} ${included} included ${render.icons.bullet} ${truncIcon} ${truncated} truncated`);
     }
     catch (err) {
-        console.error(`Bootstrap failed: ${err.message}`);
+        console.error(`${render.icons.error} Bootstrap failed: ${err.message}`);
         process.exit(1);
     }
 });
 const soul = program.command("soul").description("Manage agent soul entries");
-soul.command("set").requiredOption("--agent <id>").requiredOption("--key <key>").requiredOption("--value <value>")
+soul.command("set")
+    .requiredOption("--agent <id>")
+    .requiredOption("--key <key>")
+    .requiredOption("--value <value>")
     .option("--durability <d>", "permanent")
+    .option("--json", "Emit raw JSON response (also: pipe + FLAIR_OUTPUT=json)")
     .action(async (opts) => {
-    const out = await api("POST", "/Soul", { id: `${opts.agent}:${opts.key}`, agentId: opts.agent, key: opts.key, value: opts.value, durability: opts.durability });
-    console.log(JSON.stringify(out, null, 2));
+    const out = await api("POST", "/Soul", {
+        id: `${opts.agent}:${opts.key}`,
+        agentId: opts.agent,
+        key: opts.key,
+        value: opts.value,
+        durability: opts.durability,
+    });
+    const mode = render.resolveOutputMode(opts);
+    if (mode === "json") {
+        console.log(render.asJSON(out));
+        return;
+    }
+    console.log(`${render.icons.ok} ${render.wrap(render.c.green, "soul entry set")}`);
+    console.log(render.kv("agent", opts.agent));
+    console.log(render.kv("key", render.wrap(render.c.bold, opts.key)));
+    console.log(render.kv("value", String(opts.value)));
+    if (opts.durability)
+        console.log(render.kv("durability", render.wrap(render.c.magenta, opts.durability)));
+});
+soul.command("get")
+    .argument("<id>")
+    .option("--json", "Emit raw JSON response (also: pipe + FLAIR_OUTPUT=json)")
+    .action(async (id, opts) => {
+    const out = await api("GET", `/Soul/${id}`);
+    const mode = render.resolveOutputMode(opts);
+    if (mode === "json") {
+        console.log(render.asJSON(out));
+        return;
+    }
+    if (!out || (typeof out === "object" && !out.id)) {
+        console.log(`${render.icons.info} ${render.wrap(render.c.dim, "no entry")}`);
+        return;
+    }
+    console.log(render.wrap(render.c.bold, out.id ?? id));
+    if (out.agentId)
+        console.log(render.kv("agent", out.agentId));
+    if (out.key)
+        console.log(render.kv("key", out.key));
+    if (out.value !== undefined)
+        console.log(render.kv("value", String(out.value)));
+    if (out.durability)
+        console.log(render.kv("durability", render.wrap(render.c.magenta, String(out.durability))));
+    if (out.priority)
+        console.log(render.kv("priority", String(out.priority)));
+    if (out.createdAt)
+        console.log(render.kv("created", `${render.relativeTime(out.createdAt)} ${render.wrap(render.c.dim, `(${out.createdAt})`)}`));
+    if (out.updatedAt && out.updatedAt !== out.createdAt) {
+        console.log(render.kv("updated", `${render.relativeTime(out.updatedAt)} ${render.wrap(render.c.dim, `(${out.updatedAt})`)}`));
+    }
+});
+soul.command("list")
+    .option("--agent <id>", "Agent ID (or set FLAIR_AGENT_ID env)")
+    .option("--json", "Emit raw JSON array (also: pipe + FLAIR_OUTPUT=json)")
+    .action(async (opts) => {
+    const agentId = resolveAgentIdOrEnv(opts);
+    if (!agentId) {
+        console.error(`${render.icons.error} --agent <id> required (or set FLAIR_AGENT_ID)`);
+        process.exit(2);
+    }
+    const out = await api("GET", `/Soul?agentId=${encodeURIComponent(agentId)}`);
+    const mode = render.resolveOutputMode(opts);
+    if (mode === "json") {
+        console.log(render.asJSON(out));
+        return;
+    }
+    const all = Array.isArray(out) ? out : (out?.results ?? out?.items ?? []);
+    if (all.length === 0) {
+        console.log(`${render.icons.info} ${render.wrap(render.c.dim, `no soul entries for agent ${agentId}`)}`);
+        return;
+    }
+    console.log(`${render.wrap(render.c.bold, String(all.length))} soul entries for agent ${render.wrap(render.c.bold, agentId)}\n`);
+    const priorityColor = (p) => {
+        if (p === "critical")
+            return render.c.red;
+        if (p === "high")
+            return render.c.yellow;
+        if (p === "low")
+            return render.c.gray;
+        return render.c.cyan;
+    };
+    const cols = [
+        { label: "key", key: "key", format: (v) => render.wrap(render.c.bold, String(v ?? "—")) },
+        {
+            label: "priority",
+            key: "priority",
+            format: (v) => {
+                const p = String(v ?? "standard");
+                return render.wrap(priorityColor(p), p);
+            },
+        },
+        {
+            label: "durability",
+            key: "durability",
+            format: (v) => {
+                const d = String(v ?? "—");
+                return d === "permanent" ? render.wrap(render.c.magenta, d) : render.wrap(render.c.dim, d);
+            },
+        },
+        {
+            label: "value",
+            key: "value",
+            format: (v) => String(v ?? "").replace(/\s+/g, " ").slice(0, 80),
+        },
+    ];
+    console.log(render.table(cols, all));
 });
-soul.command("get").argument("<id>").action(async (id) => console.log(JSON.stringify(await api("GET", `/Soul/${id}`), null, 2)));
-soul.command("list").requiredOption("--agent <id>")
-    .action(async (opts) => console.log(JSON.stringify(await api("GET", `/Soul?agentId=${encodeURIComponent(opts.agent)}`), null, 2)));
 // ─── flair bridge ────────────────────────────────────────────────────────────
 // Slice 1: discovery + scaffold. Slice 2: YAML runtime + `import` for Shape A
 // + agentic-stack reference adapter as a built-in.
@@ -6549,24 +7550,39 @@ bridge
     const { discover } = await import("./bridges/discover.js");
     const { builtinDiscoveryRecords } = await import("./bridges/builtins/index.js");
     const found = await discover({ builtins: builtinDiscoveryRecords() });
-    if (opts.json) {
-        console.log(JSON.stringify(found, null, 2));
+    const mode = render.resolveOutputMode(opts);
+    if (mode === "json") {
+        console.log(render.asJSON(found));
         return;
     }
     if (found.length === 0) {
-        console.log("No bridges installed.");
-        console.log("Add one with:  flair bridge scaffold <name> --file");
-        console.log("Or install from npm:  npm install flair-bridge-<name>");
+        console.log(`${render.icons.info} ${render.wrap(render.c.dim, "No bridges installed.")}`);
+        console.log(`${render.wrap(render.c.dim, "  Add one with:")}     flair bridge scaffold <name> --file`);
+        console.log(`${render.wrap(render.c.dim, "  Or install from npm:")} npm install flair-bridge-<name>`);
         return;
     }
-    const nameW = Math.max(4, ...found.map((b) => b.name.length));
-    const kindW = Math.max(4, ...found.map((b) => b.kind.length));
-    const srcW = Math.max(6, ...found.map((b) => b.source.length));
-    console.log(`  ${"name".padEnd(nameW)}  ${"kind".padEnd(kindW)}  ${"source".padEnd(srcW)}  description`);
-    for (const b of found) {
-        const desc = b.description ?? "";
-        console.log(`  ${b.name.padEnd(nameW)}  ${b.kind.padEnd(kindW)}  ${b.source.padEnd(srcW)}  ${desc}`);
-    }
+    console.log(`${render.wrap(render.c.bold, String(found.length))} bridge${found.length === 1 ? "" : "s"}\n`);
+    const cols = [
+        { label: "name", key: "name", format: (v) => render.wrap(render.c.bold, String(v ?? "—")) },
+        {
+            label: "kind",
+            key: "kind",
+            format: (v) => {
+                const k = String(v ?? "—");
+                return render.wrap(k === "yaml" ? render.c.cyan : k === "api" ? render.c.magenta : render.c.dim, k);
+            },
+        },
+        {
+            label: "source",
+            key: "source",
+            format: (v) => {
+                const s = String(v ?? "—");
+                return render.wrap(s === "builtin" ? render.c.green : render.c.dim, s);
+            },
+        },
+        { label: "description", key: "description", format: (v) => String(v ?? "") },
+    ];
+    console.log(render.table(cols, found));
 });
 bridge
     .command("scaffold <name>")
@@ -7004,21 +8020,22 @@ bridge
     .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));
+    const mode = render.resolveOutputMode(opts);
+    if (mode === "json") {
+        console.log(render.asJSON(entries));
         return;
     }
     if (entries.length === 0) {
-        console.log("No code-plugin bridges are allow-listed yet.");
-        console.log("Allow one with: flair bridge allow <name>");
+        console.log(`${render.icons.info} ${render.wrap(render.c.dim, "No code-plugin bridges are allow-listed yet.")}`);
+        console.log(`${render.wrap(render.c.dim, "  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`);
+    console.log(`${render.wrap(render.c.bold, String(entries.length))} allow-listed code-plugin bridge${entries.length === 1 ? "" : "s"}\n`);
     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)}…`);
+        console.log(`${render.wrap(render.c.bold, e.name)}  ${render.wrap(render.c.dim, `(${e.version ?? "—"})`)}  ${render.wrap(render.c.green, "✓ allowed")} ${render.wrap(render.c.dim, e.allowedAt)}`);
+        console.log(render.kv("location", render.wrap(render.c.dim, e.packageDir)));
+        console.log(render.kv("digest", render.wrap(render.c.dim, `sha256:${e.packageJsonSha256.slice(0, 16)}…`)));
+        console.log();
     }
 });
 function printBridgeError(err) {
@@ -7116,13 +8133,26 @@ program
     .option("--agents <ids>", "Comma-separated agent IDs to include (default: all)")
     .option("--port <port>", "Harper HTTP port")
     .option("--url <url>", "Flair base URL (overrides --port)")
-    .option("--admin-pass <pass>", "Admin password (or set FLAIR_ADMIN_PASS env)")
+    .option("--admin-pass <pass>", "Admin password (or set FLAIR_ADMIN_PASS env, or use --admin-pass-file)")
+    .option("--admin-pass-file <path>", "Read admin password from a file (e.g., ~/.flair/admin-pass). Preferred over --admin-pass for launchd/cron — keeps the secret out of ps and shell history.")
     .action(async (opts) => {
     const baseUrl = opts.url ?? `http://127.0.0.1:${resolveHttpPort(opts)}`;
-    const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
+    let adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
+    if (!adminPass && opts.adminPassFile) {
+        // readAdminPassFileSecure refuses world/group readable files (mode 0600
+        // recommended). Common gotcha: files generated via
+        // `openssl rand -base64 24 > admin-pass` end in a newline; helper trims it.
+        try {
+            adminPass = readAdminPassFileSecure(opts.adminPassFile);
+        }
+        catch (err) {
+            console.error(`Error reading --admin-pass-file ${opts.adminPassFile}: ${err.message}`);
+            process.exit(1);
+        }
+    }
     const adminUser = DEFAULT_ADMIN_USER;
     if (!adminPass) {
-        console.error("Error: --admin-pass or FLAIR_ADMIN_PASS required for backup");
+        console.error("Error: --admin-pass, --admin-pass-file, or FLAIR_ADMIN_PASS required for backup");
         process.exit(1);
     }
     const auth = `Basic ${Buffer.from(`${adminUser}:${adminPass}`).toString("base64")}`;
@@ -7181,11 +8211,11 @@ program
     const tmp = outputPath + ".tmp";
     writeFileSync(tmp, JSON.stringify(backup, null, 2) + "\n", "utf-8");
     renameSync(tmp, outputPath);
-    console.log(`\n✅ Backup complete`);
-    console.log(`   Agents:   ${agents.length}`);
-    console.log(`   Memories: ${memories.length}`);
-    console.log(`   Souls:    ${souls.length}`);
-    console.log(`   Output:   ${outputPath}`);
+    console.log(`\n${render.icons.ok} ${render.wrap(render.c.green, "Backup complete")}`);
+    console.log(render.kv("Agents", render.wrap(render.c.bold, String(agents.length))));
+    console.log(render.kv("Memories", render.wrap(render.c.bold, String(memories.length))));
+    console.log(render.kv("Souls", render.wrap(render.c.bold, String(souls.length))));
+    console.log(render.kv("Output", render.wrap(render.c.dim, outputPath)));
 });
 // ─── flair restore ────────────────────────────────────────────────────────────
 program
@@ -7299,10 +8329,10 @@ program
             console.warn(`  warn: soul ${soul.id}: ${err.message}`);
         }
     }
-    console.log(`\n✅ Restore complete`);
-    console.log(`   Agents restored:   ${agentCount}/${agents.length}`);
-    console.log(`   Memories restored: ${memoryCount}/${memories.length}`);
-    console.log(`   Souls restored:    ${soulCount}/${souls.length}`);
+    console.log(`\n${render.icons.ok} ${render.wrap(render.c.green, "Restore complete")}`);
+    console.log(render.kv("Agents restored", `${render.wrap(render.c.bold, String(agentCount))}${render.wrap(render.c.dim, `/${agents.length}`)}`));
+    console.log(render.kv("Memories restored", `${render.wrap(render.c.bold, String(memoryCount))}${render.wrap(render.c.dim, `/${memories.length}`)}`));
+    console.log(render.kv("Souls restored", `${render.wrap(render.c.bold, String(soulCount))}${render.wrap(render.c.dim, `/${souls.length}`)}`));
 });
 // ─── flair export ────────────────────────────────────────────────────────────
 program
@@ -7384,13 +8414,16 @@ program
     writeFileSync(outputPath, JSON.stringify(exportData, null, 2), { mode: fileMode });
     if (privateKey)
         chmodSync(outputPath, 0o600); // enforce even if umask is permissive
-    console.log(`\n✅ Agent '${agentId}' exported`);
-    console.log(`   Memories: ${memories.length}`);
-    console.log(`   Souls:    ${souls.length}`);
-    console.log(`   Grants:   ${grants.length}`);
-    console.log(`   Key:      ${privateKey ? "included (UNENCRYPTED — protect this file)" : "not included"}`);
-    console.log(`   Mode:     ${fileMode.toString(8)} (${privateKey ? "owner-only" : "standard"})`);
-    console.log(`   Output:   ${outputPath}`);
+    console.log(`\n${render.icons.ok} ${render.wrap(render.c.green, `Agent '${agentId}' exported`)}`);
+    console.log(render.kv("Memories", render.wrap(render.c.bold, String(memories.length))));
+    console.log(render.kv("Souls", render.wrap(render.c.bold, String(souls.length))));
+    console.log(render.kv("Grants", render.wrap(render.c.bold, String(grants.length))));
+    const keyText = privateKey
+        ? `${render.wrap(render.c.magenta, "included")} ${render.wrap(render.c.red, "(UNENCRYPTED — protect this file)")}`
+        : render.wrap(render.c.dim, "not included");
+    console.log(render.kv("Key", keyText));
+    console.log(render.kv("Mode", `${fileMode.toString(8)} ${render.wrap(render.c.dim, `(${privateKey ? "owner-only" : "standard"})`)}`));
+    console.log(render.kv("Output", render.wrap(render.c.dim, outputPath)));
 });
 // ─── flair import ────────────────────────────────────────────────────────────
 program
@@ -7481,40 +8514,50 @@ program
         }
         catch { /* skip failures */ }
     }
-    console.log(`\n✅ Agent '${agentId}' imported`);
-    console.log(`   Memories: ${memCount}/${(data.memories ?? []).length}`);
-    console.log(`   Souls:    ${soulCount}/${(data.souls ?? []).length}`);
-    console.log(`   Key:      ${privPath}`);
+    console.log(`\n${render.icons.ok} ${render.wrap(render.c.green, `Agent '${agentId}' imported`)}`);
+    console.log(render.kv("Memories", `${render.wrap(render.c.bold, String(memCount))}${render.wrap(render.c.dim, `/${(data.memories ?? []).length}`)}`));
+    console.log(render.kv("Souls", `${render.wrap(render.c.bold, String(soulCount))}${render.wrap(render.c.dim, `/${(data.souls ?? []).length}`)}`));
+    console.log(render.kv("Key", render.wrap(render.c.dim, privPath)));
 });
 // ─── flair backup inspect ────────────────────────────────────────────────────
 program
     .command("inspect <path>")
     .description("Show contents of a backup or export file")
-    .action(async (filePath) => {
+    .option("--json", "Emit raw JSON of the file (also: pipe + FLAIR_OUTPUT=json)")
+    .action(async (filePath, opts) => {
     if (!existsSync(filePath)) {
-        console.error(`File not found: ${filePath}`);
+        console.error(`${render.icons.error} File not found: ${render.wrap(render.c.dim, filePath)}`);
         process.exit(1);
     }
     const data = JSON.parse(readFileSync(filePath, "utf-8"));
-    console.log(`File: ${filePath}`);
-    console.log(`Type: ${data.type ?? "full-backup"}`);
-    console.log(`Created: ${data.createdAt ?? data.exportedAt ?? "unknown"}`);
-    console.log(`Source: ${data.source ?? "unknown"}`);
+    const mode = render.resolveOutputMode(opts);
+    if (mode === "json") {
+        console.log(render.asJSON(data));
+        return;
+    }
+    console.log(`${render.wrap(render.c.bold, "File:")}    ${render.wrap(render.c.dim, filePath)}`);
+    const type = data.type ?? "full-backup";
+    const typeColor = type === "agent-export" ? render.c.cyan : render.c.magenta;
+    console.log(render.kv("Type", render.wrap(typeColor, type)));
+    console.log(render.kv("Created", String(data.createdAt ?? data.exportedAt ?? render.wrap(render.c.dim, "unknown"))));
+    console.log(render.kv("Source", String(data.source ?? render.wrap(render.c.dim, "unknown"))));
     if (data.type === "agent-export") {
-        console.log(`\nAgent: ${data.agent?.id ?? "unknown"}`);
-        console.log(`  Name: ${data.agent?.name ?? data.agent?.id}`);
-        console.log(`  Memories: ${(data.memories ?? []).length}`);
-        console.log(`  Souls: ${(data.souls ?? []).length}`);
-        console.log(`  Grants: ${(data.grants ?? []).length}`);
-        console.log(`  Key included: ${data.privateKey ? "yes" : "no"}`);
+        console.log(`\n${render.wrap(render.c.bold, "Agent")}: ${render.wrap(render.c.bold, data.agent?.id ?? "unknown")}`);
+        console.log(render.kv("Name", String(data.agent?.name ?? data.agent?.id ?? "—")));
+        console.log(render.kv("Memories", render.wrap(render.c.bold, String((data.memories ?? []).length))));
+        console.log(render.kv("Souls", render.wrap(render.c.bold, String((data.souls ?? []).length))));
+        console.log(render.kv("Grants", render.wrap(render.c.bold, String((data.grants ?? []).length))));
+        const keyText = data.privateKey ? render.wrap(render.c.magenta, "yes") : render.wrap(render.c.dim, "no");
+        console.log(render.kv("Key included", keyText));
     }
     else {
         const agents = data.agents ?? [];
-        console.log(`\nAgents: ${agents.length}`);
-        for (const a of agents)
-            console.log(`  - ${a.id} (${a.name ?? a.id})`);
-        console.log(`Memories: ${(data.memories ?? []).length}`);
-        console.log(`Souls: ${(data.souls ?? []).length}`);
+        console.log(`\n${render.wrap(render.c.bold, "Agents")}: ${render.wrap(render.c.bold, String(agents.length))}`);
+        for (const a of agents) {
+            console.log(`  ${render.wrap(render.c.dim, "·")} ${render.wrap(render.c.bold, a.id)} ${render.wrap(render.c.dim, `(${a.name ?? a.id})`)}`);
+        }
+        console.log(render.kv("Memories", render.wrap(render.c.bold, String((data.memories ?? []).length))));
+        console.log(render.kv("Souls", render.wrap(render.c.bold, String((data.souls ?? []).length))));
     }
 });
 // ─── flair migrate-harness-memory ───────────────────────────────────────────