@synap-core/cli 1.8.0 → 1.11.0

package/dist/commands/data.js

@@ -1,7 +1,10 @@
 import chalk from "chalk";
 import { log } from "../utils/logger.js";
-import { resolveHubConfig, resolveUserId, hubGet, hubPost, hubPatch } from "../lib/hub-client.js";
-import { resolveWorkspaceName, formatLaneLine, laneJsonFields, } from "../lib/capture-lane.js";
+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";
+import { requireFullId } from "../lib/id.js";
 export const parseLimit = (s, def) => s ? parseInt(s, 10) : def;
 export function formatHit(hit) {
     const doc = (hit.document ?? hit);
@@ -10,115 +13,120 @@ export function formatHit(hit) {
         // `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),
+        // Full id, never truncated: this is the handle callers feed straight back
+        // into `synap get entity <id>` — an 8-char prefix isn't a valid UUID and
+        // 500s on the pod (see `renderHubError`'s uuid-shape hint).
+        id: String(doc.id ?? hit.id ?? ""),
     };
 }
-// ─── orient ───────────────────────────────────────────────────────────────────
 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.
-        // Newer pods return `entityCount` directly on GET /workspaces; for older
-        // pods fall back to counting a real page of entities (GET /entities
-        // returns a bare array — there is no `total` field on the wire).
-        const FALLBACK_PAGE = 100;
-        const wsDetails = await Promise.all(wsList.map(async (ws) => {
-            const wsId = String(ws.id ?? "");
-            const declaredCount = typeof ws.entityCount === "number" ? ws.entityCount : undefined;
-            const [profilesRes, entitiesRes] = await Promise.allSettled([
-                hubGet("/profiles", { userId, workspaceId: wsId }, cfg),
-                declaredCount === undefined
-                    ? hubGet("/entities", { userId, workspaceId: wsId, limit: FALLBACK_PAGE }, cfg)
-                    : Promise.resolve(null),
-            ]);
-            const profiles = profilesRes.status === "fulfilled"
-                ? (profilesRes.value.profiles ?? profilesRes.value)
-                : [];
-            const profileList = Array.isArray(profiles) ? profiles : [];
-            let entityTotal = declaredCount ?? 0;
-            let countIsLowerBound = false;
-            if (declaredCount === undefined && entitiesRes.status === "fulfilled" && entitiesRes.value) {
-                const v = entitiesRes.value;
-                const arr = Array.isArray(v) ? v : (v.entities ?? []);
-                entityTotal = Array.isArray(arr) ? arr.length : 0;
-                countIsLowerBound = entityTotal === FALLBACK_PAGE;
-            }
-            return { ws, profileList, entityTotal, countIsLowerBound };
-        }));
+        // 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) {
-            const capabilities = [
-                "synap graph --entity <id> --depth 2",
-                "synap events --entity <id>",
-                "synap subscribe --event entity.*",
-                "synap context",
-                "synap automation list",
-                "synap list views --type whiteboard",
-                "synap view create --type kanban --profile task",
-                "synap proposals list",
-                "synap explain",
-            ];
-            console.log(JSON.stringify({ userId, podUrl: cfg.podUrl, workspaceId: cfg.workspaceId, workspaces: wsDetails, me, capabilities }, 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, countIsLowerBound } 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}${countIsLowerBound ? "+" : ""} entities`)
+                const id = chalk.dim(String(ws.id ?? ""));
+                const count = ws.entityCount > 0
+                    ? chalk.dim(`${ws.entityCount} entities`)
                     : chalk.dim("empty");
-                log.info(`${marker}${name}  ${id}  ${count}`);
+                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.");
         }
-        // ── Capabilities block ─────────────────────────────────────────────────
-        log.blank();
-        log.heading("Capabilities");
-        console.log(`  ${chalk.cyan("Graph traversal")}   synap graph --entity <id> --depth 2`);
-        console.log(`  ${chalk.cyan("Event chain")}       synap events --entity <id>`);
-        console.log(`  ${chalk.cyan("Subscribe")}         synap subscribe --event entity.*`);
-        console.log(`  ${chalk.cyan("Session context")}   synap context`);
-        console.log(`  ${chalk.cyan("Automations")}       synap automation list`);
-        console.log(`  ${chalk.cyan("Views")}             synap list views --type whiteboard · synap view create --type kanban --profile task`);
-        console.log(`  ${chalk.cyan("Governance")}        synap proposals list`);
         log.blank();
-        log.dim("For full capability map: synap explain");
+        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);
     }
 }
@@ -129,8 +137,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(", ");
@@ -139,16 +146,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 ?? ""))}`);
+        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);
     }
 }
@@ -157,8 +174,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;
@@ -173,7 +189,7 @@ export async function listWorkspaces(opts) {
         }
     }
     catch (e) {
-        console.error(chalk.red("Error: " + e.message));
+        renderHubError(e);
         process.exit(1);
     }
 }
@@ -183,14 +199,23 @@ export async function listEntities(opts) {
         const cfg = await resolveHubConfig(opts);
         const userId = await resolveUserId(cfg);
         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, count: list.length, limit, truncated: list.length === limit }, null, 2));
             return;
@@ -206,8 +231,7 @@ export async function listEntities(opts) {
                         workspaceId: opts.workspace ?? cfg.workspaceId,
                         type: opts.profile,
                     }, cfg);
-                    const views = viewsRes.views
-                        ?? (Array.isArray(viewsRes) ? viewsRes : []);
+                    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" : ""}.`);
@@ -227,7 +251,8 @@ export async function listEntities(opts) {
             const e = entity;
             const name = String(e.title ?? e.id ?? "");
             const profile = e.profileSlug ?? e.profile ?? e.type ?? "";
-            const id = String(e.id ?? "").slice(0, 8);
+            // Full id — this is the handle `synap get entity <id>` expects next.
+            const id = String(e.id ?? "");
             log.info(`${name} ${chalk.dim(`(${profile})`)} — ${chalk.dim(id)}`);
         }
         if (list.length === limit) {
@@ -235,12 +260,15 @@ export async function listEntities(opts) {
         }
     }
     catch (e) {
-        console.error(chalk.red("Error: " + e.message));
+        renderHubError(e);
         process.exit(1);
     }
 }
 // ─── getEntity ────────────────────────────────────────────────────────────────
 export async function getEntity(id, opts) {
+    // `synap ask`/`synap list entities` now print full UUIDs, so an 8-char
+    // value here is almost always a leftover short id from before this fix.
+    requireFullId(id, "entity", chalk, log);
     try {
         const cfg = await resolveHubConfig(opts);
         const userId = await resolveUserId(cfg);
@@ -263,64 +291,7 @@ export async function getEntity(id, opts) {
         }
     }
     catch (e) {
-        console.error(chalk.red("Error: " + e.message));
-        process.exit(1);
-    }
-}
-// ─── noteData ─────────────────────────────────────────────────────────────────
-export async function noteData(text, opts) {
-    try {
-        const cfg = await resolveHubConfig(opts);
-        const userId = await resolveUserId(cfg);
-        // A `note` is the human raw-inbox primitive ("dump now, structure later") —
-        // it lands in the active workspace, NOT a private agent-memory ws (that lane
-        // was removed). The AI should never write a note: structuring is its job, so
-        // it uses `synap capture` (structured) instead.
-        const workspaceId = cfg.workspaceId;
-        if (!workspaceId) {
-            console.error(chalk.red("No workspace set. Run: synap use <workspace-id>"));
-            process.exit(1);
-        }
-        const res = await hubPost("/entities", {
-            userId,
-            profileSlug: "note",
-            title: text.slice(0, 200),
-            workspaceId,
-            // The `note` profile requires a `content` property — carry the full text
-            // (title is truncated). Without this the hub rejects the write (HTTP 500).
-            properties: {
-                content: text,
-                ...(opts.context ? { sourceEntityId: opts.context } : {}),
-            },
-        }, cfg);
-        const isProposed = res.status === "proposed" || Boolean(res.proposalId);
-        const report = {
-            lane: "work",
-            workspaceId,
-            workspaceName: await resolveWorkspaceName(workspaceId, cfg),
-            governance: isProposed ? "proposed" : "auto",
-        };
-        if (opts.json) {
-            if (isProposed) {
-                console.log(JSON.stringify({ proposed: true, proposalId: res.proposalId ?? res.id, ...laneJsonFields(report) }, null, 2));
-            }
-            else {
-                console.log(JSON.stringify({ id: res.id, stored: true, ...laneJsonFields(report) }, null, 2));
-            }
-            return;
-        }
-        if (isProposed) {
-            log.warn(`Queued for approval (proposal: ${String(res.proposalId ?? "")})`);
-            if (res.reviewUrl)
-                log.dim(`  Review: ${String(res.reviewUrl)}`);
-        }
-        else {
-            log.success(`Note saved: "${text.slice(0, 80)}" ${chalk.dim(String(res.id ?? "").slice(0, 8))}`);
-        }
-        console.log("  " + formatLaneLine(report));
-    }
-    catch (e) {
-        console.error(chalk.red("Error: " + e.message));
+        renderHubError(e);
         process.exit(1);
     }
 }
@@ -356,18 +327,75 @@ function formatAskItem(substrate, item) {
         ? chalk.dim(" — " +
             (desc.length > 90 ? desc.slice(0, 87) + "…" : desc).replace(/\s+/g, " "))
         : "";
-    return `${title} ${chalk.dim(`[${type}]`)} ${chalk.dim(id)}${snippet}`;
+    // Full id trails at the end (never truncated — it's what `synap get entity`
+    // expects next) so it doesn't push the snippet off-screen on a narrow terminal.
+    return `${title} ${chalk.dim(`[${type}]`)}${snippet} ${chalk.dim(id)}`;
+}
+/**
+ * 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 limit = parseLimit(opts.limit, 10);
         const workspaceId = opts.workspace ?? cfg.workspaceId;
-        const res = (await hubPost("/knowledge/ask", { query, ...(workspaceId ? { workspaceId } : {}), limit }, cfg));
+        const sessionId = opts.session ? readActiveSessionId() : undefined;
+        const res = (await hubPost("/knowledge/ask", {
+            query,
+            ...(workspaceId ? { workspaceId } : {}),
+            ...(sessionId ? { sessionId } : {}),
+            limit,
+            ...(opts.compare ? { compare: true } : {}),
+        }, cfg));
         if (opts.json) {
             console.log(JSON.stringify(res, null, 2));
             return;
         }
+        // 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;
+        }
         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
@@ -405,12 +433,40 @@ export async function askKnowledge(query, opts) {
             }
             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);
     }
 }
+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 ?? "?")}) — consider updating it instead of duplicating`);
+    }
+    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 ─────────────────────────────────────────────────────────────
 export async function createEntity(opts) {
     try {
@@ -425,24 +481,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.warn(`Queued for approval — not yet created.`);
-            log.dim(`  proposal: ${String(entity.proposalId ?? entity.id ?? "")}`);
-            if (entity.reviewUrl)
-                log.dim(`  Review: ${String(entity.reviewUrl)}`);
-            else
-                log.dim(`  Open Synap to approve the pending proposal.`);
-        }
-        else {
-            log.success(`Created: ${opts.name} ${chalk.dim(String(entity.id ?? "").slice(0, 8))}`);
-        }
+        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);
     }
 }
@@ -456,8 +508,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;
@@ -470,11 +522,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);
     }
 }
@@ -491,14 +550,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);
     }
 }
@@ -521,9 +582,15 @@ export async function updateEntity(id, opts) {
             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);
     }
 }