@sechroom/cli 2026.6.1 → 2026.6.2-rc.2ab57437

package/README.md

@@ -54,15 +54,27 @@ npm i -g @sechroom/cli@next
 npx @sechroom/cli login
 ```
 
+## Develop
+
+This is a **pnpm workspace member** (`frontend/apps/cli`). Install from the repo root
+(`pnpm install`), then run scripts via the filter (or `pnpm <script>` from this dir):
+
+```bash
+pnpm --filter @sechroom/cli run gen          # regenerate the typed client
+pnpm --filter @sechroom/cli run check-types
+pnpm --filter @sechroom/cli run build
+pnpm --filter @sechroom/cli run dev -- --help # tsx, no build
+```
+
 ## Generate the client (once, and after any API change)
 
 ```bash
 # defaults to https://app.sechroom.ai/api/openapi/v1.json
-npm run gen
-SECHROOM_OPENAPI_URL=https://<host>/api/openapi/v1.json npm run gen   # other envs
+pnpm --filter @sechroom/cli run gen
+SECHROOM_OPENAPI_URL=https://<host>/api/openapi/v1.json pnpm --filter @sechroom/cli run gen   # other envs
 ```
 
-`npm run gen` overwrites `src/generated/api.d.ts`. The **real generated types are
+`gen` overwrites `src/generated/api.d.ts`. The **real generated types are
 committed** (regenerated from the live prod spec) so builds are hermetic — no
 live-API dependency at compile time; re-run `gen` after any API change. Generating
 against the live schema is what caught the original placeholder's shape drift
@@ -82,17 +94,119 @@ sechroom memory get mem_XXXX
 sechroom memory search "convention lifecycle drift" --limit 5
 sechroom worklog append --text "shipped CLI skeleton; pointers: ..." --source claude-code-chris
 
+sechroom lookup mem_XXXX                 # what is this id? -> kind / title / view URL
+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
 
 ```
@@ -101,10 +215,23 @@ src/
   auth.ts             OAuth auth-code+PKCE loopback (fixed-port DCR) + refresh + cache
   client.ts           openapi-fetch client (auth + tenant middleware) + emit/fail
   config.ts           base-url / tenant / token resolution + persistence
-  generated/api.d.ts  typed client — `npm run gen`; real types committed (hermetic)
+  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
@@ -123,9 +250,9 @@ Public **npmjs** under the `@sechroom` org is the host; **TeamCity** is the
 publisher (build config `Sechroom_PublishCli`). The full pipeline — steps,
 parameters, npm auth, provisioning, and how to run a publish — is documented in
 [`ci/PUBLISHING.md`](./ci/PUBLISHING.md). In short: a manual-trigger config runs
-`npm ci → gen → typecheck → build → publish` in a `node:20` container, authed by
-a masked `NPM_TOKEN` param; `next` stamps a per-build prerelease, `latest` ships
-`BASE_CLI_VERSION`.
+`pnpm install → gen → check-types → build → publish` (filtered to `@sechroom/cli`)
+in a `node:20` container, authed by a masked `NPM_TOKEN` param. Every publish gets a
+fresh calendar version `YYYY.M.<n>` (own counter); the dist-tag separates next/latest.
 
 Why public npmjs: the CLI is customer-facing, and `npx @sechroom/cli` must work
 with zero `.npmrc`/token on the customer side. GitHub Packages or a private