@mutagent/cli 0.1.195 → 0.1.196

package/README.md

@@ -24,179 +24,85 @@
 </p>
 
 <p align="center">
-  <strong>Optimize Prompts. Manage Agents. Integrate Any Framework.</strong>
+  <strong>Authenticate. Configure providers. Install MutagenT lifecycle tools.</strong>
 </p>
 
 ---
 
 ## What is MutagenT CLI?
 
-MutagenT CLI is the command-line interface for the **MutagenT AI platform** — a next-generation prompt optimization and observability system designed for AI-native development workflows.
+MutagenT CLI is the command-line client for the **MutagenT AI platform**. It is the
+entry point that AI coding agents and developers use to authenticate, set up a
+project, manage BYOK LLM providers, check account usage, and install MutagenT's
+lifecycle tooling (diagnostics, evaluator, and — when available — helix).
+
+Every command is **AI-first**: run any command with `--json` for machine-readable
+output, and install the bundled Claude Code skill so coding agents know how to
+drive the CLI without human hand-holding.
 
 ### Key Features
 
-- **Prompt-Centric**: Datasets, evaluations, and optimizations are all scoped to prompts
-- **Native Tracing**: Built-in trace observability without external dependencies
-- **AI-First Design**: Every command supports `--json` with `_links` for programmatic usage
-- **Framework Integrations**: One-command setup for Mastra, LangChain, LangGraph, Vercel AI SDK, Claude Code
-- **Bun-Native**: Built for speed with Bun runtime (Node.js 18+ compatible)
-- **Post-Onboarding Flow**: Guided paths after login for integration or optimization
-- **Codebase Exploration**: `mutagent explore` scans your code for prompts, datasets, and markers
-- **Optimization Scorecard**: Before/after comparison with apply/reject flow
-- **State Tracking**: `.mutagent/mutation-context.md` tracks your entire workflow locally
+- **AI-First Design**: Every command supports `--json` with `_directive` + `_links` for programmatic use by coding agents
+- **One-Command Auth**: `mutagent login` handles signup, onboarding, and CLI authorization via browser OAuth (or an API key for CI)
+- **BYOK Providers**: Configure and test your own LLM provider keys (`mutagent providers`)
+- **Lifecycle Meta-Installer**: `mutagent install <diagnostics|evaluator|helix>` pulls MutagenT packages (login-gated)
+- **Claude Code Integration**: Install the CLI skill (`mutagent skills install`) and session-telemetry hooks (`mutagent hooks install`)
+- **Built-in Feedback**: `mutagent feedback send` reports bugs and product feedback, optionally with your coding-agent session transcript
+- **Bun-Native**: Built for speed with the Bun runtime (Node.js 22+ compatible)
 
 ---
 
 ## Interaction Flow Map
 
-This is the complete map of all user-facing routes through the CLI. Use this as a reference for UX decisions.
+The active command surface and the typical routes through it.
 
 ```mermaid
 flowchart TD
     INSTALL["npm i -g @mutagent/cli"] --> AUTH_CHOICE{How to authenticate?}
 
-    AUTH_CHOICE -->|Interactive| AUTH_LOGIN["mutagent auth login"]
-    AUTH_CHOICE -->|Browser OAuth| AUTH_BROWSER["mutagent auth login --browser"]
-    AUTH_CHOICE -->|API Key| AUTH_KEY["mutagent auth login --api-key mg_..."]
-    AUTH_CHOICE -->|Env Var| AUTH_ENV["export MUTAGENT_API_KEY=mg_..."]
+    AUTH_CHOICE -->|Interactive / browser OAuth| LOGIN["mutagent login"]
+    AUTH_CHOICE -->|Force browser| LOGIN_B["mutagent login --browser"]
+    AUTH_CHOICE -->|CI / env var| ENV["export MUTAGENT_API_KEY=mt_...<br/>mutagent login --json"]
 
-    AUTH_LOGIN --> ONBOARD
-    AUTH_BROWSER --> ONBOARD
-    AUTH_KEY --> ONBOARD
-    AUTH_ENV --> MANUAL
+    LOGIN --> INIT["mutagent init<br/>(.mutagentrc.json)"]
+    LOGIN_B --> INIT
+    ENV --> INIT
 
-    subgraph ONBOARD ["Post-Onboarding Menu (interactive only)"]
-        direction TB
-        MENU["What would you like to do?"]
-        PATH_A["A: Guided Integration"]
-        PATH_B["B: Quick Optimization"]
-        PATH_C["C: Exit — manual mode"]
-        MENU --> PATH_A
-        MENU --> PATH_B
-        MENU --> PATH_C
-    end
+    INIT --> SETUP
 
-    PATH_C --> MANUAL
-    PATH_A --> EXPLORE_A["mutagent explore (auto-scan)"]
-    PATH_B --> EXPLORE_B["mutagent explore (auto-scan)"]
-
-    EXPLORE_A --> FW_SELECT["Select framework"]
-    FW_SELECT --> INTEGRATE["mutagent integrate <framework>"]
-    INTEGRATE --> VERIFY["mutagent integrate <fw> --verify"]
-    VERIFY --> MANUAL
-
-    EXPLORE_B --> PROMPT_CREATE
-    PROMPT_CREATE --> EVAL_CREATE
-    EVAL_CREATE --> DS_ADD
-    DS_ADD --> OPT_START
-    OPT_START --> OPT_STATUS
-    OPT_STATUS --> OPT_RESULTS
-    OPT_RESULTS --> SCORECARD["Scorecard: Apply / Reject"]
-    SCORECARD -->|Apply| PROMPT_UPDATED["Prompt updated (platform + local)"]
-    SCORECARD -->|Reject| MANUAL
-
-    subgraph MANUAL ["Manual CLI Usage"]
+    subgraph SETUP ["Project Setup & Discovery"]
         direction TB
 
         subgraph AUTH_CMDS ["Auth & Config"]
             AUTH_STATUS["mutagent auth status"]
             AUTH_LOGOUT["mutagent auth logout"]
             CONFIG_LIST["mutagent config list"]
-            CONFIG_GET["mutagent config get <key>"]
             CONFIG_SET_WS["mutagent config set workspace <id>"]
             CONFIG_SET_ORG["mutagent config set org <id>"]
         end
 
-        subgraph DISCOVER ["Discovery"]
-            EXPLORE["mutagent explore"]
-            EXPLORE_PATH["mutagent explore --path ./src"]
-            EXPLORE_MARKERS["mutagent explore --markers-only"]
-            SKILLS["mutagent skills install"]
-        end
-
-        subgraph PROMPT_CMDS ["Prompt CRUD"]
-            PROMPT_LIST["mutagent prompts list"]
-            PROMPT_GET["mutagent prompts get <id>"]
-            PROMPT_CREATE["mutagent prompts create"]
-            PROMPT_UPDATE["mutagent prompts update <id>"]
-            PROMPT_DELETE["mutagent prompts delete <id>"]
-        end
-
-        subgraph DATASET_CMDS ["Dataset Management"]
-            DS_LIST["mutagent prompts dataset list <pid>"]
-            DS_ADD["mutagent prompts dataset add <pid>"]
-            DS_DELETE["mutagent prompts dataset delete <pid> <did>"]
-        end
-
-        subgraph EVAL_CMDS ["Evaluations"]
-            EVAL_LIST["mutagent prompts evaluation list <pid>"]
-            EVAL_CREATE["mutagent prompts evaluation create <pid>"]
-            EVAL_GUIDED["mutagent prompts evaluation create <pid> --guided"]
-            EVAL_RESULTS["mutagent prompts evaluation results <rid>"]
-        end
-
-        subgraph OPT_CMDS ["Optimization"]
-            OPT_START["mutagent prompts optimize start <pid>"]
-            OPT_STATUS["mutagent prompts optimize status <jid>"]
-            OPT_RESULTS["mutagent prompts optimize results <jid>"]
-        end
-
-        subgraph TRACE_CMDS ["Traces"]
-            TRACE_LIST["mutagent traces list"]
-            TRACE_GET["mutagent traces get <id>"]
-            TRACE_ANALYZE["mutagent traces analyze <pid>"]
-            TRACE_EXPORT["mutagent traces export"]
-        end
-
-        subgraph INTEGRATION_CMDS ["Integrations"]
-            INT_LIST["mutagent integrate list"]
-            INT_FW["mutagent integrate <framework>"]
-            INT_VERIFY["mutagent integrate <fw> --verify"]
-        end
-
-        subgraph PLAYGROUND_CMDS ["Playground"]
-            PG_RUN["mutagent playground run <pid>"]
-            PG_STREAM["mutagent playground run <pid> --stream"]
-        end
-
         subgraph PLATFORM_CMDS ["Platform (read-only)"]
             WS_LIST["mutagent workspaces list"]
             WS_GET["mutagent workspaces get <id>"]
+            USAGE["mutagent usage"]
+        end
+
+        subgraph PROVIDER_CMDS ["Providers (BYOK)"]
             PROV_LIST["mutagent providers list"]
-            PROV_GET["mutagent providers get <id>"]
+            PROV_ADD["mutagent providers add"]
             PROV_TEST["mutagent providers test <id>"]
-            AGENTS_LIST["mutagent agents list"]
-            AGENTS_GET["mutagent agents get <id>"]
         end
-    end
-```
-
-### Evaluate-Optimize Loop (Detail)
-
-```mermaid
-flowchart LR
-    CREATE["prompts create\n-d / --file / --raw"] --> DATASET["dataset add\n--file / -d"]
-    DATASET --> EVAL["evaluation create\n--guided / --file / -d"]
-    EVAL --> OPT["optimize start\n--dataset --max-iterations"]
-    OPT --> STATUS["optimize status"]
-    STATUS -->|poll| STATUS
-    STATUS --> RESULTS["optimize results\n(scorecard)"]
-    RESULTS -->|Apply| UPDATE["prompts update\n(new version)"]
-    RESULTS -->|Reject| TWEAK["Adjust prompt/eval\nand re-run"]
-    TWEAK --> OPT
-```
 
-### State Tracking Flow
+        subgraph AGENT_TOOLING ["Coding-Agent Tooling"]
+            SKILLS["mutagent skills install"]
+            HOOKS["mutagent hooks install"]
+        end
 
-```mermaid
-flowchart LR
-    EXPLORE["mutagent explore"] -->|writes| CTX[".mutagent/mutation-context.md"]
-    CREATE["prompts create"] -->|updates| CTX
-    UPLOAD["dataset add"] -->|updates| CTX
-    EVAL["evaluation create"] -->|updates| CTX
-    OPTIMIZE["optimize results --apply"] -->|updates| CTX
-    MARKERS["MutagenT:START/END\ncomment markers"] -->|tracked by| CTX
-    STATUS["auth status"] -->|reads| CTX
+        subgraph LIFECYCLE ["Lifecycle Tools & Feedback"]
+            INSTALL_PKG["mutagent install <diagnostics|evaluator|helix>"]
+            FEEDBACK["mutagent feedback send"]
+        end
+    end
 ```
 
 ---
@@ -253,63 +159,57 @@ mutagent auth login
 > `mutagent login` is the canonical command. `mutagent auth login` is preserved
 > as a back-compat alias; both behave identically.
 
-### 2. Post-Onboarding (Interactive)
+### 2. Initialize Your Project
 
-After login, the CLI offers 3 paths:
+```bash
+mutagent init                 # Interactive setup — writes .mutagentrc.json
+mutagent init --non-interactive   # CLI-only defaults, no prompts
 
-| Path | Description |
-|------|-------------|
-| **A: Guided Integration** | Auto-scans codebase, selects framework, generates integration code |
-| **B: Quick Optimization** | Auto-scans codebase, uploads prompt, creates eval, runs optimization |
-| **C: Exit** | Skip guidance, use CLI manually |
+# Confirm state
+mutagent auth status
+```
 
-### 3. Explore Your Codebase
+### 3. Configure Providers (BYOK)
 
 ```bash
-mutagent explore                    # Scan current directory
-mutagent explore --path ./src       # Scan specific path
-mutagent explore --markers-only     # Find existing MutagenT markers only
+mutagent providers list                 # List configured providers
+mutagent providers list --models        # Show available models per provider
+mutagent providers add                  # Add a provider key (interactive)
+mutagent providers test <provider-id>   # Verify connectivity
 ```
 
-### 4. Create & Optimize
+### 4. Install Lifecycle Tools
 
 ```bash
-# Create a prompt (inline JSON — recommended for AI agents)
-mutagent prompts create -d '{"name":"summarizer","systemPrompt":"Summarize the text","humanPrompt":"{{text}}","outputSchema":{"type":"object","properties":{"summary":{"type":"string"}}}}'
-
-# Upload a dataset
-mutagent prompts dataset add <prompt-id> --file data.json --name "Training Data"
-
-# Create evaluation criteria (guided interactive mode)
-mutagent prompts evaluation create <prompt-id> --guided
-
-# Start optimization
-mutagent prompts optimize start <prompt-id> --dataset <dataset-id> --max-iterations 1
-
-# Review results (shows scorecard with apply/reject)
-mutagent prompts optimize results <job-id>
+mutagent install diagnostics            # Install diagnostics from npm (login-gated)
+mutagent install evaluator              # Install evaluator from npm
+mutagent install evaluator --version 1.2.3   # Pin a version
+mutagent install --help                 # helix (pending) | diagnostics | evaluator
 ```
 
-### 5. Get Framework Integration
+### 5. Wire Up Your Coding Agent
 
 ```bash
-mutagent integrate mastra       # Mastra
-mutagent integrate langchain    # LangChain
-mutagent integrate langgraph    # LangGraph
-mutagent integrate vercel-ai    # Vercel AI SDK
-mutagent integrate openai       # OpenAI SDK
-mutagent integrate claude-code  # Claude Code
+mutagent skills install                 # Install the MutagenT CLI skill for AI agents
+mutagent hooks install                  # Install Claude Code session-telemetry hooks
 ```
 
 ---
 
 ## Commands Reference
 
+The active command surface:
+
+`login` · `auth` · `config` · `workspaces` · `providers` · `usage` · `init` · `skills` · `hooks` · `install` · `feedback`
+
+Run `mutagent <command> --help` for the authoritative, current flag list — the CLI
+is the source of truth for flags.
+
 ### Global Options
 
 | Option | Description |
 |--------|-------------|
-| `--json` | Output results as JSON with `_links` to web UI |
+| `--json` | Output results as JSON with `_directive` + `_links` |
 | `--non-interactive` | Disable all interactive prompts (also: `CI=true`) |
 | `--api-key <key>` | Override API key for this command |
 | `--endpoint <url>` | Override API endpoint |
@@ -320,218 +220,154 @@ mutagent integrate claude-code  # Claude Code
 
 | Variable | Description |
 |----------|-------------|
-| `MUTAGENT_API_KEY` | API key (skips login entirely) |
+| `MUTAGENT_API_KEY` | API key (skips interactive login) |
 | `MUTAGENT_ENDPOINT` | Custom API endpoint |
 | `MUTAGENT_NON_INTERACTIVE=true` | Non-interactive mode |
 | `CI=true` | Enables non-interactive mode |
 
-### Authentication & Configuration
+### Authentication (`login` / `auth`)
 
 ```bash
-mutagent auth login                 # Interactive login
-mutagent auth login --browser       # Browser OAuth
-mutagent auth login --api-key KEY   # API key login
-mutagent auth status                # Check auth + onboarding state + resource counts
-mutagent auth logout                # Clear credentials
+mutagent login                      # Browser OAuth (recommended)
+mutagent login --browser            # Force browser flow
+mutagent login --json               # Non-interactive (uses MUTAGENT_API_KEY)
 
-mutagent config list                # List all config values
-mutagent config get <key>           # Get specific value
-mutagent config set workspace <id>  # Set default workspace
-mutagent config set org <id>        # Set default organization
+mutagent auth login                 # Back-compat alias for `mutagent login`
+mutagent auth status                # Check auth + workspace + onboarding state
+mutagent auth logout                # Clear stored credentials
 ```
 
-### Discovery & Skills
+### Configuration (`config`)
 
 ```bash
-# Explore codebase for prompts, datasets, MutagenT markers
-mutagent explore                          # Scan current directory
-mutagent explore --path ./src             # Scan specific path
-mutagent explore --include "**/*.py"      # Python projects only
-mutagent explore --markers-only           # Only find MutagenT:START/END markers
-mutagent explore --json                   # JSON output
-
-# Install Claude Code skill
-mutagent skills install                   # Creates .claude/skills/mutagent-cli/SKILL.md
+mutagent config list                # List all config values
+mutagent config get <key>           # Get a value (apiKey, endpoint, format, timeout, defaultWorkspace, defaultOrg)
+mutagent config set workspace <id>  # Set default workspace
+mutagent config set org <id>        # Set default organization
 ```
 
-### Prompts
+### Project Setup (`init`)
 
 ```bash
-# List / Get
-mutagent prompts list
-mutagent prompts get <id>
-mutagent prompts get <id> --with-datasets --with-evals
-
-# Create (multiple input methods, priority order)
-mutagent prompts create -d '{"name":"...","systemPrompt":"...","outputSchema":{...}}'   # Inline JSON (recommended)
-mutagent prompts create --file prompt.json                                               # From JSON file
-mutagent prompts create --name "my-prompt" --raw-file prompt.txt                         # From text file
-mutagent prompts create --name "my-prompt" --system "You are..." --human "{{input}}"     # System + human
-mutagent prompts create --name "my-prompt" --raw "Summarize: {{text}}"                   # Raw text
-mutagent prompts create --name "chat" --messages '[{"role":"system","content":"..."}]'   # Messages array
-
-# Update (same input methods as create)
-mutagent prompts update <id> -d '{"name":"new-name","systemPrompt":"Updated"}'
-mutagent prompts update <id> --name "new-name"
-mutagent prompts update <id> --file updated.json
-
-# Delete
-mutagent prompts delete <id>
-mutagent prompts delete <id> --force
+mutagent init                       # Interactive wizard — writes .mutagentrc.json
+mutagent init --non-interactive     # Skip prompts (CLI-only defaults)
 ```
 
-> **outputSchema** is required for optimization. Include it in `--data`, `--file`, or use `--output-schema`. In interactive mode, you will be prompted if missing.
-
-### Datasets
+### Workspaces (`workspaces`, read-only)
 
 ```bash
-mutagent prompts dataset list <prompt-id>
-
-# Add from file (JSON, JSONL, CSV)
-mutagent prompts dataset add <prompt-id> --file data.json --name "My Dataset"
-
-# Add inline JSON
-mutagent prompts dataset add <prompt-id> -d '[{"input":{...},"expectedOutput":{...}}]' --name "Inline Data"
-
-mutagent prompts dataset delete <prompt-id> <dataset-id>
+mutagent workspaces list            # List all workspaces
+mutagent workspaces list --limit 20 --offset 0
+mutagent workspaces get <id>        # Workspace details
 ```
 
-### Evaluations
+### Providers (`providers`, BYOK)
 
 ```bash
-mutagent prompts evaluation list <prompt-id>
-
-# Guided interactive mode (fetches outputSchema, helps build criteria)
-mutagent prompts evaluation create <prompt-id> --guided
+mutagent providers list             # List configured providers
+mutagent providers list --models    # Show available models per provider
+mutagent providers get <id>         # Provider details
+mutagent providers test <id>        # Test provider connectivity
 
-# Inline JSON
-mutagent prompts evaluation create <prompt-id> -d '{"name":"Accuracy","evalConfig":{"criteria":[...]}}'
-
-# From file with dataset association
-mutagent prompts evaluation create <prompt-id> --name "Quality" --file criteria.json --dataset <dataset-id>
-
-mutagent prompts evaluation results <run-id>
+# Manage keys
+mutagent providers add              # Add a provider (interactive; --scope, --base-url, --set-default)
+mutagent providers update <id> --name "New name" --active true
+mutagent providers delete <id> --force
 ```
 
-> `-d` is `--data` (inline JSON). `--dataset` requires the full flag name (no shorthand).
-
-### Optimization
+### Usage (`usage`)
 
 ```bash
-mutagent prompts optimize start <prompt-id> --dataset <dataset-id>
-mutagent prompts optimize start <prompt-id> --dataset <id> --max-iterations 5 --target-score 0.95
-
-mutagent prompts optimize status <job-id>
-
-# Results include scorecard with before/after comparison and apply/reject flow
-mutagent prompts optimize results <job-id>
+mutagent usage                      # Show account usage + provider status
+mutagent usage --json               # Machine-readable
 ```
 
-### Traces
+### Skills & Hooks (Claude Code)
 
 ```bash
-mutagent traces list
-mutagent traces list --prompt <prompt-id> --limit 10
-mutagent traces get <trace-id>
-mutagent traces analyze <prompt-id>
-mutagent traces export --format json --output traces.json
-mutagent traces export --format csv --prompt <prompt-id>
+# Install the MutagenT CLI skill so coding agents know how to drive the CLI
+mutagent skills install             # Creates .claude/skills/mutagent-cli/SKILL.md
+
+# Install session-telemetry hooks (safe merge into .claude/settings.local.json)
+mutagent hooks install
+mutagent hooks install --cwd ./path # Target a specific directory
 ```
 
-### Framework Integration
+### Lifecycle Meta-Installer (`install`)
 
 ```bash
-mutagent integrate                    # Auto-detect framework
-mutagent integrate list               # List supported frameworks
-mutagent integrate <framework>        # Generate integration code
-mutagent integrate <fw> --verify      # Verify integration setup
-mutagent integrate <fw> --output FILE # Save to file
-mutagent integrate <fw> --raw         # Raw markdown output
+mutagent install diagnostics        # Install @mutagent/diagnostics from npm (login-gated)
+mutagent install evaluator          # Install @mutagent/evaluator from npm
+mutagent install evaluator --version 1.2.3   # Pin a specific version
+mutagent install helix              # Self-hosted install (may return NOT_IMPLEMENTED — pending)
 ```
 
-| Framework | Package | Description |
-|-----------|---------|-------------|
-| `mastra` | `@mastra/core` | Modern AI agent framework |
-| `langchain` | `langchain` | Popular LLM framework |
-| `langgraph` | `@langchain/langgraph` | Agent workflow framework |
-| `vercel-ai` | `ai` | AI SDK for streaming chat |
-| `openai` | `openai` | Direct OpenAI SDK integration |
-| `claude-code` | MCP Server | Native Anthropic integration |
-| `generic` | `openai` | Any OpenAI-compatible API |
+| Package | Source | Notes |
+|---------|--------|-------|
+| `diagnostics` | public npm | Installs today |
+| `evaluator` | public npm | Installs today |
+| `helix` | self-hosted | Pending — may return `NOT_IMPLEMENTED` for now |
 
-### Playground
+### Feedback (`feedback`)
 
 ```bash
-mutagent playground run <prompt-id> --input '{"topic": "AI"}'
-mutagent playground run <prompt-id> --input '{"topic": "AI"}' --stream
-mutagent playground run <prompt-id> --system "You are..." --human "Hello!"
-mutagent playground run <prompt-id> --messages '[{"role":"user","content":"Hi"}]'
-mutagent playground run <prompt-id> --input '{}' --model gpt-4o
-```
+# Report a bug or send product feedback (login-gated)
+mutagent feedback send "describe what went wrong" --category cli
 
-### Platform (Read-Only)
+# Lifecycle-stage feedback
+mutagent feedback send "eval gate unclear" --category stage:evaluate
 
-```bash
-# Workspaces
-mutagent workspaces list
-mutagent workspaces get <id>
-
-# Providers
-mutagent providers list
-mutagent providers get <id>
-mutagent providers test <id>
-
-# Agents
-mutagent agents list
-mutagent agents get <id>
-mutagent agents create --name "Agent" --slug agent --system-prompt "..."
-mutagent agents update <id> --status paused
-mutagent agents delete <id>
+# Link to a session and attach your coding-agent transcript
+mutagent feedback send "the CLI crashed on init" \
+  --category cli --session <session-id> --attach-transcript
 ```
 
+| Flag | Description |
+|------|-------------|
+| `<feedback>` | Feedback body / content (required, ≤10000 chars) |
+| `--title <string>` | Optional 5–8 word summary of the session timeline |
+| `--category <value>` | `cli` (default) · `helix` · `stage:<spec\|build\|evaluate\|diagnose\|optimize>` |
+| `--session <id>` | Link feedback to a session id (server `sessionId`) |
+| `--attach-transcript [path]` | Attach the coding-agent session JSONL (bare = auto-detect newest) |
+
 ---
 
 ## AI-First Usage
 
-Every command supports `--json` for machine-readable output with `_links` to the web dashboard:
+Every command supports `--json` for machine-readable output with `_directive`
+(next-step guidance for agents) and `_links` (dashboard/API URLs):
 
 ```bash
 # Zero-config with env var
-export MUTAGENT_API_KEY="mg_live_xxxx"
+export MUTAGENT_API_KEY="mt_live_xxxx"
 
-# Discover commands
+# Discover the surface
 mutagent --help
+mutagent --version --json
 
-# JSON output with deep links
-mutagent prompts list --json
-mutagent prompts get <id> --json
-
-# Inline JSON for create/update (recommended for AI agents)
-mutagent prompts create -d '{"name":"my-prompt","systemPrompt":"...","outputSchema":{...}}'
+# JSON output
+mutagent workspaces list --json
+mutagent providers list --models --json
+mutagent usage --json
 
 # Non-interactive mode
-mutagent prompts list --non-interactive
+mutagent init --non-interactive
 
-# Generate integration code (raw markdown)
-mutagent integrate langchain --raw
-
-# Install skill for Claude Code
+# Install the skill so agents can self-serve
 mutagent skills install
 ```
 
-### JSON Output Format
+### JSON Directive & Links
 
-```json
-{
-  "data": { "id": 42, "name": "my-prompt", "..." : "..." },
-  "_links": {
-    "dashboard": "https://app.mutagent.io/prompts/dashboard?prompt=42",
-    "api": "/api/prompts/42",
-    "datasets": "https://app.mutagent.io/prompts/dashboard?prompt=42&tab=datasets",
-    "evaluations": "https://app.mutagent.io/prompts/dashboard?prompt=42&tab=evaluations"
-  }
-}
-```
+`--json` responses may include:
+
+| Field | Meaning |
+|-------|---------|
+| `_directive.renderedCard` | Pre-formatted status card — agents **must** echo it verbatim in chat |
+| `_directive.instruction` | Self-contained next step for the agent |
+| `_directive.next` | Array of suggested follow-up commands |
+| `_links` | Dashboard / API URLs |
+| `_compat` | Compat metadata: `cliVersion`, `skillVersion`, `skillMinCliVersion` |
 
 ### Exit Codes
 
@@ -547,43 +383,19 @@ mutagent skills install
 
 ---
 
-## State Tracking
-
-The CLI maintains local state to track your MutagenT workflow:
-
-| Artifact | Location | Purpose |
-|----------|----------|---------|
-| **Mutation context** | `.mutagent/mutation-context.md` | Tracks discovered prompts, uploaded resources, optimization history |
-| **Comment markers** | Source files | `MutagenT:START` / `MutagenT:END` markers identifying managed prompts |
-| **Auth status** | `mutagent auth status` | Shows onboarding state, context file status, resource counts |
-| **Claude Code skill** | `.claude/skills/mutagent-cli/SKILL.md` | Teaches AI agents how to use MutagenT CLI |
-
-```bash
-# Scan codebase and populate context
-mutagent explore
-
-# Check your current state
-mutagent auth status
-
-# Install Claude Code skill
-mutagent skills install
-```
-
----
-
 ## Configuration
 
 ### Environment Variables
 
 ```bash
-MUTAGENT_API_KEY=mg_live_xxxxxxxx
+MUTAGENT_API_KEY=mt_live_xxxxxxxx
 MUTAGENT_ENDPOINT=https://api.mutagent.io
 MUTAGENT_APP_URL=https://app.mutagent.io
 ```
 
 ### RC Files
 
-Create `.mutagentrc.json`:
+`mutagent init` writes `.mutagentrc.json`. Example:
 
 ```json
 {
@@ -601,28 +413,8 @@ mutagent config set org <id>        # Required for org-scoped API keys
 
 ### Global Config
 
-Stored in `~/.config/mutagent/credentials.json` (created by `mutagent auth login`).
-
----
-
-## Migration from Langfuse
-
-```typescript
-// Before (Langfuse)
-import { Langfuse } from 'langfuse';
-const langfuse = new Langfuse({
-  publicKey: process.env.LANGFUSE_PUBLIC_KEY,
-  secretKey: process.env.LANGFUSE_SECRET_KEY,
-});
-
-// After (MutagenT)
-import { initTracing } from '@mutagent/sdk/tracing';
-initTracing({ apiKey: process.env.MUTAGENT_API_KEY! });
-
-// Framework-specific: use integration packages
-import { MutagentCallbackHandler } from '@mutagent/langchain';
-const handler = new MutagentCallbackHandler();
-```
+Credentials are stored in `~/.config/mutagent/credentials.json` (created by
+`mutagent login`).
 
 ---
 
@@ -631,7 +423,7 @@ const handler = new MutagentCallbackHandler();
 ### Prerequisites
 
 - [Bun](https://bun.sh) >= 1.0.0
-- Node.js >= 18.0.0 (fallback)
+- Node.js >= 22.0.0 (fallback)
 
 ### Setup
 
@@ -646,11 +438,11 @@ bun install
 ```bash
 bun run dev          # Run in development mode
 bun run build        # Build
-bun run typecheck    # Type check
+bun run type-check   # Type check
 bun run lint         # Lint
 bun run lint:fix     # Lint with auto-fix
-bun run test         # Run all tests (574+ tests)
-bun run verify       # Full verification (lint + typecheck + build + test)
+bun run test         # Run all tests
+bun run verify       # Full verification (lint + type-check + build)
 ```
 
 ---
@@ -660,8 +452,6 @@ bun run verify       # Full verification (lint + typecheck + build + test)
 - **[@mutagent/sdk](https://www.npmjs.com/package/@mutagent/sdk)** — TypeScript SDK for programmatic access
 - **[docs.mutagent.io](https://docs.mutagent.io)** — Full platform documentation
 - **[CLI Commands Reference](https://docs.mutagent.io/cli/commands)** — All commands with flags
-- **[Integration Guides](https://docs.mutagent.io/integrations/overview)** — Mastra, LangChain, LangGraph, Vercel AI
-- **[Tracing Setup](https://docs.mutagent.io/tracing/setup)** — OTel integration walkthrough
 - **[mutagent.io](https://mutagent.io)** — Homepage
 
 ---