@kata-sh/cli 0.1.1 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # 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 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, MCP server integration, and more.
 
 ## Quick Start
 
@@ -28,7 +28,7 @@ Kata CLI is a thin wrapper around pi-coding-agent. It does not fork pi — it co
 apps/cli/
   src/
     loader.ts              — Entry point: sets KATA_* env vars, imports cli.ts
-    cli.ts                 — Calls pi-coding-agent's main()
+    cli.ts                 — Calls createAgentSession() + InteractiveMode
     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
@@ -47,8 +47,12 @@ apps/cli/
 
 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
+3. `loader.ts` injects `--mcp-config ~/.kata-cli/agent/mcp.json` into `process.argv` for the MCP adapter
+4. `resource-loader.ts` syncs bundled extensions, agents, skills, and `AGENTS.md` to `~/.kata-cli/agent/` on every launch
+5. `resource-loader.ts` scaffolds a starter `mcp.json` on first launch (never overwrites existing config)
+6. `cli.ts` seeds `npm:pi-mcp-adapter` into settings so pi auto-installs it
+7. `cli.ts` injects the `mcp-config` flag into the extension runtime (required because Kata bypasses pi's `main()` and its two-pass argv parsing)
+8. `cli.ts` calls `createAgentSession()` + `InteractiveMode` — pi handles everything from there
 
 ## Bundled Extensions
 
@@ -64,6 +68,136 @@ apps/cli/
 | `mac-tools/` | macOS-specific utilities |
 | `shared/` | Shared UI components (library, not an entry point) |
 
+## MCP Support
+
+Kata ships with [MCP](https://modelcontextprotocol.io/) (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 in context) gives the agent on-demand access to any MCP server's tools without burning context on individual tool definitions.
+
+### How It Works
+
+The MCP integration has three parts:
+
+1. **Package seeding**: `cli.ts` ensures `npm:pi-mcp-adapter` is in the settings packages list on every startup. Pi's package manager auto-installs it globally if missing.
+2. **Config path injection**: `loader.ts` pushes `--mcp-config` into `process.argv` and `cli.ts` sets the flag on `runtime.flagValues` — both are needed because the adapter reads the config path at two different points in its lifecycle.
+3. **Config scaffolding**: `resource-loader.ts` creates a starter `~/.kata-cli/agent/mcp.json` on first launch. Never overwrites existing config.
+
+### Adding MCP Servers
+
+Edit `~/.kata-cli/agent/mcp.json`:
+
+```json
+{
+  "settings": {
+    "toolPrefix": "server",
+    "idleTimeout": 10
+  },
+  "mcpServers": {}
+}
+```
+
+#### Example: Linear (OAuth via mcp-remote)
+
+Many hosted MCP servers (Linear, etc.) use OAuth 2.1 authentication. These require [`mcp-remote`](https://github.com/geelen/mcp-remote) as a stdio proxy that handles the browser-based OAuth flow:
+
+```json
+{
+  "settings": { "toolPrefix": "server", "idleTimeout": 10 },
+  "mcpServers": {
+    "linear": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://mcp.linear.app/mcp"]
+    }
+  }
+}
+```
+
+After adding the config and restarting Kata:
+
+1. Connect the server (opens browser for OAuth):
+   ```
+   mcp({ connect: "linear" })
+   ```
+2. Authorize in the browser when prompted by Linear.
+3. Use tools:
+   ```
+   mcp({ server: "linear" })              — list all Linear tools
+   mcp({ search: "issues" })              — search for issue-related tools
+   mcp({ tool: "linear_list_teams" })     — call a tool
+   ```
+
+Tokens are cached in `~/.mcp-auth/` for subsequent sessions. If you hit errors, clear cached auth with `rm -rf ~/.mcp-auth` and reconnect.
+
+#### Example: Stdio server with env vars
+
+```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`.
+
+#### Example: HTTP server with bearer token
+
+```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: `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 Reference
+
+| Command | Description |
+|---------|-------------|
+| `mcp({ })` | Show server status |
+| `mcp({ server: "name" })` | List tools from a server |
+| `mcp({ search: "query" })` | Search tools (space-separated words OR'd) |
+| `mcp({ describe: "tool_name" })` | Show tool parameters |
+| `mcp({ tool: "name", args: '{}' })` | Call a tool (args is a JSON string) |
+| `mcp({ connect: "name" })` | Force connect/reconnect a server |
+| `/mcp` | Interactive panel (status, tools, reconnect) |
+
+### 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 OAuth servers.
+- **Figma remote MCP** (`mcp.figma.com`): Blocks dynamic client registration — only whitelisted clients can connect via OAuth. Use Figma's desktop app local MCP server instead (`http://127.0.0.1:3845/mcp`), which requires Dev Mode (paid plan).
+- **Metadata cache**: `pi-mcp-adapter` caches tool metadata to `~/.pi/agent/mcp-cache.json` (hardcoded path, doesn't affect functionality).
+- **OAuth token storage**: `mcp-remote` stores tokens in `~/.mcp-auth/`, separate from Kata's config dir.
+
 ## The /kata Command
 
 The main extension registers `/kata` with subcommands:
@@ -111,8 +245,9 @@ Kata uses `~/.kata-cli/` (not `~/.kata/`) to avoid collision with other Kata app
     agents/              — Synced from src/resources/agents/
     skills/              — Synced from src/resources/skills/
     AGENTS.md            — Synced from src/resources/AGENTS.md
+    mcp.json             — MCP server configuration (scaffolded on first launch, never overwritten)
     auth.json            — API keys
-    settings.json        — User settings
+    settings.json        — User settings (includes packages: ["npm:pi-mcp-adapter"])
     models.json          — Custom model definitions
   sessions/              — Session history
   preferences.md         — Global Kata preferences
@@ -130,6 +265,7 @@ Set by `loader.ts` before pi starts:
 | `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 |
+| `KATA_MCP_CONFIG_PATH` | Absolute path to `~/.kata-cli/agent/mcp.json` |
 
 ## Development
 
@@ -143,7 +279,7 @@ npm run copy-themes
 # Run
 node dist/loader.js
 
-# Test
+# Test (37 tests: app smoke, resource sync, MCP integration, package validation)
 npm test
 ```
 

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.1",
+  "version": "0.2.0",
   "description": "Kata CLI coding agent",
   "license": "MIT",
   "private": false,

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/` 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/docs/preferences-reference.md

@@ -1,6 +1,6 @@
 # Kata Preferences Reference
 
-Full documentation for `~/.kata/preferences.md` (global) and `.kata/preferences.md` (project).
+Full documentation for `~/.kata-cli/preferences.md` (global) and `.kata/preferences.md` (project).
 
 ---
 

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

@@ -132,7 +132,7 @@ auto_supervisor: {}
 
 Project-specific guidance for skill selection and execution preferences.
 
-See \`~/.kata/agent/extensions/kata/docs/preferences-reference.md\` for full field documentation and examples.
+See \`~/.kata-cli/agent/extensions/kata/docs/preferences-reference.md\` for full field documentation and examples.
 
 ## Fields
 

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

@@ -122,7 +122,7 @@ export interface SkillResolutionReport {
 
 /**
  * Known skill directories, in priority order.
- * User skills (~/.kata/agent/skills/) take precedence over project skills.
+ * User skills (~/.kata-cli/agent/skills/) take precedence over project skills.
  */
 function getSkillSearchDirs(
   cwd: string,
@@ -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/prompts/complete-milestone.md

@@ -7,7 +7,7 @@ All relevant context has been preloaded below — the roadmap, all slice summari
 {{inlinedContext}}
 
 Then:
-1. Read the milestone-summary template at `~/.kata/agent/extensions/kata/templates/milestone-summary.md`
+1. Read the milestone-summary template at `~/.kata-cli/agent/extensions/kata/templates/milestone-summary.md`
 2. If a `Kata Skill Preferences` block is present in system context, use it to decide which skills to load and follow during completion, without relaxing required verification or artifact rules
 3. Verify each **success criterion** from the milestone definition in `{{roadmapPath}}`. For each criterion, confirm it was met with specific evidence from slice summaries, test results, or observable behavior. List any criterion that was NOT met.
 4. Verify the milestone's **definition of done** — all slices are `[x]`, all slice summaries exist, and any cross-slice integration points work correctly.

package/src/resources/extensions/kata/prompts/complete-slice.md

@@ -8,8 +8,8 @@ All relevant context has been preloaded below — the slice plan, all task summa
 
 Then:
 1. Read the templates:
-   - `~/.kata/agent/extensions/kata/templates/slice-summary.md`
-   - `~/.kata/agent/extensions/kata/templates/uat.md`
+   - `~/.kata-cli/agent/extensions/kata/templates/slice-summary.md`
+   - `~/.kata-cli/agent/extensions/kata/templates/uat.md`
 2. If a `Kata Skill Preferences` block is present in system context, use it to decide which skills to load and follow during completion, without relaxing required verification or artifact rules
 3. Run all slice-level verification checks defined in the slice plan. All must pass before marking the slice done. If any fail, fix them first.
 4. Confirm the slice's observability/diagnostic surfaces are real and useful where relevant: status inspection works, failure state is externally visible, structured errors/logs are actionable, and hidden failures are not being mistaken for success.

package/src/resources/extensions/kata/prompts/discuss.md

@@ -126,11 +126,11 @@ Directories use bare IDs. Files use ID-SUFFIX format. Titles live inside file co
 
 Once the user is satisfied, in a single pass:
 1. `mkdir -p .kata/milestones/{{milestoneId}}/slices`
-2. Write or update `.kata/PROJECT.md` — read the template at `~/.kata/agent/extensions/kata/templates/project.md` first. Describe what the project is, its current state, and list the milestone sequence.
-3. Write or update `.kata/REQUIREMENTS.md` — read the template at `~/.kata/agent/extensions/kata/templates/requirements.md` first. Confirm requirement states, ownership, and traceability before roadmap creation.
-4. Write `{{contextAbsPath}}` — read the template at `~/.kata/agent/extensions/kata/templates/context.md` first. Preserve key risks, unknowns, existing codebase constraints, integration points, and relevant requirements surfaced during discussion.
-5. Write `{{roadmapAbsPath}}` — read the template at `~/.kata/agent/extensions/kata/templates/roadmap.md` first. Decompose into demoable vertical slices with checkboxes, risk, depends, demo sentences, proof strategy, verification classes, milestone definition of done, requirement coverage, and a boundary map. If the milestone crosses multiple runtime boundaries, include an explicit final integration slice that proves the assembled system works end-to-end in a real environment.
-6. Seed `.kata/DECISIONS.md` — read the template at `~/.kata/agent/extensions/kata/templates/decisions.md` first. Append rows for any architectural or pattern decisions made during discussion.
+2. Write or update `.kata/PROJECT.md` — read the template at `~/.kata-cli/agent/extensions/kata/templates/project.md` first. Describe what the project is, its current state, and list the milestone sequence.
+3. Write or update `.kata/REQUIREMENTS.md` — read the template at `~/.kata-cli/agent/extensions/kata/templates/requirements.md` first. Confirm requirement states, ownership, and traceability before roadmap creation.
+4. Write `{{contextAbsPath}}` — read the template at `~/.kata-cli/agent/extensions/kata/templates/context.md` first. Preserve key risks, unknowns, existing codebase constraints, integration points, and relevant requirements surfaced during discussion.
+5. Write `{{roadmapAbsPath}}` — read the template at `~/.kata-cli/agent/extensions/kata/templates/roadmap.md` first. Decompose into demoable vertical slices with checkboxes, risk, depends, demo sentences, proof strategy, verification classes, milestone definition of done, requirement coverage, and a boundary map. If the milestone crosses multiple runtime boundaries, include an explicit final integration slice that proves the assembled system works end-to-end in a real environment.
+6. Seed `.kata/DECISIONS.md` — read the template at `~/.kata-cli/agent/extensions/kata/templates/decisions.md` first. Append rows for any architectural or pattern decisions made during discussion.
 7. Update `.kata/STATE.md`
 8. Commit: `docs({{milestoneId}}): context, requirements, and roadmap`
 
@@ -140,8 +140,8 @@ After writing the files and committing, say exactly: "Milestone {{milestoneId}}
 
 Once the user confirms the milestone split, in a single pass:
 1. `mkdir -p .kata/milestones/{{milestoneId}}/slices` for each milestone
-2. Write `.kata/PROJECT.md` — read the template at `~/.kata/agent/extensions/kata/templates/project.md` first.
-3. Write `.kata/REQUIREMENTS.md` — read the template at `~/.kata/agent/extensions/kata/templates/requirements.md` first. Capture Active, Deferred, Out of Scope, and any already Validated requirements. Later milestones may have provisional ownership where slice plans do not exist yet.
+2. Write `.kata/PROJECT.md` — read the template at `~/.kata-cli/agent/extensions/kata/templates/project.md` first.
+3. Write `.kata/REQUIREMENTS.md` — read the template at `~/.kata-cli/agent/extensions/kata/templates/requirements.md` first. Capture Active, Deferred, Out of Scope, and any already Validated requirements. Later milestones may have provisional ownership where slice plans do not exist yet.
 4. Write a `CONTEXT.md` for **every** milestone — capture the intent, scope, risks, constraints, user-visible outcome, completion class, final integrated acceptance, and relevant requirements for each. Each future milestone's CONTEXT.md should be rich enough that a planning agent encountering it fresh — with no memory of this conversation — can understand the intent, constraints, dependencies, what this milestone unlocks, and what "done" looks like.
 5. Write a `ROADMAP.md` for **only the first milestone** — detail-planning later milestones now is waste because the codebase will change. Include requirement coverage and a milestone definition of done.
 6. Seed `.kata/DECISIONS.md`.

package/src/resources/extensions/kata/prompts/execute-task.md

@@ -50,8 +50,8 @@ Then:
     - Know when to stop. If you've tried 3+ fixes without progress, your mental model is probably wrong. Stop. List what you know for certain. List what you've ruled out. Form fresh hypotheses from there.
     - Don't fix symptoms. Understand *why* something fails before changing code. A test that passes after a change you don't understand is luck, not a fix.
 11. **Blocker discovery:** If execution reveals that the remaining slice plan is fundamentally invalid — not just a bug or minor deviation, but a plan-invalidating finding like a wrong API, missing capability, or architectural mismatch — set `blocker_discovered: true` in the task summary frontmatter and describe the blocker clearly in the summary narrative. Do NOT set `blocker_discovered: true` for ordinary debugging, minor deviations, or issues that can be fixed within the current task or the remaining plan. This flag triggers an automatic replan of the slice.
-12. If you made an architectural, pattern, library, or observability decision during this task that downstream work should know about, append it to `.kata/DECISIONS.md` (read the template at `~/.kata/agent/extensions/kata/templates/decisions.md` if the file doesn't exist yet). Not every task produces decisions — only append when a meaningful choice was made.
-13. Read the template at `~/.kata/agent/extensions/kata/templates/task-summary.md`
+12. If you made an architectural, pattern, library, or observability decision during this task that downstream work should know about, append it to `.kata/DECISIONS.md` (read the template at `~/.kata-cli/agent/extensions/kata/templates/decisions.md` if the file doesn't exist yet). Not every task produces decisions — only append when a meaningful choice was made.
+13. Read the template at `~/.kata-cli/agent/extensions/kata/templates/task-summary.md`
 14. Write `{{taskSummaryAbsPath}}`
 15. Mark {{taskId}} done in `{{planPath}}` (change `[ ]` to `[x]`)
 16. Commit your work: `git add -A && git commit -m 'feat({{sliceId}}/{{taskId}}): <what was built>'`. If `git add` silently fails to stage files (a known git worktree stat-cache bug), use this workaround per file: `git update-index --cacheinfo 100644,$(git hash-object -w <file>),<file>` then commit. If that also fails, move on — the system will auto-commit remaining changes after your session ends.

package/src/resources/extensions/kata/prompts/guided-complete-slice.md

@@ -1 +1 @@
-Complete slice {{sliceId}} ("{{sliceTitle}}") of milestone {{milestoneId}}. All tasks are done. Read the templates at `~/.kata/agent/extensions/kata/templates/slice-summary.md` and `uat.md`. If a `Kata Skill Preferences` block is present in system context, use it to decide which skills to load and follow during completion, without relaxing required verification or artifact rules. Write `{{sliceId}}-SUMMARY.md` (compress task summaries), write `{{sliceId}}-UAT.md`, and fill the `UAT Type` plus `Not Proven By This UAT` sections explicitly so the artifact states what class of acceptance it covers and what still remains unproven. Review task summaries for `key_decisions` and ensure any significant ones are in `.kata/DECISIONS.md`. Mark the slice checkbox done in the roadmap, update STATE.md, update milestone summary, and leave the slice branch clean for the extension to squash-merge back to main automatically.
+Complete slice {{sliceId}} ("{{sliceTitle}}") of milestone {{milestoneId}}. All tasks are done. Read the templates at `~/.kata-cli/agent/extensions/kata/templates/slice-summary.md` and `uat.md`. If a `Kata Skill Preferences` block is present in system context, use it to decide which skills to load and follow during completion, without relaxing required verification or artifact rules. Write `{{sliceId}}-SUMMARY.md` (compress task summaries), write `{{sliceId}}-UAT.md`, and fill the `UAT Type` plus `Not Proven By This UAT` sections explicitly so the artifact states what class of acceptance it covers and what still remains unproven. Review task summaries for `key_decisions` and ensure any significant ones are in `.kata/DECISIONS.md`. Mark the slice checkbox done in the roadmap, update STATE.md, update milestone summary, and leave the slice branch clean for the extension to squash-merge back to main automatically.

package/src/resources/extensions/kata/prompts/guided-discuss-milestone.md

@@ -1,3 +1,3 @@
-Discuss milestone {{milestoneId}} ("{{milestoneTitle}}"). Identify gray areas, ask the user about them, and write `{{milestoneId}}-CONTEXT.md` in the milestone directory with the decisions. Read the template at `~/.kata/agent/extensions/kata/templates/context.md` first. If a `Kata Skill Preferences` block is present in system context, use it to decide which skills to load and follow; do not override required artifact rules.
+Discuss milestone {{milestoneId}} ("{{milestoneTitle}}"). Identify gray areas, ask the user about them, and write `{{milestoneId}}-CONTEXT.md` in the milestone directory with the decisions. Read the template at `~/.kata-cli/agent/extensions/kata/templates/context.md` first. If a `Kata Skill Preferences` block is present in system context, use it to decide which skills to load and follow; do not override required artifact rules.
 
 **Investigate between question rounds to make your questions smarter.** Before each round of questions, do enough lightweight research that your questions are grounded in reality — not guesses about what exists or what's possible. Check library docs (`resolve_library`/`get_library_docs`) when tech choices are relevant, search the web (`search-the-web` with `freshness`/`domain` filters, then `fetch_page` for full content) to verify the landscape, scout the codebase (`rg`, `find`, `scout`) to understand what already exists. Don't go deep — just enough that your next question reflects what's actually true. The goal is to ask questions the user can't answer by saying "did you check the docs?" or "look at the code."

package/src/resources/extensions/kata/prompts/guided-discuss-slice.md

@@ -45,7 +45,7 @@ If the user wants to keep going, keep asking. Stop when they say wrap up.
 
 Once the user is ready to wrap up:
 
-1. Read the slice context template at `~/.kata/agent/extensions/kata/templates/slice-context.md`
+1. Read the slice context template at `~/.kata-cli/agent/extensions/kata/templates/slice-context.md`
 2. `mkdir -p {{sliceDirAbsPath}}`
 3. Write `{{contextAbsPath}}` — use the template structure, filling in:
    - **Goal** — one sentence: what this slice delivers

package/src/resources/extensions/kata/prompts/guided-execute-task.md

@@ -1 +1 @@
-Execute the next task: {{taskId}} ("{{taskTitle}}") in slice {{sliceId}} of milestone {{milestoneId}}. Read the task plan (`{{taskId}}-PLAN.md`), load relevant summaries from prior tasks, and execute each step. Verify must-haves when done. If the task touches UI, browser flows, DOM behavior, or user-visible web state, exercise the real flow in the browser, prefer `browser_batch` for obvious sequences, prefer `browser_assert` for explicit pass/fail verification, use `browser_diff` when an action's effect is ambiguous, and use browser diagnostics when validating async or failure-prone UI. If you made an architectural, pattern, or library decision, append it to `.kata/DECISIONS.md`. Read the template at `~/.kata/agent/extensions/kata/templates/task-summary.md`. Write `{{taskId}}-SUMMARY.md`, mark it done, commit, and advance. If a `Kata Skill Preferences` block is present in system context, use it to decide which skills to load and follow during execution, without relaxing required verification or artifact rules. If running long and not all steps are finished, stop implementing and prioritize writing a clean partial summary over attempting one more step — a recoverable handoff is more valuable than a half-finished step with no documentation. If verification fails, debug methodically: form a hypothesis and test that specific theory before changing anything, change one variable at a time, read entire functions not just the suspect line, distinguish observable facts from assumptions, and if 3+ fixes fail without progress stop and reassess your mental model — list what you know for certain, what you've ruled out, and form fresh hypotheses. Don't fix symptoms — understand why something fails before changing code.
+Execute the next task: {{taskId}} ("{{taskTitle}}") in slice {{sliceId}} of milestone {{milestoneId}}. Read the task plan (`{{taskId}}-PLAN.md`), load relevant summaries from prior tasks, and execute each step. Verify must-haves when done. If the task touches UI, browser flows, DOM behavior, or user-visible web state, exercise the real flow in the browser, prefer `browser_batch` for obvious sequences, prefer `browser_assert` for explicit pass/fail verification, use `browser_diff` when an action's effect is ambiguous, and use browser diagnostics when validating async or failure-prone UI. If you made an architectural, pattern, or library decision, append it to `.kata/DECISIONS.md`. Read the template at `~/.kata-cli/agent/extensions/kata/templates/task-summary.md`. Write `{{taskId}}-SUMMARY.md`, mark it done, commit, and advance. If a `Kata Skill Preferences` block is present in system context, use it to decide which skills to load and follow during execution, without relaxing required verification or artifact rules. If running long and not all steps are finished, stop implementing and prioritize writing a clean partial summary over attempting one more step — a recoverable handoff is more valuable than a half-finished step with no documentation. If verification fails, debug methodically: form a hypothesis and test that specific theory before changing anything, change one variable at a time, read entire functions not just the suspect line, distinguish observable facts from assumptions, and if 3+ fixes fail without progress stop and reassess your mental model — list what you know for certain, what you've ruled out, and form fresh hypotheses. Don't fix symptoms — understand why something fails before changing code.

package/src/resources/extensions/kata/prompts/guided-plan-milestone.md

@@ -1,4 +1,4 @@
-Plan milestone {{milestoneId}} ("{{milestoneTitle}}"). Read `.kata/DECISIONS.md` if it exists — respect existing decisions. Read `.kata/REQUIREMENTS.md` if it exists and treat Active requirements as the capability contract. If `REQUIREMENTS.md` is missing, continue in legacy compatibility mode but explicitly note missing requirement coverage. Read the template at `~/.kata/agent/extensions/kata/templates/roadmap.md`. Create `{{milestoneId}}-ROADMAP.md` in the milestone directory with slices, risk levels, dependencies, demo sentences, verification classes, milestone definition of done, requirement coverage, and a boundary map. Write success criteria as observable truths, not implementation tasks. If the milestone crosses multiple runtime boundaries, include an explicit final integration slice that proves the assembled system works end-to-end in a real environment. If planning produces structural decisions, append them to `.kata/DECISIONS.md`. If a `Kata Skill Preferences` block is present in system context, use it to decide which skills to load and follow during planning, without overriding required roadmap formatting.
+Plan milestone {{milestoneId}} ("{{milestoneTitle}}"). Read `.kata/DECISIONS.md` if it exists — respect existing decisions. Read `.kata/REQUIREMENTS.md` if it exists and treat Active requirements as the capability contract. If `REQUIREMENTS.md` is missing, continue in legacy compatibility mode but explicitly note missing requirement coverage. Read the template at `~/.kata-cli/agent/extensions/kata/templates/roadmap.md`. Create `{{milestoneId}}-ROADMAP.md` in the milestone directory with slices, risk levels, dependencies, demo sentences, verification classes, milestone definition of done, requirement coverage, and a boundary map. Write success criteria as observable truths, not implementation tasks. If the milestone crosses multiple runtime boundaries, include an explicit final integration slice that proves the assembled system works end-to-end in a real environment. If planning produces structural decisions, append them to `.kata/DECISIONS.md`. If a `Kata Skill Preferences` block is present in system context, use it to decide which skills to load and follow during planning, without overriding required roadmap formatting.
 
 ## Requirement Rules
 

package/src/resources/extensions/kata/prompts/guided-plan-slice.md

@@ -1 +1 @@
-Plan slice {{sliceId}} ("{{sliceTitle}}") of milestone {{milestoneId}}. Read `.kata/DECISIONS.md` if it exists — respect existing decisions. Read `.kata/REQUIREMENTS.md` if it exists — identify which Active requirements the roadmap says this slice owns or supports, and ensure the plan delivers them. Read the roadmap boundary map, any existing context/research files, and dependency summaries. Read the templates at `~/.kata/agent/extensions/kata/templates/plan.md` and `task-plan.md`. Decompose into tasks with must-haves. Fill the `Proof Level` and `Integration Closure` sections truthfully so the plan says what class of proof this slice really delivers and what end-to-end wiring still remains. Write `{{sliceId}}-PLAN.md` and individual `T##-PLAN.md` files in the `tasks/` subdirectory. If planning produces structural decisions, append them to `.kata/decisions.md`. If a `Kata Skill Preferences` block is present in system context, use it to decide which skills to load and follow during planning, without overriding required plan formatting. Before committing, self-audit the plan: every must-have maps to at least one task, every task has complete sections (steps, must-haves, verification, observability impact, inputs, and expected output), task ordering is consistent with no circular references, every pair of artifacts that must connect has an explicit wiring step, task scope targets 2–5 steps and 3–8 files (6–8 steps or 8–10 files — consider splitting; 10+ steps or 12+ files — must split), the plan honors locked decisions from context/research/decisions artifacts, the proof-level wording does not overclaim live integration if only fixture/contract proof is planned, every Active requirement this slice owns has at least one task with verification that proves it is met, and every task produces real user-facing progress — if the slice has a UI surface at least one task builds the real UI, if it has an API at least one task connects it to a real data source, and showing the completed result to a non-technical stakeholder would demonstrate real product progress rather than developer artifacts.
+Plan slice {{sliceId}} ("{{sliceTitle}}") of milestone {{milestoneId}}. Read `.kata/DECISIONS.md` if it exists — respect existing decisions. Read `.kata/REQUIREMENTS.md` if it exists — identify which Active requirements the roadmap says this slice owns or supports, and ensure the plan delivers them. Read the roadmap boundary map, any existing context/research files, and dependency summaries. Read the templates at `~/.kata-cli/agent/extensions/kata/templates/plan.md` and `task-plan.md`. Decompose into tasks with must-haves. Fill the `Proof Level` and `Integration Closure` sections truthfully so the plan says what class of proof this slice really delivers and what end-to-end wiring still remains. Write `{{sliceId}}-PLAN.md` and individual `T##-PLAN.md` files in the `tasks/` subdirectory. If planning produces structural decisions, append them to `.kata/decisions.md`. If a `Kata Skill Preferences` block is present in system context, use it to decide which skills to load and follow during planning, without overriding required plan formatting. Before committing, self-audit the plan: every must-have maps to at least one task, every task has complete sections (steps, must-haves, verification, observability impact, inputs, and expected output), task ordering is consistent with no circular references, every pair of artifacts that must connect has an explicit wiring step, task scope targets 2–5 steps and 3–8 files (6–8 steps or 8–10 files — consider splitting; 10+ steps or 12+ files — must split), the plan honors locked decisions from context/research/decisions artifacts, the proof-level wording does not overclaim live integration if only fixture/contract proof is planned, every Active requirement this slice owns has at least one task with verification that proves it is met, and every task produces real user-facing progress — if the slice has a UI surface at least one task builds the real UI, if it has an API at least one task connects it to a real data source, and showing the completed result to a non-technical stakeholder would demonstrate real product progress rather than developer artifacts.

package/src/resources/extensions/kata/prompts/guided-research-slice.md

@@ -1,4 +1,4 @@
-Research slice {{sliceId}} ("{{sliceTitle}}") of milestone {{milestoneId}}. Read `.kata/DECISIONS.md` if it exists — respect existing decisions, don't contradict them. Read `.kata/REQUIREMENTS.md` if it exists — identify which Active requirements this slice owns or supports and target research toward risks, unknowns, and constraints that could affect delivery of those requirements. If a `Kata Skill Preferences` block is present in system context, use it to decide which skills to load and follow during research, without relaxing required verification or artifact rules. Explore the relevant code — use `rg`/`find` for targeted reads, or `scout` if the area is broad or unfamiliar. Check libraries with `resolve_library`/`get_library_docs`. Read the template at `~/.kata/agent/extensions/kata/templates/research.md`. Write `{{sliceId}}-RESEARCH.md` in the slice directory with summary, don't-hand-roll, common pitfalls, and relevant code sections.
+Research slice {{sliceId}} ("{{sliceTitle}}") of milestone {{milestoneId}}. Read `.kata/DECISIONS.md` if it exists — respect existing decisions, don't contradict them. Read `.kata/REQUIREMENTS.md` if it exists — identify which Active requirements this slice owns or supports and target research toward risks, unknowns, and constraints that could affect delivery of those requirements. If a `Kata Skill Preferences` block is present in system context, use it to decide which skills to load and follow during research, without relaxing required verification or artifact rules. Explore the relevant code — use `rg`/`find` for targeted reads, or `scout` if the area is broad or unfamiliar. Check libraries with `resolve_library`/`get_library_docs`. Read the template at `~/.kata-cli/agent/extensions/kata/templates/research.md`. Write `{{sliceId}}-RESEARCH.md` in the slice directory with summary, don't-hand-roll, common pitfalls, and relevant code sections.
 
 ## Strategic Questions to Answer
 

package/src/resources/extensions/kata/prompts/plan-milestone.md

@@ -7,13 +7,13 @@ All relevant context has been preloaded below — start working immediately with
 {{inlinedContext}}
 
 Then:
-1. Read the template at `~/.kata/agent/extensions/kata/templates/roadmap.md`
+1. Read the template at `~/.kata-cli/agent/extensions/kata/templates/roadmap.md`
 2. Read `.kata/REQUIREMENTS.md` if it exists. Treat **Active** requirements as the capability contract for planning. If it does not exist, continue in legacy compatibility mode but explicitly note that requirement coverage is operating without a contract.
 3. If a `Kata Skill Preferences` block is present in system context, use it to decide which skills to load and follow during planning, without overriding required roadmap formatting
 4. Create the roadmap: decompose into demoable vertical slices — as many as the work needs, no more
 5. Order by risk (high-risk first)
 6. Write `{{outputPath}}` with checkboxes, risk, depends, demo sentences, proof strategy, verification classes, milestone definition of done, **requirement coverage**, and a boundary map. Write success criteria as observable truths, not implementation tasks. If the milestone crosses multiple runtime boundaries, include an explicit final integration slice that proves the assembled system works end-to-end in a real environment
-7. If planning produced structural decisions (e.g. slice ordering rationale, technology choices, scope exclusions), append them to `.kata/DECISIONS.md` (read the template at `~/.kata/agent/extensions/kata/templates/decisions.md` if the file doesn't exist yet)
+7. If planning produced structural decisions (e.g. slice ordering rationale, technology choices, scope exclusions), append them to `.kata/DECISIONS.md` (read the template at `~/.kata-cli/agent/extensions/kata/templates/decisions.md` if the file doesn't exist yet)
 8. Update `.kata/STATE.md`
 
 ## Requirement Mapping Rules

package/src/resources/extensions/kata/prompts/plan-slice.md

@@ -15,8 +15,8 @@ Pay particular attention to **Forward Intelligence** sections — they contain h
 Then:
 0. If `REQUIREMENTS.md` was preloaded above, identify which Active requirements the roadmap says this slice owns or supports. These are the requirements this plan must deliver — every owned requirement needs at least one task that directly advances it, and verification must prove the requirement is met.
 1. Read the templates:
-   - `~/.kata/agent/extensions/kata/templates/plan.md`
-   - `~/.kata/agent/extensions/kata/templates/task-plan.md`
+   - `~/.kata-cli/agent/extensions/kata/templates/plan.md`
+   - `~/.kata-cli/agent/extensions/kata/templates/task-plan.md`
 2. If a `Kata Skill Preferences` block is present in system context, use it to decide which skills to load and follow during planning, without overriding required plan formatting
 3. Define slice-level verification first — the objective stopping condition for this slice:
    - For non-trivial slices: plan actual test files with real assertions. Name the files. The first task creates them (initially failing). Remaining tasks make them pass.

package/src/resources/extensions/kata/prompts/queue.md

@@ -69,7 +69,7 @@ Determine where the new milestones should go in the overall sequence. Consider d
 Once the user is satisfied, in a single pass for **each** new milestone (starting from {{nextId}}):
 
 1. `mkdir -p .kata/milestones/<ID>/slices`
-2. Write `.kata/milestones/<ID>/<ID>-CONTEXT.md` — read the template at `~/.kata/agent/extensions/kata/templates/context.md` first. Capture intent, scope, risks, constraints, integration points, and relevant requirements. Mark the status as "Queued — pending auto-mode execution."
+2. Write `.kata/milestones/<ID>/<ID>-CONTEXT.md` — read the template at `~/.kata-cli/agent/extensions/kata/templates/context.md` first. Capture intent, scope, risks, constraints, integration points, and relevant requirements. Mark the status as "Queued — pending auto-mode execution."
 
 Then, after all milestone directories and context files are written:
 

package/src/resources/extensions/kata/prompts/research-milestone.md

@@ -11,7 +11,7 @@ Then research the codebase and relevant technologies:
 2. **Skill Discovery ({{skillDiscoveryMode}}):**{{skillDiscoveryInstructions}}
 3. Explore relevant code. For small/familiar codebases, use `rg`, `find`, and targeted reads. For large or unfamiliar codebases, use `scout` to build a broad map efficiently before diving in.
 4. Use `resolve_library` / `get_library_docs` for unfamiliar libraries
-5. Read the template at `~/.kata/agent/extensions/kata/templates/research.md`
+5. Read the template at `~/.kata-cli/agent/extensions/kata/templates/research.md`
 6. If `.kata/REQUIREMENTS.md` exists, research against it. Identify which Active requirements are table stakes, likely omissions, overbuilt risks, or domain-standard behaviors the user may or may not want.
 7. Write `{{outputPath}}` with:
    - Summary (2-3 paragraphs, primary recommendation)

package/src/resources/extensions/kata/prompts/research-slice.md

@@ -18,7 +18,7 @@ Then research what this slice needs:
 2. **Skill Discovery ({{skillDiscoveryMode}}):**{{skillDiscoveryInstructions}}
 3. Explore relevant code for this slice's scope. For targeted exploration, use `rg`, `find`, and reads. For broad or unfamiliar subsystems, use `scout` to map the relevant area first.
 4. Use `resolve_library` / `get_library_docs` for unfamiliar libraries
-5. Read the template at `~/.kata/agent/extensions/kata/templates/research.md`
+5. Read the template at `~/.kata-cli/agent/extensions/kata/templates/research.md`
 6. Write `{{outputPath}}`
 
 The slice directory already exists at `{{slicePath}}/`. Do NOT mkdir — just write the file.

package/src/resources/extensions/kata/prompts/system.md

@@ -12,9 +12,9 @@ Kata ships with bundled skills. Load the relevant skill file with the `read` too
 
 | Trigger                                                                                          | Skill to load                                     |
 | ------------------------------------------------------------------------------------------------ | ------------------------------------------------- |
-| Frontend UI — web components, pages, landing pages, dashboards, React/HTML/CSS, styling          | `~/.kata/agent/skills/frontend-design/SKILL.md`   |
-| macOS or iOS apps — SwiftUI, Xcode, App Store                                                    | `~/.kata/agent/skills/swiftui/SKILL.md`           |
-| Debugging — complex bugs, failing tests, root-cause investigation after standard approaches fail | `~/.kata/agent/skills/debug-like-expert/SKILL.md` |
+| Frontend UI — web components, pages, landing pages, dashboards, React/HTML/CSS, styling          | `~/.kata-cli/agent/skills/frontend-design/SKILL.md`   |
+| macOS or iOS apps — SwiftUI, Xcode, App Store                                                    | `~/.kata-cli/agent/skills/swiftui/SKILL.md`           |
+| Debugging — complex bugs, failing tests, root-cause investigation after standard approaches fail | `~/.kata-cli/agent/skills/debug-like-expert/SKILL.md` |
 
 ## Hard Rules
 
@@ -84,7 +84,7 @@ Titles live inside file content (headings, frontmatter), not in file or director
 ### Artifact Templates
 
 Templates showing the expected format for each artifact type are in:
-`~/.kata/agent/extensions/kata/templates/`
+`~/.kata-cli/agent/extensions/kata/templates/`
 
 **Always read the relevant template before writing an artifact** to match the expected structure exactly. The parsers that read these files depend on specific formatting:
 

package/src/resources/extensions/kata/templates/preferences.md

@@ -12,4 +12,4 @@ auto_supervisor: {}
 
 # Kata Skill Preferences
 
-See `~/.kata/agent/extensions/kata/docs/preferences-reference.md` for full field documentation and examples.
+See `~/.kata-cli/agent/extensions/kata/docs/preferences-reference.md` for full field documentation and examples.

package/src/resources/extensions/kata/tests/complete-milestone.test.ts

@@ -9,7 +9,7 @@ import { join, dirname } from "node:path";
 import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 
-// loadPrompt reads from ~/.kata/agent/extensions/kata/prompts/ (main checkout).
+// loadPrompt reads from ~/.kata-cli/agent/extensions/kata/prompts/ (main checkout).
 // In a worktree the file may not exist there yet, so we resolve prompts
 // relative to this test file's location (the worktree copy).
 const __dirname = dirname(fileURLToPath(import.meta.url));

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'],
+    },
+  ]);
+});

package/src/resources/extensions/kata/tests/reassess-prompt.test.ts

@@ -2,7 +2,7 @@ import { readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
-// loadPrompt reads from ~/.kata/agent/extensions/kata/prompts/ (main checkout).
+// loadPrompt reads from ~/.kata-cli/agent/extensions/kata/prompts/ (main checkout).
 // In a worktree the file may not exist there yet, so we resolve prompts
 // relative to this test file's location (the worktree copy).
 const __dirname = dirname(fileURLToPath(import.meta.url));

package/src/resources/extensions/slash-commands/create-extension.ts

@@ -273,66 +273,66 @@ function sendPrompt(
     : "";
 
   const docHints: string[] = [
-    "- `~/.kata/agent/docs/extending-pi/01-what-are-extensions.md` — capabilities overview",
-    "- `~/.kata/agent/docs/extending-pi/03-getting-started.md` — minimal extension, hot reload",
-    "- `~/.kata/agent/docs/extending-pi/08-extensioncontext-what-you-can-access.md` — ExtensionContext API",
-    "- `~/.kata/agent/docs/extending-pi/09-extensionapi-what-you-can-do.md` — ExtensionAPI: registration, messaging",
-    "- `~/.kata/agent/docs/extending-pi/22-key-rules-gotchas.md` — must-read rules before shipping",
+    "- `~/.kata-cli/agent/docs/extending-pi/01-what-are-extensions.md` — capabilities overview",
+    "- `~/.kata-cli/agent/docs/extending-pi/03-getting-started.md` — minimal extension, hot reload",
+    "- `~/.kata-cli/agent/docs/extending-pi/08-extensioncontext-what-you-can-access.md` — ExtensionContext API",
+    "- `~/.kata-cli/agent/docs/extending-pi/09-extensionapi-what-you-can-do.md` — ExtensionAPI: registration, messaging",
+    "- `~/.kata-cli/agent/docs/extending-pi/22-key-rules-gotchas.md` — must-read rules before shipping",
   ];
 
   if (uiSelected.includes("custom component")) {
     docHints.push(
-      "- `~/.kata/agent/docs/extending-pi/12-custom-ui-visual-components.md` — dialogs, widgets, overlays",
+      "- `~/.kata-cli/agent/docs/extending-pi/12-custom-ui-visual-components.md` — dialogs, widgets, overlays",
     );
     docHints.push(
-      "- `~/.kata/agent/docs/pi-ui-tui/06-ctx-ui-custom-full-custom-components.md` — ctx.ui.custom() API",
+      "- `~/.kata-cli/agent/docs/pi-ui-tui/06-ctx-ui-custom-full-custom-components.md` — ctx.ui.custom() API",
     );
     docHints.push(
-      "- `~/.kata/agent/docs/pi-ui-tui/07-built-in-components-the-building-blocks.md` — Text, Box, SelectList",
+      "- `~/.kata-cli/agent/docs/pi-ui-tui/07-built-in-components-the-building-blocks.md` — Text, Box, SelectList",
     );
     docHints.push(
-      "- `~/.kata/agent/docs/pi-ui-tui/09-keyboard-input-how-to-handle-keys.md` — Key, matchesKey",
+      "- `~/.kata-cli/agent/docs/pi-ui-tui/09-keyboard-input-how-to-handle-keys.md` — Key, matchesKey",
     );
     docHints.push(
-      "- `~/.kata/agent/docs/pi-ui-tui/10-line-width-the-cardinal-rule.md` — truncation, width rules",
+      "- `~/.kata-cli/agent/docs/pi-ui-tui/10-line-width-the-cardinal-rule.md` — truncation, width rules",
     );
     docHints.push(
-      "- `~/.kata/agent/docs/pi-ui-tui/19-building-a-complete-component-step-by-step.md` — step-by-step guide",
+      "- `~/.kata-cli/agent/docs/pi-ui-tui/19-building-a-complete-component-step-by-step.md` — step-by-step guide",
     );
     docHints.push(
-      "- `~/.kata/agent/docs/pi-ui-tui/21-common-mistakes-and-how-to-avoid-them.md` — pitfalls",
+      "- `~/.kata-cli/agent/docs/pi-ui-tui/21-common-mistakes-and-how-to-avoid-them.md` — pitfalls",
     );
   } else if (uiSelected.includes("Dialogs")) {
     docHints.push(
-      "- `~/.kata/agent/docs/pi-ui-tui/04-built-in-dialog-methods.md` — select, confirm, input, editor",
+      "- `~/.kata-cli/agent/docs/pi-ui-tui/04-built-in-dialog-methods.md` — select, confirm, input, editor",
     );
   } else if (uiSelected.includes("Status")) {
     docHints.push(
-      "- `~/.kata/agent/docs/pi-ui-tui/05-persistent-ui-elements.md` — status, widgets, footer, header",
+      "- `~/.kata-cli/agent/docs/pi-ui-tui/05-persistent-ui-elements.md` — status, widgets, footer, header",
     );
   }
 
   if (uiSelected.includes("tool") || result.answers["purpose"]) {
     docHints.push(
-      "- `~/.kata/agent/docs/extending-pi/14-custom-rendering-controlling-what-the-user-sees.md` — renderCall / renderResult",
+      "- `~/.kata-cli/agent/docs/extending-pi/14-custom-rendering-controlling-what-the-user-sees.md` — renderCall / renderResult",
     );
   }
 
   if (eventsSelected && !eventsSelected.includes("standalone")) {
     docHints.push(
-      "- `~/.kata/agent/docs/extending-pi/07-events-the-nervous-system.md` — all events reference",
+      "- `~/.kata-cli/agent/docs/extending-pi/07-events-the-nervous-system.md` — all events reference",
     );
   }
 
   if (eventsSelected.includes("context / prompt")) {
     docHints.push(
-      "- `~/.kata/agent/docs/extending-pi/15-system-prompt-modification.md` — system prompt hooks",
+      "- `~/.kata-cli/agent/docs/extending-pi/15-system-prompt-modification.md` — system prompt hooks",
     );
   }
 
   if (persistenceSelected.includes("session")) {
     docHints.push(
-      "- `~/.kata/agent/docs/extending-pi/13-state-management-persistence.md` — pi.appendEntry, session state",
+      "- `~/.kata-cli/agent/docs/extending-pi/13-state-management-persistence.md` — pi.appendEntry, session state",
     );
   }
 
@@ -350,11 +350,11 @@ ${docHints.join("\n")}
 
 Write the complete implementation as a single self-contained extension file:
 
-\`~/.kata/agent/extensions/<kebab-case-name>.ts\`
+\`~/.kata-cli/agent/extensions/<kebab-case-name>.ts\`
 
 Then register it in the main extensions index:
 
-\`~/.kata/agent/extensions/index.ts\` — import and call the new extension's default export alongside existing ones
+\`~/.kata-cli/agent/extensions/index.ts\` — import and call the new extension's default export alongside existing ones
 
 ## Rules you must follow exactly
 

package/src/resources/extensions/slash-commands/create-slash-command.ts

@@ -257,8 +257,8 @@ function sendPrompt(
 ${contextSection}
 Write the complete file contents for two files:
 
-1. \`~/.kata/agent/extensions/slash-commands/<name>.ts\` — the command implementation
-2. Update \`~/.kata/agent/extensions/slash-commands/index.ts\` — import and register the new command alongside existing ones
+1. \`~/.kata-cli/agent/extensions/slash-commands/<name>.ts\` — the command implementation
+2. Update \`~/.kata-cli/agent/extensions/slash-commands/index.ts\` — import and register the new command alongside existing ones
 
 Rules you must follow exactly:
 - Command registration: \`pi.registerCommand("name", { description, handler })\`

package/src/resources/extensions/subagent/index.ts

@@ -502,7 +502,7 @@ export default function (pi: ExtensionAPI) {
       const discovery = discoverAgents(ctx.cwd, "both");
       if (discovery.agents.length === 0) {
         ctx.ui.notify(
-          "No agents found. Add .md files to ~/.kata/agent/agents/ or .kata/agents/",
+          "No agents found. Add .md files to ~/.kata-cli/agent/agents/ or .kata/agents/",
           "warning",
         );
         return;
@@ -525,7 +525,7 @@ export default function (pi: ExtensionAPI) {
       "Delegate tasks to specialized subagents with isolated context windows.",
       "Each subagent is a separate pi process with its own tools, model, and system prompt.",
       "Modes: single ({ agent, task }), parallel ({ tasks: [{agent, task},...] }), chain ({ chain: [{agent, task},...] } with {previous} placeholder).",
-      "Agents are defined as .md files in ~/.kata/agent/agents/ (user) or .kata/agents/ (project).",
+      "Agents are defined as .md files in ~/.kata-cli/agent/agents/ (user) or .kata/agents/ (project).",
       "Use the /subagent command to list available agents and their descriptions.",
       "Use chain mode to pipeline: scout finds context, planner designs, worker implements.",
     ].join(" "),