agent-policy-kit 0.2.0 → 0.4.0

package/docs/reference/assistants.md

@@ -0,0 +1,165 @@
+# AI assistants
+
+This document describes how APK works with each AI assistant: how it detects the assistant, which files it writes, which native limits apply and which prerequisites setup checks. It also covers the desktop apps on macOS. It is for everyone who sets up APK and for agents that install it.
+
+APK configures the coding agent of each assistant. In this document, "assistant" means that coding agent:
+
+| Assistant | Coding agent | APK id | Executable | Native folder | Folder override variable |
+|---|---|---|---|---|---|
+| ChatGPT | Codex | `chatgpt` | `codex` | `~/.codex` | `CODEX_HOME` |
+| Claude | Claude Code | `claude` | `claude` | `~/.claude` | `CLAUDE_CONFIG_DIR` |
+| Kimi | Kimi Code | `kimi` | `kimi` | `~/.kimi-code` | `KIMI_CODE_HOME` |
+| Gemini | Antigravity | `gemini` | `agy` | `~/.gemini` | none |
+| Grok | Grok Build | `grok` | `grok` | `~/.grok` | `GROK_HOME` |
+
+Gemini means Antigravity. APK detects the `agy` executable and writes Antigravity role settings. Gemini CLI also uses `~/.gemini`, but APK does not detect or configure it. Plain chats in the assistants do not change.
+
+## Detection
+
+`detect` and `setup` find each assistant by the identity of its executable. A folder alone is not proof that an assistant is installed. APK checks these locations in this order and uses the first executable that passes the identity check:
+
+1. Each absolute directory in `PATH`. APK ignores empty and relative `PATH` entries.
+2. The conventional location: `~/.kimi-code/bin/kimi` for Kimi, `~/.local/bin/claude` and `~/.claude/local/claude` for Claude, and `~/.local/bin/<executable>` for the others.
+3. On macOS only, the copy of the CLI inside a desktop app. See [Desktop apps](#desktop-apps).
+
+The identity check runs the executable with `--version` and matches the product name in the output. Kimi and Antigravity can print only a version number. For them, APK also runs `--help` and checks the product text. Each check has a time limit of 5 seconds.
+
+The result of each assistant has a status and an origin:
+
+- Status: `detected`, `not_found`, `invalid` (the file is not the expected executable) or `timeout`.
+- Origin: `path`, `known_location` or `desktop_app`.
+
+Only detected assistants that the preferences select receive files. For the command output, see [Commands](../guide/commands.md).
+
+## Files written
+
+APK writes only user-level files in the native folder. `<role>` is one of `worker`, `reviewer`, `explorer`, `tester`, `writer` and `routine`. APK writes a role file only for each selected role.
+
+| Assistant | Role files | Configuration file | Instruction file |
+|---|---|---|---|
+| ChatGPT | `~/.codex/agents/apk-<role>.toml` | `~/.codex/config.toml` | `~/.codex/AGENTS.md` |
+| Claude | `~/.claude/agents/apk-<role>.md` | `~/.claude/settings.json` | `~/.claude/CLAUDE.md` |
+| Kimi | `~/.kimi-code/agents/apk-<role>.md` | `~/.kimi-code/config.toml` | `~/.kimi-code/AGENTS.md` |
+| Gemini | `~/.gemini/config/agents/apk-<role>.md` | none | `~/.gemini/AGENTS.md` |
+| Grok | `~/.grok/agents/apk-<role>.md` | `~/.grok/config.toml` | `~/.grok/AGENTS.md` |
+
+- A role file must not exist before setup. If a file with that name exists and APK does not own it, setup stops with `OWNERSHIP_CONFLICT`.
+- In the instruction file, APK adds one block between `<!-- BEGIN agent-policy-kit -->` and `<!-- END agent-policy-kit -->`. It keeps the rest of the file. If the file already has these markers and APK does not own them, setup stops with `OWNERSHIP_CONFLICT`.
+- In the configuration file, APK sets only the settings in the next section. It keeps all other settings. TOML edits change only the text of the owned values. Claude's `settings.json` is written again as formatted JSON with two-space indentation.
+- New files get the mode `0600`. Existing files keep their mode.
+
+The content of role files and the instruction block is described in [Roles](roles.md). How APK records and removes its changes is described in [Ownership and state](ownership.md).
+
+### Settings in the configuration file
+
+| Assistant | Settings that APK owns |
+|---|---|
+| ChatGPT | `[agents]` `max_concurrent_threads_per_session`, `default_subagent_model` and, when the effort is pinned, `default_subagent_reasoning_effort` |
+| Claude | In `env`: `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`, `CLAUDE_CODE_SUBAGENT_MODEL` and, when the effort is pinned, `CLAUDE_CODE_SUBAGENT_EFFORT` |
+| Kimi | `[secondary_model]` `default_model`, one `[secondary_model.models]` entry for each selected alias that names the roles that use it, and `[models.<alias>.overrides]` `default_effort` for each alias with a pinned effort |
+| Gemini | none |
+| Grok | `[subagents]` `max_concurrent`, one `[subagents.models]` entry `apk-<role>` for each selected role, and `[subagents.models]` `general-purpose` |
+
+When a Kimi alias has a pinned effort, APK also removes `secondary_model.default_effort` and records its old value, so that the per-alias setting applies. Removal restores it.
+
+The default model and effort settings apply to subagents that have no named role. See [Roles](roles.md#default-subagent-per-assistant).
+
+## Native limits
+
+APK writes settings through native features. It does not run during agent work and does not enforce a setting on each request. No hook, wrapper or proxy is installed to strengthen a missing native feature.
+
+| Assistant | Parallel limit | Model per role | Effort per role | Precedence |
+|---|---|---|---|---|
+| ChatGPT | Native setting | Role file | Role file | Project settings, explicit spawn settings and higher-priority instructions follow Codex rules and can override user settings. |
+| Claude | Native setting. It applies to ordinary Agent-tool spawns, with documented exceptions. | Role file | Role file | Session, project and managed settings, environment overrides and some spawn paths can override user settings. |
+| Kimi | Guidance only. No native cap is set. | Guidance only. The parent selects the pool alias when it spawns. | Per alias, not per role | Native Kimi rules |
+| Gemini | Guidance only. There is no universal native cap. | Native tier per role | None | Native Antigravity rules |
+| Grok | Native setting | `config.toml` per role | None. Subagents use the main session effort. | Project settings, explicit spawn settings and higher-priority instructions follow Grok Build rules. |
+
+Each assistant adds warning codes to the setup result. The codes tell the person or agent which limits apply:
+
+| Assistant | Warning codes |
+|---|---|
+| ChatGPT | `chatgpt-native-precedence-limits` |
+| Claude | `claude-native-precedence-limits` |
+| Kimi | `kimi-concurrency-guidance-only`, `kimi-model-pool-routing-guidance` |
+| Gemini | `gemini-concurrency-guidance-only`, `gemini-per-role-effort-unsupported` |
+| Grok | `grok-per-role-effort-unsupported`, `grok-native-precedence-limits` |
+
+Other limits apply to all assistants:
+
+- A configured setting is not proof of the provider model that runs, of account access or of task quality.
+- Provider aliases and tiers can resolve to other models over time.
+- An avoid list is routing guidance, not a block.
+- A native client can need a new session to load the changes.
+
+## Prerequisites and refusals
+
+A prerequisite stops setup for one assistant before any write. Other assistants continue. The result names the prerequisite code.
+
+These rules apply to all assistants except Gemini:
+
+- If the folder override variable (for example `CODEX_HOME`) points to a folder other than the standard one, setup returns `native-home-override-unsupported` and writes nothing for that assistant. An explicit `--home` selects the standard layout under that folder instead. See [Commands](../guide/commands.md).
+
+### ChatGPT (Codex)
+
+- If `[agents]` has the older `max_threads` setting, setup stops with `CHATGPT_CAP_ALIAS_CONFLICT`. Decide which setting to keep, then run setup again.
+- An existing `max_concurrent_threads_per_session` that is not a positive whole number stops setup with `UNSUPPORTED_CONFIG`.
+
+### Claude (Claude Code)
+
+- If `env.CLAUDE_CODE_SUBAGENT_MODEL_FORCE` is `1`, setup returns `claude-force-model-conflict`. That setting forces one model for all subagents, so the role models cannot apply. Change the native setting first.
+- Claude Code 2.1.316 or later reads `CLAUDE_CODE_SUBAGENT_EFFORT`. Earlier versions ignore it.
+
+### Kimi (Kimi Code)
+
+Kimi needs provisioned model entries. APK never creates aliases, providers or credentials.
+
+- Each selected alias must exist in `config.toml` with a provider, an upstream model and a context size, and its provider must exist. If not, setup returns `kimi-provisioned-models-required`.
+- If a preferred catalog alias is missing, setup looks for exactly one existing alias with the same upstream model and uses it. The result then has the warning `kimi-catalog-alias-resolved`. If more than one alias matches, setup returns `kimi-catalog-alias-ambiguous`.
+- If a resolved alias is in the avoid list, setup returns `kimi-resolved-model-avoided`.
+- The alias `primary` is reserved and cannot be a pool entry.
+- If thinking is off (`thinking.enabled = false`) and a selected alias needs thinking, setup returns `kimi-thinking-disabled`. Both K3.1 Pro variants need thinking. APK does not change the thinking setting.
+
+Kimi sets effort for each alias, not for each role. The effort rules and their refusal codes are in [Roles](roles.md#kimi-alias-effort).
+
+### Gemini (Antigravity)
+
+- APK writes only role files and the instruction block. It accepts only the tiers `pro`, `flash`, `flash_lite` and `inherit`. See [Model catalog](model-catalog.md#gemini-antigravity).
+
+### Grok (Grok Build)
+
+- Existing `[subagents]` or `[subagents.models]` values that are not tables, or a `max_concurrent` that is not a positive whole number, stop setup with `UNSUPPORTED_CONFIG`.
+- Grok Build reads `~/.claude/CLAUDE.md` by default. If Claude is also configured, Grok Build can therefore also read the Claude instruction block. APK does not change that behavior.
+
+## Desktop apps
+
+Some desktop apps include their own copy of a CLI and do not put it on `PATH`. On macOS, detection also checks these copies, after `PATH` and the conventional locations:
+
+| App | Checked location | Settings it reads |
+|---|---|---|
+| ChatGPT Desktop (Codex) | `/Applications/ChatGPT.app/Contents/Resources/codex-cli/CodexCLI.app/Contents/MacOS/codex`, and the same path under `~/Applications` | `~/.codex`, the same as the Codex CLI |
+| Claude Desktop (Code tab) | `~/Library/Application Support/Claude/claude-code/<version>/<build>/claude.app/Contents/MacOS/claude` | `~/.claude`, the same as the Claude Code CLI |
+
+- For Claude Desktop, detection checks the newest version first. In one version, it checks the most recently written build first. It checks at most 8 copies.
+- An assistant found this way has the origin `desktop_app`. The app must be installed, and the copy of the CLI must pass the identity check.
+- The settings apply to new desktop sessions.
+
+These desktop features are not configured:
+
+- Claude Cowork reads instructions and plugins from your Claude account, not from `~/.claude`.
+- ChatGPT conversations outside Codex have no subagent settings.
+
+## Platforms
+
+- macOS is the local acceptance host.
+- Hosted CI runs the test suites on macOS and Ubuntu. See [Verification](../maintainers/verification.md).
+- APK does not write files on Windows. A plan can run, but an apply that has changes stops with `PLATFORM_UNSUPPORTED`.
+
+## Sources
+
+- [Codex subagents](https://learn.chatgpt.com/docs/agent-configuration/subagents)
+- [Claude Code subagents](https://code.claude.com/docs/en/sub-agents)
+- [Kimi configuration files](https://github.com/MoonshotAI/kimi-code/blob/main/docs/en/configuration/config-files.md) and [Kimi agent definitions](https://github.com/MoonshotAI/kimi-code/blob/main/docs/en/customization/agents.md)
+- [Antigravity subagents](https://antigravity.google/docs/subagents?tab=cli)
+- [Grok Build subagents](https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-pager/docs/user-guide/16-subagents.md), observed with Grok Build 1.0.70 and an isolated `GROK_HOME`

package/docs/reference/model-catalog.md

@@ -0,0 +1,194 @@
+# Model catalog
+
+This document describes `models/catalog.json`, the model catalog of release 0.4.0. It explains the fields, lists the models and effort levels for each AI assistant, and records defaults, lifecycle dates and access requirements. It is for everyone who chooses a model in Custom or wants to know which values a release accepts.
+
+## What the catalog is
+
+The model catalog is a dated snapshot of the native subagent selectors that each AI assistant accepts. A selector is the value that a native role setting takes: a model ID, an alias or a tier. The catalog ships inside the package. One package version has one catalog, as with presets (see [Presets](presets.md)).
+
+- The snapshot date is `reviewedAt`: 2026-11-01 UTC. The review checked the installed native clients and the current vendor documentation. No vendor released or retired a subagent model between the previous check on 2026-10-30 and this one.
+- The configurator page and the preferences validation use the same data. For the validation rules, see [Preferences](../guide/preferences.md).
+- APK never fetches a catalog at run time. Normal agent work never reads the catalog.
+- The catalog is not a live inventory and not a list of what one account can use. Account access and custom deployment IDs vary.
+
+Hidden security and utility models, session modes and private deployments are not in this inventory. Custom model IDs stay available where the native format supports them. Gemini is the exception: its role field accepts only the four tiers.
+
+## Fields
+
+The top level has `schemaVersion` (1), `reviewedAt`, `scope` and `clients`. `clients` has one entry for each assistant: `chatgpt`, `claude`, `kimi`, `gemini` and `grok`.
+
+Each assistant entry has these fields:
+
+| Field | Meaning |
+|---|---|
+| `label` | Name on the page and in output. |
+| `efforts` | The native effort levels of the assistant. A custom model ID can request only these levels. An empty list means no per-role effort. |
+| `observedClientVersion` | The native client version that the review checked. |
+| `observation`, `note` | How the inventory was checked, and limits of the data. |
+| `excluded` | Selectors that the review found but left out, each with a reason. |
+| `models` | The known selectors. |
+
+Each model entry has these fields:
+
+| Field | Meaning |
+|---|---|
+| `id` | The native selector that APK writes. |
+| `label` | The name on the page. |
+| `kind` | `model`, `alias`, `inherit`, `native-alias` (Kimi) or `tier` (Gemini). |
+| `efforts` | Native effort levels for this selector. An explicit effort outside this list is refused. An empty list allows only an unpinned effort. |
+| `defaultEffort` | The native default effort. `null` means that the default is not documented. APK does not invent a value. |
+| `source` | The primary source for the entry. |
+
+Some entries have optional fields:
+
+| Field | Meaning |
+|---|---|
+| `apiEfforts`, `apiDefaultEffort`, `apiSource` | Effort facts of the vendor API, where they differ from the native client. APK does not offer these levels. |
+| `bundledDefaultEffort` | The default in the catalog that is bundled with the Codex CLI, where the signed-in server catalog differs. |
+| `delegationModes` | Execution modes such as `ultra`. These are not effort levels. |
+| `nativeSource` | A second source for the native behavior. |
+| `effortResolution` | How an alias or `inherit` resolves effort. |
+| `lifecycle` | Status (`active`, `deprecated` or `retired`), a retirement date or earliest retirement date, the scope and the source. |
+| `upstreamModelId`, `thinkingRequired`, `planRequirement` | Kimi: the upstream model, whether thinking must be on, and the plan that the model needs. |
+| `documented` | `false` when the native client accepts a selector that the vendor documentation does not list. |
+
+## Native and API capabilities
+
+The `efforts` and `defaultEffort` fields describe native choices. The `apiEfforts` and `apiDefaultEffort` fields keep API facts where they differ. APK offers and validates only the native set for known IDs.
+
+An effort level that the native picker does not show is not proof that the native file rejects it. For example, Codex 0.166.0 does not show `none` in its picker. APK still does not offer `none` for known Codex models.
+
+`ultra` is a delegating execution mode in Codex. The catalog records it in `delegationModes`. APK does not offer it as an effort level.
+
+## ChatGPT (Codex)
+
+The inventory has 9 model IDs from the catalog that is bundled with Codex CLI 0.166.0. The signed-in server catalog of 2026-11-01 shows 8, because GPT-5.5 left Codex for ChatGPT sign-in on 2026-10-14. Efforts follow the bundled catalog. Defaults follow the server catalog where it differs.
+
+| ID | Label | Native efforts | Native default |
+|---|---|---|---|
+| `gpt-6-astra` | GPT-6 Astra | low, medium, high, xhigh, max | medium (bundled: low) |
+| `gpt-6.1-sol` | GPT-6.1 Sol | low, medium, high, xhigh, max | low |
+| `gpt-6.1-terra` | GPT-6.1 Terra | low, medium, high, xhigh, max | low |
+| `gpt-6-sol` | GPT-6 Sol | low, medium, high, xhigh, max | medium |
+| `gpt-6-luna` | GPT-6 Luna | low, medium, high, xhigh, max | medium |
+| `gpt-5.6-sol` | GPT-5.6 Sol | low, medium, high, xhigh, max | low |
+| `gpt-5.6-terra` | GPT-5.6 Terra | low, medium, high, xhigh, max | medium |
+| `gpt-5.6-luna` | GPT-5.6 Luna | low, medium, high, xhigh, max | medium |
+| `gpt-5.5` | GPT-5.5 (API key only) | low, medium, high, xhigh | medium |
+
+- The ChatGPT level set for custom IDs is none, minimal, low, medium, high, xhigh and max.
+- `ultra` is a delegation mode of Astra, both Sol models, both Terra models and GPT-5.6 Sol.
+- Excluded: the hidden specialized selectors `gpt-daybreak-blue-latest` and `gpt-daybreak-red-latest`, the internal utility `codex-auto-review`, and the hidden, undocumented `gpt-reserve` from the server catalog.
+
+## Claude (Claude Code)
+
+The inventory has 14 versioned IDs, 4 family aliases and `inherit`. The review checked Claude Code 2.1.316.
+
+| ID | Label | Native efforts | Native default |
+|---|---|---|---|
+| `claude-fable-5-1` | Fable 5.1 | low, medium, high, xhigh, max | high |
+| `claude-opus-5-5` | Opus 5.5 | low, medium, high, xhigh, max | medium |
+| `claude-sonnet-5-5` | Sonnet 5.5 | low, medium, high, xhigh, max | medium |
+| `claude-haiku-5-5` | Haiku 5.5 | low, medium, high, xhigh, max | medium |
+| `claude-fable-5` | Fable 5 | low, medium, high, xhigh, max | high |
+| `claude-opus-5` | Opus 5 | low, medium, high, xhigh, max | high |
+| `claude-sonnet-5` | Sonnet 5 | low, medium, high, xhigh, max | high |
+| `claude-opus-4-8` | Opus 4.8 | low, medium, high, xhigh, max | high |
+| `claude-opus-4-7` | Opus 4.7 | low, medium, high, xhigh, max | xhigh |
+| `claude-opus-4-6` | Opus 4.6 | low, medium, high, max | high |
+| `claude-sonnet-4-6` | Sonnet 4.6 | low, medium, high, max | high |
+| `claude-opus-4-5-20251101` | Opus 4.5 | none | not documented |
+| `claude-sonnet-4-5-20250929` | Sonnet 4.5 (deprecated) | none | not documented |
+| `claude-haiku-4-5-20251001` | Haiku 4.5 | none | not documented |
+| `fable` | Fable (alias) | low, medium, high, xhigh, max | high |
+| `opus` | Opus (alias) | low, medium, high, xhigh, max | not documented |
+| `sonnet` | Sonnet (alias) | low, medium, high, xhigh, max | not documented |
+| `haiku` | Haiku (alias) | low, medium, high, xhigh, max | not documented |
+| `inherit` | Inherit main model | low, medium, high, xhigh, max | not documented |
+
+- The native effort table of Claude Code omits Opus 4.5, although the API supports effort for it (`apiEfforts`: low, medium, high). The page therefore offers no effort for Opus 4.5.
+- Alias and `inherit` rows list the levels that a role can request. The resolved provider model can clamp or ignore them. Aliases can resolve to a different model over time and per provider. Use a versioned ID when you need predictable capabilities.
+- Excluded: `best`, `default`, `opus[1m]`, `opusplan` and `sonnet[1m]`. These are session or context selectors, not distinct subagent models. A custom native ID stays available.
+
+## Kimi (Kimi Code)
+
+The inventory has 6 upstream models through preferred native aliases. The review checked Kimi Code 2.4.1 and corroborated the aliases through provisioned metadata. Native aliases use the `kimi-code/` prefix.
+
+| ID | Label | Upstream ID | Native efforts | Native default |
+|---|---|---|---|---|
+| `kimi-code/k3.1-pro` | K3.1 Pro | `k3.1-pro` | low, high, max | high |
+| `kimi-code/k3.1-pro-highspeed` | K3.1 Pro Highspeed | `k3.1-pro-highspeed` | low, high, max | high |
+| `kimi-code/k3` | K3 | `k3` | low, high, max | high |
+| `kimi-code/k3-256k` | K3 · 256K | `k3-256k` | low, high, max | high |
+| `kimi-code/kimi-for-coding` | K2.8 Preview | `kimi-for-coding` | low, high, max | max |
+| `kimi-code/kimi-for-coding-highspeed` | K2.7 Code HighSpeed | `kimi-for-coding-highspeed` | none | not documented |
+
+- Both K3.1 Pro variants require thinking (`thinkingRequired`).
+- K2.8 Preview has no medium level.
+- The old kimi.ai help page lists only four IDs. It is not the inventory source.
+- An alias must exist in the native configuration before setup. For how setup resolves a missing preferred alias, see [AI assistants](assistants.md#kimi-kimi-code).
+
+## Gemini (Antigravity)
+
+The native role field takes a tier, not a model ID. The review checked the Antigravity CLI 1.4.12.
+
+| ID | Label | Documented |
+|---|---|---|
+| `pro` | Pro | yes |
+| `flash` | Flash | yes |
+| `flash_lite` | Flash Lite | no |
+| `inherit` | Inherit main model | yes |
+
+- The Antigravity subagent documentation lists only `inherit`, `flash` and `pro`. The parser of CLI 1.4.12 also accepts `flash_lite`. Presets that use Flash Lite therefore rely on an undocumented tier.
+- Google does not document which Gemini model each tier uses. The server sets it for each account.
+- The session model inventory of Antigravity is a different surface. The role tier field cannot select it.
+- There is no per-role effort. `--effort` and `/effort` apply to the whole session.
+
+## Grok (Grok Build)
+
+The inventory has 4 model IDs from the documented xAI model list. The review checked Grok Build 1.0.70.
+
+| ID | Label | Native efforts | API efforts |
+|---|---|---|---|
+| `grok-4.7` | Grok 4.7 | none | low, medium, high (default), xhigh |
+| `grok-4.6` | Grok 4.6 | none | not recorded |
+| `grok-4.5` | Grok 4.5 | none | not recorded |
+| `grok-build-0.1` | Grok Build 0.1 | none | not recorded |
+
+The Grok 4.7 levels are API capabilities. APK writes only a model for each Grok role, so the catalog has no native efforts for Grok. For how Grok Build resolves subagent effort, see [Roles](roles.md#how-effort-applies).
+
+## Lifecycle
+
+| Model | Status | Date | Scope |
+|---|---|---|---|
+| GPT-5.5 | retired | 2026-10-14 | Codex with ChatGPT sign-in. API-key sign-in keeps access. |
+| Sonnet 4.5 | deprecated | retirement 2026-11-30 | Anthropic-operated platforms. Partner schedules differ. |
+| Opus 4.5 | active | earliest retirement 2026-11-24 | Anthropic model lifecycle |
+| Haiku 4.5 | active | earliest retirement 2026-10-15 | Anthropic model lifecycle |
+
+The earliest retirement date of Haiku 4.5, 2026-10-15, passed without an announced deprecation. This was the state on the review date, 2026-11-01.
+
+A release does not keep a retired model available. See [Updates and removal](../guide/updates-and-removal.md).
+
+## Access requirements
+
+A catalog entry does not grant access. The account plan and the provider decide access.
+
+- **GPT-6.1 Terra** launched on 2026-10-26 for the Plus, Pro, Business, Enterprise and Edu plans.
+- **Fable 5.1** requires Claude Code 2.1.257 or later. On Pro it uses usage credits. On Max and Ultra it has its own weekly limit. Some non-interactive native paths bill those credits without a consent prompt. APK does not change billing settings.
+- **K3 and K3.1 Pro** need the Kimi Plus plan (legacy name Moderato) or higher.
+- **The 1M context of K3 and every Highspeed model** need the Kimi Pro plan (legacy name Allegretto) or higher. On Plus, K3 stays at 256K context and still uses about twice the quota of K3 256K.
+- **Quota:** Kimi documents about twice the quota usage for K3.1 Pro Highspeed compared with K3.1 Pro, and for K3 compared with K3 256K. K2.7 Code HighSpeed uses about three times the quota.
+- **Grok:** account access to each model varies by plan.
+
+## Sources
+
+Each entry has a `source` URL in `models/catalog.json`. The main sources are:
+
+- ChatGPT: [OpenAI models](https://learn.chatgpt.com/docs/models) and the Codex CLI 0.166.0 bundled and server catalogs.
+- Claude: [Claude Code model configuration](https://code.claude.com/docs/en/model-config) and [model lifecycle](https://platform.claude.com/docs/en/about-claude/model-deprecations).
+- Kimi: [Kimi Code models](https://www.kimi.com/code/docs/en/kimi-code/models) and [membership](https://www.kimi.com/code/docs/en/kimi-code/membership.html).
+- Gemini: [Antigravity subagents](https://antigravity.google/docs/subagents?tab=cli) and the CLI 1.4.12 parser.
+- Grok: [xAI models](https://docs.x.ai/developers/models) and [Grok Build subagents](https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-pager/docs/user-guide/16-subagents.md).
+
+For how maintainers update the catalog for a release, see [Model review procedure](../maintainers/model-review.md).

package/docs/reference/ownership.md

@@ -0,0 +1,177 @@
+# Ownership and state
+
+This document describes how APK records the settings that it writes, how it detects changes to them and how it applies and rolls back a change safely. It covers the state directory, the receipt formats v2, v3 and v4, transactions, drift and rollback. It is for advanced users and maintainers who need to know exactly what APK owns.
+
+For the steps to update, remove or recover a setup, see [Updates and removal](../guide/updates-and-removal.md). For the files that APK writes in each assistant, see [AI assistants](assistants.md#files-written).
+
+## Glossary
+
+| Term | Meaning |
+|---|---|
+| Owned setting | A file, an instruction block or a single value that APK wrote and recorded in a receipt. APK changes or removes only owned settings. |
+| Receipt | The record of the owned settings of one assistant. It is the file `installations/<assistant>.json` in the state directory. The receipt is the applied truth. |
+| Drift | A change to an owned setting after APK wrote it. For example, a person edits an `apk-*` role file. APK refuses to change or remove a setting that has drift. |
+| Applied release | The APK version, source and preset that a receipt records for one assistant. Each assistant has its own applied release. |
+| Requested snapshot | The file `policy.json` in the state directory. It holds the preferences of the latest setup request. It is not proof that each assistant applied them. |
+| Transaction | One apply operation for one assistant. It changes all files of the plan or, after a failure, restores them. |
+| Source | Where the applied preferences came from: `release` (a preset of the release), `custom` (explicit arguments, `--config` or `--policy`) or `saved` (the requested snapshot in the state directory). |
+
+## State directory
+
+The state directory holds receipts, the requested snapshot and transaction data. It is private: directories have the mode `0700` and files the mode `0600`.
+
+APK selects the state directory in this order:
+
+1. `--state-dir PATH`
+2. The environment variable `AGENT_POLICY_HOME`
+3. `.agent-policy-kit` in the home folder: the `--home` folder when it is given, otherwise your home folder
+
+The path must be absolute. It must not be the home folder or contain the home folder. Use the same `--home` and `--state-dir` values for later inspection and removal, because each receipt records both paths.
+
+| Path | Content | Lifetime |
+|---|---|---|
+| `installations/<assistant>.json` | The receipt of one assistant | Removed by a successful uninstall |
+| `policy.json` | The requested snapshot | Kept after uninstall |
+| `.install.lock` | The ID of the running transaction | Removed after the transaction, kept after a failure that needs recovery |
+| `pending.json` | The journal of the running transaction | Removed after the transaction, kept after a failure that needs recovery |
+| `backups/<transaction-id>/index.json` | A copy of the journal | Kept |
+| `backups/<transaction-id>/<n>.before` | The content of each changed file before the transaction | Kept |
+
+Backups can contain existing secrets from native configuration files. Keep the state directory private. Do not publish receipts, journals or backups.
+
+## Receipts
+
+A receipt records, for one assistant:
+
+- The format version (`schemaVersion`) and the kind `native-config`.
+- The assistant, the home folder and the state directory.
+- A SHA-256 hash of the applied preferences (`policyHash`).
+- The warning codes of the setup.
+- The applied release: `releaseVersion`, `source` and, for a named preset, `preset`.
+- The selected roles (v4 only).
+- One entry for each owned file.
+
+Each file entry records only what APK owns in that file:
+
+| Entry type | Used for | What APK records |
+|---|---|---|
+| `role` | `apk-<role>` role files | The SHA-256 hash of the content that APK wrote. A role file never existed before APK. |
+| `instructions` | The global instruction file | The exact block between the markers and the line breaks that APK added before it. |
+| `json` | Claude `settings.json` | Each owned `env` value: its key, whether it existed, its old value and its new value. Also whether APK created the `env` object. |
+| `toml` | `config.toml` of ChatGPT, Kimi and Grok | Each owned value: its key path, its old value and its new value. For Kimi, also a value that APK removed. |
+
+### Receipt formats
+
+APK 0.4.0 writes format v4. It can read, check and remove v2, v3 and v4.
+
+| Format | Written by | Roles it can own | Release fields |
+|---|---|---|---|
+| v4 | All releases from 0.1.0, including 0.4.0 | The selected subset of all six roles (`selectedRoles`) | `releaseVersion`, `source`, `preset` |
+| v3 | Development versions before 0.1.0 | The four original roles: Coder, Reviewer, Code explorer, Task runner | `releaseVersion`, `source`, `preset` |
+| v2 | Development versions before 0.1.0 | The four original roles | None. The applied release is reported as unknown. |
+
+- A v4 receipt must list exactly the files of its selected roles, plus the instruction file and, if the assistant has one, the configuration file.
+- Grok receipts exist only in v4.
+- A Claude v4 receipt owns two or three `env` values. The third, `CLAUDE_CODE_SUBAGENT_EFFORT`, is new in 0.4.0. It is present only when the effort of the first selected role is pinned. Receipts from 0.3.0 without it stay valid.
+- An older APK version can reject a v4 receipt that a newer version wrote. For example, APK 0.3.0 accepts only two owned `env` values in a Claude receipt, so it stops with `INVALID_RECEIPT` on a 0.4.0 Claude receipt that owns `CLAUDE_CODE_SUBAGENT_EFFORT`. Use a version that supports the receipt before you downgrade. For example, remove the Claude settings with 0.4.0 and then run setup with 0.3.0. [Migration boundaries](../guide/updates-and-removal.md#migration-boundaries) lists the known cases.
+
+APK refuses these receipts:
+
+- A receipt with an unknown format or layout stops with `INVALID_RECEIPT`.
+- An experimental runtime receipt (format v1, or one that records hooks or a package path) stops with `LEGACY_RUNTIME_RECEIPT`. Remove it with the version that created it. Never delete hooks only because their text looks familiar.
+- Receipts are stored under the assistant id. Releases 0.3.0 and later do not read receipts under the old ids `codex` and `agy`. See the 0.3.0 entry in the [changelog](../../CHANGELOG.md).
+
+APK checks a receipt against its recorded hashes, blocks and values. It does not need the current templates, the current catalog or the requested snapshot to check or remove it.
+
+## Drift
+
+APK checks for drift each time it reads a receipt: in `doctor`, in an update and in `uninstall`. For every entry type, a missing file is drift.
+
+| Entry type | Drift means |
+|---|---|
+| `role` | The hash of the file differs from the recorded hash. |
+| `instructions` | The file does not contain each marker exactly once, or the recorded block is not in the file unchanged. |
+| `json` | An owned value differs from the value that APK wrote. |
+| `toml` | An owned value differs from the value that APK wrote. |
+
+Drift stops the operation with `OWNED_DRIFT`. APK writes nothing. In `doctor`, the assistant gets the status `attention` with the reason.
+
+Edits outside the owned settings are not drift. APK keeps them in every update and in removal.
+
+## Plans and read dependencies
+
+Each setup and uninstall first makes a plan. The plan lists every file that it read, with the SHA-256 hash and mode of the content. These are the read dependencies. The apply step checks them again before and during the transaction. If another process changed one of them, the apply stops with `STALE_PLAN`. Make a new plan.
+
+APK reads only regular files of at most 1 MiB. It refuses symbolic links in the path (`UNSAFE_PATH`) and other file types or larger files (`UNSAFE_FILE`).
+
+## Transactions
+
+A transaction applies one plan for one assistant. The transactions of different assistants are independent. One assistant can therefore advance to a new release while another keeps its applied release.
+
+The apply step does these steps in this order:
+
+1. It creates `.install.lock` exclusively and writes a new transaction ID into it. If the lock exists, the apply stops with `INSTALL_LOCKED`.
+2. It checks that no `pending.json` exists, and checks the read dependencies again.
+3. For each changed file, it writes the old content to `backups/<transaction-id>/<n>.before`. It writes the new content to a temporary file, `.agent-policy-<transaction-id>-<n>.tmp`, in the folder of the target file.
+4. It writes the journal to `backups/<transaction-id>/index.json` and then to `pending.json`. The journal lists each changed file with its old hash, new hash, old mode and backup name.
+5. For each file, it checks the read dependencies again and then moves the temporary file over the target, or deletes the target.
+6. It deletes `pending.json`, removes the temporary files and removes the lock.
+
+APK syncs each written file and its folder to storage before the next step.
+
+### Rollback
+
+If a step fails after the journal exists, APK keeps the lock and makes sure that `pending.json` exists. It then restores each file that it already changed, in reverse order:
+
+- If the file still has the content that APK wrote, APK restores the old content.
+- If the file has other content, APK keeps it. Another process changed it, and APK does not overwrite that change.
+
+If all files were restored, APK removes `pending.json` and the lock. The apply stops with `INSTALL_FAILED`, or with the more specific code `STALE_PLAN`, `RECOVERY_REQUIRED`, `UNSAFE_PATH` or `UNSAFE_FILE`. The previous applied release stays in place.
+
+If APK could not restore a file, the apply stops with `ROLLBACK_CONFLICT`. APK keeps `pending.json` and the lock for recovery.
+
+### Recovery required
+
+Every operation first checks for an unfinished transaction. It stops with `RECOVERY_REQUIRED` when one of these conditions is true:
+
+- `pending.json` exists.
+- `.install.lock` contains a transaction ID, and `backups/<transaction-id>/index.json` exists.
+
+The lock ID can find the backup index when APK could not create `pending.json` again. Do not delete the lock or the journal only to let setup continue. Another operation can own them, and a failed transaction can need its backups. For the recovery steps, see [Updates and removal](../guide/updates-and-removal.md).
+
+## Updates
+
+An update replaces the owned settings of one release with those of another. It has no gap in which the assistant has no configuration:
+
+1. APK checks the old receipt for drift.
+2. In memory, it removes the owned settings to get the original user baseline.
+3. It renders the target settings over that baseline.
+4. It commits one final change for each file, against the actual current content.
+
+The role files of roles that the new selection removes are deleted in the same transaction.
+
+Only an explicit input can replace an existing installation: `--release` or `--preset`, `--config`, or explicit assistant arguments. Without one of these inputs:
+
+- If the receipt has the same preferences hash, a preview reports `planned` with no files, and `--apply` reports `unchanged`. If the requested snapshot no longer matches these preferences, setup stops with `OWNED_DRIFT`.
+- If the hash differs, setup stops with `INSTALLATION_CONFLICT`.
+- If no receipt exists but the requested snapshot differs from the new preferences, setup stops with `POLICY_CONFLICT`.
+
+A prerequisite or drift leaves the applied release unchanged. A late failure rolls back to it. The setup result reports, for each assistant, the target, previous and applied release, source and preset.
+
+## Removal
+
+`uninstall` restores the original user values from the receipt:
+
+- It deletes the owned role files.
+- It removes the owned instruction block and the line breaks that APK added. It deletes the instruction file if APK created it and the file is then empty.
+- It restores each owned value to its old value, or removes it if it did not exist. It deletes a configuration file if APK created it and the file is then empty.
+- It deletes the receipt.
+
+Removal restores the values from before the first APK setup, also after several updates. It keeps later edits that are not owned. It keeps `policy.json` and the backups. Without `--client`, `uninstall` processes each assistant that has a receipt.
+
+The native files do not depend on the npm package. You can remove the package after setup. To remove the APK settings later, run a compatible APK version again with the same `--home` and `--state-dir`. For the commands, see [Commands](../guide/commands.md).
+
+## Related documents
+
+- [Architecture](../maintainers/architecture.md): the modules that implement these rules.
+- [AI operator guide](../../AGENT_INSTALL.md): the guide for an agent that applies or removes APK.