@kata-sh/cli 0.1.2 → 0.2.1

package/README.md

@@ -1,155 +1,304 @@
 # Kata CLI
 
-A terminal coding agent built on [pi](https://github.com/badlogic/pi-mono) (`@mariozechner/pi-coding-agent`). Kata CLI bundles a curated set of extensions for structured planning, browser automation, web search, subagent orchestration, and more.
+A terminal coding agent that decomposes projects into milestones, slices, and tasks — then executes them autonomously with structured planning, verification, and fresh context windows.
+
+Built on [pi](https://github.com/badlogic/pi-mono) (`@mariozechner/pi-coding-agent`).
 
 ## Quick Start
 
 ```bash
-# From the monorepo root
-bun install
-cd apps/cli
-npx tsc
-npm run copy-themes
-node dist/loader.js
+npx @kata-sh/cli
 ```
 
-Authenticate with an API key:
+Or install globally:
 
 ```bash
-export ANTHROPIC_API_KEY=sk-ant-...
-node dist/loader.js
+npm install -g @kata-sh/cli
+kata-cli
+```
+
+On first launch, Kata will prompt you to authenticate with an AI provider.
+
+## Getting Started
+
+### 1. Start Kata
+
+```bash
+npx @kata-sh/cli
 ```
 
-## Architecture
+### 2. Log in to a provider
+
+```
+/login
+```
 
-Kata CLI is a thin wrapper around pi-coding-agent. It does not fork pi — it consumes it as an npm dependency and layers on branding, config, and bundled extensions.
+This opens an interactive prompt to authenticate with Anthropic, OpenAI, Google, or any supported provider. You can also set an API key directly:
 
+```bash
+ANTHROPIC_API_KEY=sk-ant-... npx @kata-sh/cli
 ```
-apps/cli/
-  src/
-    loader.ts              — Entry point: sets KATA_* env vars, imports cli.ts
-    cli.ts                 — Calls pi-coding-agent's main()
-    app-paths.ts           — ~/.kata-cli/ path constants
-    resource-loader.ts     — Syncs bundled resources to ~/.kata-cli/agent/
-    wizard.ts              — First-run setup, env key hydration
-    resources/
-      KATA-WORKFLOW.md     — The Kata planning methodology
-      AGENTS.md            — System prompt instructions (synced to agent dir)
-      agents/              — Agent templates (worker, scout, researcher)
-      extensions/          — Bundled extensions (see below)
-      skills/              — Bundled skills
-  pkg/
-    package.json           — piConfig shim (name: "kata", configDir: ".kata-cli")
-    dist/                  — Theme assets copied from pi-coding-agent
+
+### 3. Select a model
+
+```
+/model
 ```
 
-### How It Works
+Pick from available models across your authenticated providers.
 
-1. `loader.ts` sets `PI_PACKAGE_DIR` to `pkg/` so pi reads Kata's branding config
-2. `loader.ts` sets `KATA_CODING_AGENT_DIR` so pi uses `~/.kata-cli/agent/` instead of `~/.pi/agent/`
-3. `resource-loader.ts` syncs bundled extensions, agents, skills, and `AGENTS.md` to `~/.kata-cli/agent/` on every launch
-4. `cli.ts` calls pi-coding-agent's `main()` — pi handles everything from there
+### 4. Start working
 
-## Bundled Extensions
+Tell Kata what you want to build. Kata has three modes of operation:
 
-| Extension | Description |
-|-----------|-------------|
-| `kata/` | Main extension: `/kata` command, auto-mode, planning, state management |
-| `browser-tools/` | Playwright-based browser automation |
-| `subagent/` | Spawns child Kata processes for parallel work |
-| `slash-commands/` | `/kata-run` and other slash commands |
-| `bg-shell/` | Background shell execution |
-| `context7/` | Context7 library documentation lookup |
-| `search-the-web/` | Web search via Brave API |
-| `mac-tools/` | macOS-specific utilities |
-| `shared/` | Shared UI components (library, not an entry point) |
+**Step mode** — `/kata` — human in the loop (recommended for new or risk-averse users). Kata proposes each step, you approve or redirect.
 
-## The /kata Command
+**Autonomous mode** — `/kata auto` — researches, plans, executes, verifies, commits, and advances through every slice until the milestone is complete.
 
-The main extension registers `/kata` with subcommands:
+**Steering mode** — two terminals for supervised autonomy:
+
+```
+# Terminal 1: autonomous execution
+/kata auto
+
+# Terminal 2: observe and steer
+/kata status          — check progress
+/kata discuss         — discuss decisions
+/kata queue           — manage upcoming work
+
+# When you need to interrupt and redirect:
+# Terminal 1:
+/kata stop
+```
+
+## How It Works
+
+Kata breaks work into three levels:
+
+```
+Milestone  →  a shippable version (4–10 slices)
+  Slice    →  one demoable vertical capability (1–7 tasks)
+    Task   →  one context-window-sized unit of work
+```
+
+Each slice flows through phases automatically:
+
+**Research** → **Plan** → **Execute** (per task) → **Complete** → **Reassess** → **Next Slice**
+
+- **Research** scouts the codebase and relevant docs
+- **Plan** decomposes the slice into tasks with must-haves — mechanically verifiable outcomes
+- **Execute** runs each task in a fresh context window with only the relevant files pre-loaded
+- **Complete** writes the summary, UAT script, marks the roadmap, and commits
+- **Reassess** checks if the roadmap still makes sense given what was learned
+
+All planning state lives in `.kata/` at the project root — human-readable markdown files that track milestones, slices, tasks, decisions, and progress.
+
+## Commands
+
+### Kata workflow
 
 | Command | Description |
 |---------|-------------|
-| `/kata` | Contextual wizard — smart entry point based on project state |
-| `/kata auto` | Start auto-mode (loops fresh sessions until milestone complete) |
-| `/kata stop` | Stop auto-mode gracefully |
+| `/kata` | Contextual wizard — suggests next step based on project state |
+| `/kata auto` | Start autonomous mode |
+| `/kata stop` | Stop auto-mode after current task |
 | `/kata status` | Progress dashboard |
-| `/kata queue` | View/manage work queue |
+| `/kata queue` | View/manage milestone queue |
 | `/kata discuss` | Discuss gray areas before planning |
-| `/kata prefs` | Manage preferences (global/project/status) |
+| `/kata prefs` | Manage preferences (global/project) |
 | `/kata doctor` | Diagnose and fix project state |
+| `/audit` | Audit the codebase against a goal, writes report to `.kata/audits/` |
 
-### Project State
+### Session & model
 
-Kata stores planning state in `.kata/` at the project root:
+| Command | Description |
+|---------|-------------|
+| `/login` | Authenticate with an AI provider (OAuth) |
+| `/model` | Select a model |
+| `/scoped-models` | Enable/disable models for `Ctrl+P` cycling |
+| `/new` | Start a new session |
+| `/resume` | Resume a previous session |
+| `/compact` | Manually compact the session context |
+| `/fork` | Create a new fork from a previous message |
+| `/tree` | Navigate session tree (switch branches) |
+| `/session` | Show session info and stats |
+
+### Utilities
+
+| Command | Description |
+|---------|-------------|
+| `/mcp` | Show MCP server status and tools |
+| `/gh` | GitHub helper — issues, PRs, labels, milestones, status |
+| `/subagent` | List available subagents |
+| `/export` | Export session to HTML file |
+| `/share` | Share session as a secret GitHub gist |
+| `/copy` | Copy last agent message to clipboard |
+| `/hotkeys` | Show all keyboard shortcuts |
+| `/create-extension` | Scaffold a new extension with interview-driven setup |
+| `/create-slash-command` | Generate a new slash command from a plain-English description |
+
+## Preferences
+
+Kata preferences live in `~/.kata-cli/preferences.md` (global) or `.kata-cli/preferences.md` (project-local). Manage with `/kata prefs`.
+
+```yaml
+---
+version: 1
+models:
+  research: claude-sonnet-4-6
+  planning: claude-opus-4-6
+  execution: claude-sonnet-4-6
+  completion: claude-sonnet-4-6
+skill_discovery: suggest
+auto_supervisor:
+  soft_timeout_minutes: 20
+  idle_timeout_minutes: 10
+  hard_timeout_minutes: 30
+budget_ceiling: 50.00
+---
+```
+
+| Setting | What it controls |
+|---------|-----------------|
+| `models.*` | Per-phase model selection (Opus for planning, Sonnet for execution, etc.) |
+| `skill_discovery` | `auto` / `suggest` / `off` — how Kata finds and applies skills |
+| `auto_supervisor.*` | Timeout thresholds for auto-mode supervision |
+| `budget_ceiling` | USD ceiling — auto mode pauses when reached |
+| `uat_dispatch` | Enable automatic UAT runs after slice completion |
+| `always_use_skills` | Skills to always load when relevant |
+| `skill_rules` | Situational rules for skill routing |
+
+## Project State
+
+Kata stores all planning artifacts in `.kata/` at the project root:
 
 ```
 .kata/
-  STATE.md              — Dashboard (read first)
-  DECISIONS.md          — Append-only decisions register
-  PROJECT.md            — Project description
-  REQUIREMENTS.md       — Requirements tracking
+  STATE.md                — Quick-glance dashboard
+  PROJECT.md              — What the project is (living doc)
+  DECISIONS.md            — Append-only architecture decisions
+  REQUIREMENTS.md         — Requirements tracking
   milestones/
     M001/
-      M001-ROADMAP.md   — Milestone plan with slices
+      M001-ROADMAP.md     — Slices with risk levels and dependencies
+      M001-SUMMARY.md     — Milestone rollup
       slices/
         S01/
-          S01-PLAN.md   — Task decomposition
+          S01-PLAN.md     — Tasks with must-haves and estimates
+          S01-SUMMARY.md  — What was built, what changed
           tasks/
-            T01-PLAN.md
+            T01-PLAN.md   — Steps, verification, files touched
             T01-SUMMARY.md
 ```
 
-## Config Directory
+Everything is markdown. You can read it, edit it, or use it as context for other tools.
+
+## Bundled Tools
+
+Kata comes with extensions for:
+
+- **Browser automation** — Playwright-based interaction with web pages
+- **Subagents** — Spawn parallel Kata processes for independent tasks
+- **Background shell** — Long-running processes (servers, watchers, builds)
+- **Web search** — Brave Search API for current external facts
+- **Library docs** — Context7 for up-to-date framework/library documentation
+- **macOS tools** — Native app automation via Accessibility APIs
+- **MCP servers** — Connect to any [Model Context Protocol](https://modelcontextprotocol.io/) server
+
+## Bundled Agents
+
+Three specialized subagents for delegated work:
+
+| Agent | Role |
+|-------|------|
+| **Scout** | Fast codebase recon — returns compressed context for handoff |
+| **Researcher** | Web research — finds and synthesizes current information |
+| **Worker** | General-purpose execution in an isolated context window |
+
+## MCP Support
+
+Kata integrates with MCP servers via [`pi-mcp-adapter`](https://github.com/nicobailon/pi-mcp-adapter), auto-installed on first launch. Connect to Linear, Figma, or any MCP-compatible service.
+
+### Adding a server
+
+Edit `~/.kata-cli/agent/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "linear": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://mcp.linear.app/mcp"]
+    }
+  }
+}
+```
+
+Restart Kata, then connect:
+
+```
+mcp({ connect: "linear" })
+```
+
+OAuth servers (Linear, etc.) open a browser window for authorization on first connect. Tokens are cached for subsequent sessions.
+
+### Importing existing configs
+
+Pull in MCP configs from other tools:
+
+```json
+{
+  "imports": ["claude-code", "cursor"],
+  "mcpServers": {}
+}
+```
+
+Supported: `cursor`, `claude-code`, `claude-desktop`, `vscode`, `windsurf`, `codex`.
 
-Kata uses `~/.kata-cli/` (not `~/.kata/`) to avoid collision with other Kata apps (desktop, etc.):
+### Usage
+
+| Command | Description |
+|---------|-------------|
+| `mcp({ })` | Show server status |
+| `mcp({ server: "name" })` | List tools from a server |
+| `mcp({ search: "query" })` | Search tools across servers |
+| `mcp({ tool: "name", args: '{}' })` | Call a tool |
+| `/mcp` | Interactive panel |
+
+## Configuration
+
+Kata stores config in `~/.kata-cli/`:
 
 ```
 ~/.kata-cli/
   agent/
-    extensions/          — Synced from src/resources/extensions/
-    agents/              — Synced from src/resources/agents/
-    skills/              — Synced from src/resources/skills/
-    AGENTS.md            — Synced from src/resources/AGENTS.md
-    auth.json            — API keys
+    mcp.json             — MCP server configuration
+    auth.json            — Provider API keys
     settings.json        — User settings
-    models.json          — Custom model definitions
+    extensions/          — Bundled extensions (synced on launch)
+    skills/              — Bundled skills
   sessions/              — Session history
-  preferences.md         — Global Kata preferences
+  preferences.md         — Global preferences
 ```
 
-## Environment Variables
-
-Set by `loader.ts` before pi starts:
-
-| Variable | Purpose |
-|----------|---------|
-| `PI_PACKAGE_DIR` | Points to `pkg/` for Kata's piConfig |
-| `KATA_CODING_AGENT_DIR` | Tells pi to use `~/.kata-cli/agent/` |
-| `KATA_VERSION` | Package version for display |
-| `KATA_BIN_PATH` | Absolute path to loader, used by subagent |
-| `KATA_WORKFLOW_PATH` | Absolute path to bundled KATA-WORKFLOW.md |
-| `KATA_BUNDLED_EXTENSION_PATHS` | Colon-joined extension entry points for subagent |
-
 ## Development
 
+For contributing or running from source:
+
 ```bash
-# Build
+# From the monorepo root
+bun install
+cd apps/cli
 npx tsc
-
-# Copy theme assets (required once, or after pi-coding-agent updates)
 npm run copy-themes
-
-# Run
 node dist/loader.js
-
-# Test
-npm test
 ```
 
-### Key Dependency
+Run tests:
 
-`@mariozechner/pi-coding-agent` is consumed via npm (hoisted to monorepo root `node_modules/`). Never fork — run `npm update` to pick up upstream changes.
+```bash
+cd apps/cli && npm test
+```
 
 ## License
 

package/dist/cli.js

@@ -36,10 +36,30 @@ if (!settingsManager.getQuietStartup()) {
 if (!settingsManager.getCollapseChangelog()) {
     settingsManager.setCollapseChangelog(true);
 }
+// Ensure pi-mcp-adapter is in the packages list so pi auto-installs it on startup.
+// Bootstrap only when packages have never been configured. If users later remove the
+// adapter from settings.json, that opt-out should persist.
+const MCP_ADAPTER_PACKAGE = 'npm:pi-mcp-adapter';
+const globalSettings = settingsManager.getGlobalSettings();
+const globalPackages = [...(globalSettings.packages ?? [])];
+const hasConfiguredPackages = Object.prototype.hasOwnProperty.call(globalSettings, "packages");
+if (!hasConfiguredPackages && !globalPackages.includes(MCP_ADAPTER_PACKAGE)) {
+    settingsManager.setPackages([...globalPackages, MCP_ADAPTER_PACKAGE]);
+}
+await settingsManager.flush();
 const sessionManager = SessionManager.create(process.cwd(), sessionsDir);
 initResources(agentDir);
 const resourceLoader = buildResourceLoader(agentDir);
 await resourceLoader.reload();
+// Inject --mcp-config flag value into the extension runtime.
+// pi-mcp-adapter reads this via pi.getFlag("mcp-config") at session_start.
+// Kata doesn't call pi's main() which does the two-pass argv parsing that
+// normally populates flagValues, so we must do it manually here.
+const mcpConfigPath = process.env.KATA_MCP_CONFIG_PATH;
+if (mcpConfigPath) {
+    const extResult = resourceLoader.getExtensions();
+    extResult.runtime.flagValues.set('mcp-config', mcpConfigPath);
+}
 const { session, extensionsResult } = await createAgentSession({
     authStorage,
     modelRegistry,

package/dist/loader.js

@@ -91,5 +91,15 @@ process.env.KATA_BUNDLED_EXTENSION_PATHS = [
     join(agentDir, "extensions", "ask-user-questions.ts"),
     join(agentDir, "extensions", "get-secrets-from-user.ts"),
 ].join(":");
+// KATA_MCP_CONFIG_PATH — absolute path to Kata's MCP config file.
+// pi-mcp-adapter reads --mcp-config from process.argv directly (before session_start fires).
+// We inject it here so the adapter uses ~/.kata-cli/agent/mcp.json instead of the
+// default ~/.pi/agent/mcp.json.
+const mcpConfigPath = join(agentDir, "mcp.json");
+process.env.KATA_MCP_CONFIG_PATH = mcpConfigPath;
+const hasMcpConfigArg = process.argv.some((arg) => arg === "--mcp-config" || arg.startsWith("--mcp-config="));
+if (!hasMcpConfigArg) {
+    process.argv.push("--mcp-config", mcpConfigPath);
+}
 // Dynamic import defers ESM evaluation — config.js will see PI_PACKAGE_DIR above
 await import("./cli.js");

package/dist/resource-loader.js

@@ -2,6 +2,19 @@ import { DefaultResourceLoader } from '@mariozechner/pi-coding-agent';
 import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+/**
+ * Starter mcp.json written to agentDir on first launch.
+ * Uses the `imports` field so users can pull in their existing Claude/Cursor config.
+ * mcpServers is intentionally empty — users add their own servers here.
+ */
+const STARTER_MCP_JSON = JSON.stringify({
+    imports: [],
+    settings: {
+        toolPrefix: 'server',
+        idleTimeout: 10,
+    },
+    mcpServers: {},
+}, null, 2) + '\n';
 // Resolves to the bundled src/resources/ inside the npm package at runtime:
 //   dist/resource-loader.js → .. → package root → src/resources/
 const resourcesDir = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'src', 'resources');
@@ -39,6 +52,12 @@ export function initResources(agentDir) {
     if (existsSync(srcAgentsMd)) {
         writeFileSync(destAgentsMd, readFileSync(srcAgentsMd));
     }
+    // Scaffold starter mcp.json — only if it doesn't exist yet.
+    // Never overwrite: preserve the user's MCP server configuration.
+    const mcpConfigPath = join(agentDir, 'mcp.json');
+    if (!existsSync(mcpConfigPath)) {
+        writeFileSync(mcpConfigPath, STARTER_MCP_JSON, 'utf-8');
+    }
 }
 /**
  * Constructs a DefaultResourceLoader with no additionalExtensionPaths.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kata-sh/cli",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "Kata CLI coding agent",
   "license": "MIT",
   "private": false,
@@ -29,7 +29,8 @@
     "node": ">=20.6.0"
   },
   "scripts": {
-    "build": "tsc && npm run copy-themes",
+    "build": "tsc && npm run copy-themes && npm run copy-changelog",
+    "copy-changelog": "node -e \"require('fs').cpSync('CHANGELOG.md','pkg/CHANGELOG.md')\"",
     "copy-themes": "node -e \"const{mkdirSync,cpSync}=require('fs');const{resolve}=require('path');const candidates=[resolve(__dirname,'node_modules/@mariozechner/pi-coding-agent/dist/modes/interactive/theme'),resolve(__dirname,'..','..','node_modules/@mariozechner/pi-coding-agent/dist/modes/interactive/theme')];const src=candidates.find(p=>{try{require('fs').statSync(p);return true}catch{return false}});if(!src)throw new Error('theme dir not found');mkdirSync('pkg/dist/modes/interactive/theme',{recursive:true});cpSync(src,'pkg/dist/modes/interactive/theme',{recursive:true})\"",
     "test": "node --import ./src/resources/extensions/kata/tests/resolve-ts.mjs --experimental-strip-types --test 'src/resources/extensions/kata/tests/*.test.ts' 'src/resources/extensions/kata/tests/*.test.mjs' 'src/tests/*.test.ts'",
     "dev": "tsc --watch",

package/pkg/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## 0.2.1
+
+- Fix `/changelog` command — symlink `pkg/CHANGELOG.md` so Kata can find it
+- Rewrite README for consumers: quick start with `npx`, getting started flow, how it works, mode comparison, full command reference
+
+## 0.2.0
+
+- Add MCP (Model Context Protocol) support via `pi-mcp-adapter` — connect to any MCP server (Linear, Figma, custom tools) from Kata
+- Auto-install `pi-mcp-adapter` on startup and scaffold starter `mcp.json` config
+- Inject `mcp-config` flag into extension runtime for seamless MCP server discovery
+- Fix inline `[]` and `{}` literal handling in preferences YAML parser
+- Add comprehensive MCP documentation and setup guide to README
+- Add MCP smoke tests to CI
+- Install `pi-mcp-adapter` globally in CI for test coverage
+
+## 0.1.2
+
+- Fix `~/.kata/` paths to `~/.kata-cli/` to avoid collision with Kata Desktop config directory
+
+## 0.1.1
+
+- Rename `@kata/*` to `@kata-sh/*` npm scope
+- Initial public release to npm

package/src/resources/AGENTS.md

@@ -9,7 +9,7 @@ Kata CLI is a thin wrapper around pi-coding-agent that provides:
 - **Branded entry point**: `src/loader.ts` sets env vars and launches `src/cli.ts`
 - **Bundled extensions**: `src/resources/extensions/` contains all built-in extensions
 - **Resource syncing**: `src/resource-loader.ts` copies bundled extensions to `~/.kata-cli/agent/` on startup
-- **Config directory**: `~/.kata-cli/` (not `~/.kata-cli/` to avoid collision with other Kata apps)
+- **Config directory**: `~/.kata-cli/` (not `~/.pi/` to avoid collision with other Kata apps)
 - **Package shim**: `pkg/package.json` provides `piConfig` with `name: "kata"` and `configDir: ".kata-cli"`
 
 ## Directory Structure
@@ -18,7 +18,7 @@ Kata CLI is a thin wrapper around pi-coding-agent that provides:
 apps/cli/
   src/
     loader.ts              — Entry point, sets KATA_* env vars, imports cli.ts
-    cli.ts                 — Thin wrapper that calls pi-coding-agent's main()
+    cli.ts                 — Thin wrapper that calls createAgentSession() + InteractiveMode
     app-paths.ts           — Exports appRoot, agentDir, sessionsDir, authFilePath
     resource-loader.ts     — Syncs bundled resources to ~/.kata-cli/agent/
     wizard.ts              — First-run setup, env key hydration
@@ -55,6 +55,7 @@ Kata sets these env vars in `loader.ts` before importing `cli.ts`:
 | `KATA_BIN_PATH` | Absolute path to loader, used by subagent to spawn Kata |
 | `KATA_WORKFLOW_PATH` | Absolute path to bundled KATA-WORKFLOW.md |
 | `KATA_BUNDLED_EXTENSION_PATHS` | Colon-joined list of extension entry points |
+| `KATA_MCP_CONFIG_PATH` | Absolute path to `~/.kata-cli/agent/mcp.json` (also injected as `--mcp-config` argv) |
 
 ## The /kata Command
 
@@ -99,6 +100,156 @@ Kata stores project state in `.kata/` at the project root:
 - **Copy themes**: `npm run copy-themes` (copies theme assets from pi-coding-agent)
 - **Dependencies**: Consumed via npm from `@mariozechner/pi-coding-agent` — never fork
 
+## MCP Support
+
+Kata ships with MCP (Model Context Protocol) support via [`pi-mcp-adapter`](https://github.com/nicobailon/pi-mcp-adapter), auto-installed on first launch. One proxy `mcp` tool (~200 tokens) gives the agent on-demand access to any MCP server's tools without burning context on tool definitions.
+
+### How it works
+
+There are three integration points that make MCP work in Kata:
+
+1. **Package seeding** (`cli.ts`): Seeds `npm:pi-mcp-adapter` into `settingsManager.getPackages()` on every startup. Pi's package manager auto-installs it globally if missing.
+
+2. **Config path injection** (`loader.ts` + `cli.ts`): Kata bypasses pi's `main()` and calls `createAgentSession()` directly, which means pi's two-pass argv parsing (that normally populates `runtime.flagValues`) never runs. Two things compensate:
+   - `loader.ts` pushes `--mcp-config ~/.kata-cli/agent/mcp.json` into `process.argv` — the adapter reads this at extension load time for `directTools` registration.
+   - `cli.ts` manually sets `runtime.flagValues.set('mcp-config', ...)` after `resourceLoader.reload()` — the adapter reads this via `pi.getFlag('mcp-config')` at `session_start` for the main initialization.
+
+3. **Config scaffolding** (`resource-loader.ts`): Creates a starter `~/.kata-cli/agent/mcp.json` on first launch. Never overwrites existing config.
+
+### Configuring MCP servers
+
+Edit `~/.kata-cli/agent/mcp.json` to add servers. Servers can use **stdio** (local process) or **HTTP** (remote endpoint) transport.
+
+#### Stdio servers (local process)
+
+Most MCP servers run as a local process via `npx`:
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "npx",
+      "args": ["-y", "some-mcp-server"],
+      "env": {
+        "API_KEY": "${MY_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+Environment variables support `${VAR}` interpolation from `process.env`.
+
+#### HTTP servers with OAuth (e.g. Linear)
+
+Many hosted MCP servers (Linear, Figma, etc.) use OAuth 2.1 authentication via the MCP spec. These require [`mcp-remote`](https://github.com/geelen/mcp-remote) as a stdio proxy that handles the OAuth browser flow:
+
+```json
+{
+  "mcpServers": {
+    "linear": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://mcp.linear.app/mcp"]
+    }
+  }
+}
+```
+
+On first connection, `mcp-remote` opens a browser window for OAuth consent. Tokens are cached in `~/.mcp-auth/` for subsequent sessions.
+
+**Linear MCP setup (complete example):**
+
+1. Add the server to `~/.kata-cli/agent/mcp.json`:
+   ```json
+   {
+     "settings": { "toolPrefix": "server", "idleTimeout": 10 },
+     "mcpServers": {
+       "linear": {
+         "command": "npx",
+         "args": ["-y", "mcp-remote", "https://mcp.linear.app/mcp"]
+       }
+     }
+   }
+   ```
+
+2. Restart Kata.
+
+3. Connect the server (triggers the OAuth flow in your browser):
+   ```
+   mcp({ connect: "linear" })
+   ```
+
+4. Authorize Kata in the browser when prompted by Linear.
+
+5. Use Linear tools:
+   ```
+   mcp({ server: "linear" })          — list all Linear tools
+   mcp({ search: "issues" })          — search for issue-related tools
+   mcp({ tool: "linear_list_teams" }) — call a specific tool
+   ```
+
+**Troubleshooting OAuth:**
+- If you see `internal server error`, clear cached auth: `rm -rf ~/.mcp-auth` and reconnect.
+- Make sure you're running a recent version of Node.js.
+- Use `/mcp` to check server status interactively.
+
+#### HTTP servers with bearer token auth
+
+For servers that accept API keys or personal access tokens:
+
+```json
+{
+  "mcpServers": {
+    "my-api": {
+      "url": "https://api.example.com/mcp",
+      "auth": "bearer",
+      "bearerTokenEnv": "MY_API_KEY"
+    }
+  }
+}
+```
+
+#### Importing existing configs
+
+Pull in your existing Claude Code, Cursor, or VS Code MCP configuration:
+
+```json
+{
+  "imports": ["claude-code", "cursor"],
+  "mcpServers": {}
+}
+```
+
+Supported sources: `cursor`, `claude-code`, `claude-desktop`, `vscode`, `windsurf`, `codex`.
+
+### Server lifecycle
+
+| Mode | Behavior |
+|------|----------|
+| `lazy` (default) | Connect on first tool call. Disconnect after idle timeout. Cached metadata keeps search/list working offline. |
+| `eager` | Connect at startup. No auto-reconnect on drop. |
+| `keep-alive` | Connect at startup. Auto-reconnect via health checks. |
+
+### Usage
+
+```
+mcp({ })                                 — show server status
+mcp({ server: "linear" })               — list tools from a server
+mcp({ search: "issues create" })         — search tools (space-separated words OR'd)
+mcp({ describe: "linear_save_issue" })   — show tool parameters
+mcp({ tool: "linear_list_teams" })       — call a tool (no args)
+mcp({ tool: "linear_save_issue", args: '{"title": "Bug fix"}' })  — call with args (JSON string)
+mcp({ connect: "linear" })               — force connect/reconnect a server
+/mcp                                      — interactive panel (status, tools, reconnect, OAuth)
+```
+
+### Known limitations
+
+- **OAuth servers require `mcp-remote`**: The adapter doesn't implement the MCP OAuth browser flow natively. Use `mcp-remote` as a stdio proxy for any server that requires OAuth (Linear, Figma remote, etc.).
+- **Figma remote MCP (`mcp.figma.com`)**: Blocks dynamic client registration — only whitelisted clients (Cursor, Claude Code, VS Code) can connect via OAuth. Use the Figma desktop app's local MCP server instead (`http://127.0.0.1:3845/mcp`), which requires Figma desktop with Dev Mode (paid plan).
+- **Metadata cache path**: `pi-mcp-adapter` caches tool metadata to `~/.pi/agent/mcp-cache.json` (hardcoded). This doesn't affect functionality — just means the cache lives outside Kata's config dir.
+- **OAuth token storage**: `mcp-remote` stores tokens in `~/.mcp-auth/`, separate from Kata's config dir.
+
 ## Key Conventions
 
 - All env var names use `KATA_` prefix (not `GSD_` or `PI_`)
@@ -106,3 +257,4 @@ Kata stores project state in `.kata/` at the project root:
 - Extensions are synced from `src/resources/extensions/` to `~/.kata-cli/agent/extensions/` on every launch
 - The `shared/` extension directory is a library, not an entry point — it's imported by other extensions
 - Branch naming for workflow: `kata/M001/S01` (milestone/slice)
+- MCP config lives at `~/.kata-cli/agent/mcp.json` (not `~/.pi/agent/mcp.json`)

package/src/resources/extensions/kata/preferences.ts

@@ -398,8 +398,9 @@ function parseFrontmatterBlock(frontmatter: string): KataPreferences {
     const valuePart = remainder.trim();
 
     if (valuePart === "") {
-      const nextLine = lines[i + 1] ?? "";
-      const nextTrimmed = nextLine.trim();
+      const nextNonEmptyLine =
+        lines.slice(i + 1).find((candidate) => candidate.trim() !== "") ?? "";
+      const nextTrimmed = nextNonEmptyLine.trim();
       if (nextTrimmed.startsWith("- ")) {
         const items: unknown[] = [];
         let j = i + 1;
@@ -481,9 +482,16 @@ function parseFrontmatterBlock(frontmatter: string): KataPreferences {
         current[key] = items;
         i = j - 1;
       } else {
-        const obj: Record<string, unknown> = {};
-        current[key] = obj;
-        stack.push({ indent, value: obj });
+        // Check if the next non-empty line is actually indented deeper (a real nested block).
+        // If not, this key simply has no value — skip it rather than creating an empty object.
+        const nextIndent =
+          nextNonEmptyLine.match(/^\s*/)?.[0].length ?? indent;
+        if (nextIndent > indent) {
+          const obj: Record<string, unknown> = {};
+          current[key] = obj;
+          stack.push({ indent, value: obj });
+        }
+        // else: key with no value and no nested block — leave it undefined
       }
       continue;
     }
@@ -494,9 +502,13 @@ function parseFrontmatterBlock(frontmatter: string): KataPreferences {
   return root as KataPreferences;
 }
 
-function parseScalar(value: string): string | number | boolean {
+function parseScalar(
+  value: string,
+): string | number | boolean | unknown[] | Record<string, never> {
   if (value === "true") return true;
   if (value === "false") return false;
+  if (value === "[]") return [];
+  if (value === "{}") return {};
   if (/^-?\d+$/.test(value)) return Number(value);
   return value.replace(/^['\"]|['\"]$/g, "");
 }

package/src/resources/extensions/kata/tests/preferences-frontmatter.test.mjs

@@ -0,0 +1,53 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const resolveTsHookPath = fileURLToPath(new URL('./resolve-ts.mjs', import.meta.url));
+const preferencesPath = fileURLToPath(new URL('../preferences.ts', import.meta.url));
+
+test('loadEffectiveKataPreferences preserves blank-line-separated skill_rules lists', () => {
+  const tmp = mkdtempSync(join(tmpdir(), 'kata-preferences-frontmatter-'));
+  const kataDir = join(tmp, '.kata');
+  mkdirSync(kataDir, { recursive: true });
+  writeFileSync(
+    join(kataDir, 'preferences.md'),
+    `---
+skill_rules:
+
+  - when: build
+    use:
+      - test-driven-development
+---
+`,
+  );
+
+  const script = `
+    import { loadEffectiveKataPreferences } from ${JSON.stringify(preferencesPath)};
+    const prefs = loadEffectiveKataPreferences();
+    console.log(JSON.stringify(prefs?.preferences.skill_rules ?? null));
+  `;
+
+  const output = execFileSync(
+    'node',
+    ['--import', resolveTsHookPath, '--experimental-strip-types', '-e', script],
+    {
+      cwd: tmp,
+      env: {
+        ...process.env,
+        HOME: tmp,
+      },
+      encoding: 'utf-8',
+    },
+  ).trim();
+
+  assert.deepEqual(JSON.parse(output), [
+    {
+      when: 'build',
+      use: ['test-driven-development'],
+    },
+  ]);
+});