agent-policy-kit 0.2.0 → 0.3.0

package/AGENT_INSTALL.md

@@ -13,8 +13,8 @@ Package version is configuration-release version. Read that version's CHANGELOG.
 After publication, pinned invocation is supported:
 
 ```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.3.0 agent-policy release
+npx --yes --ignore-scripts --package agent-policy-kit@0.3.0 agent-policy setup --release
 ```
 
 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.
@@ -27,16 +27,16 @@ The page always prints explicit arguments, including when a preset filled the fo
 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' \
+  --chatgpt 'reviewer=gpt-6.1-sol:high,explorer=gpt-6-luna:high' \
+  --avoid-chatgpt 'gpt-6-astra' \
   --claude 'reviewer=sonnet:high,explorer=haiku:high' \
   --avoid-claude 'opus,fable' \
   --apply
 ```
 
-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.
+Use --chatgpt, --claude, --kimi, --gemini and/or --grok to select AI assistants. Each tool must list every selected role exactly once. --roles and --max-concurrent are required in this mode. :native means effort null. Gemini accepts role=tier and Grok 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.
 
-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.
+Optional --chatgpt-max-concurrent, --claude-max-concurrent, --kimi-max-concurrent, --gemini-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.
 
 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.
 
@@ -52,7 +52,7 @@ Optional top-level selectedRoles selects worker, reviewer, explorer, tester, wri
 
 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.
 
-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.
+Run detect and inspect the setup plan. Working executable identity is required; stale directories are not presence. On macOS, detect also checks the CLIs bundled in ChatGPT Desktop and Claude Desktop after PATH; such a client reports origin desktop_app and uses the standard native root. 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. Apply the concrete reviewed plan
 
@@ -68,7 +68,7 @@ The available role names are apk-worker/apk-reviewer/apk-explorer/apk-tester/apk
 
 ## 4. Native limits
 
-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.
+ChatGPT (Codex) and Claude (Claude Code) have native defaults/caps with higher-priority setting and execution-path exceptions. Kimi role-to-pool selection and concurrency are guidance. Gemini (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.
 
 ## 5. Removal and incompatible formats
 

package/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 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.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

package/README.md

@@ -2,69 +2,30 @@
 
 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.** APK gives each subagent role a model that fits the task and your plan in ChatGPT, Claude, Kimi, Gemini and Grok. One command, then it 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/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/). Pick roles, your AI assistants and a mode: **Light**, **Standard** or **Top-tier**, by how much of your plan subagents may use.
+2. Copy the command and run it. Remove the last `--apply` line to preview first; nothing is written without it.
 
-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
+## Good to know
 
-Choose only the roles you need:
+- Your main agent and its model stay unchanged. It 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.
+- Desktop apps on macOS work too. APK finds the Codex that ChatGPT Desktop includes and the Claude Code in the Code tab of Claude Desktop. Both read the same settings as their CLIs. Claude Cowork reads its settings from your Claude account, so APK does not change Cowork.
+- No proxy and no background process. Delete the npm package after setup.
+- `npx --yes --ignore-scripts --package agent-policy-kit@0.3.0 agent-policy show` reads your current settings. Use `uninstall --apply` instead of `show` to remove APK's settings and keep yours.
 
-| 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 |
-
-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.
-
-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.
+[Model catalog](docs/model-catalog.md) · [Release notes](CHANGELOG.md) · [AI operator guide](AGENT_INSTALL.md) · [Support](docs/compatibility.md) · [Privacy](docs/privacy.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/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>

package/docs/compatibility.md

@@ -1,15 +1,31 @@
 # Native configuration support
 
-| Client | Written native configuration | Limits |
+| AI assistant | Written native configuration | Limits |
 |---|---|---|
-| Codex | User role TOMLs, native subagent defaults/concurrency, routing instructions | Higher-priority project/explicit settings still follow Codex rules |
-| Claude Code | User role Markdown with model/effort, native default/concurrency env, routing instructions | Force settings and native execution-path exceptions can override the intended mapping |
-| Kimi Code | User role Markdown, existing secondary-model pool, per-alias effort, routing instructions | Model-role selection and max concurrency are guidance; provisioned aliases/capabilities are required |
-| Antigravity | User role Markdown with Pro/Flash/Flash Lite/inherit tiers and routing instructions | No concrete provider pin, documented per-role effort, or universal native max-three cap |
-| Grok Build | User role Markdown (read-only roles use permission_mode plan), per-role models and a general-purpose fallback in config.toml, native max_concurrent, routing instructions | No documented per-role effort; subagents use the main session effort. Higher-priority project/explicit settings still follow Grok Build rules |
+| ChatGPT (Codex) | User role TOMLs, native subagent defaults/concurrency, routing instructions | Higher-priority project/explicit settings still follow Codex rules |
+| Claude (Claude Code) | User role Markdown with model/effort, native default/concurrency env, routing instructions | Force settings and native execution-path exceptions can override the intended mapping |
+| Kimi (Kimi Code) | User role Markdown, existing secondary-model pool, per-alias effort, routing instructions | Model-role selection and max concurrency are guidance; provisioned aliases/capabilities are required |
+| Gemini (Antigravity) | User role Markdown with Pro/Flash/Flash Lite/inherit tiers and routing instructions | No concrete provider pin, documented per-role effort, or universal native max-three cap |
+| Grok (Grok Build) | User role Markdown (read-only roles use permission_mode plan), per-role models and a general-purpose fallback in config.toml, native max_concurrent, routing instructions | No documented per-role effort; subagents use the main session effort. Higher-priority project/explicit settings still follow Grok Build rules |
 
 These are preferences implemented through native features. APK does not participate in later agent operation and does not enforce policy on every request. avoidModels is guidance. No hook, wrapper or proxy is installed to bypass native limits.
 
+## 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 CLI 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`, newest version first, and within a version the most recently written build first | `~/.claude`, the same as the Claude Code CLI |
+
+A client found this way has `origin: "desktop_app"` in detect output. The app must be installed, and the bundled CLI must report a valid version. 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.
+
 Global configuration can be superseded by a project's native settings, session flags, environment or plugins. A fresh client session may be needed. Configured files, native loading and actual provider model execution are separate evidence.
 
 macOS is the local acceptance host. Linux has a source-isolation gate using bubblewrap and a hosted workflow prepared; hosted runs are pending. Windows application is explicitly unsupported.

package/docs/configuration-page.md

@@ -5,25 +5,25 @@ Open site/index.html in Google Chrome. The page is one self-contained HTML file.
 ## Four steps
 
 1. Add the subagent roles you need. A green check confirms a nonempty role selection. Each question-mark button explains its description and native prompt. Removing a role also removes its configuration rows. Readding it preserves its choices in the current page session.
-2. Add your coding tools. A green check confirms a nonempty tool selection. New tools append to the list. The first becomes active. From the second onward, All is active by default. A manually selected tool or All stays active during later additions. All configures the selected tools together. The CLI, not the browser, detects which selected tools are installed.
-3. Choose a work mode. No mode is selected initially. Each selected tool needs a chosen mode before the command becomes available. The first choice has no replacement warning. Individual tool details show every selected role's model and supported effort, followed by that tool's parallel limit. The shared All view hides these controls. All offers shared presets. Custom can be selected manually and is also set by model or effort edits. Each tool shows its own mode beneath its name. Individual presets warn before changing that tool. Replacing genuinely edited values, mixed per-tool bases or partially chosen modes from All warns before changing all selected tools. Selecting Custom alone without changing values does not create an overwrite warning. Cancel preserves the choices.
-4. Copy the setup command and run it in a terminal. Incomplete selections identify the missing steps with links. Invalid model settings or per-tool limits disable copying and clear the previous command. Clipboard failure selects the full command for manual copying.
+2. Add your AI assistants. A green check confirms a nonempty assistant selection. New assistants append to the list. The first becomes active. From the second onward, All is active by default. A manually selected assistant or All stays active during later additions. All configures the selected assistants together. The CLI, not the browser, detects which selected assistants are installed.
+3. Choose a work mode. No mode is selected initially. Each selected assistant needs a chosen mode before the command becomes available. The first choice has no replacement warning. Individual assistant details show every selected role's model and supported effort, followed by that assistant's parallel limit. The shared All view hides these controls. All offers shared presets. Custom can be selected manually and is also set by model or effort edits. Each assistant shows its own mode beneath its name. Individual presets warn before changing that assistant. Replacing genuinely edited values, mixed per-assistant bases or partially chosen modes from All warns before changing all selected assistants. Selecting Custom alone without changing values does not create an overwrite warning. Cancel preserves the choices.
+4. Copy the setup command and run it in a terminal. Incomplete selections identify the missing steps with links. Invalid model settings or per-assistant limits disable copying and clear the previous command. Clipboard failure selects the full command for manual copying.
 
-The page starts with every subagent role selected and no coding tool. A completed third step requires selected modes and valid model settings. A fourth green check means the current command was successfully copied, not installed. Configuration changes clear that check; opening another tool without changing values preserves it. Reset form clears selections, modes, copy status and the URL fragment without changing any installed native files. Light uses 2 parallel subagents, Standard uses 3 and Top-tier uses 2. Selecting a preset restores its models, effort and parallel limit for the targeted tools. Editing a limit marks only that tool Custom. Effort buttons fill their section and show supported explicit levels. A dash means no native effort setting. Unpinned values remain unpinned until changed. Kimi roles sharing a model alias share its effort. Antigravity offers only native tiers. Other tools also accept custom native model IDs, subject to CLI and account support.
+The page starts with every subagent role selected and no AI assistant. A completed third step requires selected modes and valid model settings. A fourth green check means the current command was successfully copied, not installed. Configuration changes clear that check; opening another assistant without changing values preserves it. Reset form clears selections, modes, copy status and the URL fragment without changing any installed native files. Light uses 2 parallel subagents, Standard uses 3 and Top-tier uses 2. Selecting a preset restores its models, effort and parallel limit for the targeted assistants. Editing a limit marks only that assistant Custom. Effort buttons fill their section and show supported explicit levels. A dash means no native effort setting. Unpinned values remain unpinned until changed. Kimi roles sharing a model alias share its effort. Gemini offers only native tiers. Other assistants also accept custom native model IDs, subject to CLI and account support.
 
-The command is pinned to this page's package version. It always expands every selected tool and role into visible model/effort arguments. Presets fill the form but do not shorten or hide the command. Tools follow their selected order. --roles carries the selected role IDs and --max-concurrent carries the shared fallback. Optional --codex-max-concurrent, --claude-max-concurrent, --kimi-max-concurrent and --antigravity-max-concurrent carry independent overrides. Nonempty --avoid-TOOL lists preserve existing model-avoidance guidance. Omitted tools are not configured.
+The command is pinned to this page's package version. It always expands every selected assistant and role into visible model/effort arguments. Presets fill the form but do not shorten or hide the command. Assistants follow their selected order. --roles carries the selected role IDs and --max-concurrent carries the shared fallback. Optional --chatgpt-max-concurrent, --claude-max-concurrent, --kimi-max-concurrent, --gemini-max-concurrent and --grok-max-concurrent carry independent overrides. Nonempty --avoid-TOOL lists preserve existing model-avoidance guidance. Omitted assistants are not configured.
 
-Each tool uses role=model:effort entries. :native means no explicit effort pin. Antigravity uses role=tier and Grok Build uses role=model, both without an effort suffix. The parser splits at the last colon, preserving model IDs that contain colons or @. Every selected role must be present exactly once for every selected tool. The generated command reports custom provenance because its values are explicit, even when a preset filled the form.
+Each assistant uses role=model:effort entries. :native means no explicit effort pin. Gemini uses role=tier and Grok uses role=model, both without an effort suffix. The parser splits at the last colon, preserving model IDs that contain colons or @. Every selected role must be present exactly once for every selected assistant. The generated command reports custom provenance because its values are explicit, even when a preset filled the form.
 
 The complete command is visible in a read-only field that grows to fit its contents. Copy preserves the visible POSIX shell line continuations. Soft wrapping adds no additional newlines. [Native field sizing](https://developer.chrome.com/docs/css-ui/css-field-sizing) handles content and window-size changes without a JavaScript resize helper. The page never executes the command or grants model access.
 
-Role/tool changes use native View Transitions with a reduced-motion setting and a synchronous fallback. Section hints are conditional: role guidance after selection, add-more guidance for one tool, individual-configuration guidance for two or more tools, mode guidance when available, and Copied in the fourth heading. Changed hints, step markers, editing-scope labels and per-tool mode captions hold a soft highlight for two seconds, then fade for two seconds. Tool-caption nodes are reused so switching the editing view does not interrupt a pulse. Identical state does not repeat the animation. Labels retain their size during layout changes. No animation dependency is installed.
+Role/assistant changes use native View Transitions with a reduced-motion setting and a synchronous fallback. Section hints are conditional: role guidance after selection, add-more guidance for one assistant, individual-configuration guidance for two or more assistants, mode guidance when available, and Copied in the fourth heading. Changed hints, step markers, editing-scope labels and per-assistant mode captions hold a soft highlight for two seconds, then fade for two seconds. Assistant-caption nodes are reused so switching the editing view does not interrupt a pulse. Identical state does not repeat the animation. Labels retain their size during layout changes. No animation dependency is installed.
 
 ## Share a setup
 
-The Max at once field appears only in individual coding-tool details. It accepts whole numbers from 1 to 32. Each tool retains its own limit while switching the editing view. Model-preset selection restores that tool's preset limit. Invalid selected-tool limits block the command and copy action. Invalid cached settings on unselected tools do not block selected tools. Kimi and Antigravity use the value as guidance rather than a native hard cap.
+The Max at once field appears only in individual AI assistant details. It accepts whole numbers from 1 to 32. Each assistant retains its own limit while switching the editing view. Model-preset selection restores that assistant's preset limit. Invalid selected-assistant limits block the command and copy action. Invalid cached settings on unselected assistants do not block selected assistants. Kimi and Gemini use the value as guidance rather than a native hard cap.
 
-Each form edit replaces the current URL fragment with its visible state. Copy the page address to share it. Version 2 fragments contain roles, tool order, mode/base, selected model/effort pairs, each tool's limit and editing scope. Version 1 scalar-limit links remain readable. Their exact count is preserved; a count that differs from the current preset makes the restored tool Custom. It excludes clipboard completion and unselected cached choices. Opening a link restores the form, including unfinished choices and model drafts. Command validation still blocks incomplete or invalid settings.
+Each form edit replaces the current URL fragment with its visible state. Copy the page address to share it. Version 2 fragments contain roles, assistant order, mode/base, selected model/effort pairs, each assistant's limit and editing scope. Version 1 scalar-limit links remain readable. Links from 0.2.0 or earlier that include ChatGPT or Gemini do not open, because those assistants then had the IDs codex and agy. Their exact count is preserved; a count that differs from the current preset makes the restored assistant Custom. It excludes clipboard completion and unselected cached choices. Opening a link restores the form, including unfinished choices and model drafts. Command validation still blocks incomplete or invalid settings.
 
 src/share.mjs is the pure browser/Node codec. It uses versioned base64url JSON with strict IDs, fields, duplicate-key, size, UTF-8 and release checks. The fragment stays in the browser and needs no database or config lookup service. Invalid or mismatched-release links show an error and cannot produce an applicable command. Missing-step links scroll/focus without overwriting the setup fragment.
 
@@ -37,7 +37,7 @@ Serve site/index.html from any static host. It can become part of getacc.dev wit
 
 The current version is unreleased. Its page labels that status. Before npm publication, use the verified local tarball as described in the [AI operator guide](../AGENT_INSTALL.md). The checks do not publish or deploy anything.
 
-The introduction includes a collapsed “How it works and why you need it” explanation aligned with the README. Native details/summary supports keyboard toggling; opening/closing takes 200 ms and honors reduced motion. The hosted versioned URL preserves release-specific shared links.
+The introduction matches the README: it states the problem, and a collapsed “Why” section holds the inline limit illustration from scripts/build-limits-chart.mjs and a link to [how it was measured](limits-evidence.md). Native details/summary supports keyboard toggling; opening/closing takes 200 ms and honors reduced motion. The hosted versioned URL preserves release-specific shared links.
 
 The footer credits Mykola Maksymenko and links to his supplied LinkedIn profile, Agents Can Communicate and Automatis Skills. Package author metadata is the source for the visible byline, title, author tags and static JSON-LD Person/project/page relationship. The canonical URL follows the homepage origin and bundled release version. These links load only when followed; no social widgets or runtime metadata requests are added.
 

package/docs/deployment.md

@@ -6,6 +6,8 @@ The latest configurator at https://agent-policy-kit.trymenow.io/ follows reviewe
 
 GitHub Actions runs Deploy configurator after a successful same-repository push verification on main. A successful version-tag verification can retry a site build after a package release. The deployment workflow always checks out main, never the triggering branch or tag's code. It verifies successful main-push CI for the checked-out commit and rechecks the latest main immediately before upload. Stale runs skip; deployments are serialized.
 
+A merged version bump waits for its release. When the package version has no v-prefixed or bare tag reachable from main, the guard skips the deployment, and the run states that the version is not tagged and published yet. The run does not fail. The tag push after npm publication starts the deployment. A tagged version that npm does not serve yet still fails the build; use the manual retry after publication.
+
 The production environment permits the main branch only. It has no required-reviewer pause, so normal merges need no manual deployment. workflow_dispatch provides a main-only retry after an external outage or delayed npm publication.
 
 ## Latest page and archived releases

package/docs/development.md

@@ -10,8 +10,18 @@ npm run test:unit
 npm run test:package
 ```
 
+Enable the contributor pre-push check once per clone:
+
+```sh
+git config core.hooksPath .githooks
+```
+
+The hook runs npm run check and npm run test:unit before each push that updates a branch or tag. A push that only deletes refs skips both. The hook is not packaged and is unrelated to generated client settings. The packed-package gate runs in CI, and CI also requires the Lint check.
+
 npm run test:cache primes public dependency metadata on a fresh machine before the offline tarball consumers run. It installs only into a disposable directory and removes it afterward. npm ci alone may cache tarballs without the registry metadata required by a new offline consumer.
 
+Detection checks desktop app bundles under /Applications. Set AGENT_POLICY_APPLICATIONS_DIR to another absolute directory to replace /Applications. The tests set it, so apps installed on the host do not change their results.
+
 npm test includes both unit tests and the installed-tarball gate. The gate needs macOS sandbox-exec or Linux bubblewrap. It must actually deny checkout access; unavailable isolation fails rather than skipping. Use a normal approved host if a managed sandbox forbids nesting.
 
 src/policy.mjs validates shared preferences. src/detect.mjs probes executable identity. Native generation and the installer write ordinary role/config/instruction files. src/setup.mjs coordinates detected clients. src/inspect.mjs reads bounded native subagent fields without writes or executable probing. src/output.mjs formats readable terminal results. bin/agent-policy.mjs retains captured JSON output and supports explicit --json.

package/docs/installation.md

@@ -6,11 +6,11 @@ Use setup --release --preset balanced to preview Standard, a version's default c
 
 Interactive terminals show readable results. Captured output remains JSON, and --json always requests JSON. A preview writes nothing. A repeated application reports unchanged clients. Partial results identify the clients that need attention.
 
-Run `agent-policy show` to read current user-level native subagent settings before or after APK setup. Add `--client codex` for one tool or `--json` for machine output. It needs neither client executables nor APK receipts. Relevant native-home environment variables select the active user profile. An explicit --home selects standard client directories under that home. The command never changes files or calls a model.
+Run `agent-policy show` to read current user-level native subagent settings before or after APK setup. Add `--client chatgpt` for one AI assistant or `--json` for machine output. It needs neither client executables nor APK receipts. Relevant native-home environment variables select the active user profile. An explicit --home selects standard client directories under that home. The command never changes files or calls a model.
 
-Show reads Codex TOML roles, Claude/Antigravity/Grok Build Markdown role fields (Grok Build models come from config.toml [subagents.models]), and Kimi's native secondary-model pool. Kimi APK role mappings and APK concurrency instructions are labeled as guidance. Missing pins stay unspecified. Supported Markdown fields use plain, single-quoted or JSON-compatible double-quoted scalar values. Unsupported role syntax, unsafe files and incomplete reads produce explicit attention statuses and exit code 3. External role-file references, project/managed settings, plugins and session overrides are not resolved. Show displays supported current values even when APK-managed files have local edits. It does not print prompts, credentials, raw configuration or private paths.
+Show reads ChatGPT's Codex TOML roles, Claude/Gemini/Grok Markdown role fields (Grok models come from config.toml [subagents.models]), and Kimi's native secondary-model pool. Kimi APK role mappings and APK concurrency instructions are labeled as guidance. Missing pins stay unspecified. Supported Markdown fields use plain, single-quoted or JSON-compatible double-quoted scalar values. Unsupported role syntax, unsafe files and incomplete reads produce explicit attention statuses and exit code 3. External role-file references, project/managed settings, plugins and session overrides are not resolved. Show displays supported current values even when APK-managed files have local edits. It does not print prompts, credentials, raw configuration or private paths.
 
-Only genuine detected and selected clients receive files. A standard native profile is required for automatic setup; nondefault native-home environment roots get a zero-write prerequisite. Explicit --home selects the standard layout under an intentional target. Preserve original --home/--state-dir for later removal.
+Only genuine detected and selected clients receive files. On macOS, detection also finds the CLIs that ChatGPT Desktop and Claude Desktop include; see [desktop apps](compatibility.md#desktop-apps). A standard native profile is required for automatic setup; nondefault native-home environment roots get a zero-write prerequisite. Explicit --home selects the standard layout under an intentional target. Preserve original --home/--state-dir for later removal.
 
 Named APK roles and a managed global instruction block configure optional delegation. Main models, credentials, permissions, disabled agent features and unrelated hooks/plugins/settings are preserved. Native capabilities still differ; see [support](compatibility.md).
 

package/docs/limits-evidence.md

@@ -0,0 +1,24 @@
+# How the limit illustration was measured
+
+The README illustration comes from the author's local Codex session logs (`~/.codex/sessions`). It records one developer's work on one plan. It is not a benchmark.
+
+## Method
+
+Codex logs the weekly limit as `rate_limits.primary.used_percent` together with its reset time. Free limit resets started two separate windows, each from 0%. The illustration compares them:
+
+| | Without APK | With APK |
+|---|---|---|
+| Subagent setup | No role settings; about half of subagent tokens ran on GPT-6 Astra, the top model | Roles put most subagent work on GPT-6.1 Sol and GPT-6 Luna |
+| Subagents started | 67 | 131 |
+| Active work until the limit reached 100% | 5.3 h | 25.0 h |
+| Credits per 1M tokens after the limit | 35.3 | 3.0 |
+
+Active work counts 10-minute intervals that contain at least one model response. Idle time, such as nights, is excluded. The illustration places these hours on 8-hour workdays.
+
+## Limits of the comparison
+
+- The tasks differed between the two windows.
+- Main-session effort was mostly xhigh in the first window and mostly high or lower in the second.
+- Both windows come from one account and one developer's habits.
+
+Claude Code logs showed the same pattern. When subagents inherited Opus, they produced 2.7 times as many output tokens as the main session. With roles on Sonnet and Haiku, they produced 0.16 times as many. That "after" sample covers one day.

package/docs/model-catalog.md

@@ -4,11 +4,11 @@ models/catalog.json is the release snapshot, checked on 2026-10-30 UTC (2026-10-
 
 | Tool | Current selectable inventory | Evidence |
 |---|---|---|
-| Codex | 9 visible model IDs | CLI 0.166.0 bundled catalog and [official models](https://learn.chatgpt.com/docs/models) |
-| Claude Code | 14 versioned IDs, 4 family aliases and inherit | [Native model configuration](https://code.claude.com/docs/en/model-config), CLI 2.1.312 |
-| Kimi Code | 6 upstream models through preferred native aliases | [Current Kimi Code models](https://www.kimi.com/code/docs/en/kimi-code/models), CLI 2.4.0 provisioned metadata |
-| Antigravity | Pro, Flash, Flash Lite and inherit tiers | CLI 1.4.10 parser and [subagent documentation](https://antigravity.google/docs/subagents?tab=cli) |
-| Grok Build | Grok 4.7, 4.6, 4.5 and Grok Build 0.1 model IDs (checked 2026-11-01) | [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), CLI 1.0.70 |
+| ChatGPT (Codex) | 9 visible model IDs | CLI 0.166.0 bundled catalog and [official models](https://learn.chatgpt.com/docs/models) |
+| Claude (Claude Code) | 14 versioned IDs, 4 family aliases and inherit | [Native model configuration](https://code.claude.com/docs/en/model-config), CLI 2.1.312 |
+| Kimi (Kimi Code) | 6 upstream models through preferred native aliases | [Current Kimi Code models](https://www.kimi.com/code/docs/en/kimi-code/models), CLI 2.4.0 provisioned metadata |
+| Gemini (Antigravity) | Pro, Flash, Flash Lite and inherit tiers | CLI 1.4.10 parser and [subagent documentation](https://antigravity.google/docs/subagents?tab=cli) |
+| Grok (Grok Build) | Grok 4.7, 4.6, 4.5 and Grok Build 0.1 model IDs (checked 2026-11-01) | [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), CLI 1.0.70 |
 
 Hidden security/utility models, session modes and private deployments are separate from this native subagent inventory. Custom IDs remain available where the native format supports them.
 
@@ -41,10 +41,10 @@ Account/provider access varies. Custom model IDs remain available for supported
 
 These are starting recommendations, reviewed on 2026-10-30. Subagent usage counts against the same plan limits as the main session, and every parallel session adds to it. The presets therefore differ in how much of the plan subagents may use, not in a claimed quality ranking. No comparative task benchmark was run. Vendors' effort labels and subscription usage are not directly comparable, so one role can get different levels in different tools.
 
-- **Light:** light models for every role, so plan limits last longest. It suits entry plans and many parallel sessions. In Codex and Claude Code, reviews and test creation receive extra reasoning because checking edge cases differs from executing known steps. Kimi roles share one alias and therefore one effort, kept low to save quota; Antigravity has no per-role effort and uses Flash for code and Flash Lite for lighter work.
-- **Standard:** stronger implementation, review, test creation and documentation, with light models for fact gathering and mechanical work. Antigravity's light tier for exploration and docs is Flash. Codex runs Luna at high for exploration, OpenAI's suggested starting level for Luna; Claude's Haiku explorer uses its native default, medium. No role uses Astra, Fable or K3.1 Pro. Kimi uses K3 256K for code to keep its quota footprint below the full-context K3 variant; larger-context choices remain editable.
-- **Top-tier:** Opus 5.5, GPT-6.1 Sol and K3 at high effort for implementation, review and tests. It uses limits fastest and suits top plans with few parallel sessions. Exploration and documentation use the same high-end model; only the Task runner stays lighter. Kimi keeps one effort per shared alias, and because K2.8 has no medium level its Task runner rises from low to high. Antigravity has one top tier, Pro, so its Standard and Top-tier differ only in exploration, docs and the Task runner.
-- **Top models switch:** under Top-tier, a per-tool switch replaces the Coder, Reviewer and Test writer model with the tool's top model: Fable 5.1, GPT-6 Astra or K3.1 Pro, still at high effort. Antigravity and Grok Build have no such tier. The switch is off by default because these models use limits much faster and native default subagent settings copy the first selected role (the Coder when selected) to subagents started without a named role. It is part of Top-tier, not a separate preset, and share links keep it.
+- **Light:** light models for every role, so plan limits last longest. It suits entry plans and many parallel sessions. In ChatGPT and Claude, reviews and test creation receive extra reasoning because checking edge cases differs from executing known steps. Kimi roles share one alias and therefore one effort, kept low to save quota; Gemini has no per-role effort and uses Flash for code and Flash Lite for lighter work.
+- **Standard:** stronger implementation, review, test creation and documentation, with light models for fact gathering and mechanical work. Gemini's light tier for exploration and docs is Flash. ChatGPT runs Luna at high for exploration, OpenAI's suggested starting level for Luna; Claude's Haiku explorer uses its native default, medium. No role uses Astra, Fable or K3.1 Pro. Kimi uses K3 256K for code to keep its quota footprint below the full-context K3 variant; larger-context choices remain editable.
+- **Top-tier:** Opus 5.5, GPT-6.1 Sol and K3 at high effort for implementation, review and tests. It uses limits fastest and suits top plans with few parallel sessions. Exploration and documentation use the same high-end model; only the Task runner stays lighter. Kimi keeps one effort per shared alias, and because K2.8 has no medium level its Task runner rises from low to high. Gemini has one top tier, Pro, so its Standard and Top-tier differ only in exploration, docs and the Task runner.
+- **Top models switch:** under Top-tier, a per-tool switch replaces the Coder, Reviewer and Test writer model with the tool's top model: Fable 5.1, GPT-6 Astra or K3.1 Pro, still at high effort. Gemini and Grok have no such tier. The switch is off by default because these models use limits much faster and native default subagent settings copy the first selected role (the Coder when selected) to subagents started without a named role. It is part of Top-tier, not a separate preset, and share links keep it.
 
 Top-tier, with or without top models, pins high rather than xhigh or max. Native default subagent settings copy the first selected role (the Coder when selected), so a higher level would also apply to every subagent started without a named role. OpenAI recommends starting Astra at Light and places High and Extra High in the same band for difficult multi-step work. Anthropic describes high as the level for work where verification matters and xhigh as deeper reasoning at higher token spend; high is Fable's native default. Higher levels remain available in Custom.
 
@@ -52,7 +52,7 @@ No preset bans any model. An unselected model remains available in Custom. Expli
 
 ### Light
 
-| Role | Codex | Claude Code | Kimi Code | Antigravity | Grok Build |
+| Role | ChatGPT | Claude | Kimi | Gemini | Grok |
 |---|---|---|---|---|---|
 | Coder | Luna · medium | 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 |
@@ -63,7 +63,7 @@ No preset bans any model. An unselected model remains available in Custom. Expli
 
 ### Standard
 
-| Role | Codex | Claude Code | Kimi Code | Antigravity | Grok Build |
+| 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 |
@@ -74,7 +74,7 @@ No preset bans any model. An unselected model remains available in Custom. Expli
 
 ### Top-tier
 
-| Role | Codex | Claude Code | Kimi Code | Antigravity | Grok Build |
+| 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 |
@@ -83,7 +83,7 @@ No preset bans any model. An unselected model remains available in Custom. Expli
 | Docs writer | Sol · high | Opus 5.5 · high | K3 · high | Pro | Grok 4.7 |
 | Task runner | Sol · medium | Sonnet 5.5 · medium | K2.8 Preview · high | Flash | Grok Build 0.1 |
 
-With the top models switch on, Coder, Reviewer and Test writer use Astra · high in Codex, Fable 5.1 · high in Claude Code and K3.1 Pro · high in Kimi Code.
+With the top models switch on, Coder, Reviewer and Test writer use Astra · high in ChatGPT, Fable 5.1 · high in Claude and K3.1 Pro · high in Kimi.
 
 ## Reasons and access requirements
 
@@ -93,9 +93,9 @@ Anthropic's [model comparison](https://platform.claude.com/docs/en/models/overvi
 
 [Kimi's model table](https://www.kimi.com/code/docs/en/kimi-code/models.html) describes K2.8 Preview's efficient thinking and the smaller quota footprint of K3 256K. Pro Highspeed has the same capabilities as regular Pro at a quota premium, so it is optional rather than a default for either economical or quality priorities. Selected aliases must be provisioned and Pro must have thinking enabled. Roles sharing one alias share its native effort setting.
 
-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. Light uses Grok Build 0.1 everywhere, Standard adds Grok 4.7 for code, review, tests and docs, and Top-tier also uses it for exploration. Grok 4.6 and 4.5 stay available in Custom. Account access to each model varies by plan. Per-role effort is unavailable, and there is no top models switch for Grok Build.
+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. Light uses Grok Build 0.1 everywhere, Standard adds Grok 4.7 for code, review, tests and docs, and Top-tier also uses it for exploration. Grok 4.6 and 4.5 stay available in Custom. Account access to each model varies by plan. Per-role effort is unavailable, and there is no top models switch for Grok.
 
-Antigravity recommendations use only its native role tiers. The CLI's Pro/Flash/Flash Lite selectors do not freeze the underlying provider model, and there is no per-role effort field. Account access and native precedence still apply; see [support](compatibility.md).
+Gemini recommendations use only the native role tiers of Antigravity. The CLI's Pro/Flash/Flash Lite selectors do not freeze the underlying provider model, and there is no per-role effort field. Account access and native precedence still apply; see [support](compatibility.md).
 
 Native default effort means no explicit override. Unsupported effort fields are omitted. Explicit levels are filtered by model and native client; Kimi additionally checks provisioned support_efforts. It never silently changes the main agent's effort to satisfy a helper's setting.
 

package/docs/policy.md

@@ -3,7 +3,7 @@
 Start with policies/balanced.json or another preset in the selected release. The [JSON Schema](../schema/policy.schema.json) describes data shape; the configuration validator also checks the release catalog's known model/effort compatibility.
 
 - schemaVersion1; maxConcurrent is the shared fallback, from 1 to 32. Optional clients[tool].maxConcurrent overrides it for one tool. Older policies without overrides keep their shared behavior.
-- clients contains codex, claude, kimi, agy (the technical key for Antigravity) and/or grok (Grok Build).
+- clients contains chatgpt (Codex), claude (Claude Code), kimi (Kimi Code), gemini (Antigravity) and/or grok (Grok Build). Version 0.2.0 and earlier used the keys codex and agy. They are not accepted.
 - Optional top-level selectedRoles is a nonempty unique array of worker, reviewer, explorer, tester, writer and routine IDs. Omit it for all six roles in the executing release. Only selected roles receive native files and routing instructions.
 - code/light hold default model+effort pairs.
 - Optional roles inside each client overrides each selected role independently. Worker/reviewer/tester otherwise use code; explorer/writer/routine use light. Public presets also contain role-specific overrides.