@synap-core/cli 1.7.0 → 1.10.0

package/dist/commands/data.js

@@ -1,75 +1,128 @@
 import chalk from "chalk";
 import { log } from "../utils/logger.js";
-import { resolveHubConfig, resolveUserId, hubGet, hubPost, hubPatch } from "../lib/hub-client.js";
-// ─── orient ───────────────────────────────────────────────────────────────────
+import { resolveHubConfig, resolveUserId, hubGet, hubPost, hubPatch, readActiveSessionId, renderHubError } from "../lib/hub-client.js";
+import { unwrapList } from "../lib/unwrapList.js";
+import { reportWrite } from "../lib/capture-lane.js";
+import { renderNextSteps, FLOW } from "../lib/next-steps.js";
+export const parseLimit = (s, def) => s ? parseInt(s, 10) : def;
+export function formatHit(hit) {
+    const doc = (hit.document ?? hit);
+    return {
+        title: String(doc.title ?? doc.id ?? hit.id ?? ""),
+        // `type` is the entity's profile (entities carry `type`; search hits carry
+        // `entityType`/`collection`). Include `doc.type` or the badge renders blank.
+        type: String(doc.entityType ?? doc.profileSlug ?? doc.type ?? hit.collection ?? ""),
+        id: String(doc.id ?? hit.id ?? "").slice(0, 8),
+    };
+}
 export async function orient(opts) {
     try {
         const cfg = await resolveHubConfig(opts);
-        const [workspacesRes, meRes] = await Promise.all([
-            hubGet("/workspaces", {}, cfg),
-            hubGet("/users/me", {}, cfg),
-        ]);
-        const workspaces = workspacesRes.workspaces ?? workspacesRes;
-        const me = meRes;
-        const userId = String(me.id ?? cfg.userId);
-        const wsList = Array.isArray(workspaces) ? workspaces : [];
-        // For each workspace, fetch profiles + entity count in parallel
-        const wsDetails = await Promise.all(wsList.map(async (ws) => {
-            const wsId = String(ws.id ?? "");
-            const [profilesRes, entitiesRes] = await Promise.allSettled([
-                hubGet("/profiles", { userId, workspaceId: wsId }, cfg),
-                hubGet("/entities", { userId, workspaceId: wsId, limit: 1 }, cfg),
-            ]);
-            const profiles = profilesRes.status === "fulfilled"
-                ? (profilesRes.value.profiles ?? profilesRes.value)
-                : [];
-            const profileList = Array.isArray(profiles) ? profiles : [];
-            const entityTotal = entitiesRes.status === "fulfilled"
-                ? Number(entitiesRes.value.total ?? 0)
-                : 0;
-            return { ws, profileList, entityTotal };
-        }));
+        // ONE canonical shape: the backend `discover()` service (via GET /orient)
+        // assembles the lens map — workspaces + projects + profile sample +
+        // disclosure (onboarding→goal, entity counts, per-ws profiles under full).
+        // The CLI only RENDERS it; `--details` maps to detail:'full'. No client-side
+        // assembly, no N+1 fanout — the server does the shaping.
+        const res = (await hubGet("/orient", opts.details ? { detail: "full" } : {}, cfg));
+        const userId = String(res.me?.userId ?? cfg.userId);
+        const projList = res.projects ?? [];
+        const wsList = res.workspaces ?? [];
         if (opts.json) {
-            console.log(JSON.stringify({ userId, podUrl: cfg.podUrl, workspaceId: cfg.workspaceId, workspaces: wsDetails, me }, null, 2));
+            console.log(JSON.stringify({ ...res, podUrl: cfg.podUrl, workspaceId: cfg.workspaceId, nextSteps: FLOW.afterOrient() }, null, 2));
             return;
         }
+        // Render content rows with console.log (default terminal fg) rather than
+        // log.info — log.info wraps every line in chalk.blue, and that blue fg
+        // persists through inner bold/dim (they reset weight, not color), flattening
+        // the hierarchy. We keep only targeted accents: bold=name, dim=metadata,
+        // green ▶ = active.
         log.heading("Pod Orientation");
-        log.info(`User     : ${String(me.email ?? me.name ?? userId)}`);
-        log.info(`Pod URL  : ${cfg.podUrl}`);
-        if (cfg.workspaceId)
-            log.info(`Workspace: ${cfg.workspaceId} ${chalk.dim("(active — use 'synap use <id>' to change)")}`);
+        console.log(`  User     : ${userId}`);
+        console.log(`  Pod URL  : ${cfg.podUrl}`);
+        // The per-Claude-session lens (project + workspace + session) — "where am I".
+        // Full ids so they can be pasted into 'synap project use' / 'synap use'.
+        const { getClaudeSessionId, resolveActiveLens } = await import("../lib/session-lens.js");
+        let activeProjectId;
+        if (getClaudeSessionId()) {
+            const lens = resolveActiveLens();
+            activeProjectId = lens?.projectId ?? undefined;
+            const proj = lens?.projectId ?? chalk.dim("none");
+            const ws = lens?.workspaceId ?? cfg.workspaceId ?? chalk.dim("pod-wide");
+            const sess = lens?.focusSessionId ?? chalk.dim("none");
+            console.log(`  Lens     : ${chalk.dim("project")} ${proj} · ${chalk.dim("ws")} ${ws} · ${chalk.dim("session")} ${sess}`);
+        }
+        else if (cfg.workspaceId) {
+            console.log(`  Workspace: ${cfg.workspaceId} ${chalk.dim("(active — use 'synap use <id>' to change)")}`);
+        }
+        // ── Projects (companies / initiatives) — the primary lens ───────────────
+        log.blank();
+        log.heading("Projects");
+        if (projList.length === 0) {
+            log.dim("No projects yet — a project is a company/initiative that ties workspaces together.");
+        }
+        else {
+            for (const p of projList) {
+                const isActive = p.id === activeProjectId;
+                const marker = isActive ? chalk.green("▶ ") : "  ";
+                const name = chalk.bold(String(p.name ?? p.id));
+                const id = chalk.dim(String(p.id ?? ""));
+                const status = p.status ? chalk.dim(String(p.status)) : "";
+                const homePart = p.homeWorkspace ? chalk.dim(`· ${p.homeWorkspace}`) : "";
+                console.log(`  ${marker}${name}  ${id}  ${status}${homePart ? "  " + homePart : ""}`);
+            }
+        }
+        // ── Workspaces (operational domains) ────────────────────────────────────
         log.blank();
         log.heading("Workspaces");
-        if (wsDetails.length === 0) {
+        if (wsList.length === 0) {
             log.dim("No workspaces found.");
         }
-        else {
-            for (const { ws, profileList, entityTotal } of wsDetails) {
+        else if (opts.details) {
+            for (const ws of wsList) {
                 const isActive = ws.id === cfg.workspaceId;
                 const marker = isActive ? chalk.green("▶ ") : "  ";
                 const name = chalk.bold(String(ws.name ?? ws.id));
-                const id = chalk.dim(String(ws.id ?? "").slice(0, 8) + "…");
-                const count = entityTotal > 0 ? chalk.dim(`${entityTotal} entities`) : chalk.dim("empty");
-                log.info(`${marker}${name}  ${id}  ${count}`);
+                const id = chalk.dim(String(ws.id ?? ""));
+                const count = ws.entityCount > 0
+                    ? chalk.dim(`${ws.entityCount} entities`)
+                    : chalk.dim("empty");
+                console.log(`  ${marker}${name}  ${id}  ${count}`);
                 if (ws.description)
                     log.dim(`     ${String(ws.description)}`);
-                if (profileList.length > 0) {
-                    const slugs = profileList
-                        .map((p) => String(p.slug ?? p.name ?? ""))
+                if (ws.onboarding?.goal && ws.entityCount === 0) {
+                    log.dim(`     ${chalk.cyan("→ onboard:")} ${String(ws.onboarding.goal)}`);
+                }
+                const profiles = ws.profiles ?? [];
+                if (profiles.length > 0) {
+                    const slugs = profiles
+                        .map((p) => p.slug)
                         .filter(Boolean)
                         .slice(0, 8)
                         .join(chalk.dim(", "));
-                    log.dim(`     profiles: ${slugs}${profileList.length > 8 ? chalk.dim(" …") : ""}`);
+                    log.dim(`     profiles: ${slugs}${profiles.length > 8 ? chalk.dim(" …") : ""}`);
                 }
             }
-            if (!cfg.workspaceId) {
-                log.blank();
-                log.dim("Tip: run 'synap use <workspaceId>' to set a default workspace.");
+        }
+        else {
+            // Light: name + id + domain (operational-domain label = workspaceSubtype
+            // falling back to workspaceType, resolved server-side).
+            for (const ws of wsList) {
+                const isActive = ws.id === cfg.workspaceId;
+                const marker = isActive ? chalk.green("▶ ") : "  ";
+                const name = chalk.bold(String(ws.name ?? ws.id));
+                const id = chalk.dim(String(ws.id ?? ""));
+                const domain = ws.domain ? chalk.dim(String(ws.domain)) : "";
+                console.log(`  ${marker}${name}  ${id}  ${domain}`);
             }
+            log.blank();
+            log.dim("Workspaces are operational domains; run 'synap orient --details' for profiles + entity counts.");
         }
+        log.blank();
+        log.dim("Lenses compose — a project spans workspaces; a workspace spans projects. Omit them to stay pod-wide.");
+        renderNextSteps(FLOW.afterOrient());
     }
     catch (e) {
-        console.error(chalk.red("Error: " + e.message));
+        renderHubError(e);
         process.exit(1);
     }
 }
@@ -80,8 +133,7 @@ export async function useWorkspace(workspaceId, opts) {
         const userId = await resolveUserId(cfg);
         // Verify the workspace exists and is accessible
         const res = await hubGet("/workspaces", {}, cfg);
-        const workspaces = res.workspaces ?? res;
-        const list = Array.isArray(workspaces) ? workspaces : [];
+        const list = unwrapList(res, ["workspaces"]);
         const match = list.find((w) => w.id === workspaceId || String(w.name).toLowerCase() === workspaceId.toLowerCase());
         if (!match) {
             const names = list.map((w) => `${String(w.name ?? w.id)}`).join(", ");
@@ -90,17 +142,26 @@ export async function useWorkspace(workspaceId, opts) {
                 log.dim(`Available: ${names}`);
             process.exit(1);
         }
-        const { setActiveWorkspaceId } = await import("../lib/pod.js");
-        setActiveWorkspaceId(String(match.id));
+        // In a Claude Code session, scope to THIS session's lens (so concurrent
+        // sessions can be on different workspaces). Otherwise set the global default.
+        const { getClaudeSessionId, writeLens } = await import("../lib/session-lens.js");
+        const claudeSession = getClaudeSessionId();
+        if (claudeSession) {
+            writeLens(claudeSession, { workspaceId: String(match.id) });
+        }
+        else {
+            const { setActiveWorkspaceId } = await import("../lib/pod.js");
+            setActiveWorkspaceId(String(match.id));
+        }
         if (opts.json) {
-            console.log(JSON.stringify({ workspaceId: match.id, name: match.name }, null, 2));
+            console.log(JSON.stringify({ workspaceId: match.id, name: match.name, scope: claudeSession ? "session" : "global" }, null, 2));
             return;
         }
-        log.success(`Now in workspace: ${chalk.bold(String(match.name ?? match.id))} ${chalk.dim(String(match.id ?? ""))}`);
-        void userId; // consumed by resolveUserId side-effect
+        const scopeNote = claudeSession ? chalk.dim(" (this session)") : "";
+        log.success(`Now in workspace: ${chalk.bold(String(match.name ?? match.id))} ${chalk.dim(String(match.id ?? ""))}${scopeNote}`);
     }
     catch (e) {
-        console.error(chalk.red("Error: " + e.message));
+        renderHubError(e);
         process.exit(1);
     }
 }
@@ -109,8 +170,7 @@ export async function listWorkspaces(opts) {
     try {
         const cfg = await resolveHubConfig(opts);
         const res = await hubGet("/workspaces", {}, cfg);
-        const workspaces = res.workspaces ?? res;
-        const list = Array.isArray(workspaces) ? workspaces : [];
+        const list = unwrapList(res, ["workspaces"]);
         if (opts.json) {
             console.log(JSON.stringify({ workspaces: list }, null, 2));
             return;
@@ -125,7 +185,7 @@ export async function listWorkspaces(opts) {
         }
     }
     catch (e) {
-        console.error(chalk.red("Error: " + e.message));
+        renderHubError(e);
         process.exit(1);
     }
 }
@@ -134,21 +194,53 @@ export async function listEntities(opts) {
     try {
         const cfg = await resolveHubConfig(opts);
         const userId = await resolveUserId(cfg);
-        const limit = parseInt(opts.limit ?? "20", 10);
+        const limit = parseLimit(opts.limit, 20);
+        const workspaceId = opts.workspace ?? cfg.workspaceId;
+        // --role needs a workspace to resolve facet scope (see browseEntities);
+        // without one the filter is silently dropped and "no entities" would lie.
+        if (opts.role && !workspaceId) {
+            throw new Error("--role needs an active workspace to resolve the role. Run 'synap use <workspace>' or pass --workspace <id>.");
+        }
         const res = await hubGet("/entities", {
             userId,
-            workspaceId: opts.workspace ?? cfg.workspaceId,
+            workspaceId,
             profileSlug: opts.profile,
+            // Browse-by-role: the list route resolves facet scope from the
+            // `workspaceId` QUERY PARAM (already threaded above), not the
+            // X-Workspace-Id header — verified against the live pod.
+            facetSlug: opts.role,
             limit,
         }, cfg);
-        const entities = res.entities ?? res;
-        const list = Array.isArray(entities) ? entities : [];
+        const list = unwrapList(res, ["entities"]);
         if (opts.json) {
-            console.log(JSON.stringify({ entities: list }, null, 2));
+            console.log(JSON.stringify({ entities: list, count: list.length, limit, truncated: list.length === limit }, null, 2));
             return;
         }
         if (list.length === 0) {
             log.dim("No entities found.");
+            // Whiteboards, kanbans, calendars… are VIEWS, not entity profiles.
+            // If the requested profile is actually a view type, point there.
+            if (opts.profile) {
+                try {
+                    const viewsRes = await hubGet("/views", {
+                        userId,
+                        workspaceId: opts.workspace ?? cfg.workspaceId,
+                        type: opts.profile,
+                    }, cfg);
+                    const views = unwrapList(viewsRes, ["views"]);
+                    if (views.length > 0) {
+                        log.blank();
+                        log.info(`'${opts.profile}' is a ${chalk.bold("view type")}, not an entity profile — found ${views.length} view${views.length !== 1 ? "s" : ""}.`);
+                        log.dim(`  Run: synap list views --type ${opts.profile}`);
+                        return;
+                    }
+                }
+                catch {
+                    // best-effort hint only — never fail the empty-result path
+                }
+                log.dim(`  Profiles in this workspace: synap list profiles`);
+                log.dim(`  Views (whiteboard, kanban, …): synap list views`);
+            }
             return;
         }
         for (const entity of list) {
@@ -158,9 +250,12 @@ export async function listEntities(opts) {
             const id = String(e.id ?? "").slice(0, 8);
             log.info(`${name} ${chalk.dim(`(${profile})`)} — ${chalk.dim(id)}`);
         }
+        if (list.length === limit) {
+            log.dim(`${list.length} shown (hit --limit ${limit}; more may exist — raise --limit or filter with --profile)`);
+        }
     }
     catch (e) {
-        console.error(chalk.red("Error: " + e.message));
+        renderHubError(e);
         process.exit(1);
     }
 }
@@ -188,130 +283,178 @@ export async function getEntity(id, opts) {
         }
     }
     catch (e) {
-        console.error(chalk.red("Error: " + e.message));
+        renderHubError(e);
         process.exit(1);
     }
 }
-// ─── searchData ───────────────────────────────────────────────────────────────
-export async function searchData(query, opts) {
+/** Render one item according to its substrate. */
+function formatAskItem(substrate, item) {
+    if (substrate === "procedural") {
+        // knowledge_keys rows: addressed by `key`, body in `value`.
+        const key = (item.key ?? item.slug ?? item.namespace);
+        const value = (item.value ?? "");
+        const snippet = value
+            ? " — " + (value.length > 80 ? value.slice(0, 77) + "…" : value).replace(/\s+/g, " ")
+            : "";
+        return `${key ?? "(untitled)"}${chalk.dim(snippet)}`;
+    }
+    if (substrate === "episodic") {
+        // knowledge_facts rows: text is in `fact` (content/text are wire fallbacks).
+        const content = (item.fact ?? item.content ?? item.text ?? "");
+        return content.length > 120 ? content.slice(0, 117) + "…" : content || "(empty)";
+    }
+    // semantic — an entity. Surface a body snippet (not just a pointer): the
+    // entity carries its content in `preview` or a description-ish property, so a
+    // "how do I…" answer shows the gist inline instead of only an entity title.
+    const { title, type, id } = formatHit(item);
+    const props = (item.properties ?? {});
+    const desc = String(item.preview ??
+        props.description ??
+        props.recipeDescription ??
+        props.summary ??
+        props.body ??
+        props.content ??
+        "");
+    const snippet = desc
+        ? chalk.dim(" — " +
+            (desc.length > 90 ? desc.slice(0, 87) + "…" : desc).replace(/\s+/g, " "))
+        : "";
+    return `${title} ${chalk.dim(`[${type}]`)} ${chalk.dim(id)}${snippet}`;
+}
+/**
+ * Render the A/B ranker diagnostic: baseline vs Horizon top-N side-by-side,
+ * then the diff. Comparison is by RANK POSITION (not score magnitude) — the two
+ * strategies score on different scales, so only the ordering is comparable.
+ */
+function renderComparison(query, comparison) {
+    if (!comparison) {
+        log.dim(`"${query}" → no ranker comparison returned (semantic pool empty?).`);
+        return;
+    }
+    const { baseline, horizon, diff } = comparison;
+    const n = Math.max(baseline.length, horizon.length);
+    log.dim(`"${query}" → A/B ranker comparison (by RANK, not score magnitude)`);
+    log.blank();
+    // Side-by-side: rank · title for each column.
+    const trunc = (s, w) => (s.length > w ? s.slice(0, w - 1) + "…" : s).padEnd(w, " ");
+    const COL = 38;
+    log.info("  " + chalk.bold("BASELINE".padEnd(COL + 5)) + chalk.bold("HORIZON"));
+    for (let i = 0; i < n; i++) {
+        const b = baseline[i];
+        const h = horizon[i];
+        const bCell = b ? `${chalk.dim(`#${b.rank}`)} ${trunc(b.title, COL)}` : "".padEnd(COL + 4);
+        const hCell = h ? `${chalk.dim(`#${h.rank}`)} ${trunc(h.title, COL)}` : "";
+        log.info("  " + bCell + " " + hCell);
+    }
+    log.blank();
+    // Diff — overlap@N + items that moved rank between the two strategies.
+    const topN = Math.max(baseline.length, horizon.length);
+    log.info(chalk.bold("DIFF") +
+        chalk.dim(` · overlap@${topN}: ${diff.overlapAtN}/${topN} shared ids`));
+    if (diff.moved.length === 0) {
+        log.dim("  No shared item changed rank between the two rankers.");
+    }
+    else {
+        for (const m of diff.moved) {
+            const dir = m.horizonRank < m.baselineRank ? chalk.green("↑") : chalk.red("↓");
+            log.info(`  ${dir} ${m.title} ${chalk.dim(`(baseline #${m.baselineRank} → horizon #${m.horizonRank})`)}`);
+        }
+    }
+    log.blank();
+}
+export async function askKnowledge(query, opts) {
     try {
         const cfg = await resolveHubConfig(opts);
-        const userId = await resolveUserId(cfg);
-        const limit = parseInt(opts.limit ?? "20", 10);
-        let collections;
-        if (opts.type === "entity")
-            collections = "entities";
-        else if (opts.type === "doc")
-            collections = "documents";
-        const res = await hubGet("/search", {
-            userId,
+        const limit = parseLimit(opts.limit, 10);
+        const workspaceId = opts.workspace ?? cfg.workspaceId;
+        const sessionId = opts.session ? readActiveSessionId() : undefined;
+        const res = (await hubPost("/knowledge/ask", {
             query,
-            workspaceId: opts.workspace ?? cfg.workspaceId,
+            ...(workspaceId ? { workspaceId } : {}),
+            ...(sessionId ? { sessionId } : {}),
             limit,
-            collections,
-        }, cfg);
+            ...(opts.compare ? { compare: true } : {}),
+        }, cfg));
         if (opts.json) {
             console.log(JSON.stringify(res, null, 2));
             return;
         }
-        const data = res;
-        // hits may live at .hits, .results, or top-level array
-        const rawHits = data.hits ??
-            data.results ??
-            (Array.isArray(res) ? res : []);
-        if (rawHits.length === 0) {
-            const workspaceId = opts.workspace ?? cfg.workspaceId;
-            log.dim(`No results for "${query}".`);
-            if (workspaceId) {
-                // Show what IS in the workspace so the user isn't left with a blank wall
-                const [profilesRes, entitiesRes] = await Promise.allSettled([
-                    hubGet("/profiles", { userId, workspaceId }, cfg),
-                    hubGet("/entities", { userId, workspaceId, limit: 5 }, cfg),
-                ]);
-                if (profilesRes.status === "fulfilled") {
-                    const profiles = profilesRes.value.profiles ?? profilesRes.value;
-                    const pList = Array.isArray(profiles) ? profiles : [];
-                    if (pList.length > 0) {
-                        const total = (entitiesRes.status === "fulfilled")
-                            ? Number(entitiesRes.value.total ?? 0)
-                            : 0;
-                        log.blank();
-                        log.dim(`This workspace has ${total > 0 ? `${total} entities` : "no entities yet"} across ${pList.length} profile${pList.length !== 1 ? "s" : ""}:`);
-                        for (const p of pList.slice(0, 6)) {
-                            log.dim(`  · ${String(p.name ?? p.slug ?? "")} ${chalk.dim(`--profile=${String(p.slug ?? "")}`)}`);
-                        }
-                        log.blank();
-                        log.dim(`Try: synap search <term> --workspace ${workspaceId}`);
-                        log.dim(`  or synap list --workspace ${workspaceId} --profile <slug>`);
-                    }
-                }
-            }
+        // A/B ranker diagnostic — render the comparison and STOP. This is a
+        // ranking diff (baseline vs Horizon on the same candidate pool), not the
+        // normal answer, so it replaces the substrate listing when requested.
+        if (opts.compare) {
+            renderComparison(query, res.comparison);
             return;
         }
-        for (const hit of rawHits) {
-            const h = hit;
-            // Search hits: { id, collection, document: { id, title, entityType, ... } }
-            const doc = (h.document ?? h);
-            const name = String(doc.title ?? doc.id ?? h.id ?? "");
-            const type = String(doc.entityType ?? doc.profileSlug ?? h.collection ?? "");
-            const id = String(doc.id ?? h.id ?? "").slice(0, 8);
-            log.info(`${name} ${chalk.dim(`[${type}]`)} ${chalk.dim(id)}`);
-        }
-    }
-    catch (e) {
-        console.error(chalk.red("Error: " + e.message));
-        process.exit(1);
-    }
-}
-// ─── rememberData ─────────────────────────────────────────────────────────────
-export async function rememberData(text, opts) {
-    try {
-        const cfg = await resolveHubConfig(opts);
-        const userId = await resolveUserId(cfg);
-        const res = await hubPost("/memory", {
-            userId,
-            fact: text,
-            sourceEntityId: opts.context,
-        }, cfg);
-        const data = res;
-        const id = String(data.id ?? "");
-        if (opts.json) {
-            console.log(JSON.stringify({ id, stored: true }, null, 2));
+        const routed = (res.routedTo ?? []).join(", ");
+        const verdict = res.verdict ? chalk.dim(` · ${res.verdict}`) : "";
+        // Honest routing: if the query's cue suggested one substrate but another
+        // actually answered (e.g. "how to…" cued procedural but the runbook is an
+        // entity), say so instead of dangling a "primary" that returned nothing.
+        const routeNote = res.intent && res.intent !== res.primary
+            ? `${chalk.bold(routed)} · asked-for ${res.intent}, answered by ${chalk.bold(res.primary)}`
+            : `${chalk.bold(routed)} (primary: ${chalk.bold(res.primary)})`;
+        log.dim(`"${query}" → routed to ${routeNote}${verdict}`);
+        log.blank();
+        const answers = res.answers ?? [];
+        const total = answers.reduce((n, a) => n + (a.items?.length ?? 0), 0);
+        const anyErrored = (res.degraded?.length ?? 0) > 0;
+        // Only claim a clean "no results" when every store actually answered. If one
+        // errored, fall through to the per-substrate loop so the outage is shown.
+        if (total === 0 && !anyErrored) {
+            log.dim(`No results across ${routed || "any substrate"}.`);
+            log.dim(`  Try broader terms, or capture knowledge with: synap capture`);
             return;
         }
-        log.success(`Stored: "${text.slice(0, 80)}"`);
+        for (const answer of answers) {
+            const items = answer.items ?? [];
+            // Glass-box: an errored store is NOT "found nothing" — say so, never hide it.
+            if (answer.status === "error") {
+                log.info(chalk.bold(answer.substrate.toUpperCase()) +
+                    chalk.yellow(" — store unavailable (not searched)"));
+                log.blank();
+                continue;
+            }
+            if (items.length === 0)
+                continue;
+            log.info(chalk.bold(answer.substrate.toUpperCase()) + chalk.dim(` (${items.length})`));
+            for (const item of items) {
+                log.info("  " + formatAskItem(answer.substrate, item));
+            }
+            log.blank();
+        }
+        // res.degraded was only ever checked as a boolean (anyErrored) above —
+        // surface which substrate(s) actually degraded, verbatim, so the answer's
+        // incompleteness is visible rather than just its existence.
+        if (res.degraded && res.degraded.length > 0) {
+            log.dim(`Degraded: ${res.degraded.join(", ")}`);
+        }
     }
     catch (e) {
-        console.error(chalk.red("Error: " + e.message));
+        renderHubError(e);
         process.exit(1);
     }
 }
-// ─── recallData ───────────────────────────────────────────────────────────────
-export async function recallData(query, opts) {
-    try {
-        const cfg = await resolveHubConfig(opts);
-        const userId = await resolveUserId(cfg);
-        const limit = parseInt(opts.limit ?? "20", 10);
-        const res = await hubGet("/memory", { userId, q: query, limit }, cfg);
-        const memories = res.memories ?? res;
-        const list = Array.isArray(memories) ? memories : [];
-        if (opts.json) {
-            console.log(JSON.stringify({ memories: list }, null, 2));
-            return;
-        }
-        if (list.length === 0) {
-            log.dim("No memories found.");
-            return;
-        }
-        list.forEach((mem, i) => {
-            const m = mem;
-            const content = String(m.fact ?? m.content ?? "").slice(0, 120);
-            log.info(`${i + 1}. ${content}`);
-        });
+const refLabel = (r) => `${String(r.name ?? r.id ?? "?")}${r.profileSlug ? ` [${r.profileSlug}]` : ""}`;
+/** Print 1-3 dim graph-impact lines for a create response. No-op if absent. */
+function reportResolution(res) {
+    const resolution = res.resolution;
+    if (!resolution)
+        return;
+    const existing = resolution.existingSameProfile;
+    if (existing) {
+        log.dim(`⚠ an entity named "${String(existing.name ?? "?")}" already exists as profile ${String(existing.profileSlug ?? "?")} (${String(existing.id ?? "?").slice(0, 8)}) — consider updating it instead of duplicating`);
     }
-    catch (e) {
-        console.error(chalk.red("Error: " + e.message));
-        process.exit(1);
+    const autoConnected = resolution.autoConnected ?? [];
+    if (autoConnected.length > 0) {
+        const names = autoConnected.map(refLabel).join(", ");
+        log.dim(`→ auto-linked to ${autoConnected.length} existing same-name entit${autoConnected.length === 1 ? "y" : "ies"}: ${names}`);
+    }
+    // suggestions beyond what was already auto-connected
+    const autoIds = new Set(autoConnected.map((r) => r.id).filter(Boolean));
+    const suggestions = (resolution.suggestions ?? []).filter((s) => !autoIds.has(s.id));
+    if (suggestions.length > 0) {
+        log.dim(`· you may want to link: ${suggestions.map(refLabel).join(", ")}`);
     }
 }
 // ─── createEntity ─────────────────────────────────────────────────────────────
@@ -319,7 +462,6 @@ export async function createEntity(opts) {
     try {
         const cfg = await resolveHubConfig(opts);
         const userId = await resolveUserId(cfg);
-        // parse props as unknown then cast — user-supplied JSON
         const properties = JSON.parse(opts.props ?? "{}");
         const res = await hubPost("/entities", {
             userId,
@@ -329,19 +471,20 @@ export async function createEntity(opts) {
             properties,
         }, cfg);
         const entity = res;
-        if (opts.json) {
-            console.log(JSON.stringify(entity, null, 2));
-            return;
-        }
-        if (entity.status === "proposed") {
-            log.info(`Proposed: ${opts.name} (proposal: ${String(entity.proposalId ?? "")})`);
-        }
-        else {
-            log.success(`Created: ${opts.name} (${String(entity.id ?? "")})`);
-        }
+        await reportWrite(entity, {
+            label: `Created: ${opts.name}`,
+            lane: "work",
+            workspaceId: opts.workspace ?? cfg.workspaceId,
+            cfg,
+            json: opts.json,
+        });
+        // Graph-impact feedback — human output only (the `--json` path already
+        // passed the raw response, including `resolution`, through reportWrite).
+        if (!opts.json)
+            reportResolution(entity);
     }
     catch (e) {
-        console.error(chalk.red("Error: " + e.message));
+        renderHubError(e);
         process.exit(1);
     }
 }
@@ -355,8 +498,8 @@ export async function listProfiles(opts) {
             console.error(chalk.red("No workspace set. Run: synap use <workspace-id>"));
             process.exit(1);
         }
-        const res = await hubGet("/profiles", { userId, workspaceId }, cfg);
-        const profiles = (res.profiles ?? (Array.isArray(res) ? res : []));
+        const res = await hubGet("/profiles", { userId, workspaceId, ...(opts.json ? { detail: "full" } : {}) }, cfg);
+        const profiles = unwrapList(res, ["profiles"]);
         if (opts.json) {
             console.log(JSON.stringify(profiles, null, 2));
             return;
@@ -369,11 +512,18 @@ export async function listProfiles(opts) {
         for (const p of profiles) {
             const scope = String(p.entityScope ?? "workspace");
             const desc = p.description ? chalk.dim(` — ${String(p.description).slice(0, 60)}`) : "";
-            log.info(`${chalk.bold(String(p.slug ?? ""))}  ${chalk.dim(scope)}${desc}`);
+            // A role-profile (client, partner, …) is a hat an existing entity wears
+            // via `synap facet attach` — never created as its own entity. Label it
+            // distinctly so it's never confused with a primary kind.
+            const applicableKinds = p.applicableKinds;
+            const kindLabel = p.profileKind === "role"
+                ? chalk.magenta(`[Role${applicableKinds?.length ? ` of ${applicableKinds.join("/")}` : ""}]`)
+                : chalk.green("[Kind]");
+            log.info(`${chalk.bold(String(p.slug ?? ""))}  ${kindLabel}  ${chalk.dim(scope)}${desc}`);
         }
     }
     catch (e) {
-        console.error(chalk.red("Error: " + e.message));
+        renderHubError(e);
         process.exit(1);
     }
 }
@@ -390,14 +540,16 @@ export async function createRelation(opts) {
             type: opts.type,
         }, cfg);
         const relation = res;
-        if (opts.json) {
-            console.log(JSON.stringify(relation, null, 2));
-            return;
-        }
-        log.success(`Created relation: ${opts.type} (${opts.source} → ${opts.target})`);
+        await reportWrite(relation, {
+            label: `Relation: ${opts.type} (${opts.source} → ${opts.target})`,
+            lane: "work",
+            workspaceId: opts.workspace ?? cfg.workspaceId,
+            cfg,
+            json: opts.json,
+        });
     }
     catch (e) {
-        console.error(chalk.red("Error: " + e.message));
+        renderHubError(e);
         process.exit(1);
     }
 }
@@ -405,21 +557,30 @@ export async function createRelation(opts) {
 export async function updateEntity(id, opts) {
     try {
         const cfg = await resolveHubConfig(opts);
+        const workspaceId = opts.workspace ?? cfg.workspaceId;
         // parse props as unknown then cast — user-supplied JSON
         const metadata = JSON.parse(opts.props);
-        const res = await hubPatch(`/entities/${id}`, {
-            userId: cfg.userId,
-            metadata,
-        }, cfg);
+        const body = { userId: cfg.userId, metadata };
+        // backend reads body.workspaceId to scope automation matching — without it
+        // the update lands pod-wide and workspace-gated automations never fire
+        if (workspaceId)
+            body.workspaceId = workspaceId;
+        const res = await hubPatch(`/entities/${id}`, body, cfg);
         const entity = res;
         if (opts.json) {
             console.log(JSON.stringify(entity, null, 2));
             return;
         }
         log.success(`Updated: ${id}`);
+        // Graph-impact feedback — shallow immediate neighbors the edit may touch.
+        // Additive + graceful: absent on older backends, so output is unchanged.
+        const impact = entity.impact;
+        if (Array.isArray(impact) && impact.length > 0) {
+            log.dim(`→ ${impact.length} connected entit${impact.length === 1 ? "y" : "ies"} may be affected: ${impact.map(refLabel).join(", ")}`);
+        }
     }
     catch (e) {
-        console.error(chalk.red("Error: " + e.message));
+        renderHubError(e);
         process.exit(1);
     }
 }