agent-policy-kit 0.2.0 → 0.4.0

package/AGENT_INSTALL.md

@@ -1,79 +1,163 @@
 # Agent Policy Kit — AI operator guide
 
-APK is configuration-only. Native files remain independent after npm package/source removal. There is no hook, proxy, launcher, plugin, daemon, runtime audit or background updater. Subagent preferences apply only if the main agent chooses to delegate; preserve ordinary direct work and disabled delegation features.
+This guide is for an AI agent that installs, updates or removes Agent Policy Kit (APK) settings for its owner. It gives the steps in order: select the release, detect, choose the input, plan, apply, verify, remove and report. Flags, output fields and per-assistant details are in the linked documents. `agent-policy instructions` prints this guide.
 
-Perform authorized technical setup/removal yourself; do not hand the owner a shell checklist. Use JSON plans/results, preserve main models, credentials, permissions, unrelated settings and later edits. Never log in, collect credentials, accept terms, start model tasks, publish, weaken sandboxes or bypass trust to force installation success. Private backups can contain existing secrets; keep state private.
+## Rules
 
-Captured output stays JSON. Use --json explicitly when a terminal is attached. Interactive users receive a readable summary. Run show to inspect existing user-level native subagent settings without APK receipts or client executables. Show reads current supported fields, including manual edits, but does not resolve project, managed or session precedence. An incomplete read exits with code 3 while retaining independent client results. Doctor remains the owned-configuration integrity check.
+APK is configuration-only. It writes native files and exits. It adds no hook, proxy, launcher, plugin, daemon, runtime audit or background updater. The native files stay independent after the npm package and the source are removed.
 
-## 1. Select the requested release
+Obey these rules in every step:
 
-Package version is configuration-release version. Read that version's CHANGELOG.md or release output for what changed, why and migration limits. Check the installed tool versions, actual provisioned model aliases and current official model/effort documentation before applying. Preserve explicit user choices; a newer package/model is not an instruction to switch silently. See [model maintenance](docs/model-updates.md) and the dated [model catalog/presets](docs/model-catalog.md).
+1. Do the authorized setup or removal yourself. Do not give the owner a shell checklist.
+2. Preserve main models, credentials, permissions, unrelated settings and later user edits.
+3. Subagent preferences apply only when the main agent decides to delegate. Do not require delegation. Do not enable a disabled delegation feature.
+4. Never log in, collect credentials, accept terms, start model tasks or publish anything.
+5. Never weaken a sandbox or bypass a trust check to make an installation succeed. Never add a runtime gate to replace a missing native feature.
+6. Read JSON. Add `--json` to every command. Captured output is JSON without the flag, but a terminal gets readable text.
+7. Read every per-client result. One client can succeed while another fails. Never report a partial result as a full update.
+8. Keep the state directory private. Its backups can contain existing secrets.
 
-After publication, pinned invocation is supported:
+In the steps below, `agent-policy` means the pinned command for the requested release:
 
 ```sh
-npx --yes --ignore-scripts --package agent-policy-kit@0.2.0 agent-policy release
-npx --yes --ignore-scripts --package agent-policy-kit@0.2.0 agent-policy setup --release
+npx --yes --ignore-scripts --package agent-policy-kit@0.4.0 agent-policy
 ```
 
-Before publication, replace the registry spec with the verified local .tgz. For several commands, install to a temporary or user-owned prefix with npm install --prefix PREFIX TARBALL --ignore-scripts --no-audit --no-fund, then invoke PREFIX/node_modules/.bin/agent-policy. No stable runtime prefix, sudo or shell-profile changes are needed.
+## Step 1: Select the release
 
-## 2. Choose the input
+The package version is the configuration release. Use the version that the owner names, or the version in the command from the configurator.
 
-The page always prints explicit arguments, including when a preset filled the form:
+1. Read the release notes:
+
+   ```sh
+   npx --yes --ignore-scripts --package agent-policy-kit@0.4.0 agent-policy release --json
+   ```
+
+2. Read the entry for this version in [CHANGELOG.md](CHANGELOG.md): what changed, why, and the migration limits.
+3. For a downgrade, also read the entry of each newer version, up to the version that is applied now. `doctor` shows the applied version of each client. A migration boundary is recorded in the entry of the newer version. The release notes of an older package do not contain newer entries, so run `release --json` with the applied version.
+4. Check the installed tool versions, the model aliases that the account actually has, and the current official model and effort documentation.
+5. Keep the explicit choices of the owner. A newer package or a newer model is not an instruction to switch.
+
+For several commands, you can install the package into a temporary or user-owned prefix:
+
+```sh
+npm install --prefix PREFIX agent-policy-kit@0.4.0 --ignore-scripts --no-audit --no-fund
+```
+
+Then run `PREFIX/node_modules/.bin/agent-policy`. If the owner gives you a verified local `.tgz` file of a version that is not on npm, install that file in the same way. You need no sudo, no fixed prefix and no shell profile change.
+
+More: [updates and removal](docs/guide/updates-and-removal.md), [presets](docs/reference/presets.md), [model review procedure](docs/maintainers/model-review.md).
+
+## Step 2: Detect
 
 ```sh
-agent-policy setup \
-  --roles reviewer,explorer \
-  --max-concurrent 3 \
-  --codex 'reviewer=gpt-6.1-sol:high,explorer=gpt-6-luna:high' \
-  --avoid-codex 'gpt-6-astra' \
-  --claude 'reviewer=sonnet:high,explorer=haiku:high' \
-  --avoid-claude 'opus,fable' \
-  --apply
+npx --yes --ignore-scripts --package agent-policy-kit@0.4.0 agent-policy detect --json
 ```
 
-Use --codex, --claude, --kimi, --antigravity and/or --grok to select tools. Each tool must list every selected role exactly once. --roles and --max-concurrent are required in this mode. :native means effort null. Antigravity accepts role=tier and Grok Build accepts role=model, both without an effort. Split the model/effort pair at its last colon. Keep the visible shell quotes and line continuations. The optional --avoid-TOOL lists preserve routing guidance. An omitted list is empty.
+1. Read the status of each assistant: `detected`, `not_found`, `invalid` or `timeout`.
+2. APK needs a working executable. A leftover settings folder is not an installed assistant.
+3. On macOS, `origin: desktop_app` means the CLI inside ChatGPT Desktop or Claude Desktop. It uses the standard native folder.
+4. If `CODEX_HOME`, `CLAUDE_CONFIG_DIR`, `KIMI_CODE_HOME` or `GROK_HOME` points to a nonstandard folder, setup returns a prerequisite for that client and writes nothing. Do not change the variable to force a setup.
+5. `--home PATH` selects the standard layout under another base folder. If you use `--home` or `--state-dir`, use the same values in every later command.
+
+More: [assistants](docs/reference/assistants.md).
+
+## Step 3: Choose the input
+
+Use exactly one input mode. A combination fails before any write.
+
+| Input | Use it when |
+|---|---|
+| Explicit tool arguments (`--roles`, `--max-concurrent`, `--chatgpt`, `--claude`, `--kimi`, `--gemini`, `--grok` and their options) | The owner gives a command from the configurator. Keep its shell quotes and line continuations |
+| `setup --release --preset fast`, `balanced` or `quality` | The owner wants a named preset of this release. This is the supported path to upgrade or downgrade to a pinned release |
+| `setup --config BASE64URL` | The owner gives encoded preferences. Decode and inspect the JSON first. It must contain preferences only, never credentials or executable content |
+| `setup --policy FILE` | The owner keeps a preferences file. This mode does not replace different saved choices. To replace them deliberately, validate the file and pass it as `--config` |
+
+The configurator command lists every selected role for every selected assistant. The tools that it does not name are not configured.
+
+Some release changes cross a migration boundary. For example, to move Claude from 0.4.0 to 0.3.0, first remove its settings with 0.4.0. Read [migration boundaries](docs/guide/updates-and-removal.md#migration-boundaries) before an upgrade or a downgrade.
+
+More: [commands](docs/guide/commands.md), [preferences](docs/guide/preferences.md).
+
+## Step 4: Plan
+
+1. Run the chosen setup command without `--apply`.
+2. Read the overall `status` and each entry in `results`.
+3. Read each entry in `requiredActions`.
+
+Exit code 3 means one of these conditions:
+
+- No selected assistant was detected.
+- At least one selected assistant returned a prerequisite, an error, or an invalid or timed-out detection.
+
+The other clients still have valid results.
+
+Resolve a prerequisite only in a way that preserves the main behavior:
+
+- Kimi needs provisioned aliases, provider metadata and supported efforts. Do not invent them. Do not change the main thinking setting to install a helper.
+- If a selected Kimi alias also serves the main model, a changed effort default returns `kimi-main-effort-conflict`. Use a separate compatible alias, or prepare a native variant that keeps the main behavior.
+- `claude-force-model-conflict` means that the Claude settings force one subagent model. It needs an explicit decision about that native setting from the owner.
+
+More: [commands](docs/guide/commands.md), [assistants](docs/reference/assistants.md).
+
+## Step 5: Apply
+
+1. Add `--apply` to the same command that you planned. A configuration that the owner already authorized needs no second confirmation.
+2. Read each result. `configured` and `unchanged` are successful results.
+
+APK updates owned files in a transaction for each client, without a removal gap. Drift or a missing prerequisite keeps the existing release of that client. A late failure rolls that client back.
 
-Optional --codex-max-concurrent, --claude-max-concurrent, --kimi-max-concurrent, --antigravity-max-concurrent and --grok-max-concurrent override --max-concurrent for their selected tool. They accept whole numbers from 1 to 32 and require the corresponding tool argument. JSON preferences can instead set clients[tool].maxConcurrent. Omitted overrides use the top-level fallback.
+## Step 6: Verify
 
-Explicit arguments are setup/install-only and cannot combine with --client, --release, --preset, --policy or --config. Duplicate flags and incomplete role maps fail before writes. Omit --apply to plan first. Explicit commands allow deliberate owned replacement and record custom source with no named preset provenance. The native files do not retain a dependency on the codec or package.
+1. Run `doctor`:
 
-Other supported inputs remain available:
+   ```sh
+   npx --yes --ignore-scripts --package agent-policy-kit@0.4.0 agent-policy doctor --json
+   ```
 
-- setup --release --preset balanced explicitly applies this executable's named preset and templates (fast/quality are alternatives). It is the supported pinned-release upgrade/downgrade path.
-- setup --config BASE64URL explicitly applies custom choices through this version's templates. This legacy encoded input remains supported. Decode/inspect the JSON; it must contain preferences only, never credentials or executable content.
-- init --policy FILE creates editable defaults without overwriting. setup --policy FILE is a conservative advanced workflow; ordinary mismatching setup refuses replacement. To deliberately replace saved choices from a file, validate it, encode its JSON with Buffer.from(JSON.stringify(preferences)).toString('base64url'), and use --config.
+   Each client reports its saved release, source and preset from its receipt, independent of the version that runs `doctor`. `verified` means that the owned files match the receipt.
 
-Explicit arguments, --release/--preset, --config and --policy are alternative input modes. The --config JSON is canonical unpadded base64url, at most 64 KiB decoded. APK validates it before target mutation and removes its temporary input file afterward.
+2. Run `show` to read the current user-level subagent settings, including manual edits:
 
-Optional top-level selectedRoles selects worker, reviewer, explorer, tester, writer and/or routine. It must be nonempty and contain no duplicates. Omit it to configure all six roles in that release. Optional client roles overrides the selected roles' code/light recommendations. A selected subset creates only those native files and routing instructions. Unselected aliases do not require provisioning or receive effort pins. The first selected role in catalog order supplies the native subagent default.
+   ```sh
+   npx --yes --ignore-scripts --package agent-policy-kit@0.4.0 agent-policy show --json
+   ```
 
-Use model-supported native effort levels. null means no explicit pin. A known catalog model rejects unsupported explicit effort. Keep at most one non-null pin per selected Kimi alias. Preset identity and custom source are reported separately. Tools omitted from clients are not selected.
+   `show` does not resolve project, managed or session settings. It exits with code 3 when a client needs attention, and it keeps the results of the other clients.
 
-Run detect and inspect the setup plan. Working executable identity is required; stale directories are not presence. Automatic targets use standard native roots. Nondefault CODEX_HOME/CLAUDE_CONFIG_DIR/KIMI_CODE_HOME/GROK_HOME returns a per-client zero-write prerequisite rather than configuring a dormant folder. Explicit --home selects the standard layout under that intended base; preserve exact --home/--state-dir for later inspection/removal. It does not remap arbitrary native roots.
+3. Tell the owner that a native client can need a new session to load the changes. Do not stop active sessions.
 
-## 3. Apply the concrete reviewed plan
+A verified configuration does not prove that a model runs. After verification, you can remove the npm package or the temporary prefix. Keep the state directory: its receipts are necessary for a later owned removal.
 
-Already-authorized configuration needs no repeat confirmation. Add --apply to the same selected-release or custom-config command. APK updates existing owned files transactionally without an uninstall gap. It verifies old ownership, virtually restores the original user baseline, then commits the target files/receipt/requested snapshot. Drift or a native prerequisite leaves the existing release intact; a late failure rolls it back. Preserve unrelated edits.
+## Step 7: Remove
 
-Run doctor afterward. It reports each client's actual saved release/source independently of the current executable, bundle, external source or canonical preferences. A verified config is not model execution proof. Native clients may need a fresh session to load changes; do not terminate active user sessions automatically.
+1. Plan the removal:
 
-Per-client transactions are independent. A missing/blocked client can retain an older applied release while another advances. Read all results; never label a partial outcome fully updated. stateDir/policy.json is the latest requested snapshot, not the applied truth. Receipts are the applied truth. Canonical preferences may therefore differ from an older client's snapshot. Ordinary saved-file setup still detects unsafe mismatch. Explicit tool arguments and --release/--config are deliberate replacement operations.
+   ```sh
+   npx --yes --ignore-scripts --package agent-policy-kit@0.4.0 agent-policy uninstall --json
+   ```
 
-Kimi needs provisioned aliases/provider metadata and supported effort; do not invent them. K3.1 Pro variants require thinking: explicit native thinking.enabled=false returns a prerequisite even if every requested effort is null. Do not change the main thinking setting to force helper installation. If a selected alias also serves the main model, a changed effort default without a valid explicit global override returns kimi-main-effort-conflict. Use a compatible separate native alias or deliberately prepare a native variant while preserving main behavior. Reserved primary cannot be a pool key. Claude force-model conflicts require an explicit native setting decision rather than a false per-role success.
+2. Review the plan.
+3. Run the same command with `--apply`.
 
-The available role names are apk-worker/apk-reviewer/apk-explorer/apk-tester/apk-writer/apk-routine. APK creates only the selected names. Changing the selected role set through explicit arguments or --config safely replaces the earlier owned role set. APK preserves unowned files and refuses removal of edited owned roles. Only when delegation is chosen do model/effort/routing/parallelism preferences apply. Native files must not execute/import the package or depend on its executable/npm/source/state path. After verification you may remove the npm package. Keep private receipts for future owned undo.
+The receipts verify ownership. Removal restores the original user settings and keeps unrelated later edits. APK refuses to remove an owned file that someone edited.
 
-## 4. Native limits
+- Do not restore old whole-file backups.
+- Do not delete locks or pending journals by force.
+- Do not delete hooks by text match.
+- Use a version that can read the receipt. All versions from 0.1.0 write receipt format v4, but an older version can refuse the content of a newer receipt. Versions 0.3.0 and earlier cannot read a 0.4.0 Claude receipt that owns `CLAUDE_CODE_SUBAGENT_EFFORT`: remove it with 0.4.0. ChatGPT and Gemini settings from 0.2.0 or earlier need removal with the version that created them. See [migration boundaries](docs/guide/updates-and-removal.md#migration-boundaries).
 
-Codex/Claude have native defaults/caps with higher-priority setting and execution-path exceptions. Kimi role-to-pool selection and concurrency are guidance. Antigravity uses native Pro/Flash/Flash Lite/inherit tiers, with no documented per-role effort or universal hard cap. Grok Build writes agents/apk-ROLE.md, per-role models and a general-purpose fallback in config.toml [subagents.models], and a native [subagents] max_concurrent cap; it has no per-role effort, so subagents use the main session effort. avoidModels is guidance. A pinned configuration does not prove provider identity, entitlement, task quality or unchanged alias resolution. Never add a runtime gate to strengthen a missing native feature.
+More: [ownership](docs/reference/ownership.md), [updates and removal](docs/guide/updates-and-removal.md).
 
-## 5. Removal and incompatible formats
+## Step 8: Report
 
-Run uninstall, review it, then uninstall --apply. Receipts verify ownership without canonical/source preferences or the native executable. Final removal restores original user settings, including after supported release changes, and keeps unrelated later edits. Do not restore stale whole-file backups or force-delete locks/pending journals.
+Give the owner a short result for each client:
 
-Current native receipt v4 records selectedRoles and their bounded fixed filenames. It verifies that the owned file set matches the role selection. Historical v3 and v2 native receipts remain inspectable and removable. v2 has unknown release provenance. Older executables can reject v4. Use an executable that supports the receipt before an incompatible downgrade. Unknown formats/layouts fail safely and require a documented compatible migration. Experimental runtime v1 receipts need their original owned uninstall first. Never delete arbitrary hooks by matching text.
+- Detection: status, version and origin.
+- Result: the status, for example `configured`, `unchanged`, `prerequisite` or `error`, and its codes.
+- Applied release, source and preset, from `doctor`.
+- Required actions that remain.
+- Whether a new session is necessary.
+- What is not checked: model execution, provider identity, entitlement and alias resolution.
 
-Return concise per-client detected/configured/applied-release/source results, prerequisites, new-session needs and unchecked model/provider evidence. No public release, deployment or live model task is part of configuration acceptance.
+Receipts are the applied truth. `policy.json` in the state directory is only the latest requested snapshot, so it can differ from an older client. Kimi and Gemini limits and all avoid lists are guidance, not hard caps. A public release, a deployment or a live model task is not part of this work.

package/CHANGELOG.md

@@ -2,6 +2,96 @@
 
 Each npm version is one configuration release: its presets, native role definitions, instructions and configuration page. Published versions are not rewritten. Applying another release is explicit; package installation alone changes no settings.
 
+## 0.4.0 — 2026-11-01
+
+### Why this release
+
+The presets and the model catalog were checked again on 2026-11-01 against the installed native clients and current vendor documentation. No vendor released or retired a subagent model since 2026-10-30. The new evidence changes where effort is spent, and it shows that Claude's top model is Opus 5.5, not Fable 5.1.
+
+### Who should update
+
+- Anyone who uses ChatGPT or Claude presets and wants the revised effort levels.
+- Anyone who uses the Top-tier top models switch in Claude.
+- Claude Code 2.1.316+ users who want subagents without a named role to stop inheriting the main session effort.
+
+Kimi, Gemini and Grok preset values do not change, so their 0.3.0 installations need no update.
+
+### Migration and rollback
+
+Assistant IDs, preset ids (`fast`, `balanced`, `quality`), share-link format v2 and receipt format v4 are unchanged. Setup with 0.4.0 replaces a 0.3.0 installation in place, and receipts written by 0.3.0 still validate and uninstall. Setup with 0.3.0 moves ChatGPT, Kimi, Gemini and Grok back.
+
+Claude has a migration boundary in the downgrade direction. A 0.4.0 Claude receipt owns a third setting, `CLAUDE_CODE_SUBAGENT_EFFORT`, whenever the Coder effort is pinned, and every preset pins it. Version 0.3.0 does not know this setting, so its setup reports `INVALID_RECEIPT` and changes nothing. To move Claude back to 0.3.0, first remove its settings with 0.4.0: `npx --yes --ignore-scripts --package agent-policy-kit@0.4.0 agent-policy uninstall --client claude --apply`. Then set up with 0.3.0. This was checked with the 0.3.0 source in an isolated home. Removal restores the value that the setting had before setup, or removes it. Share links of 0.3.0 open on the 0.3.0 page.
+
+### Presets and model catalog
+
+Re-running setup applies these values. Installations keep their current values until then.
+
+- **Light, ChatGPT:** the Coder runs Luna at high instead of medium, the starting level OpenAI suggests for Luna. Luna stays the cheapest Codex model.
+- **Standard, ChatGPT:** the Docs writer uses GPT-6.1 Terra at medium instead of GPT-6.1 Sol. OpenAI positions Terra for clear writing, at half of Sol's usage.
+- **Top-tier, ChatGPT and Claude:** the Code explorer and Docs writer keep GPT-6.1 Sol and Opus 5.5 but run at medium instead of high. Implementation, review and tests stay at high.
+- **Top models switch, Claude:** Coder, Reviewer and Test writer use Opus 5.5 at xhigh instead of Fable 5.1 at high. Anthropic's own benchmarks put Opus 5.5 ahead of Fable 5.1 on every published coding benchmark at 2.5 times lower price, and Anthropic suggests a higher Opus effort before Fable. Fable 5.1 stays available in Custom. The switch now sets a model and an effort; ChatGPT and Kimi keep GPT-6 Astra and K3.1 Pro at high.
+
+The catalog snapshot is dated 2026-11-01:
+
+- GPT-5.5 is marked retired from Codex for ChatGPT sign-in on 2026-10-14; it remains for API-key sign-in.
+- GPT-6 Astra's native default effort is medium in the signed-in server catalog; the bundled value low is kept as `bundledDefaultEffort`. The hidden, undocumented `gpt-reserve` selector is excluded.
+- Claude Code 2.1.316, Kimi Code 2.4.1 and Antigravity 1.4.12 are the observed client versions. Opus 4.5 and Haiku 4.5 record their earliest retirement dates.
+- Kimi records plan requirements: K3 and K3.1 Pro need Plus or higher, and the 1M context of K3 needs Pro or higher.
+- Antigravity's Flash Lite tier is marked undocumented: the CLI accepts it, but the subagent documentation lists only inherit, Flash and Pro.
+- Grok 4.7's reasoning levels (low to xhigh) are recorded as API capabilities. APK still writes only a model for each Grok role, so subagents use the main session effort.
+
+Configuration checks are not model-quality evaluations.
+
+### What changed
+
+- Claude: setup also writes `CLAUDE_CODE_SUBAGENT_EFFORT`, the effort for subagents that name none, from the Coder effort capped at high. Claude Code 2.1.316 added this setting; earlier versions ignore it. Before, those subagents kept the main session effort.
+- `agent-policy show` reports the stored Claude default subagent effort and a `CLAUDE_CODE_SUBAGENT_EFFORT` environment override.
+- The top models switch label shows each tool's model and effort.
+- The website deployment guard also compares `src/release.mjs` with the release tag, because the page embeds its preset labels and top choices.
+- The configurator shows a note when Gemini is selected: APK configures Antigravity, not Gemini CLI. The README and the AI assistants reference say the same.
+- The documentation is reorganized into independent documents by audience: `docs/guide/` for people who use APK, `docs/reference/` for facts about assistants, roles, presets, the catalog and ownership, `docs/research/` for the evidence behind presets, and `docs/maintainers/` for development, releases and the website. [docs/README.md](docs/README.md) is the index. Old `docs/*.md` paths are removed without redirects. The 2026-11-01 model review is documented in [docs/research/2026-11-01-model-review.md](docs/research/2026-11-01-model-review.md).
+
+## 0.3.0 — 2026-11-01
+
+### Why this release
+
+People know their assistants as ChatGPT, Claude, Kimi, Gemini and Grok, not by the names of the coding agents inside them. The configurator and the CLI now use those names. Some people use only the desktop apps, and they have no CLI on PATH. Before this release, setup found nothing for them.
+
+### Who should update
+
+- Anyone who uses Codex in ChatGPT Desktop or Claude Code in the Code tab of Claude Desktop on macOS without a separate CLI.
+- Anyone who wants the general assistant names on the page and in the terminal.
+
+Preset values do not change, so an installation of 0.2.0 keeps working without an update.
+
+### Breaking change
+
+AI assistants now have general names: ChatGPT, Claude, Kimi, Gemini and Grok. APK still configures their coding agents: Codex, Claude Code, Kimi Code, Antigravity and Grok Build. Two technical IDs changed, and there is no migration:
+
+- `codex` is now `chatgpt`: `--chatgpt`, `--chatgpt-max-concurrent`, `--avoid-chatgpt`, `--client chatgpt` and the `clients.chatgpt` policy key.
+- `agy` is now `gemini`: `--gemini`, `--gemini-max-concurrent`, `--avoid-gemini`, `--client gemini` and the `clients.gemini` policy key.
+- Warning and error codes follow the new IDs, for example `chatgpt-native-precedence-limits` and `CHATGPT_CAP_ALIAS_CONFLICT`.
+
+Before you use this version, remove the APK settings for these two assistants with the version that created them: `npx --yes --ignore-scripts --package agent-policy-kit@0.2.0 agent-policy uninstall --apply`. This version does not read the old `codex` and `agy` installation receipts, so its setup refuses the existing `apk-*` files as unowned. Policy files and share links that use the old IDs are refused too. Claude, Kimi and Grok keep their IDs.
+
+### Migration and rollback
+
+The two renamed IDs set a migration boundary. These results come from tests with the published 0.2.0 package and this release:
+
+- **ChatGPT (Codex) and Gemini (Antigravity):** remove the APK settings with the version that created them before you set up with the other version. A move in either direction without removal reports `OWNERSHIP_CONFLICT` and changes nothing. After removal, setup with the other version succeeds.
+- **Claude, Kimi and Grok:** their IDs and receipt format v4 are unchanged. In the tests, setup with 0.3.0 upgraded 0.2.0 installations of Claude and Grok in place, and setup with 0.2.0 moved Claude back. Kimi uses the same receipt format, but it was not tested with a provisioned model pool.
+
+`uninstall --apply` removes the settings of every assistant. Run setup again afterwards for the assistants you use.
+
+### Presets and model catalog
+
+Preset models, effort levels and parallel limits are the same as in 0.2.0. Only the keys `codex` and `agy` became `chatgpt` and `gemini`, and the catalog labels became the general names. The model catalog snapshot is still dated 2026-10-30, with the Grok entries checked on 2026-11-01. Configuration checks are not model-quality evaluations.
+
+### What changed
+
+- The configurator calls the second step "AI assistants" and shows the general names. Readable CLI output uses the same names.
+- On macOS, setup finds the Codex that ChatGPT Desktop includes and the Claude Code in the Code tab of Claude Desktop, also when no CLI is on PATH. Both apps read the same settings as their CLIs. A CLI on PATH or in a conventional location still has priority. Detect output reports these clients with `origin: "desktop_app"`. Claude Cowork reads its settings from the Claude account, so APK does not configure it.
+
 ## 0.2.0 — 2026-11-01
 
 ### Why this release
@@ -50,9 +140,9 @@ Use a common approach to optional delegation across Codex, Claude Code, Kimi and
 
 ### What it configures
 
-Six focused roles cover implementation, read-only review, code discovery, test creation, documentation and prescribed execution. Each preset assigns a model and supported effort to every role; the [preset matrix](docs/model-catalog.md#how-the-presets-are-designed) explains the choices.
+Six focused roles cover implementation, read-only review, code discovery, test creation, documentation and prescribed execution. Each preset assigns a model and supported effort to every role; the [preset matrix](docs/reference/presets.md) explains the choices.
 
-These are starting preferences, not model-quality benchmarks. Native model formats and alias behavior were reviewed against the official sources linked in [support](docs/compatibility.md) and [model maintenance](docs/model-updates.md). Model availability must be checked before applying. Provider aliases and tiers may resolve differently over time.
+These are starting preferences, not model-quality benchmarks. Native model formats and alias behavior were reviewed against the official sources linked in [support](docs/reference/assistants.md) and [model maintenance](docs/maintainers/model-review.md). Model availability must be checked before applying. Provider aliases and tiers may resolve differently over time.
 
 ### Presets and model catalog
 
@@ -92,7 +182,7 @@ People who want consistent subagent preferences across their installed coding to
 npx --yes --ignore-scripts --package agent-policy-kit@0.1.0 agent-policy setup --release --apply
 ```
 
-Without --apply the same command previews the changes. The page-generated explicit tool arguments apply the visible choices using this release's native templates. See [release usage](docs/releases.md).
+Without --apply the same command previews the changes. The page-generated explicit tool arguments apply the visible choices using this release's native templates. See [release usage](docs/guide/updates-and-removal.md).
 
 ### Migration and limits
 

package/README.md

@@ -2,69 +2,37 @@
 
 Created and maintained by [Mykola Maksymenko](https://www.linkedin.com/in/nick-maximenko/).
 
-Coding agents can delegate specific tasks to temporary subagents. Those tasks vary in complexity and importance. A single model for every task is rarely the best balance of capability, speed and cost.
+**Stop subagents from burning your plan limits.** Agent Policy Kit (APK) gives each subagent role a model that fits the task and your plan in ChatGPT, Claude, Kimi, Gemini and Grok. You run one command, and then APK exits.
 
-Agent Policy Kit lets you match subagent roles with models and effort. It configures your coding tools’ native environment, then exits. The main agent still decides when to delegate, and its model stays unchanged.
+![One weekly limit: 5.3 h vs 25 h of work](docs/assets/subagent-limits.svg)
 
-```mermaid
-flowchart LR
-    Roles("1. Choose subagent roles") --> Tools("2. Choose your coding tools")
-    Tools --> Models("3. Choose models and effort")
-    Models --> Command("4. Run one setup command")
-    Command --> Done("Native configs saved<br/>APK exits")
-    classDef default fill:#f5f7fb,stroke:#e0e5ed,color:#19283e
-    classDef action fill:#3158c3,stroke:#3158c3,color:#ffffff
-    class Command action
-```
+<sub>My own Codex logs; tasks differed between the runs. [How it was measured](docs/research/limits-evidence.md).</sub>
 
-## Choose your setup
+## Set it up
 
-Open the [configuration page](https://agent-policy-kit.trymenow.io/v/0.2.0/) in your browser. Choose roles and coding tools, keep a preset or adjust each role, then copy the fully expanded setup command. The page address saves your visible choices for sharing. APK creates only the selected roles in installed, selected tools.
+1. Open the [configurator](https://agent-policy-kit.trymenow.io/). Select roles, your AI assistants and a mode: **Light**, **Standard** or **Top-tier**. The mode sets how much of your plan subagents can use.
+2. Copy the command and run it. To preview first, delete the last line (`--apply`) and the ` \` at the end of the line before it. Without `--apply`, APK writes nothing.
 
-The [bundled page](site/index.html) also works offline. APK has no proxy, background process or runtime during your normal coding sessions. You can remove the npm package afterward.
+![Configurator: models and effort for each subagent role, and the setup command](docs/assets/configurator.png)
 
-## Roles and work modes
+[Getting started](docs/guide/getting-started.md) shows the full path, from the configurator to removal.
 
-Choose only the roles you need:
+## Good to know
 
-| Role | Result |
-|---|---|
-| Coder | Implementation and fixes |
-| Reviewer | Read-only correctness, security and regression findings |
-| Code explorer | Read-only code and documentation discovery |
-| Test writer | Tests and targeted execution; product fixes return to Coder |
-| Docs writer | Verified docs, examples and release notes |
-| Task runner | Prescribed commands and mechanical edits; uncertain decisions return to the parent |
+- Your main agent and its model do not change. The main agent still decides when to delegate.
+- APK configures the coding agent of each assistant: Codex in ChatGPT, Claude Code in Claude, Kimi Code, Antigravity for Gemini, and Grok Build. Plain chats do not change. [Assistants](docs/reference/assistants.md) lists the details, also for the desktop apps.
+- APK adds no proxy and no background process. You can delete the npm package after setup.
+- `npx --yes --ignore-scripts --package agent-policy-kit@0.4.0 agent-policy show` reads your current settings. Use `uninstall --apply` instead of `show` to remove the APK settings and keep yours.
+- Apart from the npm download, APK makes no network requests. [Privacy](docs/guide/privacy.md) tells what it reads and writes.
 
-Subagents draw on the same plan limits as your main session, and every parallel session adds to that usage. Choose the mode by how much of your plan subagents may use. Light uses light models for every role, so limits last longest; it suits entry plans and many parallel sessions. Standard gives code, review, tests and docs stronger models and keeps search and routine work on light models; it fits most plans. Top-tier uses high-end models for most roles; it uses limits fastest and suits top plans with few parallel sessions. A switch under Top-tier opts each tool into its top model (Fable, Astra or K3.1 Pro) for those roles; it is off by default. All choices remain editable. Claude Fable may use additional usage credits on plans that do not include it.
+## Documentation
 
-See the [exact preset choices and rationale](docs/model-catalog.md#how-the-presets-are-designed). Recommendations contain no personal model bans. They configure the environment; the main agent still chooses whether to delegate.
-
-## Use a specific release's defaults
-
-```sh
-npx --yes --ignore-scripts --package agent-policy-kit@0.2.0 agent-policy setup --release --apply
-```
-
-Omit --apply to preview. Each version includes its own presets, instructions and configuration page. [Release notes](CHANGELOG.md) explain what changed and why; [release usage](docs/releases.md) covers upgrade and downgrade.
-
-Prefer your AI agent to handle installation or removal? Give it the [AI operator guide](AGENT_INSTALL.md).
-
-## Read your current setup
-
-Run `agent-policy show` to read existing user-level subagent settings, including settings created before APK. Use `--client codex` to inspect one tool. The command shows roles, models, effort and concurrency without changing files or starting model tasks. Project and session settings can override these user-level values.
-
-Configuration commands show a short summary in an interactive terminal. Captured output remains JSON. Add `--json` to request JSON explicitly.
-
-Open an individual coding tool's details to set its maximum concurrent subagents from 1 to 32. Each tool has its own limit per session. Presets start at Light 2, Standard 3 and Top-tier 2; a manual limit makes that tool Custom. Kimi and Antigravity treat it as guidance; Grok Build applies it as a native cap.
-
-[Model catalog](docs/model-catalog.md) · [Support](docs/compatibility.md) · [Model updates](docs/model-updates.md) · [Privacy](docs/privacy.md) · [Verification](docs/verification.md)
-
-Node.js 22.x (22.13+) or 24+; macOS/Linux. Version 0.2.0. MIT licensed.
+- [Documentation index](docs/README.md)
+- [Presets](docs/reference/presets.md)
+- [Release notes](CHANGELOG.md)
+- [AI operator guide](AGENT_INSTALL.md)
 
 ## Related projects
 
-Other open-source projects by [Mykola Maksymenko](https://www.linkedin.com/in/nick-maximenko/):
-
-- [Agents Can Communicate (ACC)](https://github.com/automatis-tools/agents-can-communicate) connects independent AI coding sessions across clients for local questions, code reviews, and handoffs. [Website](https://getacc.dev/).
-- [Automatis Skills](https://github.com/automatis-tools/automatis-skills) provides reusable engineering skills for GitHub workflows, Git cleanup, port conflicts, and technical writing.
+- [Agents Can Communicate (ACC)](https://github.com/automatis-tools/agents-can-communicate): connect independent AI coding sessions for questions, reviews and handoffs.
+- [Automatis Skills](https://github.com/automatis-tools/automatis-skills): reusable engineering skills for GitHub workflows, Git cleanup and technical writing.

package/bin/agent-policy.mjs

@@ -28,7 +28,7 @@ Usage: agent-policy <command> [options]
 
   instructions  Print the AI setup and removal guide
   init          Copy default preferences to --policy (never overwrite)
-  detect        Detect installed coding tools from executable identity
+  detect        Detect installed AI assistants from executable identity
   release       Show this package's configuration version and release notes
   setup         Plan native configuration; add --apply to write
   install       Plan one --client or all detected clients
@@ -36,17 +36,17 @@ Usage: agent-policy <command> [options]
   doctor        Check owned native configuration without model calls
   show          Read current user-level native subagent configuration
 
-Options: --client codex|claude|kimi|agy|grok --home PATH --state-dir PATH
+Options: --client chatgpt|claude|kimi|gemini|grok --home PATH --state-dir PATH
          --policy FILE | --release [--preset fast|balanced|quality] | --config BASE64URL
          --roles worker,reviewer,explorer,tester,writer,routine --max-concurrent 3
-         --codex ROLE=MODEL:EFFORT,... --claude ROLE=MODEL:EFFORT,...
-         --kimi ROLE=ALIAS:EFFORT,... --antigravity ROLE=TIER,... --grok ROLE=MODEL,...
-         --codex-max-concurrent N --claude-max-concurrent N
-         --kimi-max-concurrent N --antigravity-max-concurrent N --grok-max-concurrent N
-         --avoid-codex MODELS --avoid-claude MODELS --avoid-kimi MODELS --avoid-antigravity MODELS --avoid-grok MODELS
+         --chatgpt ROLE=MODEL:EFFORT,... --claude ROLE=MODEL:EFFORT,...
+         --kimi ROLE=ALIAS:EFFORT,... --gemini ROLE=TIER,... --grok ROLE=MODEL,...
+         --chatgpt-max-concurrent N --claude-max-concurrent N
+         --kimi-max-concurrent N --gemini-max-concurrent N --grok-max-concurrent N
+         --avoid-chatgpt MODELS --avoid-claude MODELS --avoid-kimi MODELS --avoid-gemini MODELS --avoid-grok MODELS
          --apply --json --help --version
 
-Explicit tool input requires --roles and --max-concurrent. Use :native for unpinned effort. Antigravity and Grok Build take ROLE=TIER and ROLE=MODEL with no effort.
+Explicit tool input requires --roles and --max-concurrent. Use :native for unpinned effort. Gemini and Grok take ROLE=TIER and ROLE=MODEL with no effort.
 Include every selected role for each selected tool. Per-tool concurrency overrides the shared fallback.
 Avoid lists are comma-separated.
 State defaults to AGENT_POLICY_HOME or ~/.agent-policy-kit.
@@ -149,8 +149,8 @@ async function main(){
       catch(error){configuration={status:'attention',reason:safeCode(error.code)};}
     }
     report.clients[selected]={detection,configuration,modelExecution:'not_checked',
-      concurrency:['codex','claude','grok'].includes(selected)?'native_setting_with_client_exceptions':'instructions_only',
-      models:selected==='agy'?'native_tiers':selected==='kimi'?'native_pool_with_routing_guidance':'native_role_settings'};
+      concurrency:['chatgpt','claude','grok'].includes(selected)?'native_setting_with_client_exceptions':'instructions_only',
+      models:selected==='gemini'?'native_tiers':selected==='kimi'?'native_pool_with_routing_guidance':'native_role_settings'};
   }
   print(report);
 }

package/docs/README.md

@@ -0,0 +1,46 @@
+# Agent Policy Kit documentation
+
+This index tells you which document answers your question. Each document covers one topic and can be read on its own. Documents are grouped by who reads them.
+
+## Use APK
+
+| Question | Document |
+|---|---|
+| How do I set up subagent roles for the first time? | [Getting started](guide/getting-started.md) |
+| How does the configuration page work, and how do I share a setup? | [Configurator](guide/configurator.md) |
+| Which commands, flags and output formats does the CLI have? | [Commands](guide/commands.md) |
+| How do I write my own preferences file? | [Preferences](guide/preferences.md) |
+| How do I update, downgrade, remove or recover a setup? | [Updates and removal](guide/updates-and-removal.md) |
+| What does APK read and write, and what does it never send? | [Privacy](guide/privacy.md) |
+
+An AI agent that installs APK for you follows the [AI operator guide](../AGENT_INSTALL.md).
+
+## Look up facts
+
+| Question | Document |
+|---|---|
+| What does APK write for each AI assistant, and what are the native limits? | [AI assistants](reference/assistants.md) |
+| What do the six roles do, and which model does a subagent without a role use? | [Roles](reference/roles.md) |
+| Which model and effort does each preset choose, and why? | [Presets](reference/presets.md) |
+| Which models and effort levels does this release know? | [Model catalog](reference/model-catalog.md) |
+| How does APK track its own settings, and what is drift? | [Ownership and state](reference/ownership.md) |
+
+## Evidence
+
+| Question | Document |
+|---|---|
+| What evidence supports the 0.4.0 presets? | [Model review of 2026-11-01](research/2026-11-01-model-review.md) |
+| How was the limit illustration in the README measured? | [Limits evidence](research/limits-evidence.md) |
+
+## Maintain APK
+
+| Question | Document |
+|---|---|
+| How is the code organized? | [Architecture](maintainers/architecture.md) |
+| How do I set up a development environment and run the tests? | [Development](maintainers/development.md) |
+| How do I review models and presets for a release? | [Model review procedure](maintainers/model-review.md) |
+| How do I prepare and publish a release? | [Release](maintainers/release.md) |
+| How is the configuration page built and deployed? | [Website](maintainers/website.md) |
+| What was verified for each release? | [Verification](maintainers/verification.md) |
+
+Design decisions are recorded as dated documents in `docs/design/`. Release notes are in the [changelog](../CHANGELOG.md).

package/docs/assets/subagent-limits.svg

@@ -0,0 +1,44 @@
+<svg xmlns="http://www.w3.org/2000/svg" class="apk-limits" viewBox="0 0 880 322" width="880" height="322" role="img" aria-labelledby="apk-limits-title">
+<title id="apk-limits-title">One weekly Codex limit lasted 5.3 h of my work without APK and 25 h with APK</title>
+<defs>
+  <pattern id="apk-limits-hatch" width="8" height="8" patternUnits="userSpaceOnUse" patternTransform="rotate(45)">
+    <rect width="8" height="8" class="hb"/><line x1="0" y1="0" x2="0" y2="8" class="hl"/>
+  </pattern>
+</defs>
+<style>
+  .apk-limits { --bg:#ffffff; --ink:#0b0b0b; --ink2:#52514e; --ink3:#8a8984; --hb:#f4f3ef; --hl:#e2e0d9; --before:#eb6834; --after:#2a78d6; }
+  @media (prefers-color-scheme: dark) {
+    .apk-limits { --bg:#0d1117; --ink:#f0efec; --ink2:#c3c2b7; --ink3:#8b8a82; --hb:#141920; --hl:#262c35; --before:#d95926; --after:#3987e5; }
+  }
+  .apk-limits text { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif; fill: var(--ink); }
+  .apk-limits .bg { fill: var(--bg); }
+  .apk-limits .h1 { font-size: 24px; font-weight: 700; }
+  .apk-limits .sub { font-size: 14px; fill: var(--ink2); }
+  .apk-limits .day { font-size: 12px; font-weight: 600; fill: var(--ink3); }
+  .apk-limits .hb { fill: var(--hb); } .apk-limits .hl { stroke: var(--hl); stroke-width: 3; }
+  .apk-limits .before { fill: var(--before); } .apk-limits .after { fill: var(--after); }
+  .apk-limits .sep { stroke: var(--bg); stroke-width: 2; }
+  .apk-limits .rl { font-size: 15px; font-weight: 650; }
+  .apk-limits .rn { font-size: 14px; font-weight: 400; fill: var(--ink2); }
+  .apk-limits .val { font-size: 18px; font-weight: 700; }
+  .apk-limits .chip { fill: var(--bg); }
+</style>
+<rect class="bg" width="880" height="322" rx="12"/>
+<text class="h1" x="32" y="48">One weekly limit: 5.3 h vs 25 h of work</text>
+<text class="sub" x="32" y="74">My own Codex work on the same plan, in 8-hour workdays. Hatched: limit used up.</text>
+<text class="day" x="113.6" y="114" text-anchor="middle">Mon</text><text class="day" x="276.8" y="114" text-anchor="middle">Tue</text><text class="day" x="440.0" y="114" text-anchor="middle">Wed</text><text class="day" x="603.2" y="114" text-anchor="middle">Thu</text><text class="day" x="766.4" y="114" text-anchor="middle">Fri</text>
+
+  <text class="rl" x="32" y="140">Without APK<tspan class="rn"> · half of subagent work ran on the top model</tspan></text>
+  <rect fill="url(#apk-limits-hatch)" x="32" y="152" width="816" height="48" rx="8"/>
+  <rect class="before" x="32" y="152" width="108.8" height="48" rx="8"/>
+  <line class="sep" x1="195.2" x2="195.2" y1="152" y2="200"/><line class="sep" x1="358.4" x2="358.4" y1="152" y2="200"/><line class="sep" x1="521.6" x2="521.6" y1="152" y2="200"/><line class="sep" x1="684.8" x2="684.8" y1="152" y2="200"/>
+  <rect class="chip" x="150.8" y="161" width="71" height="30" rx="6"/>
+  <text class="val" x="158.8" y="183">5.3 h</text>
+
+  <text class="rl" x="32" y="228">With APK<tspan class="rn"> · each role ran on a model that fits the task and the plan</tspan></text>
+  <rect fill="url(#apk-limits-hatch)" x="32" y="240" width="816" height="48" rx="8"/>
+  <rect class="after" x="32" y="240" width="510.0" height="48" rx="8"/>
+  <line class="sep" x1="195.2" x2="195.2" y1="240" y2="288"/><line class="sep" x1="358.4" x2="358.4" y1="240" y2="288"/><line class="sep" x1="521.6" x2="521.6" y1="240" y2="288"/><line class="sep" x1="684.8" x2="684.8" y1="240" y2="288"/>
+  <rect class="chip" x="552.0" y="249" width="60" height="30" rx="6"/>
+  <text class="val" x="560.0" y="271">25 h</text>
+</svg>