@konstantdotcloud/boombox 0.2.0 → 0.3.0

package/README.md

@@ -2,7 +2,7 @@
 
 CLI and MCP bridge for a tenant's Boombox VM.
 
-Boombox Cloud lives at <https://boombox.konstant.cloud>. Each tenant VM is served at `https://boombox-<tenant>.exe.xyz`. The CLI stores your tenant identity, talks to the VM, and exposes the Gary cassette runtime to Claude Desktop, Claude Code, Cursor, OpenClaw, or any MCP client.
+Boombox Cloud lives at <https://boombox.konstant.cloud>. Each tenant VM is served at `https://boombox-<tenant>.exe.xyz`. The CLI stores your tenant identity, talks to the VM, asks Gary questions, ingests files into HomeBase, runs and shares cassettes, and exposes the Gary cassette runtime to Claude Desktop, Claude Code, Cursor, or any MCP client.
 
 ## Install
 
@@ -10,45 +10,100 @@ Boombox Cloud lives at <https://boombox.konstant.cloud>. Each tenant VM is serve
 curl -fsSL https://boombox.konstant.cloud/install/boombox.sh | sh
 ```
 
-The installer installs `@konstantdotcloud/boombox` and then tells you to run `boombox login`.
+The installer installs `@konstantdotcloud/boombox` and then tells you to run `boombox login`. (Or run it ad hoc with `npx @konstantdotcloud/boombox <command>`.)
 
 ## Quickstart
 
 ```bash
-boombox login       # browser sign-in via boombox.konstant.cloud; writes ~/.boombox/config.toml
-boombox whoami      # verifies tenant, user, VM URL, and key expiry
-boombox admin       # opens the VM admin UI through a short-lived cloud grant
-boombox run bd_pre_meeting_brief --input meeting_uid=sample --input organizer=user@example.com --input attendees='["user@example.com"]' --input start_time=2026-06-02T15:00:00Z --input summary=Sample
+boombox login                       # browser sign-in via boombox.konstant.cloud; writes ~/.boombox/config.toml
+boombox whoami                      # verifies tenant, user, VM URL, and key expiry
+boombox ask "what's at risk on the BNY deal this week?"   # one-shot Gary answer over your org
+boombox ingest ./transcripts        # upload local files into HomeBase so Gary can answer
+boombox run weekly_recap            # trigger a cassette and tail it to a terminal state
+boombox share <run_id>              # mint a no-login link to the run's surface
+boombox admin ui                    # open the VM admin UI through a short-lived cloud grant
 ```
 
-For MCP clients, add `boombox serve --mcp` after `boombox login` succeeds. The MCP server defaults to the `advanced` profile (cassette authoring + rack verbs included); set `GARY_MCP_PROFILE=andrew` or pass `--profile` to narrow or change it.
+For MCP clients, run `boombox serve --mcp` after `boombox login` succeeds (see [MCP client setup](#mcp-client-setup)).
 
 ## Commands
 
+### Identity & setup
 | Command | What it does |
 |-|-|
 | `boombox login [--tenant <tenant_id>]` | Browser sign-in through `boombox.konstant.cloud`; writes tenant id, VM URL, API key, and expiry to `~/.boombox/config.toml`. |
-| `boombox whoami` | Calls the VM identity endpoint and prints tenant id, user id, VM URL, key expiry, and days remaining. |
-| `boombox admin` | Requests a short-lived admin grant from Boombox Cloud and opens the tenant VM admin UI. |
-| `boombox run <cassette_name> [--input key=value ...] [--no-tail] [--json]` | Manually triggers a cassette through `/gateway/rack/run`, prompts for required missing inputs, then polls to a terminal state unless `--no-tail` is set. |
-| `boombox cassettes list` | Lists active cassettes available to the tenant. |
+| `boombox whoami` | Calls the VM identity endpoint; prints tenant id, user id, VM URL, key expiry, days remaining. |
+| `boombox enroll` | Browser enrollment flow that signs in via WorkOS, provisions an inbox + key, and writes config. |
+| `boombox init` | Manual config fallback for raw provisioned credentials. Prefer `boombox login`. |
+| `boombox doctor` | Connectivity + auth check (config, VM reachability, key validity, MCP boot). |
+
+### Ask, run, share, ingest
+| Command | What it does |
+|-|-|
+| `boombox ask <question> [--model <tier>] [--thinking <level>] [--thread <id>] [--fresh] [--json]` | One-shot question to Gary (HomeBase synthesis + artifacts). `--model`: auto\|fast\|reason\|explore\|premium\|opus. `--thinking`: off\|minimal\|low\|medium\|high\|xhigh. |
+| `boombox run <cassette_name> [--input key=value ...] [--no-tail] [--json]` | Triggers a cassette, prompts for required missing inputs, then polls to a terminal state unless `--no-tail`. |
+| `boombox share <run_id> [--ttl <days>] [--email <addr>] [--json]` | Mints a no-login, signed, expiring run-room link for a run and prints the shareable URL (default TTL 14 days). |
+| `boombox ingest <path...> [--recursive] [--json]` | Uploads local files (transcripts, docs) into HomeBase via presigned upload so Gary can answer over them. |
+
+### Cassettes
+| Command | What it does |
+|-|-|
+| `boombox cassettes list [--status published\|draft\|all]` | Lists cassettes available to the tenant. |
 | `boombox cassettes show <id> [--draft]` | Prints a cassette YAML projection. |
-| `boombox cassettes publish <draft_id> --name <name> [--version <n>] [--json]` | Publishes a dry-run-approved cassette draft to the tenant tier via `POST /gateway/cassette/publish`; renders gate rejections (e.g. `dry-run-not-green`) with fix guidance. |
-| `boombox runs list [--cassette=X] [--since=24h] [--actor=Y] [--status=completed] [--limit=20]` | Lists recent runs with run id, cassette, actor, status, duration, and start time. |
-| `boombox runs show <run_id>` | Shows one run: spec hash, inputs, step trace, delivery receipts, error summary, and replay ref. |
-| `boombox logs tail [--cassette=X]` | Tails run/step events from the VM SSE stream. |
-| `boombox artifacts open <artifact_id>` | Opens `<vm_url>/artifact/<artifact_id>` in the system browser. |
+| `boombox cassettes validate <id> [--draft] [--json]` | Runs cassette oracle readiness checks. |
+| `boombox cassettes dry-run <id> [--draft] [--json]` | Dry-runs a draft and prints verdict + blockers. No durable writes. |
+| `boombox cassettes publish <draft_id> --name <name> [--version <n>] [--json]` | Publishes a dry-run-approved draft to the tenant tier; renders gate rejections (e.g. `dry-run-not-green`) with fix guidance. |
+
+### Runs, logs, artifacts
+| Command | What it does |
+|-|-|
+| `boombox runs list [--cassette <id>] [--since 24h] [--actor <id>] [--status <s>] [--limit 20]` | Lists recent runs (run id, cassette, actor, status, duration, start). |
+| `boombox runs show <run_id>` | One run: spec hash, inputs, step trace, delivery receipts, error summary, replay ref. |
+| `boombox logs tail [--cassette <id>]` | Tails run/step events from the VM SSE stream. Ctrl+C exits cleanly. |
+| `boombox artifacts open <artifact_id>` | Opens the artifact URL in the system browser. |
+
+### Tenant MCP servers, capabilities, keys
+| Command | What it does |
+|-|-|
+| `boombox mcp add --id <server_id> --name <display> --url <url> [--transport streamable_http\|sse] [--auth-header <h>] [--secret-ref <ENV_KEY>] [--tools t1,t2]` | Registers a tenant-owned MCP server on this VM for cassettes to reference. |
+| `boombox mcp list` | Lists tenant MCP servers registered on this VM. |
+| `boombox mcp rm <server_id>` | Removes a tenant MCP server registration. |
+| `boombox mcp status <server_id> [--enable\|--disable]` | Enables or disables a tenant MCP server registration. |
+| `boombox capabilities list [--kind <k>] [--status available\|missing]` | Lists registered recipes, tools, artifact templates, prompt templates. |
 | `boombox keys list` | Lists tenant API keys visible to the current API key authority. |
-| `boombox capabilities list [--kind=recipe\|tool\|artifact_template\|prompt_template] [--status=available\|missing]` | Lists registered tenant capabilities. |
-| `boombox status` | Checks VM health, `/v2/api/info`, and the run-event stream. |
-| `boombox doctor` | Checks config, VM reachability, API-key validity, and MCP boot. |
-| `boombox init` | Manual config fallback for provisioned credentials. Most users should prefer `boombox login`. |
-| `boombox enroll` | Browser enrollment flow that can write config from a provisioning payload. |
-| `boombox serve [--mcp] [--http] [--port <port>]` | Starts stdio MCP and/or the local HTTP proxy. MCP clients should use `--mcp`. |
-| `boombox reload` | Sends SIGHUP to a running local `boombox serve`. |
-| `boombox restart` | Stops and respawns local `boombox serve`. |
-| `boombox stop` | Stops a running local `boombox serve`. |
-| `boombox upgrade` | Self-update through npm. |
+
+### Serve (MCP / HTTP) & process control
+| Command | What it does |
+|-|-|
+| `boombox serve [--mcp] [--http] [--port <port>] [--profile default\|advanced\|operator]` | Boots the stdio MCP server (`--mcp`) and/or the local HTTP proxy (`--http`). |
+| `boombox status` | Checks VM health, `/v2/api/info`, and run-event stream reachability. |
+| `boombox reload` | SIGHUP a running `boombox serve` to re-read config. |
+| `boombox restart [--no-detach] [--timeout <ms>]` | Stops and respawns `boombox serve` (detached by default). |
+| `boombox stop [--timeout <ms>]` | Stops a running `boombox serve`. |
+| `boombox upgrade [--check] [--force]` | Self-update through the npm registry. |
+
+### Admin (super-admin)
+| Command | What it does |
+|-|-|
+| `boombox admin ui [--cloud-url <url>]` | Requests a short-lived admin grant and opens the tenant VM admin UI. |
+| `boombox admin provision <tenant> [--name <n>] [--company <c>] [--ceo <c>] [--control-plane <url>] [--admin-key <key>] [--json]` | Super-admin: provision a tenant (doc + keypair + VM) via the control plane. Needs `ADMIN_API_KEY` (flag or `BOOMBOX_ADMIN_API_KEY`). |
+
+## MCP client setup
+
+### Claude Desktop / Claude Code / Cursor
+
+```json
+{
+  "mcpServers": {
+    "boombox": {
+      "command": "boombox",
+      "args": ["serve", "--mcp"]
+    }
+  }
+}
+```
+
+After saving, restart your client. The MCP profile is selected with `--profile` (or `GARY_MCP_PROFILE`): `default` exposes the chat-parity tools (`ask_gary`, `list_threads`, `clear_thread`, `artifact_fetch`, `gary_status`); `advanced` adds cassette authoring + rack verbs; `operator` adds admin verbs.
 
 ## Config file
 
@@ -71,63 +126,27 @@ mcp_enabled = true
 [admin]
 ```
 
-`runtime.vm_url` is the preferred target. If it is present, CLI commands talk to the tenant VM. `gateway_url` remains the shared cloud fallback and login/onboarding origin.
+`runtime.vm_url` is the preferred target. If present, CLI commands talk to the tenant VM; `gateway_url` remains the shared cloud fallback and login/onboarding origin.
 
 The file is created with mode `600`. Override the location with `BOOMBOX_HOME=/some/dir` (config lives at `$BOOMBOX_HOME/config.toml`).
 
-## MCP client setup
-
-### Claude Desktop / Claude Code / Cursor / OpenClaw
-
-```json
-{
-  "mcpServers": {
-    "boombox": {
-      "command": "boombox",
-      "args": ["serve", "--mcp"]
-    }
-  }
-}
-```
-
-After saving, restart your client. The default MCP profile exposes the chat-parity tools: `ask_gary`, `list_threads`, `clear_thread`, `artifact_fetch`, and `gary_status`. Advanced/operator profiles can expose rack, prompt, cassette, and admin verbs when explicitly enabled.
-
-## Ops route contracts
-
-The ops CLI uses direct HTTP service routes with `Authorization: Bearer <tenant_api_key>`; it does not speak MCP wire format.
-
-| CLI command | Primary route contract |
-|-|-|
-| `whoami` | `GET /v2/api/me`. |
-| `status` | `GET /health`, `GET /v2/api/info`, `GET /admin/runs/stream` (fallback: `/api/admin/runs/stream`). |
-| `runs list` | `GET /api/admin/runs` with `cassette`, `since`, `actor`, `status`, `limit`; fallback: `GET /api/admin/cassettes/runs`. |
-| `runs show` | `GET /api/admin/runs/:run_id`; fallback: `GET /api/admin/cassettes/runs/:run_id/replay`. |
-| `logs tail` | `GET /admin/runs/stream` SSE; fallback: `GET /api/admin/runs/stream`. |
-| `run` | `GET /api/admin/cassettes/:id` for required input metadata, `POST /gateway/rack/run` to trigger, then `GET /api/admin/runs/:run_id` or replay fallback to poll. |
-| `cassettes list` | `GET /api/admin/cassettes`; the VM route currently defaults unknown status filters to `active`. |
-| `cassettes show` | `GET /api/admin/cassettes/:id/yaml?draft=true`; falls back to `GET /api/admin/cassettes/:id` if YAML is not wired. |
-| `keys list` | `GET /api/admin/keys`. |
-| `capabilities list` | `GET /api/admin/capabilities`. |
-
 ## Local HTTP server
 
 When `boombox serve --http` is running, your browser hits Hono on `localhost:8787`:
 
-- `GET http://localhost:8787/` → the bundled Boombox UI when `packages/boombox/ui/dist` exists.
-- `GET http://localhost:8787/api/...` → proxied to the configured VM/cloud gateway with `Authorization: Bearer <api_key>` injected. The browser never sees your API key.
-- `GET http://localhost:8787/gateway/...` → rewritten to `/api/gateway/...` upstream.
-- `GET http://localhost:8787/healthz` → 200 if config loaded.
+- `GET /` → the bundled Boombox UI when `ui/dist` exists.
+- `GET /api/...` → proxied to the configured VM/cloud gateway with `Authorization: Bearer <api_key>` injected. The browser never sees your API key.
+- `GET /gateway/...` → rewritten to `/api/gateway/...` upstream.
+- `GET /healthz` → 200 if config loaded.
 
-If `ui/dist/` is missing, `/` and SPA routes return `503 ui_not_built`; `/healthz` and `/api/*` still work. Run `cd packages/boombox/ui && npm run build` to populate `ui/dist/`.
-
-CORS is locked to `localhost`/`127.0.0.1` origins.
+If `ui/dist/` is missing, `/` and SPA routes return `503 ui_not_built`; `/healthz` and `/api/*` still work. CORS is locked to `localhost`/`127.0.0.1` origins.
 
 ## Troubleshooting
 
 - **`boombox doctor` says "config not found"** — run `boombox login`; use `boombox init` only when Konstant gave you raw VM credentials.
-- **`whoami` returns 401/403** — the API key is invalid, expired, or lacks authority. Run `boombox login` to refresh it.
+- **`whoami` returns 401/403** — the API key is invalid, expired, or lacks authority. Run `boombox login` to refresh.
 - **`gateway: unreachable`** — verify `runtime.vm_url` in `~/.boombox/config.toml`; the expected VM domain is `https://boombox-<tenant>.exe.xyz`.
-- **Run stays queued** — the VM may not have an Inngest/worker dispatcher wired for that cassette. Check `boombox runs show <run_id>` and the VM admin run trace.
+- **Run stays queued** — check `boombox runs show <run_id>` and the VM admin run trace.
 - **Port 8787 already in use** — pass `--port 9000` to `boombox serve --http`, or set `http_port` in config.
 - **MCP boot test fails** — make sure your Node version is `>= 20`.
 
@@ -135,10 +154,6 @@ CORS is locked to `localhost`/`127.0.0.1` origins.
 
 The CLI stores config and API keys locally; it does not store run output, telemetry, or tenant data on disk. Runtime data, replay packets, artifacts, and events live in the tenant VM/Mongo path configured for that tenant. LLM calls route through the tenant's configured provider path.
 
-## Versioning
-
-`0.1.0` — V1 ships with the default MCP tools plus CLI commands for login, VM status, cassette runs, run inspection, artifacts, keys, capabilities, admin, and lifecycle control. Run `boombox upgrade` to pull updates.
-
 ## License
 
 UNLICENSED — internal Konstant package.