docs: improve ACP and MCP onboarding

Author: danielkov

.github/workflows/ci.yml

@@ -38,7 +38,7 @@ jobs:
           PYTHONDONTWRITEBYTECODE=1 python3 -m unittest scripts/tests/test_generate_acp_swift.py
           scripts/generate-acp-swift.py --check
           PATH="$RUNNER_TEMP/bin:$PATH" scripts/generate-macos-project.sh
-          git diff --exit-code -- macos/Config/Version.xcconfig macos/KitDesktop/Generated macos/KitDesktop.xcodeproj
+          git diff --exit-code -- macos/KitDesktop/Generated macos/KitDesktop.xcodeproj
       - name: Build real debug helper
         run: cargo build --locked --bin kit
       - name: Run Swift tests and real Kit lifecycle smoke

.gitignore

@@ -4,5 +4,6 @@
 /.kit/
 /worktrees/
 /.kit-codesign-identity
+/macos/Config/Version.xcconfig
 /.env
 .DS_Store

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "kit"
-version = "0.1.121"
+version = "0.1.122"
 edition = "2024"
 rust-version = "1.94.0"
 publish = false

Cargo.toml

@@ -2,6 +2,16 @@
 
 Kit merges Model Context Protocol (MCP) servers from Agent Plugins, `mcp_config` in `~/.kit/config.toml`, `.mcp.json` in the canonical runtime root, and `--mcp-config`, in that precedence order. A higher layer replaces a whole same-named server; non-conflicting lower-layer servers remain. The project file is optional, while configured and command-line files are required when specified. Relative configured and command-line paths retain launch-directory resolution. Run `kit --help` and `kit <command> --help` for the exhaustive CLI reference.
 
+## Ask the agent to add a server
+
+Kit does not provide an MCP-specific slash command. In a `kit tui` session, describe the server and the scope that you want:
+
+> Add the Linear MCP server at `https://mcp.linear.app/mcp` for this project. Preserve the existing entries in `.mcp.json`, add a description that will help you find its tools, validate the file, and help me authenticate.
+
+For a server that should be available in every project, ask the agent to update the file selected by `mcp_config` in `~/.kit/config.toml` instead. The agent should inspect the existing file before editing it, preserve unrelated servers, and never put a credential in the file unless you explicitly require static secret configuration. You can ask it to show the compact MCP status listing after the edit. New and changed servers load on the next `tool_search` or `auth` call without a restart.
+
+Files are not the only installation route. An Agent Plugin can contribute MCP servers, and `--mcp-config` can add an explicit JSON layer for one launch. The rest of this guide documents each route and the strict JSON format for manual edits.
+
 ## Agent Plugin MCP configuration
 
 Validated Agent Plugins can contribute `stdio` and `streamable-http` servers. Deprecated `sse` servers are skipped with a stderr diagnostic naming the plugin and server. Supported server names must be unique across plugins; a collision stops startup and identifies both plugin aliases.

README.md

@@ -0,0 +1,77 @@
+# Migrate from Claude Code or Codex
+
+Kit does not have a migration slash command or a fixed importer. Source harness formats change, and a useful migration usually needs choices about global versus project scope. Start Kit in the project that you want to migrate and ask the agent to inspect, translate, and validate the relevant configuration. This guide is bundled into Kit so the agent can search it with `docs`.
+
+## Start an assisted migration
+
+Run:
+
+```sh
+kit init
+kit auth login openai
+kit tui --root /path/to/project
+```
+
+This example uses Kit's default OpenAI subscription provider. If you selected OpenRouter or Speakeasy, authenticate that provider instead.
+
+Then use a prompt that states the sources and safety boundaries:
+
+> Read the bundled "Migrate from Claude Code or Codex" guide. Inspect my Claude Code and Codex project instructions, skills, and MCP configuration. Propose a mapping into Kit, preserve every source file, do not copy or print credentials, and ask before replacing or merging an existing Kit file. After I approve the plan, make the changes and validate the MCP status.
+
+You can narrow the request:
+
+- “Bring only this project's Claude Code MCP servers into Kit's project `.mcp.json`.”
+- “Merge the useful instructions from `CLAUDE.md` into `AGENTS.md`; show conflicts first.”
+- “Find my Codex MCP servers and convert them to Kit's global MCP JSON. Do not copy tokens or environment values that contain secrets.”
+- “Configure the Claude ACP adapter as an `acp.claude` designer subagent, with `designer` mapped to Opus. Keep my Claude Code files as migration sources, and do not change the default Kit harness.”
+
+The agent can read files outside the selected project when the Kit process has operating-system access to them. Keep the request scoped, and review proposed changes to home-directory configuration before approval.
+
+## Destination files in Kit
+
+| Concern | Kit destination | Notes |
+| --- | --- | --- |
+| Runtime, provider, model, and external ACP harnesses | `~/.kit/config.toml` | Command-line flags override this file. Authenticate providers and external harnesses separately. |
+| MCP servers for every project | The JSON file named by `mcp_config` in `~/.kit/config.toml`; `kit init` defaults it to `~/.kit/mcp.json` | The file uses a top-level `mcpServers` object. |
+| MCP servers for one project | `<project>/.mcp.json` | Kit discovers this file from the canonical `--root`. Project entries override same-named global entries. |
+| Project instructions | `AGENTS.md` at the project root or an ancestor | Kit loads the chain of `AGENTS.md` files from the root and its ancestors. |
+| Agent Skills | `<project>/.agents/skills` or `~/.agents/skills` | Each compatible skill is a package containing `SKILL.md`. Inspect scripts and dependencies before copying it. |
+
+Do not migrate provider tokens, OAuth caches, `auth.json`, Keychain entries, or another harness's credential files. Use `kit auth login openai`, `kit auth login openrouter`, or `kit auth login speakeasy` for Kit providers. A remote MCP server that challenges with OAuth appears as `authentication_required`; ask the agent to authenticate it in `kit tui`, `kit serve`, or `kit acp`.
+
+## Claude Code mapping
+
+Claude Code configuration can be user-scoped, project-scoped, managed, or supplied by plugins. Its exact locations and fields depend on the installed version, so the agent should inventory the active setup instead of assuming that every possible file exists. Common sources to inspect include `~/.claude.json`, project `.mcp.json`, `.claude/settings.json`, `.claude/settings.local.json`, `CLAUDE.md`, `.claude/CLAUDE.md`, and user or project skill directories.
+
+Map compatible content as follows:
+
+- **MCP:** extract the active `mcpServers` entries and convert only fields supported by Kit's strict MCP schema. Claude Code can expand `${VAR}` and `${VAR:-default}` placeholders in MCP values; Kit's normal JSON MCP layer does not. Detect every placeholder and either translate it to supported configuration or reject the entry with an unresolved expression. A project `.mcp.json` can remain in place only when it validates and has no incompatible expansion behavior. Decide whether user-scoped servers belong in Kit's global MCP file or should become project-local. Add a specific `description` for each server.
+- **Instructions:** merge durable repository guidance from Claude instruction files into the `AGENTS.md` chain for the selected root. Do not concatenate blindly: remove Claude-only directions and reconcile conflicts with existing instructions. Kit loads only the selected root and its ancestors, not descendant `AGENTS.md` files. Consolidate nested guidance when Kit runs at the repository root, or select the corresponding subproject as `--root` when that guidance should apply only there.
+- **Skills:** place compatible Agent Skills under `.agents/skills` or `~/.agents/skills`. Review each package before copying executable scripts or dependencies. Claude-specific slash commands, hooks, plugin metadata, and UI settings do not automatically become Kit skills.
+- **Permissions and hooks:** do not translate allowlists, approval settings, or hooks into an implied Kit sandbox. Kit is not a security boundary. Convert only useful behavioral guidance into explicit instructions, and use an operating-system or container boundary for enforcement.
+- **Models and login:** choose and authenticate Kit's provider separately. Kit cannot use a Claude subscription as credentials for its built-in `acp.kit` harness. The `@agentclientprotocol/claude-agent-acp` adapter includes the Claude Agent SDK CLI and authenticates separately with a Claude subscription or Anthropic Console; that choice determines billing and usage limits.
+
+## Codex mapping
+
+Codex and Kit both use `AGENTS.md`, but their discovery rules differ. Inventory `~/.codex/AGENTS.md`, `AGENTS.override.md`, and the files that Codex loads from the repository root down to its working directory. Kit does not recognize `AGENTS.override.md`; it loads `AGENTS.md` only at the selected root and its ancestors. Merge global or override guidance into the appropriate Kit `AGENTS.md`. Consolidate descendant guidance when Kit runs from the repository root, or select that subproject as Kit's `--root`.
+
+For the remaining setup:
+
+- **MCP:** inspect active `mcp_servers` tables in Codex configuration, commonly `~/.codex/config.toml` and project `.codex/config.toml`, and translate them into Kit's JSON `mcpServers` entries. Preserve command arguments and non-secret environment settings, but review transport names and omit fields that Kit does not support.
+- **Skills:** compatible Agent Skills that already live in `.agents/skills` or `~/.agents/skills` are directly discoverable by Kit. For skills stored in a Codex-specific location, inspect and copy the complete skill package to the matching Kit scope.
+- **Provider and model settings:** treat these as intent, not portable authentication. Select a Kit provider and model in `~/.kit/config.toml` or with command-line flags, then authenticate through Kit.
+- **Approval and sandbox settings:** these have no one-to-one Kit mapping. Do not claim that a Codex sandbox or approval policy carries over. Run Kit inside a trusted security boundary.
+- **Codex as a subagent:** an installed and authenticated Codex ACP adapter can be configured under `[acp.codex]`. It remains a separate harness; Kit sends ACP session traffic but does not inject Kit credentials, plugins, or MCP configuration into it.
+
+## Validate the result
+
+After editing, ask the agent to perform the smallest relevant checks:
+
+1. Parse `~/.kit/config.toml` and every changed MCP JSON file without displaying secret values.
+2. Ask for the compact MCP status listing and confirm that each intended server is present. Kit reloads MCP files before `tool_search` and `auth`, so a restart is not required.
+3. Authenticate challenged remote servers through Kit. Recreate credentials rather than copying another harness's token cache.
+4. Search for one expected MCP capability and verify that the correct server is selected.
+5. Start a new Kit session when validating changed `AGENTS.md` files or skills, because startup establishes the project instruction context and skill catalog.
+6. If an external ACP harness was added, run its own installation or login check first, then ask Kit to start one narrow test subagent.
+
+See [Getting started and configuration](getting-started-and-configuration.md), [Configure and Use MCP Servers](mcp.md), [Reusable subagents and ACP harnesses](subagents-and-acp-harnesses.md), and [Security, limits, and troubleshooting](security-limits-and-troubleshooting.md) for the destination formats and runtime behavior.

docs/user/mcp.md

@@ -1,6 +1,47 @@
 # Reusable subagents and ACP harnesses
 
-Kit can start parent-owned nested agents through the Agent Client Protocol (ACP). A subagent is a reusable Runlet value, not a detached background task: start it with `subagent`, continue the same session with `prompt`, branch its completed context with `fork`, list retained handles with `subagents({})`, or terminate one with `close`.
+Kit can start parent-owned nested agents through the [Agent Client Protocol (ACP)](https://agentclientprotocol.com/get-started/introduction). ACP is an open interface between an agent client and an agent runtime. That separation lets Kit orchestrate Kit, Claude Code, Codex, Cursor, and other compatible harnesses through one lifecycle instead of maintaining a custom integration for each one.
+
+A subagent is a reusable Runlet value, not a detached background task: start it with `subagent`, continue the same session with `prompt`, branch its completed context with `fork`, list retained handles with `subagents({})`, or terminate one with `close`.
+
+## Why use another harness from Kit?
+
+Keep Kit as the orchestrator and route only a bounded task to a specialist. The parent can start independent specialists concurrently, give each child explicit context, require structured output, continue a useful session, or fork an alternative. This makes the specialist's result composable with shell commands, edits, tests, MCP calls, and other agents in the same Runlet program.
+
+An external harness remains a separate program with its own configuration, tools, account, and usage limits. Kit does not turn a Claude subscription into provider credentials for the built-in `acp.kit` harness. The `@agentclientprotocol/claude-agent-acp` package includes the Claude Agent SDK CLI, so it does not require a separate Claude Code installation. Authenticate that adapter out of band with either a Claude subscription or Anthropic Console. With `--claudeai`, work counts against subscription limits instead of metered Console API billing; whether that costs less depends on the workload and plan. This also lets you choose a model for work where it is particularly effective—for example, Claude Opus for visual and graphic design—without moving the whole coding session out of Kit.
+
+Configure a descriptive alias for that route:
+
+```toml
+[acp.claude]
+command = "npx"
+args = ["-y", "@agentclientprotocol/claude-agent-acp@0.69.0"]
+permissions = "deny"
+
+[subagent.harnesses."acp.claude".models]
+designer = "opus"
+```
+
+Then ask for the configured specialist explicitly:
+
+```text
+design = subagent({
+  name: "Visual Designer",
+  harness: "acp.claude",
+  model: "designer",
+  prompt: "Review the existing dashboard and propose a coherent visual direction for the new analytics view. Return design guidance, not code."
+})
+return design.output
+```
+
+`designer` is a Kit-side alias for the model ID advertised by that ACP adapter. The external harness must accept the configured ID. Before starting the first Claude subagent, authenticate the adapter outside Kit:
+
+```sh
+npx -y @agentclientprotocol/claude-agent-acp@0.69.0 --cli auth login --claudeai  # Claude subscription
+# Use --console instead for Anthropic Console API billing.
+```
+
+Kit does not perform this login. You can start Kit before authenticating the adapter; authentication only needs to finish before the subagent starts.
 
 ## Start, prompt, and fork a reusable subagent
 

docs/user/migrating-from-claude-code-and-codex.md

@@ -57,7 +57,7 @@ xcodebuild \
   build
 ```
 
-Project generation rejects other XcodeGen builds, including a same-version Homebrew binary, unless they came from the checksum-pinned archive installed by the repository script. CI regenerates both the version configuration and checked-in project and fails on drift.
+Project generation rejects other XcodeGen builds, including a same-version Homebrew binary, unless they came from the checksum-pinned archive installed by the repository script. The generated `Config/Version.xcconfig` is intentionally untracked: every project generation derives it from `Cargo.toml`, so a package version bump does not require a second manual edit. CI regenerates that local version configuration and fails only when the checked-in Swift models or Xcode project drift.
 
 The build phase always removes the previous helper before atomically copying the selected executable to `Kit.app/Contents/Helpers/kit`; dependency analysis cannot preserve a stale copy. Release ignores `KIT_BINARY` and requires the exact `target/aarch64-apple-darwin/release/kit` output. When no bundled helper exists, runtime lookup honors `KIT_BINARY`, the inherited `PATH`, common Homebrew locations, `~/.cargo/bin`, and the user's login-shell `PATH`. Debug builds also check the repository's `target/debug/kit`.