docs(roadmap,cli): close Phase 2 + cut CLI v0.1.1; plan Phase 2.5/2.6

README.md

@@ -43,6 +43,31 @@ machine unless you choose it.
 - **Per-node cost waterfall** — token and dollar attribution per node, per model.
 - **Local-first, zero-install posture** — BYOK, OS keychain, no sign-up in Phase 1.
 
+## Getting started
+
+The CLI is the first usable surface. It ships as a single npm binary — `npm install -g relavium`
+(the public npm publish is the final maintainer step of the **v0.1.1** release; until it lands, build from
+source per [local dev setup](docs/runbooks/local-dev-setup.md)). Then **start as an agent → ship the workflow
+→ own every run**:
+
+```bash
+# 1. Point Relavium at a provider — your key goes to the OS keychain, never a file
+relavium provider add anthropic
+echo "$ANTHROPIC_API_KEY" | relavium provider set-key anthropic   # the key is read from stdin, never argv
+
+# 2. Start as an agent — a multi-turn session in your terminal
+relavium chat
+#    …converse until a flow proves itself, then run /export inside the REPL
+#    to ship the session to a git-committable .relavium.yaml
+
+# 3. Own every run — execute the workflow and stream every event (CI-friendly with --json)
+relavium run ./my-workflow.relavium.yaml --json
+```
+
+Prefer to author directly? `relavium create` scaffolds an agent or a minimal single-agent workflow, and
+`relavium import` / `relavium export` move them between projects. The full surface is the
+[CLI command reference](docs/reference/cli/commands.md).
+
 ## Architecture
 
 ```mermaid
@@ -92,7 +117,7 @@ One engine, three modes behind the one `LLMProvider` seam:
 **Phase 1 — Engine and LLM is complete** (2026-06-21): the engine runs end-to-end on
 local-first BYOK — workflow parsing, DAG execution, live streaming, checkpoint/resume,
 multi-provider failover, cost governance, and multimodal media I/O. **Phase 2 (the CLI) is
-underway** — the CLI skeleton, config resolution, `relavium run` (wired to the engine), its
+feature-complete** — the CLI skeleton, config resolution, `relavium run` (wired to the engine), its
 `--json` CI machine-output contract, the engine regression harness, durable local run history, the
 provider/key commands (API keys in the OS keychain), the live `ink` streaming TUI, the human-gate
 prompt + out-of-band `relavium gate` resume, the read commands (`list` / `logs` / `status` / `gate list`)
@@ -104,7 +129,10 @@ go/no-go exit criteria now hold). The first additive lanes have since landed too
 one-shot `agent run` with deterministic offline `--fixture` replay (the first user-facing `AgentSession`
 surface); and the **inbound MCP client** — agents consume external MCP servers' tools over stdio + the
 `http`/`sse`/`websocket` network transports (behind an SSRF floor and isolated keychain-resolved secrets),
-proven by a real-spawn end-to-end test. For live status and the full roadmap, see
+proven by a real-spawn end-to-end test; and the **YAML-authoring lifecycle** — `relavium create` (a wizard
+scaffolding an agent or a minimal single-agent workflow), `import`, and a share-safe `export` (re-serialized
+from the validated AST, no provider key by construction). With every in-phase workstream merged, the CLI is
+cut as **v0.1.1** (the public npm publish is the pending final maintainer step). For live status and the full roadmap, see
 [docs/roadmap/current.md](docs/roadmap/current.md) and the
 [roadmap](docs/roadmap/README.md).
 

apps/cli/CHANGELOG.md

@@ -0,0 +1,76 @@
+# Changelog
+
+All notable changes to the `relavium` CLI are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this project is pre-1.0, so
+minor and patch bumps both land additively under a `0.1.x` line. The publish flow is
+[release-a-surface.md](../../docs/runbooks/release-a-surface.md) (tag `v<version>` →
+the `Release CLI` workflow: pack → cross-OS smoke → publish).
+
+## [0.1.1] — 2026-06-28
+
+Everything merged since the `v0.1.0` spine — the three additive lanes and the authoring
+lifecycle — with the in-phase CLI now feature-complete (Phase 2 workstreams 2.A–2.S).
+
+### Added
+
+- **Authoring lifecycle (`create` / `import` / `export`)** (2.J, PR #58). `relavium create`
+  is a `@clack/prompts` wizard that scaffolds either an **agent** (`.agent.yaml`) or a
+  **minimal single-agent workflow** (`input → agent → output`, `.relavium.yaml`), validated
+  against the kind-appropriate `@relavium/shared` schema before write. `relavium import <path>`
+  copies an external workflow/agent into the project after schema validation; `relavium
+  export <id>` writes a portable, share-safe copy **re-serialized from the validated AST**
+  (canonical, comment-free; no provider key by construction). Ids are unique **project-globally**
+  across both catalogs (a same-kind clash needs `--force`; a cross-kind clash is always
+  rejected), so a bare `<id>` stays unambiguous for `export` / `run`.
+- **Agent-first chat family** (2.M–2.Q, PR #54/#55). `relavium chat` — an interactive
+  multi-turn REPL over `AgentSession` with streaming tokens, tool-call annotations, and the
+  FS-scope tier + command allowlist honored (`/exit` returns exit code `4`); `relavium
+  chat-resume <sessionId>`, `relavium chat-list`, and `relavium chat-export` (+ the in-REPL
+  `/export`) to ship a session to a `.relavium.yaml` scaffold; a headless `relavium chat --json`
+  `SessionEvent` stream; and a one-shot `relavium agent run <agent>` with a `--fixture` cassette
+  for deterministic offline replay.
+- **Inbound MCP client** (2.R, PR #56/#57). Agents consume external MCP servers' tools across
+  `chat`, `run`, and `agent run` via the SDK-fenced `@relavium/mcp` package — `stdio` plus the
+  `http` / `sse` / `websocket` network transports behind an SSRF pre-connect floor + a per-server
+  `allow_local_endpoint` opt-in, with server credentials resolved from an isolated `mcp-secret:*`
+  keychain namespace and injected only into the spawn-time `env`. Discovered tools surface under
+  the `mcp_{server}_{tool}` namespace; a real-spawn end-to-end test proves the round-trip.
+- **Media host-wiring** (2.S, PR #52). A generative media-output fixture runs end-to-end on the
+  CLI — host `resolveMediaSurface` routing, content-addressed `MediaStore` de-inline to a
+  `media://` handle, the SSRF-validated `EgressCapability.fetch` egress, a containment-checked
+  `save_to` write port, and the produced-media render surface in both the TUI and `--json` paths.
+
+### Changed
+
+- `relavium export` / `import` re-serialize from the validated AST: the canonical form drops
+  authored comments and emits cwd-relative paths in both human and `--json` output (no absolute
+  filesystem path in any message or record).
+- The `create` wizard requires an interactive terminal on **both** ends (TTY stdout + TTY stdin);
+  it fails loud (exit `2`) under `--json` or a piped stream rather than hanging.
+
+## [0.1.0] — 2026-06-24
+
+The first published CLI — the engine-proving spine and the run/read surface.
+
+### Added
+
+- The `commander.js` CLI skeleton + process contract (output-mode detection, the deterministic
+  exit-code map, global flags) (2.A) and two-level config resolution (`~/.relavium/` → project
+  `.relavium/`) (2.B).
+- `relavium run` wired to `@relavium/core` — workflow resolution, typed `--input` coercion, the
+  live event stream, SIGINT→cancel, and the terminal-event→exit-code mapping (2.D).
+- The `--json` CI machine-output contract: one `RunEvent` per line (NDJSON), pure stdout,
+  diagnostics on stderr, deterministic exit codes (2.F).
+- The `ink` streaming TUI — live per-node status, the active node's token stream, and a running
+  cost/duration footer over the same event bus as `--json` (2.E).
+- The interactive human-gate prompt + the out-of-band `relavium gate <runId>` cross-process
+  resume (2.G).
+- Durable local run history via `@relavium/db`, powering the read commands `list` / `logs` /
+  `status` / `gate list` (2.H, 2.I).
+- `relavium provider` commands storing API keys in the OS keychain via `@napi-rs/keyring`, with a
+  `RELAVIUM_<PROVIDER>_API_KEY` env-var fallback for headless/CI hosts (2.C).
+- The engine regression harness adopted as the CI gate (2.K), and packaging + cross-OS install
+  verification — the `tsup` engine-inlined ESM bundle published as `npm i -g relavium` (2.L).
+
+[0.1.1]: https://github.com/HodeTech/Relavium/releases/tag/v0.1.1
+[0.1.0]: https://github.com/HodeTech/Relavium/releases/tag/v0.1.0

apps/cli/README.md

@@ -1,54 +1,136 @@
 # relavium
 
-> Run agent workflows from your terminal — a product of [HodeTech](https://github.com/HodeTech).
+![Node](https://img.shields.io/badge/node-%E2%89%A5%2020.12-339933?logo=nodedotjs&logoColor=white)
+![Local-first](https://img.shields.io/badge/local--first-BYOK-0aa)
+![License](https://img.shields.io/badge/license-proprietary-555)
 
-`relavium` is the command-line surface of the [Relavium](https://github.com/HodeTech/Relavium)
-local-first AI agent platform. It runs git-committable `.relavium.yaml` workflows on the same
-pure-TypeScript engine as the desktop and VS Code surfaces — every step debuggable, every token and
-dollar tracked, nothing leaving your machine unless you choose it.
+> **Start as an agent. Ship the workflow. Own every run.**
+
+`relavium` is the command-line surface of **[Relavium](https://github.com/HodeTech/Relavium)** — a
+local-first, multi-model AI agent platform from **[HodeTech](https://github.com/HodeTech)**. Begin in a
+conversational **agent session** in your terminal, graduate it into a git-committable, multi-agent
+`.relavium.yaml` **workflow**, and run it anywhere — all on the same pure-TypeScript engine that powers
+the Relavium desktop and VS Code surfaces. Every step is debuggable, every token and dollar tracked, and
+nothing leaves your machine unless you choose it.
 
 ## Install
 
 ```bash
 npm install -g relavium
 ```
 
-Requires **Node.js ≥ 20.12**. The package ships an engine-inlined bundle and installs prebuilt native
-binaries, so no C/C++ toolchain is needed.
+Requires **Node.js ≥ 20.12**. The package is an engine-inlined bundle that installs prebuilt native
+binaries — no C/C++ toolchain, no Python sidecar.
 
 ## Quick start
 
 ```bash
-# run a workflow, streaming live progress in the terminal
-relavium run ./workflows/code-review.relavium.yaml --input file=./src/index.ts
+# 1 · Point Relavium at a provider — your key goes to the OS keychain, never a file or argv
+relavium provider add anthropic
+echo "$ANTHROPIC_API_KEY" | relavium provider set-key anthropic
 
-# CI / scripting: a stable NDJSON RunEvent stream, deterministic exit codes
-relavium run ./workflows/code-review.relavium.yaml --input file=src/index.ts --json
+# 2 · Start as an agent — a streaming, multi-turn session in your terminal
+relavium chat
+#     …converse until a flow proves itself, then run /export inside the REPL
+#     to ship the session to a git-committable .relavium.yaml
 
-# store a provider key in the OS keychain (read from stdin, never argv)
-echo "$ANTHROPIC_API_KEY" | relavium provider set-key anthropic
+# 3 · Own every run — execute the workflow, streaming live (or --json for CI)
+relavium run ./my-workflow.relavium.yaml --input file=./src/index.ts
+relavium run ./my-workflow.relavium.yaml --json
 ```
 
+Prefer authoring directly? `relavium create` scaffolds an agent or a minimal single-agent workflow from
+an interactive wizard.
+
+## Why relavium
+
+- **One engine, every surface.** The terminal, desktop, and VS Code run the _identical_ engine — a
+  workflow behaves the same on your laptop and in CI.
+- **A chat-to-workflow continuum.** Sessions are persistent and resumable; one command — `/export` —
+  turns a proven conversation into a reviewed, committed workflow.
+- **Multi-model with fallback chains.** Route across Anthropic, OpenAI / DeepSeek, and Gemini behind one
+  seam; a run survives a provider outage by failing over (`[claude → gpt-4o → gemini]`).
+- **Local-first, keys in your OS keychain.** BYOK, no account, no telemetry — keys never touch a file, a
+  log, an argv, or `--json` output.
+- **Live _and_ scriptable.** A rich streaming TUI on a TTY; a stable NDJSON `RunEvent` stream with
+  deterministic exit codes under `--json` for CI.
+- **Extensible and multimodal.** Agents consume external **MCP** tools (stdio + `http` / `sse` /
+  `websocket`, behind an SSRF floor), and workflows generate image / audio / video **output** through the
+  same engine (media input via `read_media` is a tracked follow-up).
+
 ## Commands
 
-| Command | Purpose |
-|---|---|
-| `relavium run <workflow> [--input k=v]` | Execute a workflow; streams progress (or `--json` NDJSON). |
-| `relavium list [--agents]` | List discovered workflows (or agents) with last-run status. |
-| `relavium logs <runId>` | Replay a past run's event stream. |
-| `relavium status` | Show active/paused runs and their per-node status. |
-| `relavium gate <runId> --approve\|--reject\|--input …` | Resolve a pending human gate. |
-| `relavium gate list [<runId>]` | List pending human gates. |
-| `relavium provider <list\|add\|set-key\|remove-key\|test>` | Manage providers + API keys (OS keychain). |
+### Agent sessions
+
+| Command                                       | Purpose                                                     |
+| --------------------------------------------- | ----------------------------------------------------------- |
+| `relavium chat [--agent <ref>]`               | Start an interactive multi-turn agent session (the REPL).   |
+| `relavium chat-resume <sessionId>`            | Reload and continue a persisted session.                    |
+| `relavium chat-list`                          | List past sessions (id, agent, last activity).              |
+| `relavium chat-export <sessionId>`            | Export a session to a `.relavium.yaml` workflow scaffold.   |
+| `relavium agent run <agent> [--fixture <p>]`  | Run a single agent one-shot (prompt on **stdin**); `--fixture` replays a cassette (offline, CI-ready). |
+
+### Workflows & authoring
+
+| Command                              | Purpose                                                            |
+| ------------------------------------ | ----------------------------------------------------------------- |
+| `relavium run <workflow> [--input k=v]` | Execute a workflow — live TUI, or `--json` NDJSON for CI.       |
+| `relavium create`                    | Scaffold a new agent or a minimal workflow from a wizard.         |
+| `relavium import <path>`             | Import an external `.relavium.yaml` / `.agent.yaml` into the project. |
+| `relavium export <id>`               | Write a portable, share-safe copy (no secret material).           |
+
+### History & human gates
+
+| Command                                              | Purpose                                              |
+| ---------------------------------------------------- | ---------------------------------------------------- |
+| `relavium list [--agents]`                           | List discovered workflows (or agents) + last-run status. |
+| `relavium logs <runId>`                              | Replay a past run's event stream (raw under `--json`). |
+| `relavium status`                                    | Show active / paused runs and their per-node status. |
+| `relavium gate <runId> --approve\|--reject\|--input …` | Resolve a pending human gate.                       |
+| `relavium gate list [<runId>]`                       | List pending human gates across runs.                |
+
+### Providers & keys
+
+| Command                          | Purpose                                                     |
+| -------------------------------- | ---------------------------------------------------------- |
+| `relavium provider list`         | Registered providers and whether a key is set.             |
+| `relavium provider add <id>`     | Register a provider.                                        |
+| `relavium provider set-key <id>` | Store a key in the OS keychain (read from **stdin**).       |
+| `relavium provider remove-key <id>` | Delete a key from the keychain.                          |
+| `relavium provider test <id>`    | Verify a key with a minimal live request.                  |
+
+The global flags `--json`, `--cwd`, `--config`, `--no-color`, `--verbose` (`-v`), and `--quiet` (`-q`)
+apply throughout. Run `relavium --help` or `relavium <command> --help` for the full surface.
+
+## Exit codes
+
+Deterministic, for CI:
+
+| Code | Meaning                                                                |
+| ---- | --------------------------------------------------------------------- |
+| `0`  | Completed successfully                                                 |
+| `1`  | Workflow failed (a node errored and exhausted retries / fallbacks)     |
+| `2`  | Invalid invocation (bad arguments, not found, schema error)            |
+| `3`  | Run paused at a human gate (non-interactive) — resume with `relavium gate` |
+| `4`  | A `relavium chat` / `chat-resume` session ended (`/exit`, `/cancel`, or input EOF) |
+
+For a workflow run or agent session, `--json` makes stdout a pure NDJSON stream — `RunEvent`s for `run` /
+`gate`, `SessionEvent`s for `chat` / `agent run` — with all diagnostics on stderr. (`--help`, `--version`,
+and a bare invocation stay human-readable on stdout.)
+
+## Keys & configuration
 
-**Exit codes** (CI-friendly): `0` completed · `1` failed · `2` invalid invocation · `3` paused at a
-human gate. Provider keys resolve from the OS keychain → `RELAVIUM_<PROVIDER>_API_KEY` env var → error.
+Provider keys resolve **OS keychain → `RELAVIUM_<PROVIDER>_API_KEY` env var → error** — no plaintext
+fallback, and only a 4-character hint is ever displayed. Configuration layers from `~/.relavium/`
+(global) and a project `.relavium/`, with CLI flags and env vars overriding. Run history persists locally
+to `~/.relavium/history.db`.
 
 ## Documentation
 
-The full command reference, the `--json` machine contract, and the CI guide live in the
-[Relavium docs](https://github.com/HodeTech/Relavium/tree/main/docs/reference/cli/commands.md).
+The full command reference, the `--json` machine-output contract, and the CI guide live in the Relavium
+docs: **[docs/reference/cli/commands.md](https://github.com/HodeTech/Relavium/blob/main/docs/reference/cli/commands.md)**.
 
 ## License
 
-Proprietary — © HodeTech, all rights reserved. See [LICENSE](https://github.com/HodeTech/Relavium/blob/main/LICENSE).
+Proprietary — © HodeTech, all rights reserved. Not open source; no rights are granted except as expressly
+stated. See **[LICENSE](https://github.com/HodeTech/Relavium/blob/main/LICENSE)**.

apps/cli/package.json

@@ -1,23 +1,32 @@
 {
   "name": "relavium",
-  "version": "0.1.0",
-  "description": "Relavium CLI (`relavium`) — run agent workflows from the terminal; the engine's first real consumer.",
+  "version": "0.1.1",
+  "description": "The local-first Relavium CLI — run multi-model AI agent sessions and git-committable workflows from your terminal.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
   "bin": {
     "relavium": "./dist/index.js"
   },
   "files": [
     "dist",
-    "drizzle"
+    "drizzle",
+    "CHANGELOG.md"
   ],
   "keywords": [
     "relavium",
     "ai",
     "agent",
+    "ai-agent",
+    "multi-agent",
     "workflow",
     "cli",
-    "llm"
+    "llm",
+    "local-first",
+    "mcp",
+    "anthropic",
+    "openai",
+    "gemini",
+    "deepseek"
   ],
   "repository": {
     "type": "git",