@sechroom/cli 2026.6.2 → 2026.6.3-rc.f0dc3f51

package/README.md

@@ -100,14 +100,113 @@ 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
-export SECHROOM_TOKEN="<jwt from /auth/dev/token>"
+export SECHROOM_TOKEN="<bearer: a PAT or dev-token JWT>"
 export SECHROOM_TENANT=ocd
 sechroom --json memory search "rate limiting" 
 ```
 
+## Command surface (MCP parity)
+
+The CLI mirrors the sechroom MCP tool surface — every command is a thin wrapper over the same HTTP endpoint the matching MCP tool shims, so enforcement (`[TenantPermission]`) is identical. Run `sechroom <group> --help` for the subcommands + examples.
+
+| Group | Covers |
+|---|---|
+| `memory` | create / get / search · edit-text(+batch) · archive / restore / move · versions / revert · list-archived · owners / tags / types · sum-tokens · similar · by-url |
+| `relationship` | create / list / delete · suggest · `suggestion` get / accept / reject / defer |
+| `workspace` | create / list / get · rename / describe / move · archive / restore · feed |
+| `project` | create / list / get · rename / describe / move · status · victory-conditions · archive / restore |
+| `filing` | suggestions / get · preview · accept / reject / defer / edit-and-accept |
+| `continuity` | snapshot-create / -get · snapshots · resume-me / resume-lane · changed-since · load-set · grant / revoke-grant |
+| `id` | next / peek (FR-_/D-_ sequence allocation) |
+| `account` | profile / set-profile · feed · reviews / review-get / review-accept · lookup-batch |
+| `chat` | send · messages · replies · stop-tracking (Slack / Discord, via `--surface`) |
+| `worklog` · `lookup` | append · resolve any id |
+
+Notes on deliberate gaps (API-rooted, not CLI):
+- **No `memory delete`** — the API exposes no hard DELETE; `memory archive` is the soft-delete path.
+- **`memory revert`** needs `--text` + `--content` — the revert endpoint doesn't reconstruct a version's body from its number; pull them from `memory versions` / `memory get` first.
+
+## Onboarding (`init` / `setup`)
+
+`sechroom init` wires a project for sechroom by rendering the server's
+operator-surface setup descriptors (`GET /operator-surface/setup`, tenant-scoped
+— the aggregator URL is baked in) into local AI-client config + agent instruction
+files. **Idempotent — merges/appends, never clobbers** (JSON `mcpServers` merge;
+Codex TOML table replace; instruction files use a managed marker block).
+
+```bash
+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:
+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 |
+|---|---|---|
+| `claude-code` | `./.mcp.json` | `./CLAUDE.md` |
+| `claude-desktop` | `claude_desktop_config.json` (OS path) | `~/.claude/CLAUDE.md` |
+| `codex` | `~/.codex/config.toml` | `./AGENTS.md` |
+| `cursor` | `./.cursor/mcp.json` | `./AGENTS.md` |
+
+The instruction-file step pulls the role template the SEM Starter bundle ships
+(via the descriptor's tag-query artifact). If that bundle isn't installed in the
+tenant, the step **skips gracefully** with a note (MCP config still gets written).
+
 ## Layout
 
 ```
@@ -118,9 +217,21 @@ src/
   config.ts           base-url / tenant / token resolution + persistence
   generated/api.d.ts  typed client — `pnpm run gen`; real types committed (hermetic)
   commands/
-    memory.ts         create / get / search
+    memory.ts         create / get / search / edit / archive / move / versions / …
+    relationships.ts  relationships + relationship-suggestions
+    workspace.ts      workspace CRUD + feed
+    project.ts        project CRUD + status / victory-conditions
+    filing.ts         filing-suggestion review (accept / reject / defer / edit-and-accept)
+    continuity.ts     snapshots + resume / grant
+    account.ts        id next/peek + profile / feed / reviews / lookup-batch
+    chat.ts           read Slack / Discord messages + replies
     worklog.ts        append
     lookup.ts         resolve any id (mem_…/unprefixed/sechroom:<id>) -> kind/title/url
+    setup.ts          init + setup mcp/agent-files
+  setup/
+    operator-surface.ts  fetch GET /operator-surface/setup + resolve template artifacts
+    clients.ts           client→(surface, local paths, format) registry
+    apply.ts             writers: mcp json merge / codex toml / instruction marker block
 ```
 
 ## Remaining before ship