@sechroom/cli 2026.6.5 → 2026.6.7

package/README.md

@@ -100,6 +100,30 @@ sechroom lookup sechroom:mem_XXXX --json # namespaced form also resolves
 sechroom --json memory get mem_XXXX     # agent-friendly
 ```
 
+**Output shape.** Mutating commands (`memory create`, `worklog append`) print a concise confirmation line — id + view URL — the way the MCP tools hand an LLM a result, instead of dumping the raw envelope. Pass `--json` for the full response body (the machine channel) on any command. Output is lightly colorized on a TTY and auto-plain when piped, under `--json`, or when `NO_COLOR` is set.
+
+```bash
+sechroom memory create --text "a note" --title "Note"
+# ✓ created memory mem_XXXX "Note" → https://sechroom.yi.ocd.codes/view/mem_XXXX
+```
+
+**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
@@ -120,6 +144,7 @@ Codex TOML table replace; instruction files use a managed marker block).
 sechroom init                       # Claude Code (default): .mcp.json + CLAUDE.md
 sechroom init --client all          # claude-code, claude-desktop, codex, cursor
 sechroom init --client codex,cursor # a subset
+sechroom init --mcp-only            # just the MCP config (skip agent files)
 sechroom init --dry-run --json      # preview the writes, no changes
 
 # granular pieces init orchestrates:
@@ -127,6 +152,27 @@ sechroom setup mcp claude-desktop          # just the MCP config for one client
 sechroom setup agent-files codex           # just the AGENTS.md instruction file
 ```
 
+### `sechroom onboard` — guided first run
+
+`onboard` orchestrates the whole zero-to-wired path interactively: configure base
+URL + tenant, sign in, set the profile timezone, then wire your AI client(s). Two
+prompts make it fit how you actually work:
+
+- **Where to save config** — globally (`~/.config/sechroom`, all projects) or a
+  directory-local `.sechroom.json` (this project + subdirs). Defaults to local
+  when a `.sechroom.json` already governs the dir.
+- **How far to wire** — full (MCP server + agent instructions), agent
+  instructions only (skip `.mcp.json`), or **CLI only** (write nothing for AI
+  clients — for when you just want the `sechroom` command).
+
+```bash
+sechroom onboard                    # interactive: asks where to save + how to wire
+sechroom onboard --cli-only         # just the CLI — 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 --yes              # non-interactive: defaults + global config + full wire
+```
+
 Per client → where it writes:
 
 | client | MCP config | instruction file |

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) => {
@@ -115,13 +173,13 @@ function startLoopback(state) {
         }
         const got = url.searchParams.get("code");
         const gotState = url.searchParams.get("state");
-        const err = url.searchParams.get("error");
-        res.writeHead(err ? 400 : 200, { "content-type": "text/html" });
+        const err2 = url.searchParams.get("error");
+        res.writeHead(err2 ? 400 : 200, { "content-type": "text/html" });
         res.end(
-          err ? `<h3>Authorization failed: ${err}</h3>` : "<h3>Signed in to Sechroom.</h3><p>Return to the terminal.</p>"
+          err2 ? `<h3>Authorization failed: ${err2}</h3>` : "<h3>Signed in to Sechroom.</h3><p>Return to the terminal.</p>"
         );
         server.close();
-        if (err) return rejectCode(new Error(`Authorization error: ${err}`));
+        if (err2) return rejectCode(new Error(`Authorization error: ${err2}`));
         if (!got) return rejectCode(new Error("No code in callback."));
         if (gotState !== state) return rejectCode(new Error("State mismatch \u2014 possible CSRF."));
         resolveCode(got);
@@ -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());
@@ -219,6 +277,22 @@ var quiet = false;
 function setQuiet(q) {
   quiet = q;
 }
+function colorOn() {
+  return !quiet && !process.env.NO_COLOR && process.env.FORCE_COLOR !== "0" && Boolean(process.stdout.isTTY);
+}
+function wrap(open2, close) {
+  return (s) => colorOn() ? `\x1B[${open2}m${s}\x1B[${close}m` : String(s);
+}
+var style = {
+  bold: wrap(1, 22),
+  dim: wrap(2, 22),
+  red: wrap(31, 39),
+  green: wrap(32, 39),
+  yellow: wrap(33, 39),
+  cyan: wrap(36, 39)
+};
+var ok = (s) => style.green(s);
+var err = (s) => style.red(s);
 function active() {
   return !quiet && Boolean(process.stderr.isTTY);
 }
@@ -244,12 +318,12 @@ function spinner(text) {
   return {
     succeed(t) {
       clear();
-      process.stderr.write(`\u2713 ${t ?? text}
+      process.stderr.write(`${ok("\u2713")} ${t ?? text}
 `);
     },
     fail(t) {
       clear();
-      process.stderr.write(`\u2717 ${t ?? text}
+      process.stderr.write(`${err("\u2717")} ${t ?? text}
 `);
     },
     stop: clear
@@ -286,15 +360,48 @@ async function promptText(question, def) {
     rl.close();
   }
 }
+async function promptSelect(question, choices, def) {
+  if (choices.length === 0) throw new Error("promptSelect: no choices");
+  const defIdx = Math.max(
+    0,
+    def !== void 0 ? choices.findIndex((c) => c.value === def) : 0
+  );
+  if (!canPrompt()) return choices[defIdx].value;
+  const { createInterface } = await import("readline");
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    process.stderr.write(`${style.bold(question)}
+`);
+    choices.forEach((c, i) => {
+      const marker = i === defIdx ? style.cyan("\u203A") : " ";
+      const hint = c.hint ? ` ${style.dim(`\u2014 ${c.hint}`)}` : "";
+      process.stderr.write(`  ${marker} ${style.bold(String(i + 1))}. ${c.label}${hint}
+`);
+    });
+    const answer = await new Promise((resolve) => {
+      rl.question(`Choose ${style.dim(`[${defIdx + 1}]`)} `, resolve);
+    });
+    const trimmed = answer.trim();
+    if (!trimmed) return choices[defIdx].value;
+    const n = Number(trimmed);
+    if (Number.isInteger(n) && n >= 1 && n <= choices.length) return choices[n - 1].value;
+    const byLabel = choices.find(
+      (c) => c.label.toLowerCase().startsWith(trimmed.toLowerCase())
+    );
+    return byLabel ? byLabel.value : choices[defIdx].value;
+  } finally {
+    rl.close();
+  }
+}
 async function withSpinner(text, fn) {
   const s = spinner(text);
   try {
     const result = await fn();
     s.succeed();
     return result;
-  } catch (err) {
+  } catch (err2) {
     s.fail();
-    throw err;
+    throw err2;
   }
 }
 
@@ -318,14 +425,25 @@ function emit(data, json) {
     process.stdout.write(JSON.stringify(data, null, 2) + "\n");
   }
 }
+function publicUrl(url) {
+  return url.replace(/^https?:\/\/localhost:5012/, "https://sechroom.yi.ocd.codes");
+}
+function emitAction(summary, data, json) {
+  if (json) {
+    process.stdout.write(JSON.stringify(data) + "\n");
+    return;
+  }
+  process.stdout.write(`${ok("\u2713")} ${summary}
+`);
+}
 async function runApi(label, fn) {
   const s = spinner(label);
   let res;
   try {
     res = await fn();
-  } catch (err) {
+  } catch (err2) {
     s.fail();
-    fail(err);
+    fail(err2);
   }
   if (res.error !== void 0 && res.error !== null) {
     s.fail();
@@ -344,6 +462,16 @@ function fail(error) {
 // src/commands/memory.ts
 function registerMemory(program2) {
   const memory = program2.command("memory").description("Create, read, and search memories");
+  memory.addHelpText(
+    "after",
+    `
+Examples:
+  $ sechroom memory create --text "first note" --type reference --tag idea --tag cli
+  $ sechroom memory create --text "filed note" --owner-type Workspace --owner-id wsp_XXXX
+  $ sechroom memory search "rate limiting" --limit 5 --tag kind:decision
+  $ sechroom memory search "auth flow" --workspace wsp_XXXX --json
+  $ sechroom memory get mem_XXXX --json`
+  );
   memory.command("create").description("Create a memory (POST /memories)").requiredOption("--text <text>", "Memory body text").option("--type <type>", "Memory type", "reference").option("--title <title>", "Optional title").option("--tag <tag...>", "Tags (repeatable)").option("--owner-type <ownerType>", "Workspace | Project | Unfiled", "Unfiled").option("--owner-id <ownerId>", "Owner id (required for Workspace/Project)").option("--source <source>", "Source / lane stamp", "cli").option("--confidence <n>", "Confidence 0..1", "1.0").action(async (opts, cmd) => {
     const cfg = resolveConfig(cmd.optsWithGlobals());
     const unfiled = String(opts.ownerType).toLowerCase() === "unfiled";
@@ -363,7 +491,9 @@ function registerMemory(program2) {
         }
       });
     });
-    emit(data, cmd.optsWithGlobals().json);
+    const titlePart = opts.title ? ` ${style.dim(`"${opts.title}"`)}` : "";
+    const urlPart = data.url ? ` ${style.dim("\u2192")} ${publicUrl(data.url)}` : "";
+    emitAction(`created memory ${style.bold(data.id)}${titlePart}${urlPart}`, data, cmd.optsWithGlobals().json);
   });
   memory.command("get <memoryId>").description("Fetch a memory by id (GET /memories/{memoryId})").action(async (memoryId, _opts, cmd) => {
     const cfg = resolveConfig(cmd.optsWithGlobals());
@@ -398,6 +528,13 @@ function registerMemory(program2) {
 // src/commands/worklog.ts
 function registerWorklog(program2) {
   const worklog = program2.command("worklog").description("Append to the daily work log");
+  worklog.addHelpText(
+    "after",
+    `
+Examples:
+  $ sechroom worklog append --text "shipped CLI help + onboarding scope; PR #1430"
+  $ sechroom worklog append --text "smoke passed" --source claude-code-chris --title "CLI smoke"`
+  );
   worklog.command("append").description("Append a work-log entry (POST /operator-surface/work-log/append)").requiredOption("--text <text>", "Entry body (short bullets / pointers) \u2014 the bullet").option("--source <source>", "Lane stamp (e.g. claude-code-chris) \u2014 laneId", "cli").option("--workspace <workspaceId>", "Target work-log workspace (default: caller's daily log)").option("--title <title>", "Optional entry title").action(async (opts, cmd) => {
     const cfg = resolveConfig(cmd.optsWithGlobals());
     const data = await runApi("Appending work-log entry", async () => {
@@ -411,7 +548,7 @@ function registerWorklog(program2) {
         }
       });
     });
-    emit(data, cmd.optsWithGlobals().json);
+    emitAction(`appended work-log entry ${style.bold(data.memoryId)}`, data, cmd.optsWithGlobals().json);
   });
 }
 
@@ -419,6 +556,14 @@ function registerWorklog(program2) {
 function registerLookup(program2) {
   program2.command("lookup <id>").description(
     "Resolve a sechroom id to its kind, title, and view URL (mem_\u2026/wsp_\u2026/prj_\u2026, unprefixed, or sechroom:<id>)"
+  ).addHelpText(
+    "after",
+    `
+Examples:
+  $ sechroom lookup mem_XXXX             a memory -> kind / title / view URL
+  $ sechroom lookup wsp_XXXX             a workspace
+  $ sechroom lookup sechroom:mem_XXXX    namespaced / portable form also resolves
+  $ sechroom lookup mem_XXXX --json`
   ).action(async (id, _opts, cmd) => {
     const cfg = resolveConfig(cmd.optsWithGlobals());
     const data = await runApi(`Resolving ${id}`, async () => {
@@ -436,7 +581,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 = {
@@ -538,7 +683,7 @@ async function createOverride(cfg, template, personalWorkspaceId) {
 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 {
@@ -634,7 +779,7 @@ async function applyClient(cfg, setup, target, opts) {
 // src/setup/clients.ts
 import { existsSync as existsSync3 } from "fs";
 import { homedir as homedir2 } from "os";
-import { dirname as dirname2, join as join2 } from "path";
+import { dirname as dirname3, join as join2 } from "path";
 function claudeDesktopConfigPath(home) {
   switch (process.platform) {
     case "darwin":
@@ -680,7 +825,7 @@ function detectInstalledClients(cwd) {
   const home = homedir2();
   const detected = [];
   if (existsSync3(join2(home, ".claude"))) detected.push("claude-code");
-  if (existsSync3(dirname2(claudeDesktopConfigPath(home)))) detected.push("claude-desktop");
+  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;
@@ -741,7 +886,16 @@ ${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).option("--copy", "make a personal copy of the agent instructions you can edit (default: prompt on a TTY, else skip)").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)").addHelpText(
+    "after",
+    `
+Examples:
+  $ sechroom init                       Claude Code (default): ./.mcp.json + ./CLAUDE.md
+  $ sechroom init --client all          claude-code, claude-desktop, codex, cursor
+  $ sechroom init --client codex,cursor
+  $ sechroom init --mcp-only            just the MCP config (skip agent files)
+  $ sechroom init --dry-run --json      preview the writes, change nothing`
+  ).action(async (opts, cmd) => {
     const cfg = resolveConfig(cmd.optsWithGlobals());
     const setup = await withSpinner("Fetching setup descriptors", () => fetchSetup(cfg));
     const targets = clientTargets(process.cwd());
@@ -823,11 +977,12 @@ function systemTimezone() {
     return "UTC";
   }
 }
-async function ensureConfig(g, yes) {
+async function ensureConfig(g, opts) {
   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) {
+  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) {
     baseUrl = await promptText("Sechroom API base URL?", baseUrl);
     tenant = await promptText("Tenant id?", tenant || void 0);
   }
@@ -837,7 +992,26 @@ async function ensureConfig(g, yes) {
       "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 });
+  let storeLocal = Boolean(opts.local);
+  if (!opts.local && canPrompt() && !opts.yes) {
+    storeLocal = await promptSelect(
+      "Where should this tenant + base URL be saved?",
+      [
+        { label: "Globally", value: "global", hint: "all projects on this machine" },
+        { label: "This directory", value: "local", hint: ".sechroom.json \u2014 project + subdirs" }
+      ],
+      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)
+`);
+  } else {
+    writePersisted({ baseUrl, tenant });
+    if (!opts.json) process.stderr.write(`${ok("\u2713")} config saved globally (~/.config/sechroom/config.json)
+`);
+  }
   return { baseUrl, tenant, clientId: persisted.clientId };
 }
 async function ensureAuth(cfg, yes) {
@@ -891,21 +1065,45 @@ Available clients: ${ALL_CLIENT_KEYS.join(", ")}
   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) => {
+  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(
+    "after",
+    `
+Examples:
+  $ sechroom onboard                    guided, interactive (asks where to save config + how to wire)
+  $ 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 --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);
+    const cfg = await ensureConfig(g, { yes, json, local: Boolean(opts.local) });
     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}
+      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})
 ` : `timezone not set \u2014 ${tz.note}
 `;
       process.stderr.write(line);
     }
+    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);
+        return;
+      }
+      process.stdout.write(
+        `
+${style.bold("Done.")} The CLI is configured for ${style.cyan(cfg.tenant)} \u2014 no AI-client files written.
+Try: ${style.cyan('sechroom memory search "..."')}  or  ${style.cyan("sechroom --help")}
+`
+      );
+      return;
+    }
     const keys = await chooseClients(opts.client, yes, process.cwd());
     const setup = await withSpinner("Fetching setup descriptors", () => fetchSetup(cfg));
     const targets = clientTargets(process.cwd());
@@ -913,12 +1111,13 @@ function registerOnboard(program2) {
     if (!dryRun) {
       await maybeOfferCopies(cfg, setup, targets, keys, personalWorkspaceId, copyChoice(opts));
     }
+    const writeMcp = wire === "full";
     const result = [];
     for (const key of keys) {
       const target = targets[key];
       const actions = await applyClient(cfg, setup, target, {
         dryRun,
-        mcp: true,
+        mcp: writeMcp,
         agentFiles: true,
         personalWorkspaceId
       });
@@ -926,14 +1125,33 @@ function registerOnboard(program2) {
       if (!json) printActions(target, actions);
     }
     if (json) {
-      emit({ dryRun, baseUrl: cfg.baseUrl, tenant: cfg.tenant, timezone: tz, clients: result }, true);
+      emit({ dryRun, baseUrl: cfg.baseUrl, tenant: cfg.tenant, timezone: tz, wire, 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"
+      dryRun ? "\n(dry run \u2014 nothing written)\n" : 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).
+`
     );
   });
 }
+async function chooseWire(opts, yes) {
+  if (opts.cliOnly) return "cli-only";
+  if (canPrompt() && !yes) {
+    return promptSelect(
+      "How should I set up Sechroom in this project?",
+      [
+        { label: "Wire my AI client", value: "full", hint: "MCP server (.mcp.json) + agent instructions" },
+        { label: "Agent instructions only", value: "agent-only", hint: "skip MCP config" },
+        { label: "CLI only", value: "cli-only", hint: "don't write any AI-client files" }
+      ],
+      "full"
+    );
+  }
+  return opts.mcp === false ? "agent-only" : "full";
+}
 
 // src/index.ts
 function resolveVersion() {
@@ -948,17 +1166,67 @@ function resolveVersion() {
 }
 var program = new Command();
 program.name("sechroom").description("Sechroom CLI \u2014 thin generated client over the Sechroom HTTP API. An agent/human surface alongside MCP.").version(resolveVersion()).option("--base-url <url>", "API base URL (overrides config / SECHROOM_BASE_URL)").option("--tenant <tenant>", "Tenant id (required by the API; overrides config / SECHROOM_TENANT)").option("--json", "Emit compact JSON (for scripts and agents)", false);
+program.addHelpText(
+  "after",
+  `
+Examples:
+  $ sechroom onboard                              guided first-run: configure, sign in, wire this project
+  $ sechroom login                                sign in via browser (OAuth + PKCE)
+  $ sechroom config set tenant ocd                set your tenant (global)
+  $ sechroom config set --local tenant cli-smoke  pin tenant for this directory (.sechroom.json)
+  $ sechroom config show                          resolved config + which source won
+
+  $ sechroom memory create --text "a note" --title "Note" --tag idea
+  $ sechroom memory search "convention drift" --limit 5
+  $ sechroom memory get mem_XXXX
+  $ sechroom worklog append --text "shipped X; PR #123" --source claude-code-chris
+  $ sechroom lookup mem_XXXX                       resolve any id -> kind / title / view URL
+
+  $ sechroom --json memory search "auth"           compact JSON for scripts and agents
+  $ SECHROOM_TOKEN=<bearer> sechroom --json memory get mem_XXXX    headless
+
+Config precedence (high -> low): --flag  >  env (SECHROOM_*)  >  ./.sechroom.json  >  global  >  default.
+Run 'sechroom <command> --help' for command-specific examples.`
+);
 program.hook("preAction", (_thisCmd, actionCmd) => {
   setQuiet(Boolean(actionCmd.optsWithGlobals().json));
 });
-program.command("login").description("Sign in via browser (OAuth auth-code + PKCE, dynamic client registration)").action(async (_opts, cmd) => {
+program.command("login").description("Sign in via browser (OAuth auth-code + PKCE, dynamic client registration)").addHelpText(
+  "after",
+  `
+Examples:
+  $ sechroom login                                          sign in to the configured base URL + tenant
+  $ sechroom login --base-url https://staging.app.sechroom.ai/api
+  $ export SECHROOM_TOKEN=<bearer>                          headless: skip login entirely (CI / agents)`
+).action(async (_opts, cmd) => {
   const g = cmd.optsWithGlobals();
   const persisted = readPersisted();
   const baseUrl = g.baseUrl ?? process.env.SECHROOM_BASE_URL ?? persisted.baseUrl ?? "https://app.sechroom.ai/api";
   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.addHelpText(
+  "after",
+  `
+Examples:
+  $ sechroom config set baseUrl https://app.sechroom.ai/api   prod (staging: https://staging.app.sechroom.ai/api)
+  $ sechroom config set tenant ocd
+  $ sechroom config set --local tenant cli-smoke              this dir + subdirs (.sechroom.json)
+  $ 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) => {
+  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)
 `);
@@ -968,8 +1236,27 @@ 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);
@@ -977,8 +1264,8 @@ registerLookup(program);
 registerInit(program);
 registerSetup(program);
 registerOnboard(program);
-program.parseAsync().catch((err) => {
-  process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}
+program.parseAsync().catch((err2) => {
+  process.stderr.write(`error: ${err2 instanceof Error ? err2.message : String(err2)}
 `);
   process.exit(1);
 });

package/package.json

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