@sechroom/cli 2026.6.6 → 2026.6.8

package/README.md

@@ -100,6 +100,13 @@ 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
@@ -137,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:
@@ -144,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

@@ -173,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);
@@ -277,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);
 }
@@ -302,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
@@ -344,15 +360,88 @@ 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 promptMultiSelect(question, choices, preselected = []) {
+  if (choices.length === 0) return [];
+  const pre = (v) => preselected.includes(v);
+  const preValues = () => choices.filter((c) => pre(c.value)).map((c) => c.value);
+  if (!canPrompt()) return preValues();
+  const { createInterface } = await import("readline");
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    process.stderr.write(
+      `${style.bold(question)} ${style.dim("(numbers or 'all', comma-separated; Enter keeps \u25C9)")}
+`
+    );
+    choices.forEach((c, i) => {
+      const box = pre(c.value) ? style.cyan("\u25C9") : "\u25CB";
+      const hint = c.hint ? ` ${style.dim(`\u2014 ${c.hint}`)}` : "";
+      process.stderr.write(`  ${box} ${style.bold(String(i + 1))}. ${c.label}${hint}
+`);
+    });
+    const answer = await new Promise((resolve) => {
+      rl.question(`Select ${style.dim("[Enter = \u25C9]")} `, resolve);
+    });
+    const trimmed = answer.trim().toLowerCase();
+    if (!trimmed) return preValues();
+    if (trimmed === "all") return choices.map((c) => c.value);
+    const picks = [];
+    for (const tok of trimmed.split(",").map((t) => t.trim()).filter(Boolean)) {
+      const n = Number(tok);
+      if (Number.isInteger(n) && n >= 1 && n <= choices.length) {
+        picks.push(choices[n - 1].value);
+        continue;
+      }
+      const byLabel = choices.find((c) => c.label.toLowerCase().startsWith(tok));
+      if (byLabel) picks.push(byLabel.value);
+    }
+    const uniq = [...new Set(picks)];
+    return uniq.length > 0 ? uniq : preValues();
+  } 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;
   }
 }
 
@@ -376,14 +465,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();
@@ -402,6 +502,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";
@@ -421,7 +531,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());
@@ -456,6 +568,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 () => {
@@ -469,7 +588,7 @@ function registerWorklog(program2) {
         }
       });
     });
-    emit(data, cmd.optsWithGlobals().json);
+    emitAction(`appended work-log entry ${style.bold(data.memoryId)}`, data, cmd.optsWithGlobals().json);
   });
 }
 
@@ -477,6 +596,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 () => {
@@ -799,7 +926,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());
@@ -881,11 +1017,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);
   }
@@ -895,7 +1032,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) {
@@ -937,33 +1093,59 @@ async function ensureTimezone(cfg, opts) {
 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 preselected = detected.length > 0 ? detected : [DEFAULT_CLIENT_KEY];
+  if (!canPrompt() || yes) return preselected;
+  const picks = await promptMultiSelect(
+    "Which AI clients should I wire?",
+    ALL_CLIENT_KEYS.map((k) => ({
+      label: k,
+      value: k,
+      hint: detected.includes(k) ? "detected" : void 0
+    })),
+    preselected
   );
-  const answer = await promptText("Which to wire? (comma-separated, or 'all')", fallback);
-  return resolveClientKeys(answer);
+  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("--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());
@@ -971,12 +1153,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
       });
@@ -984,14 +1167,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() {
@@ -1006,16 +1208,55 @@ 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.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)) {
@@ -1065,8 +1306,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.6",
+  "version": "2026.6.8",
   "description": "Sechroom CLI — a thin, generated client over the Sechroom HTTP API. An agent/human surface alongside MCP.",
   "type": "module",
   "license": "UNLICENSED",