agent-policy-kit 0.3.0 → 0.4.0

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.

package/docs/reference/presets.md

@@ -0,0 +1,128 @@
+# Presets
+
+This document lists the three presets of release 0.4.0: Light, Standard and Top-tier. It gives the model and effort that each preset selects for each role and AI assistant, the top models switch, the parallel limits and the design principles. It is for everyone who chooses a preset or wants to know why a preset has its values.
+
+A preset is a named set of preferences that the release supplies. The data is in `policies/fast.json` (Light), `policies/balanced.json` (Standard) and `policies/quality.json` (Top-tier). The CLI uses the ids `fast`, `balanced` and `quality`. The page and this document use the labels. For the roles, see [Roles](roles.md). For model IDs, efforts and access requirements, see [Model catalog](model-catalog.md). The detailed evidence is in the [model review of 2026-11-01](../research/2026-11-01-model-review.md).
+
+## Summary
+
+| Preset | CLI id | Description | Parallel limit per assistant |
+|---|---|---|---|
+| Light | `fast` | Light models for every role. Limits last longest. | 2 |
+| Standard | `balanced` | Stronger models for code, review, tests and docs. Fits most plans. | 3 |
+| Top-tier | `quality` | High-end models for most roles. Uses limits fastest. | 2 |
+
+Standard is the default preset. `setup --release` without `--preset` applies it. For the commands, see [Commands](../guide/commands.md).
+
+## Design principles
+
+The presets were reviewed on 2026-11-01. They are starting recommendations, not a quality ranking.
+
+- Subagent usage counts against the same plan limits as the main session. Each parallel session adds to that usage. The presets therefore differ in how much of the plan the subagents can use.
+- No comparative task benchmark was run for the presets. Configuration tests check settings, not model quality.
+- Vendors' effort labels and subscription usage are not directly comparable. One role can therefore get different effort levels in different assistants.
+- Presets pin at most `high`. The only exception is the Claude top choice at `xhigh`. Higher effort gives quickly diminishing returns. Higher levels stay available in Custom.
+- No preset bans a model. A model that a preset does not select stays available in Custom. Personal avoid lists stay available in preferences and CLI input.
+- Each table cell is `model · effort`. A cell without an effort means that the assistant has no per-role effort setting. Gemini and Grok cells have no effort for this reason. See [Roles](roles.md#how-effort-applies).
+
+### Light
+
+| Role | ChatGPT | Claude | Kimi | Gemini | Grok |
+|---|---|---|---|---|---|
+| Coder | Luna · high | Haiku 5.5 · medium | K2.8 Preview · low | Flash | Grok Build 0.1 |
+| Reviewer | Luna · high | Haiku 5.5 · high | K2.8 Preview · low | Flash | Grok Build 0.1 |
+| Code explorer | Luna · low | Haiku 5.5 · low | K2.8 Preview · low | Flash Lite | Grok Build 0.1 |
+| Test writer | Luna · high | Haiku 5.5 · high | K2.8 Preview · low | Flash | Grok Build 0.1 |
+| Docs writer | Luna · low | Haiku 5.5 · low | K2.8 Preview · low | Flash Lite | Grok Build 0.1 |
+| Task runner | Luna · low | Haiku 5.5 · low | K2.8 Preview · low | Flash Lite | Grok Build 0.1 |
+
+Light uses light models for every role, so plan limits last longest. It suits entry plans and many parallel sessions.
+
+- ChatGPT runs GPT-6 Luna at high for code, review and tests. OpenAI suggests high as the starting level for Luna. Luna is the cheapest Codex model at any level.
+- Claude gives reviews and test creation more reasoning than the Coder. Checking edge cases is different from executing known steps.
+- Kimi roles share one alias, and an alias has one effort. Light keeps that effort at low to save quota.
+- Gemini uses Flash for code, review and tests, and Flash Lite for lighter work.
+- Grok uses Grok Build 0.1, the fast coding model, for every role.
+
+### Standard
+
+| Role | ChatGPT | Claude | Kimi | Gemini | Grok |
+|---|---|---|---|---|---|
+| Coder | Sol · medium | Sonnet 5.5 · medium | K3 256K · high | Pro | Grok 4.7 |
+| Reviewer | Sol · high | Sonnet 5.5 · high | K3 256K · high | Pro | Grok 4.7 |
+| Code explorer | Luna · high | Haiku 5.5 · medium | K2.8 Preview · low | Flash | Grok Build 0.1 |
+| Test writer | Sol · high | Sonnet 5.5 · high | K3 256K · high | Pro | Grok 4.7 |
+| Docs writer | Terra · medium | Sonnet 5.5 · medium | K3 256K · high | Flash | Grok 4.7 |
+| Task runner | Luna · low | Haiku 5.5 · low | K2.8 Preview · low | Flash Lite | Grok Build 0.1 |
+
+Standard uses stronger models for implementation, review, test creation and documentation. It uses light models for fact gathering and mechanical work.
+
+- ChatGPT runs GPT-6.1 Sol for code, review and tests. Luna runs at high for exploration. GPT-6.1 Terra runs at medium for docs: OpenAI positions Terra for clear writing, at half of Sol's usage.
+- Claude's Haiku 5.5 explorer uses medium, its native default.
+- Kimi uses K3 256K for code, review, tests and docs. Its quota footprint is smaller than that of the full-context K3. Larger-context choices stay editable.
+- Gemini uses Flash for exploration and docs.
+- Grok adds Grok 4.7 for code, review, tests and docs.
+- No Standard role uses GPT-6 Astra, Fable or K3.1 Pro.
+
+### Top-tier
+
+| Role | ChatGPT | Claude | Kimi | Gemini | Grok |
+|---|---|---|---|---|---|
+| Coder | Sol · high | Opus 5.5 · high | K3 · high | Pro | Grok 4.7 |
+| Reviewer | Sol · high | Opus 5.5 · high | K3 · high | Pro | Grok 4.7 |
+| Code explorer | Sol · medium | Opus 5.5 · medium | K3 · high | Pro | Grok 4.7 |
+| Test writer | Sol · high | Opus 5.5 · high | K3 · high | Pro | Grok 4.7 |
+| Docs writer | Sol · medium | Opus 5.5 · medium | K3 · high | Pro | Grok 4.7 |
+| Task runner | Sol · medium | Sonnet 5.5 · medium | K2.8 Preview · high | Flash | Grok Build 0.1 |
+
+Top-tier uses GPT-6.1 Sol, Opus 5.5 and K3 at high effort for implementation, review and tests. It uses limits fastest. It suits top plans with few parallel sessions.
+
+- Exploration and documentation use the same high-end model. In ChatGPT and Claude they run at medium. Read-only discovery and writing do not need the edge-case checking that high is for.
+- In Claude, Kimi, Gemini and Grok, only the Task runner uses a lighter model. ChatGPT uses Sol for every role. Its Task runner runs at medium, the same as exploration and documentation.
+- Kimi keeps one effort per shared alias. K2.8 Preview has no medium level, so the Kimi Task runner uses high.
+- Gemini has one top tier, Pro. Gemini's Standard and Top-tier differ only in exploration, docs and the Task runner.
+- Grok also uses Grok 4.7 for exploration. The Grok Task runner keeps Grok Build 0.1.
+
+## Top models switch
+
+The top models switch is an option of Top-tier on the [configurator](../guide/configurator.md). It is not a separate preset. Each assistant has its own switch. The switch is off by default, because the top choices use limits much faster. Share links keep the switch state.
+
+When the switch is on, the Coder, Reviewer and Test writer use the top choice of the assistant:
+
+| Assistant | Top choice |
+|---|---|
+| ChatGPT | GPT-6 Astra · high |
+| Claude | Opus 5.5 · xhigh |
+| Kimi | K3.1 Pro · high |
+
+Gemini and Grok have no top choice.
+
+For Claude, the switch raises the Opus 5.5 effort instead of selecting Fable 5.1. Anthropic's own benchmarks put Opus 5.5 ahead of Fable 5.1 on every published coding benchmark, at 2.5 times lower price. Anthropic also suggests a higher Opus effort before Fable. Fable 5.1 stays available in Custom.
+
+The default subagent setting of Claude caps the effort at high. The `xhigh` top choice therefore does not raise subagents that have no named role. See [Roles](roles.md#default-subagent-per-assistant).
+
+## Parallel limits
+
+The parallel limit is the maximum number of subagents that run at the same time in one session. The defaults are Light 2, Standard 3 and Top-tier 2 for each assistant.
+
+- Light keeps short work bounded.
+- Standard lets three independent responsibilities overlap.
+- Top-tier limits long work on heavier models that runs at the same time.
+
+These values are product defaults, not benchmark results. A limit does not start tasks and does not measure quality. Each assistant can override its limit on the page or with `--TOOL-max-concurrent`. Some assistants enforce the limit natively. For others it is guidance only. See [AI assistants](assistants.md#native-limits).
+
+## Reasons by vendor
+
+These are short reasons. The sources and the detailed comparisons are in the [model review of 2026-11-01](../research/2026-11-01-model-review.md).
+
+- **OpenAI (ChatGPT):** OpenAI positions Astra for demanding work, Sol for a balance of capability and usage, Terra for fast, clear writing and Luna for focused, efficient work. In Codex credits per token, Astra costs 5 times Sol, Terra costs half of Sol and Luna costs a tenth of Terra. OpenAI's subagent guide suggests Sol for demanding agents, Luna for lighter subagent work, high for Luna, and names reviewer or security-focused agents as examples for high. The reviewer example of the same guide uses Sol at medium.
+- **Anthropic (Claude):** Anthropic suggests Sonnet for most coding, Opus for complex architectural work and Haiku for simple subagent tasks. Anthropic suggests Fable only when Opus 5.5 at a higher effort still falls short. Anthropic describes high as the level for work where verification matters and xhigh as deeper reasoning at higher token spend. Anthropic reports that Sonnet 5.5 scored lower at max than at xhigh, because it started review subagents more often.
+- **Moonshot (Kimi):** Kimi describes K2.8 Preview as efficient thinking and K3 256K as a smaller quota footprint than K3. Moonshot recommends K3 256K for routine feature work and K3 for large-codebase analysis and multi-file refactoring. K3.1 Pro Highspeed has the same capabilities as K3.1 Pro at a quota premium, so no preset uses it.
+- **Google (Gemini):** The presets use only the native role tiers of Antigravity. The tiers do not fix the underlying model, and there is no per-role effort.
+- **xAI (Grok):** Grok Build 0.1 is xAI's fast coding model and serves light work. Grok 4.7 is the flagship and serves code, review, tests and docs. Grok 4.6 and 4.5 stay available in Custom.
+
+Account access to each model varies by plan. A preset does not grant access. For plan requirements, see [Model catalog](model-catalog.md#access-requirements).
+
+## What a preset does not freeze
+
+A preset fixes the model IDs and effort levels that it writes. It does not fix what a provider alias or tier resolves to, and it does not keep a retired model available. For release selection and updates, see [Updates and removal](../guide/updates-and-removal.md). For the review procedure for the next release, see [Model review procedure](../maintainers/model-review.md).