agent-policy-kit 0.3.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.3.0 agent-policy release
-npx --yes --ignore-scripts --package agent-policy-kit@0.3.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 \
-  --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
+npx --yes --ignore-scripts --package agent-policy-kit@0.4.0 agent-policy detect --json
 ```
 
-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.
+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 --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.
+## 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. 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. 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).
 
-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.
+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,55 @@
 
 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
@@ -91,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
 
@@ -133,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,28 +2,35 @@
 
 Created and maintained by [Mykola Maksymenko](https://www.linkedin.com/in/nick-maximenko/).
 
-**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.
+**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.
 
 ![One weekly limit: 5.3 h vs 25 h of work](docs/assets/subagent-limits.svg)
 
-<sub>My own Codex logs; tasks differed between the runs. [How it was measured](docs/limits-evidence.md).</sub>
+<sub>My own Codex logs; tasks differed between the runs. [How it was measured](docs/research/limits-evidence.md).</sub>
 
 ## Set it up
 
-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.
+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.
 
 ![Configurator: models and effort for each subagent role, and the setup command](docs/assets/configurator.png)
 
+[Getting started](docs/guide/getting-started.md) shows the full path, from the configurator to removal.
+
 ## Good to know
 
-- 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.
+- 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.
+
+## Documentation
 
-[Model catalog](docs/model-catalog.md) · [Release notes](CHANGELOG.md) · [AI operator guide](AGENT_INSTALL.md) · [Support](docs/compatibility.md) · [Privacy](docs/privacy.md)
+- [Documentation index](docs/README.md)
+- [Presets](docs/reference/presets.md)
+- [Release notes](CHANGELOG.md)
+- [AI operator guide](AGENT_INSTALL.md)
 
 ## Related projects
 

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/design/2026-11-01-documentation-structure.md

@@ -0,0 +1,58 @@
+# Documentation structure
+
+## Intent
+
+The documentation grew as a set of notes: one flat `docs/` folder for four audiences, documents that mix several topics, the same facts repeated in up to eight places, and stale statements from before the first publication. The goal is a set of independent documents. Each document answers one question for one audience, can be read without the others, and links to the single place where a related fact is documented.
+
+The research behind the presets is also documented, so a reader can check why a preset has its values.
+
+## Decisions
+
+- Documents move into audience folders. Old paths are removed without redirect stubs (owner decision). Links in code, tests, the page template and the changelog are updated to the new paths.
+- The work is a separate pull request, stacked on the 0.4.0 preset pull request (#22).
+- Language stays English. Style follows ASD-STE100 principles: short sentences, active voice, present tense, one instruction per step, terms defined on first use.
+- Every fact has one canonical document. Other documents link to it instead of restating it. Short summaries with a link are allowed where a reader needs the context.
+- Every document starts with a title and a short paragraph that says what it covers and who it is for.
+- No account data, private paths, raw configuration, credentials or test evidence from a real account goes into Git. Research describes product facts and public sources, not what one account can access.
+
+## Structure
+
+| Path | Audience | Covers | Main sources |
+|---|---|---|---|
+| `README.md` | Everyone | What APK is, quick start, links | current README |
+| `AGENT_INSTALL.md` | AI agent that installs APK | Step-by-step runbook: select release, detect, plan, apply, verify, remove, report. Details are links. | current AGENT_INSTALL |
+| `CONTRIBUTING.md`, `SECURITY.md` | Contributors, reporters | Refreshed, no pre-publication statements | current files |
+| `docs/README.md` | Everyone | Index: which document answers which question | new |
+| `docs/guide/getting-started.md` | People who use APK | Configurator → command → check → remove the package; common scenarios | installation, use-cases |
+| `docs/guide/configurator.md` | People who use APK | The page: steps, modes, top models switch, per-tool limits, share links | configuration-page (user parts) |
+| `docs/guide/commands.md` | People and agents | CLI reference: every command, input mode and flag, output formats, exit codes | AGENT_INSTALL §2, installation, releases, `bin/` and `src/` |
+| `docs/guide/preferences.md` | Advanced users | Preferences JSON format and validation rules | policy |
+| `docs/guide/updates-and-removal.md` | People who use APK | Choose a release, upgrade, downgrade, uninstall, recover from an interrupted change, what a release does not freeze | releases, recovery, model-updates (user part) |
+| `docs/guide/privacy.md` | Everyone | What APK reads, writes and never sends | privacy |
+| `docs/reference/assistants.md` | Everyone | Per assistant: detected executable, files written, native limits, desktop apps, prerequisites | compatibility, AGENT_INSTALL §4, installation, design/grok |
+| `docs/reference/roles.md` | Everyone | The six roles, their prompts and permissions, the default subagent per assistant, how effort applies | `src/roles.mjs`, `src/native.mjs`, `src/install.mjs`, architecture |
+| `docs/reference/presets.md` | Everyone | Light, Standard, Top-tier matrices, top models switch, parallel limits, design principles, short reasons with links to research | model-catalog (preset parts) |
+| `docs/reference/model-catalog.md` | Everyone | What `models/catalog.json` contains: fields, inventory per assistant, efforts, defaults, lifecycle | model-catalog (catalog parts), models/README |
+| `docs/reference/ownership.md` | Advanced users, maintainers | Receipts v2–v4, state directory, transactions, drift, rollback; glossary of owned, drift, receipt | architecture, releases, recovery, AGENT_INSTALL §5 |
+| `docs/research/2026-11-01-model-review.md` | Maintainers, curious users | Evidence for the 0.4.0 presets: sources by vendor, Opus vs Sonnet by effort, Fable vs Opus, effort returns, small models, open questions | `.agent-work` research report and notes |
+| `docs/research/limits-evidence.md` | Everyone | How the README limit illustration was measured | limits-evidence |
+| `docs/maintainers/architecture.md` | Maintainers | Modules, data flow, release = version | architecture |
+| `docs/maintainers/development.md` | Maintainers | Setup, tests, hooks, sandbox requirements | development |
+| `docs/maintainers/model-review.md` | Maintainers | How to review models and presets for a release | model-updates, model-catalog maintenance text |
+| `docs/maintainers/release.md` | Maintainers | Prepare, verify and publish a configuration release | npm-release |
+| `docs/maintainers/website.md` | Maintainers | Page build, hosting, versioned pages, automatic deployment, credentials | configuration-page (build parts), deployment |
+| `docs/maintainers/verification.md` | Maintainers | Verification log per release | verification |
+| `models/README.md` | Maintainers | Two lines: what the file is, link to the catalog reference | models/README |
+| `docs/design/` | Maintainers | Dated design specs, unchanged | — |
+
+## Constraints
+
+- `test/catalog.test.mjs` parses the preset tables (`### Light`, `### Standard`, `### Top-tier`, rows `| Coder | … |`). The tables move to `docs/reference/presets.md` in the same format, and the test reads that path.
+- `scripts/build-site.mjs` links the page to the limits evidence; the link moves to `docs/research/limits-evidence.md`.
+- The packaged `README.md` must keep `# Agent Policy Kit` as its first line and the `docs/assets/subagent-limits.svg` image.
+- `CHANGELOG.md` keeps its entries; only link targets change. The 0.4.0 entry notes the reorganization.
+- Facts must match the code on this branch. Where a document and the code disagree, the code wins and the difference is reported.
+
+## Out of scope
+
+Code behavior, presets, catalog values, the page interface and the changelog wording of released versions.