diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index ca19fc4..d254f0d 100644
--- a/.github/workflows/ci.yml
+++ b/.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
diff --git a/.gitignore b/.gitignore
index 3b88e03..e3cd358 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,5 +4,6 @@
 /.kit/
 /worktrees/
 /.kit-codesign-identity
+/macos/Config/Version.xcconfig
 /.env
 .DS_Store
diff --git a/Cargo.lock b/Cargo.lock
index fb42aea..53728f6 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2554,7 +2554,7 @@ dependencies = [
 
 [[package]]
 name = "kit"
-version = "0.1.121"
+version = "0.1.122"
 dependencies = [
  "a2a-protocol-client",
  "a2a-protocol-server",
diff --git a/Cargo.toml b/Cargo.toml
index d6c4d7d..ea9fad9 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "kit"
-version = "0.1.121"
+version = "0.1.122"
 edition = "2024"
 rust-version = "1.94.0"
 publish = false
diff --git a/README.md b/README.md
index 56bfa93..b97242a 100644
--- a/README.md
+++ b/README.md
@@ -11,7 +11,8 @@
 
 <p align="center">
   Kit is a coding agent runtime. It gives the model <strong>one tool</strong> for writing and running programs.<br>
-  Kit provides a terminal client, an ACP server, an A2A endpoint, and a subagent orchestrator in one static binary.
+  Kit provides a terminal client, an <a href="https://agentclientprotocol.com/get-started/introduction">Agent Client Protocol (ACP)</a> server, an A2A endpoint, and a subagent orchestrator in one static binary.<br>
+  ACP separates agent clients from agent runtimes, so Kit works in compatible editors and can orchestrate other harnesses without custom integrations.
 </p>
 
 <p align="center">
@@ -105,6 +106,14 @@ kit serve --root /path/to/project --remote-acp --no-a2a --no-stdio --http 0.0.0.
 
 OpenRouter and Speakeasy use the same login process. Run `kit auth login openrouter` or `kit auth login speakeasy`. Then add `--provider openrouter --model anthropic/claude-sonnet-5` to the Kit command that you run. Providers and MCP servers share one credential backend (`--credential-store keychain|file|memory`).
 
+### Coming from Claude Code or Codex
+
+Read [Migrate from Claude Code or Codex](docs/user/migrating-from-claude-code-and-codex.md) for the file mappings, safety boundaries, and settings that need manual review. Or start `kit tui` in the existing project and paste this prompt:
+
+> Help me migrate my Claude Code and Codex project instructions, skills, and MCP servers into Kit. Consult your version-matched bundled documentation for the migration procedure. Preserve my source files, do not copy credentials, and show me any conflicts before changing an existing Kit file.
+
+Kit does not need an import slash command. The agent can find the same guide in its bundled docs, inspect the source configuration, translate compatible settings, and validate the result.
+
 ## Feature tour
 
 ### One tool: `compose`
@@ -126,24 +135,30 @@ return { tests: tests.success, counts, fixed }
 
 ### Subagents you can steer, continue, and fork
 
+Kit remains the orchestrator while a bounded task runs in the harness or model best suited to it. For example, you can send visual-direction work to Claude Opus through the Claude ACP adapter, keep implementation in Kit, run independent specialists concurrently, and bring their structured results back into one workflow. External harnesses retain their own configuration and authentication. Kit cannot use a Claude subscription as provider credentials for its built-in `acp.kit` harness; the Claude adapter authenticates separately and uses either subscription limits or Anthropic Console API billing.
+
+The example below assumes the `[acp.claude]` profile, `designer` model alias, and adapter login shown in [Configuration](#configuration).
+
 A subagent is a Runlet value with an `id`, `output`, and `generation`. Use `prompt` to continue the session. Use `fork` to create a branch. Use `subagents({})` to list active subagents. Use `close` to stop a subagent. Kit rejects a stale generation. This check prevents two continuations from updating one session at the same time.
 
 ```text
-review = subagent({
+design = subagent({
+  name: "Visual Designer",
   harness: "acp.claude",
-  prompt: "Review calc.py for edge cases.",
-  output_schema: { type: "object", properties: { issues: { type: "array", items: { type: "string" } } }, required: ["issues"] }
+  model: "designer",
+  prompt: "Act as the visual designer. Inspect the existing dashboard and propose one coherent direction.",
+  output_schema: { type: "object", properties: { direction: { type: "string" }, risks: { type: "array", items: { type: "string" } } }, required: ["direction", "risks"] }
 })
-ranked = prompt({ subagent: review, prompt: "Rank those issues by severity." })
-alt    = fork({ subagent: ranked, prompt: "Now argue the opposite ranking." })
-return { ranked: ranked.output, alt: alt.output, active: subagents({}) }
+refined = prompt({ subagent: design, prompt: "Make the direction concrete enough for an implementer." })
+alt     = fork({ subagent: refined, prompt: "Explore a bolder alternative without changing the original." })
+return { refined: refined.output, alternative: alt.output, active: subagents({}) }
 ```
 
-<p align="center"><img src="docs/media/subagents.gif" alt="Kit orchestrating Claude Code and Codex subagents in parallel" width="900"></p>
+<p align="center"><img src="docs/media/subagents.gif" alt="Kit orchestrating Claude and Codex ACP subagents in parallel" width="900"></p>
 
-- **Any ACP harness.** Kit includes `acp.kit`. You can add Claude Code, Codex, Cursor, or another harness that supports ACP v1 over stdio. The TOML configuration below requires four lines. Kit reads each harness's `initialize` response at runtime. Kit uses native `session/fork` when the harness advertises it. Otherwise, Kit creates an isolated transcript fork for Kit children.
+- **Any ACP harness.** Kit includes `acp.kit`. You can add Claude, Codex, Cursor, or another harness that supports ACP v1 over stdio. The TOML configuration below requires four lines. Kit reads each harness's `initialize` response at runtime. Kit uses native `session/fork` when the harness advertises it. Otherwise, Kit creates an isolated transcript fork for Kit children.
 - **Structured output.** Set `output_schema` on any call that produces a turn. If a reply does not match the schema, Kit returns the raw text and advances the generation. The next `prompt` can repair the reply.
-- **Per-harness model aliases.** `[subagent.harnesses."acp.claude".models] architect = "opus"` lets the model request `model: "architect"` without knowing the harness namespace. An `allow_model_overrides` list restricts the available models.
+- **Per-harness model aliases.** `[subagent.harnesses."acp.claude".models] designer = "opus"` gives visual-design work an intentional route without exposing harness-specific model IDs in prompts. An `allow_model_overrides` list restricts explicit model overrides.
 - **Bounded resources.** Subagent depth is limited to 2. Each session can have 120 live subagents. The startup handshake has a 30-second limit. Kit rejects or cancels permission requests from headless children. Kit never approves these requests automatically.
 - **Explicit context.** Each child starts without the parent conversation history and receives only the prompt that you provide. An `acp.kit` child also inherits the working directory, `AGENTS.md` chain, provider, MCP configuration, and credentials. Skills load into a child on demand with `skill({ name })`.
 
@@ -151,13 +166,13 @@ See [Reusable subagents and ACP harnesses](docs/user/subagents-and-acp-harnesses
 
 ### Background work without losing the turn
 
-Set `background: true` to detach a `compose` program immediately. Set `background: 60` to keep the program in the foreground for one minute before detachment. The turn ends, but the conversation continues. Kit adds the result to the session when the program finishes. In the TUI, use `⌘B` to move the newest running call to the background. Use `^K` to stop the selected call. The model can stop a call with `close({ call_id })`.
+Set `background: true` to detach a `compose` program immediately. Set `background: 60` to keep the program in the foreground for one minute before detachment. The turn ends, but the conversation continues. Kit adds the result to the session when the program finishes. In the TUI, use `⌘B` to move the newest running call to the background. Use `^K` to stop the selected call. The model can stop a call with `close({ call_id })`. See [Compose and local tools](docs/user/compose-and-local-tools.md#run-compose-in-the-background).
 
 <p align="center"><img src="docs/media/background.gif" alt="A background compose call completing after the turn already ended" width="900"></p>
 
 ### Steer a running turn
 
-While the agent works, press `Enter` to add a message to the *current* turn through ACP v2 `steer`. Kit does not queue the message for the next turn. Press `Esc` or `^C` to interrupt a running turn. When Kit is idle, press `^C` to clear a nonempty prompt. Press `^C` again to exit after the prompt is empty.
+While the agent works, press `Enter` to add a message to the *current* turn through ACP v2 `steer`. Kit does not queue the message for the next turn. Press `Esc` or `^C` to interrupt a running turn. When Kit is idle, press `^C` to clear a nonempty prompt. Press `^C` again to exit after the prompt is empty. See [TUI interaction and sessions](docs/user/tui-and-sessions.md#tui-keys-prompt-editing-and-navigation).
 
 <!-- PLACEHOLDER: record docs/media/steer.gif — start a longer task ("refactor calc.py into a class and add tests"), then while it is working type "actually keep it functional, just add docstrings" and press Enter. Capture the prompt placeholder changing from "message kit…" to "steer kit…" and the injected message appearing inside the running turn. -->
 
@@ -171,11 +186,15 @@ While the agent works, press `Enter` to add a message to the *current* turn thro
 | `openrouter` | `kit auth login openrouter` or `OPENROUTER_API_KEY` | Kit loads a live model catalog. It uses context-window data for the gauge and compaction. |
 | `speakeasy` | `kit auth login speakeasy` | Kit uses the Speakeasy AI Control Plane. Kit maps its session ID to the Gram chat ID so that a resumed conversation stays in one thread. |
 
-`/model sonnet` switches the live session at the next safe turn boundary. Press `Tab` in the picker to also update `~/.kit/config.toml`. Use `/effort low|medium|high|default` to change the reasoning effort.
+`/model sonnet` switches the live session at the next safe turn boundary. Press `Tab` in the picker to also update `~/.kit/config.toml`. Use `/effort low|medium|high|default` to change the reasoning effort. See [Getting started and configuration](docs/user/getting-started-and-configuration.md#choose-a-provider-and-authenticate).
 
 ### Live MCP configuration
 
-You do not need to restart Kit after you add a server. Kit merges plugins, configured `mcp_config`, project-root `.mcp.json`, and `--mcp-config` in that order, then reloads every named file before each `tool_search` and `auth` call. Kit waits for new servers to finish initialization before ranking tools.
+Kit has no MCP-specific slash command. Ask the agent instead:
+
+> Add the Linear MCP server at `https://mcp.linear.app/mcp` for this project. Preserve the existing servers in `.mcp.json`, add a useful description, validate the configuration, and help me authenticate.
+
+The agent can edit the project-root `.mcp.json` or your configured global file while the session is running. You can also edit either file yourself, pass a file with `--mcp-config`, or install an Agent Plugin that contributes MCP servers. You do not need to restart Kit after you add a server. Kit merges plugins, configured `mcp_config`, project-root `.mcp.json`, and `--mcp-config` in that order, then reloads every named file before each `tool_search` and `auth` call. Kit waits for new servers to finish initialization before ranking tools.
 
 Kit detects OAuth from the server's Bearer challenge. An `auth` block is not necessary. The model calls `auth({ name })` and gives you a URL. After you complete the browser flow, Kit resumes the session. If an access token expires, Kit refreshes the token and repeats the rejected call once.
 
@@ -196,7 +215,7 @@ Kit loads validated [Agent Plugin](docs/user/agent-plugins.md) packages from a l
 
 Plugin skills become available in the `skill` catalog. Kit starts plugin `stdio` and `streamable-http` MCP servers without an `mcp.json` file.
 
-Kit discovers [Agent Skills](https://agentskills.io/) in `<root>/.agents/skills` and `~/.agents/skills`. Kit initially shows only skill names and descriptions. Kit loads the full `SKILL.md` only when requested.
+Kit discovers [Agent Skills](https://agentskills.io/) in `<root>/.agents/skills` and `~/.agents/skills`. Kit initially shows only skill names and descriptions. Kit loads the full `SKILL.md` only when requested. See [Getting started and configuration](docs/user/getting-started-and-configuration.md#agent-skills) for Kit-specific discovery and setup.
 
 ```toml
 [plugins.review]
@@ -224,7 +243,7 @@ Kit stores each conversation as an append-only JSONL transcript in `~/.kit/sessi
 
 You can resume a session from the TUI or with the `--resume` option of `kit prompt`. ACP clients can use `session/load` or `session/resume`.
 
-When the provider reports 80% context-window use, Kit converts older history into a structured note. Kit persists the replacement. Kit retains the bootstrap instructions and a tool-safe tail. Use `/compact` to compact the history on demand.
+When the provider reports 80% context-window use, Kit converts older history into a structured note. Kit persists the replacement. Kit retains the bootstrap instructions and a tool-safe tail. Use `/compact` to compact the history on demand. See [TUI interaction and sessions](docs/user/tui-and-sessions.md#manage-sessions-and-compact-from-the-tui).
 
 <p align="center"><img src="docs/media/sessions.png" alt="The /sessions picker" width="900"></p>
 <p align="center"><img src="docs/media/headless.gif" alt="kit prompt one-shot, then resuming the same session" width="900"></p>
@@ -238,6 +257,8 @@ When the provider reports 80% context-window use, Kit converts older history int
 - **Daemon operation.** `kit serve --remote-acp --no-stdio` runs independently of stdin. `SIGINT` and `SIGTERM` stop new connections, interrupt live sessions, and allow five seconds for draining. One bearer token file protects the HTTP listener.
 - **Observability.** Set `otel_endpoint = "http://localhost:4317"` to export AgentKit GenAI spans through OTLP/gRPC. Kit exports spans for the main agent, ACP sessions, nested children, and the compactor. Kit disables message-content capture by default. Kit limits captured message content when you enable it.
 
+See [Security, limits, and troubleshooting](docs/user/security-limits-and-troubleshooting.md) for the trust model, operational limits, and recovery guidance.
+
 <!-- PLACEHOLDER: screenshot docs/media/otel-trace.png — point otel_endpoint at a local Jaeger/Tempo, run a session with two subagents, screenshot the trace waterfall showing the nested gen_ai spans. -->
 
 ### Terminal client
@@ -248,7 +269,7 @@ Click a code block to copy its contents. Use `^y` to copy the last response as M
 
 ### Editors and other clients over ACP
 
-Any ACP-compatible client can use Kit. Use `kit acp` for stdio. Use `kit serve --remote-acp` for HTTP/SSE or WebSocket connections at `/acp`. V2-only clients can use `/acp/v2`. Kit also supports A2A v1 on the same listener. Kit can call other A2A agents with `a2a({ url, prompt })`.
+Any ACP-compatible client can use Kit. Use `kit acp` for stdio. Use `kit serve --remote-acp` for HTTP/SSE or WebSocket connections at `/acp`. V2-only clients can use `/acp/v2`. Kit also supports A2A v1 on the same listener. Kit can call other A2A agents with `a2a({ url, prompt })`. See [Getting started and configuration](docs/user/getting-started-and-configuration.md#acp-and-a2a-server-commands).
 
 <!-- PLACEHOLDER: screenshot docs/media/acp-editor.png — Kit running as an external agent inside an ACP-capable editor (e.g. Zed: add {"agent_servers": {"Kit": {"command": "kit", "args": ["acp", "--root", "."]}}} to settings.json). Show a prompt with a compose tool card rendered by the editor. -->
 
@@ -282,13 +303,13 @@ args = ["acp"]
 harness = "acp.kit"
 
 [subagent.harnesses."acp.claude".models]
-architect = "opus"
+designer = "opus"
 
 [subagent.harnesses."acp.kit".models]
 flash = "openrouter:openai/gpt-5.6-luna"
 ```
 
-Kit loads `AGENTS.md` files from the working directory and its ancestors as project instructions. See [Getting started and configuration](docs/user/getting-started-and-configuration.md) for all other settings.
+Before the first Claude subagent, authenticate the adapter with `npx -y @agentclientprotocol/claude-agent-acp@0.69.0 --cli auth login --claudeai` for a Claude subscription, or use `--console` for Anthropic Console API billing. Kit loads `AGENTS.md` files from the working directory and its ancestors as project instructions. See [Getting started and configuration](docs/user/getting-started-and-configuration.md) for all other settings.
 
 ## How it compares
 
@@ -306,6 +327,7 @@ Kit used the fewest tokens, took the least active time, and needed the least ste
 ## Documentation
 
 - [Getting started and configuration](docs/user/getting-started-and-configuration.md)
+- [Migrate from Claude Code or Codex](docs/user/migrating-from-claude-code-and-codex.md)
 - [Compose and local tools](docs/user/compose-and-local-tools.md)
 - [Reusable subagents and ACP harnesses](docs/user/subagents-and-acp-harnesses.md)
 - [MCP](docs/user/mcp.md)
diff --git a/docs/user/mcp.md b/docs/user/mcp.md
index 1bfdbe6..ccc990a 100644
--- a/docs/user/mcp.md
+++ b/docs/user/mcp.md
@@ -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.
diff --git a/docs/user/migrating-from-claude-code-and-codex.md b/docs/user/migrating-from-claude-code-and-codex.md
new file mode 100644
index 0000000..051e6c5
--- /dev/null
+++ b/docs/user/migrating-from-claude-code-and-codex.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.
diff --git a/docs/user/subagents-and-acp-harnesses.md b/docs/user/subagents-and-acp-harnesses.md
index 0b15938..a826626 100644
--- a/docs/user/subagents-and-acp-harnesses.md
+++ b/docs/user/subagents-and-acp-harnesses.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
 
diff --git a/macos/Config/Version.xcconfig b/macos/Config/Version.xcconfig
deleted file mode 100644
index 5ff06b2..0000000
--- a/macos/Config/Version.xcconfig
+++ /dev/null
@@ -1,2 +0,0 @@
-// Generated by scripts/generate-macos-project.sh from Cargo.toml.
-KIT_VERSION = 0.1.121
diff --git a/macos/README.md b/macos/README.md
index 60ae87c..c5268d2 100644
--- a/macos/README.md
+++ b/macos/README.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`.
 
diff --git a/src/docs.rs b/src/docs.rs
index 0f4427d..6c95868 100644
--- a/src/docs.rs
+++ b/src/docs.rs
@@ -410,6 +410,7 @@ mod tests {
                 "docs/user/compose-and-local-tools.md",
                 "docs/user/getting-started-and-configuration.md",
                 "docs/user/mcp.md",
+                "docs/user/migrating-from-claude-code-and-codex.md",
                 "docs/user/reporting-kit-issues.md",
                 "docs/user/security-limits-and-troubleshooting.md",
                 "docs/user/subagents-and-acp-harnesses.md",