@sechroom/cli 2026.6.4 → 2026.6.6

package/README.md

@@ -100,6 +100,23 @@ sechroom lookup sechroom:mem_XXXX --json # namespaced form also resolves
 sechroom --json memory get mem_XXXX     # agent-friendly
 ```
 
+**Per-directory config.** A project dir can pin its own `tenant` + `baseUrl` in a local `.sechroom.json`, discovered by walking **up** from cwd (nearest wins, so any subdir inherits it). It overrides the global config — precedence: `--flag` > env > directory-local > global > default. `clientId` / auth state stays global.
+
+```bash
+sechroom config set --local tenant  cli-smoke                       # this dir + subdirs
+sechroom config set --local baseUrl https://staging.app.sechroom.ai/api
+sechroom config show                                                # resolved values + which source won
+```
+
+**Smoke testing.** There is a dedicated **`cli-smoke`** tenant on **both staging and prod** for exercising the CLI without touching real tenants — point at staging and use it:
+
+```bash
+sechroom config set --local baseUrl https://staging.app.sechroom.ai/api
+sechroom config set --local tenant  cli-smoke
+sechroom login
+sechroom worklog append --text "cli smoke" --source claude-code-chris
+```
+
 Headless:
 
 ```bash

package/dist/index.js

@@ -11,11 +11,12 @@ import open from "open";
 
 // src/config.ts
 import { homedir } from "os";
-import { join } from "path";
+import { join, dirname } from "path";
 import { mkdirSync, readFileSync, writeFileSync, existsSync } from "fs";
 var CONFIG_DIR = join(homedir(), ".config", "sechroom");
 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";
 function ensureDir() {
   if (!existsSync(CONFIG_DIR)) mkdirSync(CONFIG_DIR, { recursive: true, mode: 448 });
@@ -32,6 +33,13 @@ function writePersisted(patch) {
   const next = { ...readPersisted(), ...patch };
   writeFileSync(CONFIG_FILE, JSON.stringify(next, null, 2), { mode: 384 });
 }
+function readDcrClientId(baseUrl) {
+  return readPersisted().clientIds?.[baseUrl];
+}
+function writeDcrClientId(baseUrl, clientId) {
+  const p = readPersisted();
+  writePersisted({ clientIds: { ...p.clientIds ?? {}, [baseUrl]: clientId } });
+}
 function readToken() {
   const envTok = process.env.SECHROOM_TOKEN;
   if (envTok) return { accessToken: envTok };
@@ -45,17 +53,67 @@ function writeToken(tok) {
   ensureDir();
   writeFileSync(TOKEN_FILE, JSON.stringify(tok, null, 2), { mode: 384 });
 }
+function findLocalConfigPath(start = process.cwd()) {
+  let dir = start;
+  for (; ; ) {
+    const candidate = join(dir, LOCAL_CONFIG_NAME);
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) return void 0;
+    dir = parent;
+  }
+}
+function readLocalConfig() {
+  const path = findLocalConfigPath();
+  if (!path) return {};
+  try {
+    const c = JSON.parse(readFileSync(path, "utf8"));
+    return { baseUrl: c.baseUrl, tenant: c.tenant, path };
+  } catch {
+    return {};
+  }
+}
+function writeLocalConfig(patch) {
+  const path = findLocalConfigPath() ?? join(process.cwd(), LOCAL_CONFIG_NAME);
+  let current = {};
+  try {
+    current = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+  }
+  writeFileSync(path, JSON.stringify({ ...current, ...patch }, null, 2), { mode: 384 });
+  return path;
+}
 function resolveConfig(flags) {
+  const local = readLocalConfig();
   const persisted = readPersisted();
-  const baseUrl = flags.baseUrl ?? process.env.SECHROOM_BASE_URL ?? persisted.baseUrl ?? DEFAULT_BASE_URL;
-  const tenant = flags.tenant ?? process.env.SECHROOM_TENANT ?? persisted.tenant ?? "";
+  const baseUrl = flags.baseUrl ?? process.env.SECHROOM_BASE_URL ?? local.baseUrl ?? persisted.baseUrl ?? DEFAULT_BASE_URL;
+  const tenant = flags.tenant ?? process.env.SECHROOM_TENANT ?? local.tenant ?? persisted.tenant ?? "";
   if (!tenant) {
     throw new Error(
-      "No tenant set. The Sechroom API rejects untenanted requests (HTTP 400). Pass --tenant <id>, set SECHROOM_TENANT, or run `sechroom config set tenant <id>`."
+      "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 };
 }
+function describeConfig(flags) {
+  const local = readLocalConfig();
+  const g = readPersisted();
+  const localTag = local.path ? `local (${local.path})` : "local";
+  const pick = (flag, env, l, gl, def) => {
+    if (flag) return { value: flag, source: "flag" };
+    if (env) return { value: env, source: "env" };
+    if (l) return { value: l, source: localTag };
+    if (gl) return { value: gl, source: "global" };
+    if (def) return { value: def, source: "default" };
+    return { value: void 0, source: "unset" };
+  };
+  const baseUrl = pick(flags.baseUrl, process.env.SECHROOM_BASE_URL, local.baseUrl, g.baseUrl, DEFAULT_BASE_URL);
+  return {
+    baseUrl: { value: baseUrl.value, source: baseUrl.source },
+    tenant: pick(flags.tenant, process.env.SECHROOM_TENANT, local.tenant, g.tenant),
+    localPath: local.path
+  };
+}
 
 // src/auth.ts
 var SCOPES = "openid email profile";
@@ -72,26 +130,26 @@ async function discover(baseUrl) {
   if (!res.ok) throw new Error(`AS discovery failed (${res.status}) at ${baseUrl}`);
   return await res.json();
 }
-async function ensureClientId(meta) {
-  const cached = readPersisted().clientId;
-  if (cached) return cached;
-  if (!meta.registration_endpoint) {
-    throw new Error(
-      "Server advertises no registration_endpoint and no client_id is cached. Pre-register a client and run `sechroom config set clientId <id>`."
-    );
+async function ensureClientId(meta, baseUrl) {
+  if (meta.registration_endpoint) {
+    const res = await fetch(meta.registration_endpoint, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        client_name: "sechroom-cli",
+        redirect_uris: CANDIDATE_PORTS.map(redirectUriFor)
+      })
+    });
+    if (!res.ok) throw new Error(`Dynamic client registration failed (${res.status}): ${await res.text()}`);
+    const reg = await res.json();
+    writeDcrClientId(baseUrl, reg.client_id);
+    return reg.client_id;
   }
-  const res = await fetch(meta.registration_endpoint, {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify({
-      client_name: "sechroom-cli",
-      redirect_uris: CANDIDATE_PORTS.map(redirectUriFor)
-    })
-  });
-  if (!res.ok) throw new Error(`Dynamic client registration failed (${res.status}): ${await res.text()}`);
-  const reg = await res.json();
-  writePersisted({ clientId: reg.client_id });
-  return reg.client_id;
+  const fallback = readPersisted().clientId ?? readDcrClientId(baseUrl);
+  if (fallback) return fallback;
+  throw new Error(
+    "Server advertises no registration_endpoint and no client_id is configured. Pre-register a client and run `sechroom config set clientId <id>`."
+  );
 }
 function startLoopback(state) {
   return new Promise((resolveOuter, rejectOuter) => {
@@ -162,7 +220,7 @@ function persistTokenResponse(json) {
 }
 async function login(cfg) {
   const meta = await discover(cfg.baseUrl);
-  const clientId = await ensureClientId(meta);
+  const clientId = await ensureClientId(meta, cfg.baseUrl);
   const state = b64url(randomBytes(16));
   const verifier = b64url(randomBytes(32));
   const challenge = b64url(createHash("sha256").update(verifier).digest());
@@ -255,6 +313,37 @@ function spinner(text) {
     stop: clear
   };
 }
+function canPrompt() {
+  return !quiet && Boolean(process.stdin.isTTY) && Boolean(process.stderr.isTTY);
+}
+async function promptYesNo(question) {
+  if (!canPrompt()) return false;
+  const { createInterface } = await import("readline");
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    const answer = await new Promise((resolve) => {
+      rl.question(`${question} [y/N] `, resolve);
+    });
+    return /^y(es)?$/i.test(answer.trim());
+  } finally {
+    rl.close();
+  }
+}
+async function promptText(question, def) {
+  if (!canPrompt()) return def ?? "";
+  const { createInterface } = await import("readline");
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    const suffix = def ? ` [${def}]` : "";
+    const answer = await new Promise((resolve) => {
+      rl.question(`${question}${suffix} `, resolve);
+    });
+    const trimmed = answer.trim();
+    return trimmed.length > 0 ? trimmed : def ?? "";
+  } finally {
+    rl.close();
+  }
+}
 async function withSpinner(text, fn) {
   const s = spinner(text);
   try {
@@ -405,7 +494,7 @@ function registerLookup(program2) {
 
 // src/setup/apply.ts
 import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2, existsSync as existsSync2 } from "fs";
-import { dirname } from "path";
+import { dirname as dirname2 } from "path";
 
 // src/setup/operator-surface.ts
 var SectionType = {
@@ -440,43 +529,74 @@ function parseTagArtifactId(id) {
   const tags = id.slice("tag:".length).split(",").map((t) => t.trim()).filter((t) => t.length > 0);
   return tags.length > 0 ? tags : null;
 }
-async function resolveInstructionBody(cfg, section) {
+async function getPersonalWorkspaceId(cfg) {
+  const client = await makeClient(cfg);
+  const { data } = await client.GET("/me/personal-workspace", {});
+  return data?.workspaceId ?? null;
+}
+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;
+}
+async function resolveInstruction(cfg, section, personalWorkspaceId) {
   const client = await makeClient(cfg);
   for (const artifact of section.artifacts) {
     const tags = parseTagArtifactId(artifact.id);
     if (!tags) continue;
     const { data } = await client.POST("/memories/search", {
-      body: {
-        query: null,
-        textQuery: null,
-        semanticQuery: artifact.title ?? "role instruction template",
-        hybrid: true,
-        limit: 1,
-        includeArchived: false,
-        includeSystem: false,
-        tags
-      }
+      body: { query: null, textQuery: null, semanticQuery: artifact.title ?? "role instruction template", hybrid: true, limit: 1, includeArchived: false, includeSystem: false, tags }
     });
     const hits = data ?? [];
     if (hits.length === 0) continue;
-    const memId = hits[0].id;
-    const { data: memEnvelope } = await client.GET("/memories/{memoryId}", {
-      params: { path: { memoryId: memId } }
-    });
-    const env = memEnvelope;
-    const body = env?.item?.text ?? env?.text;
-    if (typeof body === "string" && body.length > 0) {
-      return { title: env?.item?.title ?? env?.title ?? artifact.title, body };
+    const templateId = hits[0].id;
+    const template = await fetchMemoryFields(cfg, templateId);
+    if (typeof template?.text !== "string" || template.text.length === 0) continue;
+    const templateTags = template.tags ?? tags;
+    if (personalWorkspaceId) {
+      const { data: ovr } = await client.POST("/memories/search", {
+        body: { query: null, textQuery: null, semanticQuery: "role override", hybrid: true, limit: 1, includeArchived: false, includeSystem: false, tags: ["sechroom:role:override", `sechroom:template-ref:${templateId}`], owner: { type: "Workspace", id: personalWorkspaceId } }
+      });
+      const ovrHits = ovr ?? [];
+      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: template.title ?? artifact.title, body: template.text, source: "template", templateId, templateTags };
   }
   return null;
 }
+async function createOverride(cfg, template, personalWorkspaceId) {
+  const client = await makeClient(cfg);
+  const overrideTags = template.templateTags.filter(
+    (t) => t !== "sechroom:role:template" && !t.startsWith("sechroom:bundle:") && !t.startsWith("sechroom:template-ref:")
+  );
+  overrideTags.push("sechroom:role:override", `sechroom:template-ref:${template.templateId}`);
+  const { error } = await client.POST("/memories", {
+    body: {
+      text: template.body,
+      type: "reference",
+      content: "{}",
+      confidence: 1,
+      source: "cli-agent-instructions-customize",
+      archetype: "Document",
+      title: template.title ?? null,
+      tags: overrideTags,
+      owner: { type: "Workspace", id: personalWorkspaceId }
+    }
+  });
+  if (error) throw new Error(`creating personal copy failed: ${JSON.stringify(error)}`);
+}
 
 // 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 -->";
 function ensureDir2(path) {
-  mkdirSync2(dirname(path), { recursive: true });
+  mkdirSync2(dirname2(path), { recursive: true });
 }
 function readOr(path, fallback) {
   try {
@@ -557,11 +677,12 @@ async function applyClient(cfg, setup, target, opts) {
     if (!section) {
       actions.push({ kind: "instruction", path: target.instruction.path, status: "skipped", note: `no instruction-file section on surface '${target.instruction.surfaceKey}'` });
     } else {
-      const resolved = await resolveInstructionBody(cfg, section);
+      const resolved = await resolveInstruction(cfg, section, opts.personalWorkspaceId);
       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 {
-        actions.push(writeInstructionBlock(target.instruction.path, resolved.body, opts.dryRun));
+        const action = writeInstructionBlock(target.instruction.path, resolved.body, opts.dryRun);
+        actions.push(resolved.source === "override" ? { ...action, note: "your personal copy" } : action);
       }
     }
   }
@@ -569,8 +690,9 @@ async function applyClient(cfg, setup, target, opts) {
 }
 
 // src/setup/clients.ts
+import { existsSync as existsSync3 } from "fs";
 import { homedir as homedir2 } from "os";
-import { join as join2 } from "path";
+import { dirname as dirname3, join as join2 } from "path";
 function claudeDesktopConfigPath(home) {
   switch (process.platform) {
     case "darwin":
@@ -612,8 +734,49 @@ function clientTargets(cwd) {
 }
 var ALL_CLIENT_KEYS = ["claude-code", "claude-desktop", "codex", "cursor"];
 var DEFAULT_CLIENT_KEY = "claude-code";
+function detectInstalledClients(cwd) {
+  const home = homedir2();
+  const detected = [];
+  if (existsSync3(join2(home, ".claude"))) detected.push("claude-code");
+  if (existsSync3(dirname3(claudeDesktopConfigPath(home)))) detected.push("claude-desktop");
+  if (existsSync3(join2(home, ".codex"))) detected.push("codex");
+  if (existsSync3(join2(home, ".cursor")) || existsSync3(join2(cwd, ".cursor"))) detected.push("cursor");
+  return detected;
+}
 
 // src/commands/setup.ts
+function copyChoice(opts) {
+  return opts.copy === true ? "yes" : opts.copy === false ? "no" : "ask";
+}
+async function maybeOfferCopies(cfg, setup, targets, keys, personalWorkspaceId, choice) {
+  if (!personalWorkspaceId || choice === "no") return;
+  const seen = /* @__PURE__ */ new Set();
+  for (const key of keys) {
+    const instr = targets[key]?.instruction;
+    if (!instr || seen.has(instr.surfaceKey)) continue;
+    seen.add(instr.surfaceKey);
+    const section = findSection(findSurface(setup, instr.surfaceKey), SectionType.InstructionFile);
+    if (!section) continue;
+    const resolved = await resolveInstruction(cfg, section, personalWorkspaceId);
+    if (!resolved || resolved.source === "override") continue;
+    let make = choice === "yes";
+    if (choice === "ask") {
+      process.stderr.write(
+        `
+The ${instr.surfaceKey} agent instructions are the shared template.
+Make a personal copy to tailor them for your workflow \u2014 your agent uses your
+version, the shared template stays clean, and you can discard back anytime.
+`
+      );
+      make = await promptYesNo("Make a personal copy to customise?");
+    }
+    if (make) {
+      await createOverride(cfg, resolved, personalWorkspaceId);
+      process.stderr.write(`\u2713 personal copy created for ${instr.surfaceKey} \u2014 edit it on the Agent setup page or via the API.
+`);
+    }
+  }
+}
 function resolveClientKeys(raw) {
   const targets = clientTargets(process.cwd());
   if (raw === "all") return [...ALL_CLIENT_KEYS];
@@ -636,19 +799,24 @@ ${client.label} (${client.key}):
   }
 }
 function registerInit(program2) {
-  program2.command("init").description("Wire this project for sechroom: write MCP config + agent instruction files from the server's setup descriptors").option("--client <list>", `comma-separated clients (${ALL_CLIENT_KEYS.join(", ")}) or 'all'`, DEFAULT_CLIENT_KEY).option("--dry-run", "print what would be written without writing", false).option("--mcp-only", "only write MCP config (skip agent files)", false).option("--agent-files-only", "only write agent instruction files (skip MCP config)", false).action(async (opts, cmd) => {
+  program2.command("init").description("Wire this project for sechroom: write MCP config + agent instruction files from the server's setup descriptors").option("--client <list>", `comma-separated clients (${ALL_CLIENT_KEYS.join(", ")}) or 'all'`, DEFAULT_CLIENT_KEY).option("--dry-run", "print what would be written without writing", false).option("--mcp-only", "only write MCP config (skip agent files)", false).option("--agent-files-only", "only write agent instruction files (skip MCP config)", false).option("--copy", "make a personal copy of the agent instructions you can edit (default: prompt on a TTY, else skip)").action(async (opts, cmd) => {
     const cfg = resolveConfig(cmd.optsWithGlobals());
     const setup = await withSpinner("Fetching setup descriptors", () => fetchSetup(cfg));
     const targets = clientTargets(process.cwd());
     const keys = resolveClientKeys(opts.client);
     const json = cmd.optsWithGlobals().json;
+    const personalWorkspaceId = await getPersonalWorkspaceId(cfg);
+    if (!opts.dryRun && !opts.mcpOnly) {
+      await maybeOfferCopies(cfg, setup, targets, keys, personalWorkspaceId, copyChoice(opts));
+    }
     const result = [];
     for (const key of keys) {
       const target = targets[key];
       const actions = await applyClient(cfg, setup, target, {
         dryRun: Boolean(opts.dryRun),
         mcp: !opts.agentFilesOnly,
-        agentFiles: !opts.mcpOnly
+        agentFiles: !opts.mcpOnly,
+        personalWorkspaceId
       });
       result.push({ client: key, actions });
       if (!json) printActions(target, actions);
@@ -675,8 +843,8 @@ function registerSetup(program2) {
   setup.command("mcp <client>").description(`Write only the MCP config for a client (${ALL_CLIENT_KEYS.join(", ")})`).option("--dry-run", "print what would be written without writing", false).action(async (client, opts, cmd) => {
     await runSingle(client, cmd, { dryRun: Boolean(opts.dryRun), mcp: true, agentFiles: false });
   });
-  setup.command("agent-files <client>").description(`Write only the agent instruction file for a client (${ALL_CLIENT_KEYS.join(", ")})`).option("--dry-run", "print what would be written without writing", false).action(async (client, opts, cmd) => {
-    await runSingle(client, cmd, { dryRun: Boolean(opts.dryRun), mcp: false, agentFiles: true });
+  setup.command("agent-files <client>").description(`Write only the agent instruction file for a client (${ALL_CLIENT_KEYS.join(", ")})`).option("--dry-run", "print what would be written without writing", false).option("--copy", "make a personal copy you can edit (default: prompt on a TTY, else skip)").action(async (client, opts, cmd) => {
+    await runSingle(client, cmd, { dryRun: Boolean(opts.dryRun), mcp: false, agentFiles: true, copy: opts.copy });
   });
 }
 async function runSingle(client, cmd, opts) {
@@ -685,7 +853,16 @@ async function runSingle(client, cmd, opts) {
   const target = targets[client];
   if (!target) fail(`unknown client '${client}'. Known: ${ALL_CLIENT_KEYS.join(", ")}.`);
   const setupData = await withSpinner("Fetching setup descriptors", () => fetchSetup(cfg));
-  const actions = await applyClient(cfg, setupData, target, opts);
+  const personalWorkspaceId = await getPersonalWorkspaceId(cfg);
+  if (opts.agentFiles && !opts.dryRun) {
+    await maybeOfferCopies(cfg, setupData, targets, [client], personalWorkspaceId, copyChoice(opts));
+  }
+  const actions = await applyClient(cfg, setupData, target, {
+    dryRun: opts.dryRun,
+    mcp: opts.mcp,
+    agentFiles: opts.agentFiles,
+    personalWorkspaceId
+  });
   const json = cmd.optsWithGlobals().json;
   if (json) {
     emit({ dryRun: opts.dryRun, client, actions }, true);
@@ -695,6 +872,127 @@ async function runSingle(client, cmd, opts) {
   }
 }
 
+// src/commands/onboard.ts
+var DEFAULT_BASE_URL2 = "https://app.sechroom.ai/api";
+function systemTimezone() {
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+  } catch {
+    return "UTC";
+  }
+}
+async function ensureConfig(g, yes) {
+  const persisted = readPersisted();
+  let baseUrl = g.baseUrl ?? process.env.SECHROOM_BASE_URL ?? persisted.baseUrl ?? DEFAULT_BASE_URL2;
+  let tenant = g.tenant ?? process.env.SECHROOM_TENANT ?? persisted.tenant ?? "";
+  if (canPrompt() && !yes) {
+    baseUrl = await promptText("Sechroom API base URL?", baseUrl);
+    tenant = await promptText("Tenant id?", tenant || void 0);
+  }
+  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)."
+    );
+  }
+  writePersisted({ baseUrl, tenant });
+  return { baseUrl, tenant, clientId: persisted.clientId };
+}
+async function ensureAuth(cfg, yes) {
+  if (process.env.SECHROOM_TOKEN) return;
+  const cached = readToken();
+  const usable = Boolean(cached?.accessToken) && (cached.expiresAt === void 0 || Date.now() < cached.expiresAt - 6e4 || Boolean(cached.refreshToken));
+  if (usable) return;
+  if (!canPrompt() || yes) {
+    fail("Not signed in. Run `sechroom login` first, or set SECHROOM_TOKEN for headless use.");
+  }
+  process.stderr.write("\nNot signed in \u2014 opening the browser to authenticate.\n");
+  await login(cfg);
+}
+async function ensureTimezone(cfg, opts) {
+  const client = await makeClient(cfg);
+  const { data, error } = await client.GET("/me/profile", {});
+  if (error) return { timezone: null, action: "skipped", note: "could not read profile" };
+  const current = data?.effectiveTimezone;
+  if (current && current.trim().length > 0) return { timezone: current, action: "already-set" };
+  const system = systemTimezone();
+  let tz = system;
+  if (canPrompt() && !opts.yes) {
+    tz = await promptText("Your timezone (IANA, e.g. Europe/London)?", system);
+  } else if (!opts.yes) {
+    return {
+      timezone: null,
+      action: "skipped",
+      note: "no timezone set \u2014 re-run interactively or pass --yes to adopt the system timezone"
+    };
+  }
+  if (!tz) return { timezone: null, action: "skipped", note: "no timezone provided" };
+  if (opts.dryRun) return { timezone: tz, action: "dry-run" };
+  const { error: putErr } = await client.PUT("/me/profile", {
+    body: { displayName: null, photoUrl: null, bio: null, timezone: tz }
+  });
+  if (putErr) return { timezone: tz, action: "skipped", note: `update failed: ${JSON.stringify(putErr)}` };
+  return { timezone: tz, action: "set" };
+}
+async function chooseClients(clientFlag, yes, cwd) {
+  if (clientFlag) return resolveClientKeys(clientFlag);
+  const detected = detectInstalledClients(cwd);
+  const fallback = (detected.length > 0 ? detected : [DEFAULT_CLIENT_KEY]).join(",");
+  if (!canPrompt() || yes) return resolveClientKeys(fallback);
+  process.stderr.write(
+    `
+Available clients: ${ALL_CLIENT_KEYS.join(", ")}
+` + (detected.length > 0 ? `Detected on this machine: ${detected.join(", ")}
+` : "No clients auto-detected.\n")
+  );
+  const answer = await promptText("Which to wire? (comma-separated, or 'all')", fallback);
+  return resolveClientKeys(answer);
+}
+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("--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)", false).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);
+    await ensureAuth(cfg, yes);
+    const tz = await ensureTimezone(cfg, { yes, dryRun });
+    if (!json && tz.action !== "already-set") {
+      const line = tz.action === "set" ? `\u2713 timezone set to ${tz.timezone}
+` : tz.action === "dry-run" ? `(dry run \u2014 would set timezone to ${tz.timezone})
+` : `timezone not set \u2014 ${tz.note}
+`;
+      process.stderr.write(line);
+    }
+    const keys = await chooseClients(opts.client, yes, process.cwd());
+    const setup = await withSpinner("Fetching setup descriptors", () => fetchSetup(cfg));
+    const targets = clientTargets(process.cwd());
+    const personalWorkspaceId = await getPersonalWorkspaceId(cfg);
+    if (!dryRun) {
+      await maybeOfferCopies(cfg, setup, targets, keys, personalWorkspaceId, copyChoice(opts));
+    }
+    const result = [];
+    for (const key of keys) {
+      const target = targets[key];
+      const actions = await applyClient(cfg, setup, target, {
+        dryRun,
+        mcp: true,
+        agentFiles: true,
+        personalWorkspaceId
+      });
+      result.push({ client: key, actions });
+      if (!json) printActions(target, actions);
+    }
+    if (json) {
+      emit({ dryRun, baseUrl: cfg.baseUrl, tenant: cfg.tenant, timezone: tz, clients: result }, true);
+      return;
+    }
+    process.stdout.write(
+      dryRun ? "\n(dry run \u2014 nothing written)\n" : "\nDone. Restart your AI client (or reload MCP) to pick up the new config.\n"
+    );
+  });
+}
+
 // src/index.ts
 function resolveVersion() {
   try {
@@ -718,7 +1016,18 @@ program.command("login").description("Sign in via browser (OAuth auth-code + PKC
   await login({ baseUrl: baseUrl.replace(/\/$/, ""), tenant: g.tenant ?? "" });
 });
 var config = program.command("config").description("Manage persisted CLI config");
-config.command("set <key> <value>").description("Set baseUrl | tenant | clientId").action((key, value) => {
+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) => {
+  if (opts.local) {
+    if (!["baseUrl", "tenant"].includes(key)) {
+      process.stderr.write(`--local supports only: baseUrl | tenant (clientId is global)
+`);
+      process.exit(1);
+    }
+    const path = writeLocalConfig({ [key]: value });
+    process.stdout.write(`set ${key} (local: ${path})
+`);
+    return;
+  }
   if (!["baseUrl", "tenant", "clientId"].includes(key)) {
     process.stderr.write(`unknown key: ${key} (expected baseUrl | tenant | clientId)
 `);
@@ -728,14 +1037,34 @@ config.command("set <key> <value>").description("Set baseUrl | tenant | clientId
   process.stdout.write(`set ${key}
 `);
 });
-config.command("show").description("Print persisted config").action(() => {
-  process.stdout.write(JSON.stringify(readPersisted(), null, 2) + "\n");
+config.command("show").description("Print resolved config + sources (flag > env > local > global > default)").action((_opts, cmd) => {
+  const g = cmd.optsWithGlobals();
+  const d = describeConfig({ baseUrl: g.baseUrl, tenant: g.tenant });
+  if (g.json) {
+    process.stdout.write(
+      JSON.stringify({
+        resolved: { baseUrl: d.baseUrl, tenant: d.tenant },
+        global: readPersisted(),
+        local: readLocalConfig()
+      }) + "\n"
+    );
+    return;
+  }
+  process.stdout.write(
+    `baseUrl: ${d.baseUrl.value}  [${d.baseUrl.source}]
+tenant:  ${d.tenant.value ?? "(unset)"}  [${d.tenant.source}]
+
+global: ${JSON.stringify(readPersisted())}
+local:  ${d.localPath ?? "(none)"} ${JSON.stringify(readLocalConfig())}
+`
+  );
 });
 registerMemory(program);
 registerWorklog(program);
 registerLookup(program);
 registerInit(program);
 registerSetup(program);
+registerOnboard(program);
 program.parseAsync().catch((err) => {
   process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}
 `);

package/package.json

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