agent-policy-kit 0.3.0 → 0.5.0

package/docs/reference/assistants.md

@@ -0,0 +1,194 @@
+# 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 | Role file. It applies only when the model supports effort. A role without an effort runs at the default effort of its model. | Project settings, explicit spawn settings, Grok roles with the same name 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-effort-model-dependent`, `grok-native-precedence-limits`. Installs made by 0.4.0 keep the older code `grok-per-role-effort-unsupported` in their receipt; setup shows it with the same corrected note. |
+
+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.
+
+#### Claude model aliases on other providers
+
+APK writes a Claude alias such as `sonnet` or `haiku` as it is. Claude Code resolves the alias for each provider. The presets use versioned IDs, not aliases. A role that you set to an alias in Custom can resolve to an older model outside the Anthropic API. On 2026-11-02, the Claude Code documentation gave these resolutions:
+
+| Provider | `sonnet` | `haiku` |
+|---|---|---|
+| Anthropic API | Sonnet 5.5 | Haiku 5.5 |
+| Claude Platform on AWS | Sonnet 4.6 | Haiku 4.5 |
+| Amazon Bedrock, Google Cloud's Agent Platform | Sonnet 4.5 | Haiku 4.5 |
+| Microsoft Foundry | Sonnet 4.5 | Haiku 4.5 |
+
+- On Microsoft Foundry, the `default` model setting is also Sonnet 4.5.
+- Sonnet 4.5 is deprecated. On Bedrock and Agent Platform it stays available until the partner's own date: Bedrock lists it as Legacy with end of life on 2027-04-08, and Google announces no date. See [Model catalog](model-catalog.md#lifecycle).
+- Haiku 4.5 is active (legacy) and has no deprecation notice.
+- **Foundry risk after 2026-11-30:** Foundry follows the Claude API lifecycle, so Sonnet 4.5 retires there on 2026-11-30. Unless Claude Code changes its Foundry defaults, `sonnet` and `default` then name a retired model. Bedrock and Agent Platform show a notice and fall back to an earlier version of an unavailable alias default. Foundry has no such startup check, so Foundry users see errors instead.
+- On Foundry, pin a newer Sonnet before 2026-11-30: set `ANTHROPIC_DEFAULT_SONNET_MODEL` to a Sonnet 5.x or Sonnet 4.6 deployment, or choose a full model ID for each role and for the main model.
+- Claude Code warns when a requested model has a scheduled retirement date. The check also covers a `model` in subagent frontmatter, so it covers APK role files.
+
+### 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.
+
+#### Grok role effort
+
+Issue #27 tested whether a named agent such as `apk-reviewer` can have its own effort. It can. The result comes from the Grok Build source and from a check with Grok Build 1.0.70:
+
+- APK writes a role effort as `effort: <level>` in the frontmatter of `~/.grok/agents/apk-<role>.md`. A role with the native default gets no `effort` line.
+- Grok Build 1.0.70 accepts `low`, `medium`, `high`, `xhigh` and `max` in this field. For any other value, Grok Build drops the whole agent without a warning. `grok inspect --json` with an isolated `GROK_HOME` confirmed both cases. APK writes only the levels that the [model catalog](model-catalog.md#grok-grok-build) lists for a known model.
+- Grok Build applies the effort only when the model supports effort. Grok 4.7 lists `low`, `medium`, `high` and `xhigh`, with `high` as its default. Grok Build 0.1 has no effort setting, so Grok Build ignores an effort for it.
+- A role without an effort runs at the default effort of its model, not at the main session effort. The reason: APK pins the model of each role in `[subagents.models]`, and Grok Build gives a pinned model the default effort from its model list. For Grok 4.7 the default is `high`. Exceptions: the `--effort` option of Grok Build applies to all models, and `[models].default_reasoning_effort` applies to the default model.
+- Grok Build uses this order: a spawn override from the harness, then a Grok role with the same name as the agent (`[subagents.roles.apk-<role>]` or `~/.grok/roles/apk-<role>.toml`), then the agent frontmatter, then the default of the model. The parent model cannot select an effort when it spawns a subagent. APK writes no Grok roles.
+- Not checked: a live model task. Grok Build has no command that shows the resolved subagent effort without a model run. The source is a public sync from 2026-09-29, and the error and log text of these code paths occurs in the 1.0.70 program.
+
+## 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), [Claude Code model configuration](https://code.claude.com/docs/en/model-config) and [Claude in Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry)
+- [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,210 @@
+# Model catalog
+
+This document describes `models/catalog.json`, the model catalog of release 0.5.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-02 UTC. On that date the lifecycle of the Claude 4.5 models was checked again. See [Lifecycle](#lifecycle). The full review of 2026-11-01 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 (`retirementDate`) or earliest retirement date (`earliestRetirement`), the scope and the source. Optional: the deprecation date (`deprecationDate`), the recommended replacement ID (`replacement`), a `note`, and `partners`, a list of partner platforms that set their own schedule. Each partner entry has `platform`, `source` and, where announced, the partner's own `status`, `earliestRetirement` or `endOfLife`, or a `note`. |
+| `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 (retires 2026-11-30) | 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.
+
+The client `efforts` list is `low`, `medium`, `high`, `xhigh` and `max`: the values that Grok Build 1.0.70 accepts in the `effort` field of an agent file. A custom model ID can request these levels. Grok Build drops an agent with any other value.
+
+| ID | Label | Native efforts | Native default |
+|---|---|---|---|
+| `grok-4.7` | Grok 4.7 | low, medium, high, xhigh | high |
+| `grok-4.6` | Grok 4.6 | not verified, none offered | not documented |
+| `grok-4.5` | Grok 4.5 | not verified, none offered | not documented |
+| `grok-build-0.1` | Grok Build 0.1 | none | none |
+
+- The Grok 4.7 levels and default come from the Grok Build model list (`supports_reasoning_effort`, `reasoning_efforts`) of 1.0.70. They are the same as the API levels in `apiEfforts`. `max` is not listed for Grok 4.7, so APK does not write it for that model.
+- Grok Build 0.1 has no effort setting. Grok Build ignores an effort for a model without effort support.
+- The levels of Grok 4.6 and 4.5 were not verified, so the catalog offers no effort for them.
+- For where APK writes the effort and how Grok Build applies it, 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 since 2026-09-30 | retirement 2026-11-30 | Claude API, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed) and Microsoft Foundry. Replacement: `claude-sonnet-5-5`. |
+| Opus 4.5 | active (legacy) | earliest retirement 2026-11-24 | Anthropic-operated platforms and Microsoft Foundry. No deprecation notice. |
+| Haiku 4.5 | active (legacy) | earliest retirement 2026-10-15 | Anthropic-operated platforms and Microsoft Foundry. No deprecation notice. |
+
+Partner platforms set their own schedules:
+
+| Model | Amazon Bedrock | Google Cloud (Google managed) |
+|---|---|---|
+| Sonnet 4.5 | Legacy. End of life 2027-04-08. | No retirement date announced. The earliest retirement date, 2026-09-29, passed. |
+| Opus 4.5 | Not on the legacy list | Earliest retirement 2026-11-24 |
+| Haiku 4.5 | Not on the legacy list | Earliest retirement 2026-12-07 |
+
+- This is the state on 2026-11-02. Sonnet 4.5 still works for organizations that already have access, so the catalog records it as deprecated, not retired. The Anthropic Models API describes a deprecated model as closed to new adopters, so a new account can already fail with it.
+- The page offers Sonnet 4.5 with the label "Sonnet 4.5 (retires 2026-11-30)". After that date, a role that names `claude-sonnet-4-5-20250929` fails on the Claude API, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed) and Microsoft Foundry. Choose Sonnet 5.5 instead.
+- Anthropic gives at least 60 days' notice before it retires a model. Opus 4.5 and Haiku 4.5 had no deprecation notice, so their earliest retirement dates are floors, not scheduled dates. The date for Haiku 4.5, 2026-10-15, passed without an announcement.
+- The Claude Code aliases `sonnet`, `haiku` and `default` can resolve to these 4.5 models on some providers. See [AI assistants](assistants.md#claude-model-aliases-on-other-providers).
+
+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), [model lifecycle](https://platform.claude.com/docs/en/about-claude/model-deprecations), [Bedrock legacy models](https://docs.aws.amazon.com/bedrock/latest/userguide/model-lifecycle-legacy.html) and [Google partner model deprecations](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/deprecations/partner-models).
+- 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.