@sechroom/cli 2026.6.12 → 2026.6.14

package/dist/index.js

@@ -18,6 +18,7 @@ var CONFIG_FILE = join(CONFIG_DIR, "config.json");
 var TOKEN_FILE = join(CONFIG_DIR, "token.json");
 var LOCAL_CONFIG_NAME = ".sechroom.json";
 var DEFAULT_BASE_URL = "https://app.sechroom.ai/api";
+var LOCAL_CONFIG_SCHEMA_VERSION = 2;
 function ensureDir() {
   if (!existsSync(CONFIG_DIR)) mkdirSync(CONFIG_DIR, { recursive: true, mode: 448 });
 }
@@ -78,7 +79,14 @@ function readLocalConfig() {
   if (!path) return {};
   try {
     const c = JSON.parse(readFileSync(path, "utf8"));
-    return { baseUrl: c.baseUrl, tenant: c.tenant, path };
+    return {
+      schemaVersion: c.schemaVersion,
+      baseUrl: c.baseUrl,
+      tenant: c.tenant,
+      workspaceId: c.workspaceId,
+      defaultProjectId: c.defaultProjectId,
+      path
+    };
   } catch {
     return {};
   }
@@ -90,7 +98,8 @@ function writeLocalConfig(patch) {
     current = JSON.parse(readFileSync(path, "utf8"));
   } catch {
   }
-  writeFileSync(path, JSON.stringify({ ...current, ...patch }, null, 2), { mode: 384 });
+  const next = { ...current, ...patch, schemaVersion: LOCAL_CONFIG_SCHEMA_VERSION };
+  writeFileSync(path, JSON.stringify(next, null, 2), { mode: 384 });
   return path;
 }
 function resolveConfig(flags) {
@@ -103,7 +112,9 @@ function resolveConfig(flags) {
       "No tenant set. The Sechroom API rejects untenanted requests (HTTP 400). Pass --tenant <id>, set SECHROOM_TENANT, run `sechroom config set tenant <id>`, or `sechroom config set --local tenant <id>` for this directory."
     );
   }
-  return { baseUrl: baseUrl.replace(/\/$/, ""), tenant, clientId: persisted.clientId };
+  const workspaceId = process.env.SECHROOM_WORKSPACE ?? local.workspaceId ?? persisted.workspaceId ?? void 0;
+  const defaultProjectId = local.defaultProjectId ?? persisted.defaultProjectId ?? void 0;
+  return { baseUrl: baseUrl.replace(/\/$/, ""), tenant, workspaceId, defaultProjectId, clientId: persisted.clientId };
 }
 function describeConfig(flags) {
   const local = readLocalConfig();
@@ -121,6 +132,7 @@ function describeConfig(flags) {
   return {
     baseUrl: { value: baseUrl.value, source: baseUrl.source },
     tenant: pick(flags.tenant, process.env.SECHROOM_TENANT, local.tenant, g.tenant),
+    workspaceId: pick(void 0, process.env.SECHROOM_WORKSPACE, local.workspaceId, g.workspaceId),
     localPath: local.path
   };
 }
@@ -302,6 +314,7 @@ var style = {
   cyan: wrap(36, 39)
 };
 var ok = (s) => style.green(s);
+var warn = (s) => style.yellow(s);
 var err = (s) => style.red(s);
 function active() {
   return !quiet && Boolean(process.stderr.isTTY);
@@ -1761,6 +1774,7 @@ Examples:
 }
 
 // src/setup/apply.ts
+import { createHash as createHash2 } from "crypto";
 import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2, existsSync as existsSync2 } from "fs";
 import { dirname as dirname2 } from "path";
 
@@ -1770,11 +1784,17 @@ var SectionType = {
   McpConfigToml: "mcp-config-toml",
   InstructionFile: "instruction-file",
   ProjectConfig: "project-config",
-  Verify: "verify"
+  Verify: "verify",
+  /** SBC-999 — workspace-pinned conventions, emitted only when the request
+   *  carried a workspaceId and that workspace has agent-setup-bundle memories. */
+  WorkspaceConventions: "workspace-conventions"
 };
 async function fetchSetup(cfg) {
   const client = await makeClient(cfg);
-  const { data, error } = await client.GET("/operator-surface/setup", {});
+  const { data, error } = await client.GET(
+    "/operator-surface/setup",
+    cfg.workspaceId ? { params: { query: { workspaceId: cfg.workspaceId } } } : {}
+  );
   if (error) throw new Error(`GET /operator-surface/setup failed: ${JSON.stringify(error)}`);
   return data;
 }
@@ -1806,7 +1826,10 @@ async function fetchMemoryFields(cfg, id) {
   const client = await makeClient(cfg);
   const { data } = await client.GET("/memories/{memoryId}", { params: { path: { memoryId: id } } });
   const env = data;
-  return env?.item ?? env ?? null;
+  const m = env?.item ?? env;
+  if (!m) return null;
+  const version = typeof m.currentVersion === "string" ? Number(m.currentVersion) : m.currentVersion;
+  return { text: m.text, title: m.title, tags: m.tags, version: Number.isFinite(version) ? version : void 0 };
 }
 async function resolveInstruction(cfg, section, personalWorkspaceId) {
   const client = await makeClient(cfg);
@@ -1830,14 +1853,28 @@ async function resolveInstruction(cfg, section, personalWorkspaceId) {
       if (ovrHits.length > 0) {
         const override = await fetchMemoryFields(cfg, ovrHits[0].id);
         if (typeof override?.text === "string" && override.text.length > 0) {
-          return { title: override.title ?? template.title ?? artifact.title, body: override.text, source: "override", templateId, templateTags };
+          return { title: override.title ?? template.title ?? artifact.title, body: override.text, source: "override", templateId, templateTags, sourceRef: `${ovrHits[0].id}@v${override.version ?? 1}` };
         }
       }
     }
-    return { title: template.title ?? artifact.title, body: template.text, source: "template", templateId, templateTags };
+    return { title: template.title ?? artifact.title, body: template.text, source: "template", templateId, templateTags, sourceRef: `${templateId}@v${template.version ?? 1}` };
   }
   return null;
 }
+async function resolveWorkspaceConventions(cfg, section) {
+  const parts = [];
+  const refs = [];
+  for (const artifact of section.artifacts) {
+    if (parseTagArtifactId(artifact.id)) continue;
+    const mem = await fetchMemoryFields(cfg, artifact.id);
+    if (typeof mem?.text === "string" && mem.text.trim().length > 0) {
+      parts.push(mem.text.trim());
+      refs.push(`${artifact.id}@v${mem.version ?? 1}`);
+    }
+  }
+  if (parts.length === 0) return null;
+  return { body: parts.join("\n\n---\n\n"), refs };
+}
 async function createOverride(cfg, template, personalWorkspaceId) {
   const client = await makeClient(cfg);
   const overrideTags = template.templateTags.filter(
@@ -1861,8 +1898,57 @@ async function createOverride(cfg, template, personalWorkspaceId) {
 }
 
 // src/setup/apply.ts
-var BLOCK_BEGIN = "<!-- @sechroom/cli:begin (managed \u2014 re-run `sechroom setup agent-files` to refresh) -->";
-var BLOCK_END = "<!-- @sechroom/cli:end -->";
+var MARKER_BEGIN = "<!-- @sechroom/cli:begin";
+var MARKER_END = "<!-- @sechroom/cli:end";
+function normalizeBody(s) {
+  return s.replace(/\r\n/g, "\n").trim();
+}
+function bodySha256(body) {
+  return createHash2("sha256").update(normalizeBody(body), "utf8").digest("hex");
+}
+function renderBlock(write) {
+  const body = normalizeBody(write.body);
+  const attrs = [`block=${write.block}`];
+  if (write.source) attrs.push(`source=${write.source}`);
+  attrs.push(`sha256=${bodySha256(body)}`);
+  return `${MARKER_BEGIN} ${attrs.join(" ")} -->
+${body}
+${MARKER_END} block=${write.block} -->
+`;
+}
+function keyedBlockRe(block) {
+  const b = escapeRe(block);
+  return new RegExp(
+    `${escapeRe(MARKER_BEGIN)}[^\\n]*?\\bblock=${b}\\b[^\\n]*?-->\\n[\\s\\S]*?${escapeRe(MARKER_END)}[^\\n]*?\\bblock=${b}\\b[^\\n]*?-->\\n?`
+  );
+}
+function legacyBlockRe() {
+  return new RegExp(
+    `${escapeRe(MARKER_BEGIN)}(?:(?!block=)[^\\n])*?-->\\n[\\s\\S]*?${escapeRe(MARKER_END)}(?:(?!block=)[^\\n])*?-->\\n?`
+  );
+}
+function parseAttrs(beginLine) {
+  const attrs = {};
+  for (const m of beginLine.matchAll(/(\w+)=(\S+)/g)) attrs[m[1]] = m[2];
+  return attrs;
+}
+function innerBody(segment) {
+  const firstNl = segment.indexOf("\n");
+  const endIdx = segment.lastIndexOf(MARKER_END);
+  return segment.slice(firstNl + 1, endIdx).replace(/\n$/, "");
+}
+function parseManagedBlock(content, block) {
+  const keyed = content.match(keyedBlockRe(block));
+  if (keyed) {
+    const attrs = parseAttrs(keyed[0].slice(0, keyed[0].indexOf("\n")));
+    return { block, source: attrs.source ?? null, sha256: attrs.sha256 ?? null, body: innerBody(keyed[0]) };
+  }
+  if (block === "role-template") {
+    const legacy = content.match(legacyBlockRe());
+    if (legacy) return { block, source: null, sha256: null, body: innerBody(legacy[0]) };
+  }
+  return null;
+}
 function ensureDir2(path) {
   mkdirSync2(dirname2(path), { recursive: true });
 }
@@ -1901,32 +1987,74 @@ function mergeCodexToml(path, snippet, dryRun) {
   writeFileSync2(path, next, { mode: 384 });
   return { kind: "mcp", path, status: existed ? "merged" : "created" };
 }
-function writeInstructionBlock(path, body, dryRun) {
-  const block = `${BLOCK_BEGIN}
-${body.trim()}
-${BLOCK_END}
-`;
+function writeInstructionBlock(path, write, dryRun) {
   const existed = existsSync2(path);
-  const current = readOr(path, "");
-  let next;
-  const re = new RegExp(`${escapeRe(BLOCK_BEGIN)}[\\s\\S]*?${escapeRe(BLOCK_END)}\\n?`);
-  if (re.test(current)) {
-    next = current.replace(re, block);
-  } else {
-    next = current.trim().length > 0 ? `${current.trimEnd()}
-
-${block}` : block;
-  }
+  const next = computeBlockFile(readOr(path, ""), write);
   if (dryRun) return { kind: "instruction", path, status: "dry-run" };
   ensureDir2(path);
   writeFileSync2(path, next);
   return { kind: "instruction", path, status: existed ? "merged" : "created" };
 }
+function computeBlockFile(current, write) {
+  const rendered = renderBlock(write);
+  const keyed = keyedBlockRe(write.block);
+  if (keyed.test(current)) return current.replace(keyed, rendered);
+  if (write.block === "role-template" && legacyBlockRe().test(current)) {
+    return current.replace(legacyBlockRe(), rendered);
+  }
+  return current.trim().length > 0 ? `${current.trimEnd()}
+
+${rendered}` : rendered;
+}
+function evaluateBlock(content, block, serverBody) {
+  const onDisk = parseManagedBlock(content, block);
+  if (!onDisk) return "absent";
+  const actual = bodySha256(onDisk.body);
+  if (onDisk.sha256 && actual !== onDisk.sha256) return "drift";
+  return actual === bodySha256(serverBody) ? "current" : "stale";
+}
+function applyBlock(path, write, mode, dryRun) {
+  const current = readOr(path, "");
+  const state = evaluateBlock(current, write.block, write.body);
+  if (mode === "check") {
+    return {
+      kind: "instruction",
+      path,
+      status: state === "current" ? "current" : "skipped",
+      eval: state,
+      note: state === "current" ? void 0 : `would ${state === "absent" ? "write" : "refresh"} (${state})`
+    };
+  }
+  if (state === "current") {
+    return { kind: "instruction", path, status: "current", eval: "current" };
+  }
+  if (state === "drift" && mode !== "force") {
+    const proposedPath = `${path}.proposed`;
+    const next = computeBlockFile(current, write);
+    if (!dryRun) {
+      ensureDir2(proposedPath);
+      writeFileSync2(proposedPath, next);
+    }
+    return {
+      kind: "instruction",
+      path,
+      status: "skipped",
+      eval: "drift",
+      proposedPath,
+      note: `local edits \u2014 wrote ${proposedPath} (original left untouched)`
+    };
+  }
+  const action = writeInstructionBlock(path, write, dryRun);
+  const note = state === "stale" ? "refreshed" : state === "drift" ? "overwrote local edits" : void 0;
+  return { ...action, eval: state, note: note ?? action.note };
+}
 function escapeRe(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 async function applyClient(cfg, setup, target, opts) {
   const actions = [];
+  const mode = opts.mode ?? "apply";
+  const dryRun = opts.dryRun || mode === "check";
   if (opts.mcp && target.mcp) {
     const surface = findSurface(setup, target.mcp.surfaceKey);
     const section = findSection(surface, target.mcp.sectionType);
@@ -1935,7 +2063,7 @@ async function applyClient(cfg, setup, target, opts) {
       actions.push({ kind: "mcp", path: target.mcp.path, status: "skipped", note: `no ${target.mcp.sectionType} section on surface '${target.mcp.surfaceKey}'` });
     } else {
       actions.push(
-        target.mcp.format === "toml" ? mergeCodexToml(target.mcp.path, snippet, opts.dryRun) : mergeMcpJson(target.mcp.path, snippet, opts.dryRun)
+        target.mcp.format === "toml" ? mergeCodexToml(target.mcp.path, snippet, dryRun) : mergeMcpJson(target.mcp.path, snippet, dryRun)
       );
     }
   }
@@ -1949,8 +2077,26 @@ async function applyClient(cfg, setup, target, opts) {
       if (!resolved) {
         actions.push({ kind: "instruction", path: target.instruction.path, status: "skipped", note: "no role template found in this tenant \u2014 install the SEM Starter bundle, then re-run `sechroom setup agent-files`" });
       } else {
-        const action = writeInstructionBlock(target.instruction.path, resolved.body, opts.dryRun);
-        actions.push(resolved.source === "override" ? { ...action, note: "your personal copy" } : action);
+        const action = applyBlock(
+          target.instruction.path,
+          { block: "role-template", body: resolved.body, source: resolved.sourceRef },
+          mode,
+          opts.dryRun
+        );
+        actions.push(resolved.source === "override" && action.status !== "current" ? { ...action, note: action.note ?? "your personal copy" } : action);
+      }
+    }
+    const conventionsSection = findSection(surface, SectionType.WorkspaceConventions);
+    if (conventionsSection) {
+      const conventions = await resolveWorkspaceConventions(cfg, conventionsSection);
+      if (conventions) {
+        const action = applyBlock(
+          target.instruction.path,
+          { block: "workspace-conventions", body: conventions.body, source: `workspace:${cfg.workspaceId ?? ""}` },
+          mode,
+          opts.dryRun
+        );
+        actions.push(action.status === "current" ? action : { ...action, note: action.note ?? `workspace conventions (${conventions.refs.length})` });
       }
     }
   }
@@ -2284,20 +2430,169 @@ function systemTimezone() {
     return "UTC";
   }
 }
-async function ensureConfig(g, opts) {
+function editDistance(a, b) {
+  const m = a.length;
+  const n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+  let prev = Array.from({ length: n + 1 }, (_, j) => j);
+  for (let i = 1; i <= m; i++) {
+    const curr = [i];
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+    }
+    prev = curr;
+  }
+  return prev[n];
+}
+function namesCollide(a, b) {
+  const x = a.trim().toLowerCase();
+  const y = b.trim().toLowerCase();
+  return x === y || editDistance(x, y) <= 1;
+}
+function workspacePath(ws, byId) {
+  const parts = [];
+  const seen = /* @__PURE__ */ new Set();
+  let cur = ws;
+  while (cur && !seen.has(cur.id)) {
+    seen.add(cur.id);
+    parts.unshift(cur.name);
+    cur = cur.parentId ? byId.get(cur.parentId) : void 0;
+  }
+  return parts.join(" / ");
+}
+function resolveBaseUrl(g) {
   const persisted = readPersisted();
   const local = readLocalConfig();
-  let baseUrl = g.baseUrl ?? process.env.SECHROOM_BASE_URL ?? local.baseUrl ?? persisted.baseUrl ?? DEFAULT_BASE_URL2;
-  let tenant = g.tenant ?? process.env.SECHROOM_TENANT ?? local.tenant ?? persisted.tenant ?? "";
-  if (canPrompt() && !opts.yes) {
-    tenant = await promptText("Tenant id?", tenant || void 0);
+  const baseUrl = g.baseUrl ?? process.env.SECHROOM_BASE_URL ?? local.baseUrl ?? persisted.baseUrl ?? DEFAULT_BASE_URL2;
+  return baseUrl.replace(/\/$/, "");
+}
+async function fetchWorkspaces(client) {
+  const { data, error } = await client.GET("/workspaces", { params: { query: { includeArchived: false } } });
+  if (error) throw new Error(`Couldn't list your workspaces: ${JSON.stringify(error)}`);
+  const rows = data ?? [];
+  return rows.map((r) => r.item ?? r).filter((w) => Boolean(w?.id && w?.name)).map((w) => ({ id: w.id, name: w.name, parentId: w.parentId ?? null }));
+}
+async function lookupWorkspace(client, id) {
+  const { data, error } = await client.GET("/workspaces/{workspaceId}", { params: { path: { workspaceId: id } } });
+  if (error) return null;
+  const env = data;
+  const w = env?.item ?? env;
+  return w?.id ? { id: w.id, name: w.name ?? id, parentId: w.parentId ?? null } : null;
+}
+async function warnIfProjectStray(client, projectId, workspaceId, json) {
+  const { data, error } = await client.GET("/projects/{projectId}", { params: { path: { projectId } } });
+  if (error) return;
+  const env = data;
+  const owner = env?.item?.workspaceId;
+  if (owner && owner !== workspaceId && !json) {
+    process.stderr.write(
+      `${warn("\u26A0")} defaultProjectId ${style.dim(projectId)} belongs to a different workspace (${style.dim(owner)}), not ${style.dim(workspaceId)} \u2014 leaving it as-is.
+`
+    );
   }
-  baseUrl = baseUrl.replace(/\/$/, "");
-  if (!tenant) {
-    fail(
-      "No tenant set. Pass --tenant <id>, set SECHROOM_TENANT, or run `sechroom config set tenant <id>` \u2014 the API rejects untenanted requests (HTTP 400)."
+}
+async function pickWorkspace(client) {
+  const all = await withSpinner("Listing your workspaces", () => fetchWorkspaces(client));
+  if (all.length === 0) {
+    process.stderr.write(`no workspaces found \u2014 skipping workspace binding (you can set it later with \`sechroom config set --local workspaceId <id>\`)
+`);
+    return void 0;
+  }
+  const byId = new Map(all.map((w) => [w.id, w]));
+  let pool = all;
+  if (all.length > 12) {
+    const q = (await promptText(`Filter ${all.length} workspaces (substring, Enter to list all)?`, "")).trim().toLowerCase();
+    if (q) {
+      const hits = all.filter((w) => `${w.name} ${workspacePath(w, byId)}`.toLowerCase().includes(q));
+      if (hits.length > 0) pool = hits;
+      else process.stderr.write(`no match for "${q}" \u2014 listing all
+`);
+    }
+  }
+  const SKIP = "__skip__";
+  const choices = [
+    ...pool.slice().sort((a, b) => workspacePath(a, byId).localeCompare(workspacePath(b, byId))).map((w) => ({ label: workspacePath(w, byId), value: w.id, hint: w.id })),
+    { label: style.dim("skip \u2014 don't bind a workspace"), value: SKIP, hint: void 0 }
+  ];
+  const chosen = await promptSelect("Bind this directory to a workspace:", choices, SKIP);
+  if (chosen === SKIP) return void 0;
+  const picked = byId.get(chosen);
+  const collisions = all.filter((w) => w.id !== picked.id && namesCollide(w.name, picked.name));
+  if (collisions.length > 0) {
+    process.stderr.write(
+      `${warn("\u26A0")} ${collisions.length} other workspace(s) have a similar name to ${style.cyan(workspacePath(picked, byId))}:
+` + collisions.map((w) => `    ${style.dim(workspacePath(w, byId))} ${style.dim(`(${w.id})`)}`).join("\n") + `
+    You picked ${style.dim(picked.id)} \u2014 re-run \`sechroom config set --local workspaceId <id>\` if that's wrong.
+`
     );
   }
+  return chosen;
+}
+async function resolveWorkspaceBinding(client, existing, opts) {
+  if (opts.workspace) {
+    const found = await lookupWorkspace(client, opts.workspace);
+    if (!found && !opts.json) {
+      process.stderr.write(
+        `${warn("\u26A0")} workspace ${style.dim(opts.workspace)} not found (or you lack access) \u2014 binding it anyway.
+`
+      );
+    }
+    return opts.workspace;
+  }
+  if (existing) return existing;
+  if (!canPrompt() || opts.yes) return void 0;
+  return pickWorkspace(client);
+}
+async function ensureTenant(baseUrl, g, opts) {
+  const persisted = readPersisted();
+  const local = readLocalConfig();
+  let tenant = g.tenant ?? process.env.SECHROOM_TENANT ?? local.tenant ?? persisted.tenant ?? "";
+  if (!tenant) {
+    const client = await makeClient({ baseUrl, tenant: "", clientId: persisted.clientId });
+    const { data, error } = await client.GET("/auth/me/tenants", {});
+    if (error) {
+      fail(`Couldn't list your tenants: ${JSON.stringify(error)}. Pass --tenant <id> to skip this.`);
+    }
+    const tenants = data?.tenants ?? [];
+    if (tenants.length === 0) {
+      fail(
+        "You're signed in, but your account isn't a member of any tenant yet. Ask an admin to add you (or create one in the app), then re-run \u2014 or pass --tenant <id>."
+      );
+    } else if (tenants.length === 1) {
+      tenant = tenants[0].key;
+      if (!opts.json) {
+        process.stderr.write(
+          `${ok("\u2713")} using your tenant ${style.cyan(tenants[0].label)} ${style.dim(`(${tenant})`)}
+`
+        );
+      }
+    } else if (canPrompt() && !opts.yes) {
+      tenant = await promptSelect(
+        "You belong to several tenants \u2014 pick one:",
+        tenants.map((t) => ({ label: t.label, value: t.key, hint: t.key })),
+        data?.defaultTenantKey ?? tenants[0].key
+      );
+    } else {
+      tenant = data?.defaultTenantKey ?? tenants[0].key;
+      if (!opts.json) {
+        process.stderr.write(
+          `using tenant ${tenant} (${tenants.length} available \u2014 pass --tenant to choose another)
+`
+        );
+      }
+    }
+  }
+  const existingWorkspace = local.workspaceId ?? persisted.workspaceId ?? void 0;
+  const wsClient = await makeClient({ baseUrl, tenant, clientId: persisted.clientId });
+  const workspaceId = await resolveWorkspaceBinding(wsClient, existingWorkspace, {
+    yes: opts.yes,
+    json: opts.json,
+    workspace: opts.workspace
+  });
+  const defaultProjectId = local.defaultProjectId ?? persisted.defaultProjectId ?? void 0;
+  if (defaultProjectId && workspaceId) await warnIfProjectStray(wsClient, defaultProjectId, workspaceId, opts.json);
   let storeLocal = Boolean(opts.local);
   if (!opts.local && canPrompt() && !opts.yes) {
     storeLocal = await promptSelect(
@@ -2309,16 +2604,23 @@ async function ensureConfig(g, opts) {
       local.path ? "local" : "global"
     ) === "local";
   }
-  if (storeLocal) {
-    const path = writeLocalConfig({ baseUrl, tenant });
-    if (!opts.json) process.stderr.write(`${ok("\u2713")} config saved to ${path} (directory-local)
+  if (opts.persist !== false) {
+    const patch = { baseUrl, tenant, ...workspaceId ? { workspaceId } : {} };
+    if (storeLocal) {
+      const path = writeLocalConfig(patch);
+      if (!opts.json) process.stderr.write(`${ok("\u2713")} config saved to ${path} (directory-local)
 `);
-  } else {
-    writePersisted({ baseUrl, tenant });
-    if (!opts.json) process.stderr.write(`${ok("\u2713")} config saved globally (~/.config/sechroom/config.json)
+    } else {
+      writePersisted(patch);
+      if (!opts.json) process.stderr.write(`${ok("\u2713")} config saved globally (~/.config/sechroom/config.json)
+`);
+    }
+    if (workspaceId && !existingWorkspace && !opts.json) {
+      process.stderr.write(`${ok("\u2713")} bound to workspace ${style.dim(workspaceId)}
 `);
+    }
   }
-  return { baseUrl, tenant, clientId: persisted.clientId };
+  return { baseUrl, tenant, workspaceId, defaultProjectId, clientId: persisted.clientId };
 }
 async function ensureAuth(cfg, yes) {
   if (process.env.SECHROOM_TOKEN) return;
@@ -2373,7 +2675,7 @@ async function chooseClients(clientFlag, yes, cwd) {
   return picks.length > 0 ? picks : preselected;
 }
 function registerOnboard(program2) {
-  program2.command("onboard").description("Guided first-run setup: configure, sign in, set timezone, detect clients, and wire this project").option("--client <list>", `comma-separated clients (${ALL_CLIENT_KEYS.join(", ")}) or 'all' (default: auto-detected)`).option("--local", "save tenant + base URL to a directory-local .sechroom.json instead of the global config", false).option("--cli-only", "configure the CLI only \u2014 don't wire any AI client (no MCP config, no agent files)", false).option("--no-mcp", "skip the MCP server config (.mcp.json etc.); still write the agent instruction files").option("--copy", "make a personal copy of the agent instructions you can edit (default: prompt on a TTY, else skip)").option("--dry-run", "walk through without writing files or changing the profile", false).option("-y, --yes", "non-interactive: accept defaults (system timezone, detected clients, global config, full wire)", false).addHelpText(
+  program2.command("onboard").description("Guided first-run setup: configure, sign in, set timezone, detect clients, and wire this project").option("--client <list>", `comma-separated clients (${ALL_CLIENT_KEYS.join(", ")}) or 'all' (default: auto-detected)`).option("--local", "save tenant + base URL to a directory-local .sechroom.json instead of the global config", false).option("--workspace <id>", "bind this directory to a workspace (skips the interactive workspace pick)").option("--cli-only", "configure the CLI only \u2014 don't wire any AI client (no MCP config, no agent files)", false).option("--no-mcp", "skip the MCP server config (.mcp.json etc.); still write the agent instruction files").option("--copy", "make a personal copy of the agent instructions you can edit (default: prompt on a TTY, else skip)").option("--dry-run", "walk through without writing files or changing the profile", false).option("--refresh", "re-fetch descriptors and refresh any out-of-date managed blocks (local edits preserved to .proposed)", false).option("--force", "rewrite every managed block, overwriting local edits inside the markers (content outside untouched)", false).option("--check", "report whether anything would change and exit (0 = all current, 1 = stale/drift/absent); writes nothing", false).option("-y, --yes", "non-interactive: accept defaults (system timezone, detected clients, global config, full wire)", false).addHelpText(
     "after",
     `
 Examples:
@@ -2381,16 +2683,22 @@ Examples:
   $ sechroom onboard --cli-only         just the CLI \u2014 no .mcp.json, no agent files
   $ sechroom onboard --no-mcp           agent instructions only, skip MCP config
   $ sechroom onboard --local            save tenant + base URL to ./.sechroom.json
+  $ sechroom onboard --workspace wsp_XX  bind this directory to a workspace (no pick prompt)
+  $ sechroom onboard --refresh          refresh out-of-date instruction blocks in place
+  $ sechroom onboard --check            CI/pre-commit: nonzero exit if instructions are out of date
   $ sechroom onboard --yes              non-interactive: defaults + global config + full wire
   $ sechroom onboard --client all --dry-run    preview wiring every client, write nothing`
   ).action(async (opts, cmd) => {
     const g = cmd.optsWithGlobals();
     const json = Boolean(g.json);
-    const yes = Boolean(opts.yes);
     const dryRun = Boolean(opts.dryRun);
-    const cfg = await ensureConfig(g, { yes, json, local: Boolean(opts.local) });
-    await ensureAuth(cfg, yes);
-    const tz = await ensureTimezone(cfg, { yes, dryRun });
+    const mode = opts.check ? "check" : opts.force ? "force" : "apply";
+    const check = mode === "check";
+    const yes = Boolean(opts.yes) || check;
+    const baseUrl = resolveBaseUrl(g);
+    await ensureAuth({ baseUrl, tenant: "", clientId: readPersisted().clientId }, yes);
+    const cfg = await ensureTenant(baseUrl, g, { yes, json, local: Boolean(opts.local), workspace: opts.workspace, persist: !check });
+    const tz = await ensureTimezone(cfg, { yes, dryRun: dryRun || check });
     if (!json && tz.action !== "already-set") {
       const line = tz.action === "set" ? `${ok("\u2713")} timezone set to ${tz.timezone}
 ` : tz.action === "dry-run" ? `(dry run \u2014 would set timezone to ${tz.timezone})
@@ -2401,7 +2709,7 @@ Examples:
     const wire = await chooseWire(opts, yes);
     if (wire === "cli-only") {
       if (json) {
-        emit({ dryRun, baseUrl: cfg.baseUrl, tenant: cfg.tenant, timezone: tz, wire, clients: [] }, true);
+        emit({ dryRun, baseUrl: cfg.baseUrl, tenant: cfg.tenant, workspaceId: cfg.workspaceId ?? null, timezone: tz, wire, clients: [] }, true);
         return;
       }
       process.stdout.write(
@@ -2416,7 +2724,7 @@ Try: ${style.cyan('sechroom memory search "..."')}  or  ${style.cyan("sechroom -
     const setup = await withSpinner("Fetching setup descriptors", () => fetchSetup(cfg));
     const targets = clientTargets(process.cwd());
     const personalWorkspaceId = await getPersonalWorkspaceId(cfg);
-    if (!dryRun) {
+    if (!dryRun && !check) {
       await maybeOfferCopies(cfg, setup, targets, keys, personalWorkspaceId, copyChoice(opts));
     }
     const writeMcp = wire === "full";
@@ -2427,20 +2735,56 @@ Try: ${style.cyan('sechroom memory search "..."')}  or  ${style.cyan("sechroom -
         dryRun,
         mcp: writeMcp,
         agentFiles: true,
-        personalWorkspaceId
+        personalWorkspaceId,
+        mode
       });
       result.push({ client: key, actions });
-      if (!json) printActions(target, actions);
+      if (!json && !check) printActions(target, actions);
+    }
+    const evalCounts = { current: 0, stale: 0, drift: 0, absent: 0 };
+    for (const { actions } of result) for (const a of actions) if (a.eval) evalCounts[a.eval]++;
+    const wouldChange = evalCounts.stale + evalCounts.drift + evalCounts.absent;
+    if (check) {
+      if (json) {
+        emit({ check: true, baseUrl: cfg.baseUrl, tenant: cfg.tenant, workspaceId: cfg.workspaceId ?? null, eval: evalCounts, wouldChange, clients: result }, true);
+      } else if (wouldChange === 0) {
+        process.stdout.write(`${ok("\u2713")} all instruction blocks are up to date.
+`);
+      } else {
+        const bits = [];
+        if (evalCounts.stale) bits.push(`${evalCounts.stale} out of date`);
+        if (evalCounts.drift) bits.push(`${evalCounts.drift} with local edits`);
+        if (evalCounts.absent) bits.push(`${evalCounts.absent} not yet written`);
+        process.stderr.write(
+          `${warn("\u26A0")} ${wouldChange} instruction block(s) would change: ${bits.join(", ")}. Run ${style.cyan("sechroom onboard --refresh")}.
+`
+        );
+      }
+      process.exit(wouldChange === 0 ? 0 : 1);
     }
     if (!json && !dryRun) {
       await maybeOfferSkills(cfg, personalWorkspaceId, { yes, dryRun, surface: "claude-code" });
     }
     if (json) {
-      emit({ dryRun, baseUrl: cfg.baseUrl, tenant: cfg.tenant, timezone: tz, wire, clients: result }, true);
+      emit({ dryRun, baseUrl: cfg.baseUrl, tenant: cfg.tenant, workspaceId: cfg.workspaceId ?? null, timezone: tz, wire, eval: evalCounts, clients: result }, true);
       return;
     }
+    if (!dryRun && evalCounts.stale) {
+      process.stderr.write(`${style.cyan("\u21BB")} refreshed ${evalCounts.stale} section(s) the server had moved
+`);
+    }
+    if (!dryRun && evalCounts.drift) {
+      process.stderr.write(
+        mode === "force" ? `${warn("\u26A0")} overwrote ${evalCounts.drift} section(s) that had local edits (--force)
+` : `${warn("\u26A0")} ${evalCounts.drift} section(s) have local edits \u2014 wrote a .proposed file alongside (original untouched). Review + merge, or re-run with ${style.cyan("--force")}.
+`
+      );
+    }
+    const wroteSomething = result.some(({ actions }) => actions.some((a) => a.status === "created" || a.status === "merged"));
     process.stdout.write(
-      dryRun ? "\n(dry run \u2014 nothing written)\n" : writeMcp ? `
+      dryRun ? "\n(dry run \u2014 nothing written)\n" : !wroteSomething ? `
+${style.bold("Done.")} Everything's already up to date.
+` : writeMcp ? `
 ${style.bold("Done.")} Restart your AI client (or reload MCP) to pick up the new config.
 ` : `
 ${style.bold("Done.")} Agent instructions written (no MCP config).
@@ -2821,10 +3165,10 @@ Examples:
   $ sechroom config set clientId dyn-XXXX                     global-only escape hatch (no DCR endpoint)
   $ sechroom config show --json`
 );
-config.command("set <key> <value>").description("Set baseUrl | tenant | clientId (clientId is global-only)").option("--local", "Write to the directory-local .sechroom.json (nearest up the tree, else cwd) instead of the global config").action((key, value, opts) => {
+config.command("set <key> <value>").description("Set baseUrl | tenant | workspaceId | defaultProjectId | clientId (clientId is global-only)").option("--local", "Write to the directory-local .sechroom.json (nearest up the tree, else cwd) instead of the global config").action((key, value, opts) => {
   if (opts.local) {
-    if (!["baseUrl", "tenant"].includes(key)) {
-      process.stderr.write(`--local supports only: baseUrl | tenant (clientId is global)
+    if (!["baseUrl", "tenant", "workspaceId", "defaultProjectId"].includes(key)) {
+      process.stderr.write(`--local supports only: baseUrl | tenant | workspaceId | defaultProjectId (clientId is global)
 `);
       process.exit(1);
     }
@@ -2833,8 +3177,8 @@ config.command("set <key> <value>").description("Set baseUrl | tenant | clientId
 `);
     return;
   }
-  if (!["baseUrl", "tenant", "clientId"].includes(key)) {
-    process.stderr.write(`unknown key: ${key} (expected baseUrl | tenant | clientId)
+  if (!["baseUrl", "tenant", "clientId", "workspaceId", "defaultProjectId"].includes(key)) {
+    process.stderr.write(`unknown key: ${key} (expected baseUrl | tenant | workspaceId | defaultProjectId | clientId)
 `);
     process.exit(1);
   }
@@ -2848,7 +3192,7 @@ config.command("show").description("Print resolved config + sources (flag > env
   if (g.json) {
     process.stdout.write(
       JSON.stringify({
-        resolved: { baseUrl: d.baseUrl, tenant: d.tenant },
+        resolved: { baseUrl: d.baseUrl, tenant: d.tenant, workspaceId: d.workspaceId },
         global: readPersisted(),
         local: readLocalConfig()
       }) + "\n"
@@ -2856,8 +3200,9 @@ config.command("show").description("Print resolved config + sources (flag > env
     return;
   }
   process.stdout.write(
-    `baseUrl: ${d.baseUrl.value}  [${d.baseUrl.source}]
-tenant:  ${d.tenant.value ?? "(unset)"}  [${d.tenant.source}]
+    `baseUrl:     ${d.baseUrl.value}  [${d.baseUrl.source}]
+tenant:      ${d.tenant.value ?? "(unset)"}  [${d.tenant.source}]
+workspaceId: ${d.workspaceId.value ?? "(unset)"}  [${d.workspaceId.source}]
 
 global: ${JSON.stringify(readPersisted())}
 local:  ${d.localPath ?? "(none)"} ${JSON.stringify(readLocalConfig())}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sechroom/cli",
-  "version": "2026.6.12",
+  "version": "2026.6.14",
   "description": "Sechroom CLI — a thin, generated client over the Sechroom HTTP API. An agent/human surface alongside MCP.",
   "type": "module",
   "license": "UNLICENSED",