agent-policy-kit 0.2.0 → 0.4.0

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.

package/docs/guide/commands.md

@@ -0,0 +1,375 @@
+# Commands
+
+This document is the full reference for the `agent-policy` command line: every command, input mode and option, the output formats and the exit codes. It is for people and AI agents that run APK in a terminal. For a first setup, see [Getting started](getting-started.md).
+
+## Run the CLI
+
+APK needs Node.js 22.13 or later in the 22 line, or Node.js 24 or later.
+
+Run a pinned release with `npx`:
+
+```sh
+npx --yes --ignore-scripts --package agent-policy-kit@0.4.0 agent-policy <command> [options]
+```
+
+- `--package agent-policy-kit@0.4.0` selects the configuration release. The package version is the release version.
+- `--ignore-scripts` prevents npm install scripts.
+- `--yes` lets npx download the package without a prompt.
+
+The examples below write only `agent-policy <command>`. Put the `npx` prefix in front of them, or use an installed `agent-policy` executable.
+
+APK is a one-shot configurator. Each command runs once and exits. The native files that it writes do not depend on the package.
+
+## Commands
+
+| Command | Purpose | Writes files |
+|---|---|---|
+| [`setup`](#setup-and-install) | Plan the native configuration for detected assistants. With `--apply`, write it. | Only with `--apply` |
+| [`install`](#setup-and-install) | The same as `setup`. | Only with `--apply` |
+| [`show`](#show) | Read the current user-level subagent settings of each assistant. | No |
+| [`doctor`](#doctor) | Verify the configuration that APK owns. | No |
+| [`detect`](#detect) | Find installed assistants from their executables. | No |
+| [`release`](#release) | Show the configuration release of this package and its release notes. | No |
+| [`uninstall`](#uninstall) | Plan the removal of the configuration that APK owns. With `--apply`, remove it. | Only with `--apply` |
+| [`init`](#init) | Create an editable preferences file. | Yes, a new file only |
+| [`instructions`](#instructions) | Print the AI operator guide. | No |
+| `help` | Print the usage summary. | No |
+
+Each command accepts exactly one command name and no other positional argument. Two more options work without a command:
+
+- `--help` prints the usage summary. No command or `help` does the same.
+- `--version` prints the package version.
+
+## Common options
+
+| Option | Value | Used by | Meaning |
+|---|---|---|---|
+| `--client` | `chatgpt`, `claude`, `kimi`, `gemini` or `grok` | `setup`, `install`, `show`, `doctor`, `detect`, `uninstall` | Limit the command to one assistant. |
+| `--home` | A path | `setup`, `install`, `show`, `doctor`, `uninstall` | Use the standard assistant folders under this folder instead of your home folder. |
+| `--state-dir` | An absolute path | `setup`, `install`, `show`, `doctor`, `uninstall` | Use this APK state directory. |
+| `--apply` | none | `setup`, `install`, `uninstall` | Write the planned changes. Without it, the command is a preview. |
+| `--json` | none | all commands except `instructions` and `help` | Print JSON. See [Output](#output). |
+
+Assistant IDs map to coding agents: `chatgpt` is Codex, `claude` is Claude Code, `kimi` is Kimi Code, `gemini` is Antigravity and `grok` is Grok Build. Version 0.2.0 and earlier used `codex` and `agy`. These IDs are not accepted.
+
+### Home folder and state directory
+
+The *state directory* is the private APK folder with receipts, saved preferences and transaction backups. The [ownership reference](../reference/ownership.md#state-directory) gives its default location, the order in which APK selects it, and its content. A path that is not absolute fails with `STATE_PATH_MUST_BE_ABSOLUTE`.
+
+If you use `--home` or `--state-dir` for setup, use the same values for `doctor`, `show` and `uninstall` later.
+
+Automatic setup uses the standard native folders, for example `~/.codex` and `~/.claude`. If `CODEX_HOME`, `CLAUDE_CONFIG_DIR`, `KIMI_CODE_HOME` or `GROK_HOME` points to a different folder, setup writes nothing for that assistant. It reports the prerequisite `native-home-override-unsupported`. With `--home`, APK skips this check and uses the standard layout under `--home`.
+
+## setup and install
+
+`setup` plans the native configuration for each detected and selected assistant. `install` is the same command. Without `--apply`, the command writes nothing. With `--apply`, it writes the plan.
+
+```sh
+agent-policy setup [input] [--client ID] [--home PATH] [--state-dir PATH] [--apply] [--json]
+```
+
+APK configures only assistants that are installed and selected in the preferences. It finds them as `detect` does. An assistant that is not installed is skipped. Each assistant has its own transaction: one assistant can succeed while another stops.
+
+A repeated setup with the same values changes no file. The preview reports `planned` with no files, and the readable output shows `Already up to date`. With `--apply`, the result is `unchanged`. After a change, open a new session in the assistant to load it.
+
+### Input modes
+
+The input sets the preferences. Use one input mode at a time. A second mode fails with `CONFLICTING_OPTIONS`.
+
+| Mode | Options | Preferences | Recorded source | Replaces an earlier APK setup |
+|---|---|---|---|---|
+| Default | none | The saved `policy.json` in the state directory, or the Standard preset if there is none | `saved` or `release` | No |
+| [Explicit tool arguments](#explicit-tool-arguments) | `--roles`, `--max-concurrent` and one or more tool options | The values in the command | `custom` | Yes |
+| [Release presets](#release-presets---release-and---preset) | `--release`, `--preset NAME`, or both | A preset of this release | `release`, with the preset name | Yes |
+| [Encoded preferences](#encoded-preferences---config) | `--config BASE64URL` | The decoded JSON | `custom` | Yes |
+| [Preferences file](#preferences-file---policy) | `--policy FILE` | The file | `custom` | No |
+
+*Replaces an earlier APK setup* means that APK can change an existing APK configuration to the new values in one step. Modes that do not replace stop with `INSTALLATION_CONFLICT` or `POLICY_CONFLICT` if the request differs from the saved setup. The [ownership reference](../reference/ownership.md) explains receipts and replacement.
+
+### Explicit tool arguments
+
+The configurator generates this mode. You can also write it yourself.
+
+```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=claude-sonnet-5-5:high,explorer=claude-haiku-5-5:native' \
+  --claude-max-concurrent 2 \
+  --gemini 'reviewer=pro,explorer=flash' \
+  --grok 'reviewer=grok-4.7,explorer=grok-4.7'
+```
+
+| Option | Value | Rules |
+|---|---|---|
+| `--roles` | Comma-separated role IDs: `worker`, `reviewer`, `explorer`, `tester`, `writer`, `routine` | Required. No duplicates. |
+| `--max-concurrent` | A whole number from 1 to 32 | Required. The shared parallel limit. |
+| `--chatgpt`, `--claude`, `--kimi` | `ROLE=MODEL:EFFORT,...` | One entry for each role in `--roles`, exactly once. |
+| `--gemini` | `ROLE=TIER,...` | `TIER` is `pro`, `flash`, `flash_lite` or `inherit`. No effort. |
+| `--grok` | `ROLE=MODEL,...` | No effort. A model that ends with `:` and an effort word is refused. |
+| `--TOOL-max-concurrent` | A whole number from 1 to 32 | Optional. Replaces `--max-concurrent` for one assistant. Needs the `--TOOL` option. |
+| `--avoid-TOOL` | Comma-separated model IDs | Optional. At most 32 models. Routing guidance only. Needs the `--TOOL` option. |
+
+`TOOL` is `chatgpt`, `claude`, `kimi`, `gemini` or `grok`. At least one tool option is necessary. Each tool option selects that assistant. Assistants without a tool option are not configured.
+
+Rules for the values:
+
+- `EFFORT` is `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` or `native`. `native` sets no explicit effort, so the assistant uses its native default.
+- APK splits `MODEL:EFFORT` at the last colon. A model ID can contain colons.
+- A model ID must follow the rule in [Preferences](preferences.md#choices).
+- The effort must be a level that the assistant supports. For a model in the catalog, it must be a level of that model. The [model catalog reference](../reference/model-catalog.md) lists the levels.
+- A model in `--avoid-TOOL` cannot also be selected for a role.
+- For Kimi, effort applies to a model alias, not to a role. [Roles](../reference/roles.md#how-effort-applies) gives the rules. The alias `primary` is not accepted.
+- Each explicit option can appear only once. A duplicate fails with `DUPLICATE_OPTION`.
+- This mode works only with `setup` and `install`. It cannot be used with `--client`.
+
+Keep the shell quotes. A value that is not valid fails with `INVALID_EXPLICIT_CONFIG` before APK reads any assistant file.
+
+### Release presets (`--release` and `--preset`)
+
+This mode applies a named preset of the package release that you run.
+
+```sh
+agent-policy setup --release
+agent-policy setup --release --preset quality --apply
+```
+
+| Option | Value | Meaning |
+|---|---|---|
+| `--release` | none | Use a preset of this release. Without `--preset`, the preset is `balanced`. |
+| `--preset` | `fast`, `balanced` or `quality` | Select the preset: Light, Standard or Top-tier. `--preset` alone also selects this mode. |
+
+`--release` takes no version. The package version in the `npx` command selects the release. This mode is the supported way to upgrade or downgrade to the defaults of one release. See [Updates and removal](updates-and-removal.md). Some release changes cross a migration boundary and need a removal first, for example Claude from 0.4.0 to 0.3.0. See [Migration boundaries](updates-and-removal.md#migration-boundaries). An unknown preset fails with `UNKNOWN_PRESET`. The [presets reference](../reference/presets.md) lists the values.
+
+### Encoded preferences (`--config`)
+
+This mode applies a preferences JSON that is encoded as base64url.
+
+```sh
+agent-policy setup --config eyJzY2hlbWFWZXJzaW9uIjoxLC...
+```
+
+- The value is canonical base64url without padding.
+- The decoded JSON is at most 64 KiB.
+- The JSON must be valid [preferences](preferences.md). It contains data only.
+
+APK writes the decoded JSON to a private temporary file and removes that file when the command ends. A value that is not valid fails with `INVALID_CONFIG`. To make a value from a file, see [Preferences](preferences.md#apply-a-preferences-file).
+
+### Preferences file (`--policy`)
+
+This mode reads preferences from a file.
+
+```sh
+agent-policy setup --policy ./preferences.json
+```
+
+- The file must be a regular file, not a symbolic link, and at most 64 KiB.
+- The JSON must be valid [preferences](preferences.md). Otherwise the command fails with `INVALID_POLICY`.
+
+This mode is conservative. If APK already has a setup with other values, setup stops with `INSTALLATION_CONFLICT` or `POLICY_CONFLICT`. To replace a saved setup with the values of a file, use `--config`.
+
+### Setup results
+
+Each assistant gets one result status:
+
+| Status | Meaning |
+|---|---|
+| `planned` | Preview: APK would make the listed changes. A plan with no files means that the configuration is already current. |
+| `configured` | APK wrote the changes. |
+| `unchanged` | Only with `--apply`: the configuration was already current, and APK wrote nothing. |
+| `not_selected` | The preferences do not include this assistant. |
+| `not_found` | The assistant is not installed. |
+| `invalid` | An executable was found, but its identity could not be verified. |
+| `timeout` | Detection did not finish in time. |
+| `prerequisite` | A condition outside APK must be fixed first. APK writes nothing for this assistant. |
+| `error` | The operation failed for this assistant. |
+
+The overall status is `planned`, `configured`, `partial` or `no_clients`. `no_clients` means that no selected assistant is installed. `partial` means that at least one assistant has `prerequisite`, `error`, `invalid` or `timeout`.
+
+A plan lists files as `~/...` or `<state-dir>/...` with the action `create`, `update` or `remove`. Release fields show the target, previous and applied release, source and preset for each assistant.
+
+If an assistant stops, it keeps its earlier APK configuration. The readable output then shows `Existing configuration retained`.
+
+## show
+
+`show` reads the current user-level subagent settings of each assistant. It also reads settings that you made yourself.
+
+```sh
+agent-policy show [--client ID] [--home PATH] [--state-dir PATH] [--json]
+```
+
+- It needs no APK receipts and no assistant executables.
+- It reads the native folders that the native-home environment variables select. With `--home`, it reads the standard folders under that folder.
+- It shows the default subagent model and effort, the parallel limit, each role with its model and effort, and the Kimi model pool.
+- For Kimi and Gemini, the parallel limit is guidance from the APK instructions. Kimi role models are routing guidance.
+- For Claude, it also shows environment overrides of the subagent model, effort and parallel limit.
+- It shows APK files that have local edits with their current values, and marks them.
+
+`show` does not read project settings, managed settings, plugins, session flags or external role files. These can override the values that it shows. It never prints prompts, credentials, raw configuration or private paths. It writes nothing and calls no model.
+
+If `show` cannot read an assistant completely, that assistant has the status `attention` and the command exits with code 3. The readable output shows `incomplete read`. Causes include unsupported role syntax, unsafe files, files that change during the read and APK files with local edits.
+
+`show` does not accept `--apply`, `--policy`, `--preset`, `--release`, `--config` or explicit tool arguments.
+
+## doctor
+
+`doctor` verifies the configuration that APK owns, for each assistant.
+
+```sh
+agent-policy doctor [--client ID] [--home PATH] [--state-dir PATH] [--json]
+```
+
+For each assistant, it reports:
+
+- The detection result.
+- The configuration status: `verified` with the applied release, source and preset, `not_configured`, or `attention` with a reason code.
+- What the native settings control: native role settings, native tiers (Gemini) or a native pool with routing guidance (Kimi). It also reports whether the parallel limit is a native setting or guidance only.
+
+`doctor` reads the receipts. It does not need the current presets or saved preferences. It does not run a model, so `modelExecution` is always `not_checked`.
+
+`doctor` exits with code 0 also when an assistant has `attention`. Read the status of each assistant.
+
+## detect
+
+`detect` finds installed assistants.
+
+```sh
+agent-policy detect [--client ID] [--json]
+```
+
+APK looks for each executable on `PATH` and in the usual install folders. On macOS, it also checks the CLI copies in ChatGPT Desktop and Claude Desktop. It starts each candidate once with `--version`, and for Kimi and Antigravity sometimes with `--help`. A folder alone does not count as an installed assistant.
+
+Each result has a status: `detected` with the version, `not_found`, `invalid` or `timeout`. The `origin` field is `path`, `known_location` or `desktop_app`. The [assistants reference](../reference/assistants.md) lists the executables and locations.
+
+## release
+
+`release` shows the configuration release of the package that you run.
+
+```sh
+agent-policy release [--preset NAME] [--json]
+```
+
+The JSON output contains the version, the selected preset, all presets with their labels, the catalog review date, a hash of the preset preferences and the full release notes. The readable output shows the version and the preset. `--release` and `--config` are not accepted here.
+
+## uninstall
+
+`uninstall` plans the removal of the configuration that APK owns. With `--apply`, it removes it.
+
+```sh
+agent-policy uninstall [--client ID] [--home PATH] [--state-dir PATH] [--apply] [--json]
+```
+
+- Without `--client`, it uses every assistant that has a receipt in the state directory.
+- It needs no assistant executable and no preferences.
+- It restores your original values and keeps unrelated later edits.
+- If you edited a file or block that APK owns, it stops for that assistant with `OWNED_DRIFT`.
+
+The overall status is `completed`, `partial` or `not_installed`. If one assistant fails, the command exits with code 3. For the full procedure, see [Updates and removal](updates-and-removal.md#remove-apk).
+
+## init
+
+`init` creates an editable preferences file with the Standard preset.
+
+```sh
+agent-policy init --policy ./preferences.json
+```
+
+- `--policy` is required. Otherwise the command fails with `POLICY_PATH_REQUIRED`.
+- `init` never replaces a file. If the file exists, the command fails with `EEXIST`.
+- It creates missing folders and makes the file readable only by you.
+
+To edit and apply the file, see [Preferences](preferences.md).
+
+## instructions
+
+`instructions` prints the AI operator guide ([AGENT_INSTALL.md](../../AGENT_INSTALL.md)) as plain text. An AI agent that installs APK for you follows this guide.
+
+## Output
+
+APK prints readable text or JSON:
+
+- In an interactive terminal, the output is readable text.
+- When the output goes to a pipe or a file, it is JSON.
+- `--json` always selects JSON.
+
+Readable output starts with `Agent Policy Kit · VERSION`. A setup preview shows `Preview · no files changed`. Other headings are `Configuration applied`, `Already up to date`, `Setup incomplete` and `No supported selected tools found`. Readable output names problems with a short reason and the code, for example `Local edits prevent an update (OWNED_DRIFT)`.
+
+Setup JSON contains `requiredActions`: one entry for each problem, with the assistant and the code. A command error prints only `{"error": "CODE"}`.
+
+No output contains configuration bodies, raw executable output, raw errors or private paths. See [Privacy](privacy.md).
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | The command completed. For `setup`, all selected and installed assistants are planned, configured or unchanged. |
+| 1 | The command failed before it could produce a result, for example because of an unknown option or input that is not valid. The output contains only an error code. |
+| 3 | The result is incomplete. `setup`: no selected assistant is installed, or at least one assistant has `prerequisite`, `error`, `invalid` or `timeout`. `uninstall`: at least one assistant failed. `show`: at least one assistant has `attention`. |
+
+`doctor`, `detect`, `release`, `init` and `instructions` exit with code 0 when they produce a result.
+
+## Error codes
+
+### Command errors
+
+These codes come with exit code 1:
+
+| Code | Cause |
+|---|---|
+| `UNKNOWN_COMMAND` | The command name is not known. |
+| `UNEXPECTED_ARGUMENT` | More than one positional argument. |
+| `ERR_PARSE_ARGS_UNKNOWN_OPTION` and other `ERR_PARSE_ARGS_*` codes | An option is not known or has a wrong value type. |
+| `CONFLICTING_OPTIONS` | Two input modes, or an option that the command does not accept. |
+| `DUPLICATE_OPTION` | An explicit tool option appears twice. |
+| `UNSUPPORTED_CLIENT` | `--client` is not a supported assistant ID. |
+| `STATE_PATH_MUST_BE_ABSOLUTE` | The state directory path is relative. |
+| `UNKNOWN_PRESET` | `--preset` is not `fast`, `balanced` or `quality`. |
+| `INVALID_EXPLICIT_CONFIG` | Explicit tool arguments are not valid. |
+| `INVALID_CONFIG` | The `--config` value is not valid. |
+| `INVALID_POLICY` | The preferences file is not valid. |
+| `POLICY_PATH_REQUIRED` | `init` has no `--policy`. |
+| `EEXIST` | The `init` target file already exists. |
+| `ENOENT` | The `--policy` file of `setup` does not exist. |
+| `OPERATION_FAILED` | Another failure. |
+
+### Assistant results
+
+These codes appear in the result of one assistant. `setup` and `uninstall` then exit with code 3. `doctor` reports an error code as the reason of the status `attention` and exits with code 0.
+
+| Code | Meaning |
+|---|---|
+| `OWNED_DRIFT` | You edited a file or block that APK owns. APK keeps your edit. |
+| `INSTALLATION_CONFLICT` | The installed APK preferences differ from this request. |
+| `POLICY_CONFLICT` | The saved preferences differ from this request. |
+| `OWNERSHIP_CONFLICT` | A file that APK wants to create already exists, or the instructions file already has an APK block that APK does not own. |
+| `INVALID_RECEIPT` | The receipt has an unknown format or content, for example a receipt that a newer APK version wrote. See [Migration boundaries](updates-and-removal.md#migration-boundaries). |
+| `LEGACY_RUNTIME_RECEIPT` | The receipt comes from an experimental runtime version: format v1, hooks or a package path. Remove it with the version that created it. |
+| `RECOVERY_REQUIRED` | An interrupted transaction needs recovery. |
+| `INSTALL_LOCKED` | Another APK operation holds the lock. |
+| `STALE_PLAN` | A file that the plan read changed before or during the apply. Make a new plan. |
+| `INSTALL_FAILED` | A write failed. APK restored the earlier configuration of the assistant. |
+| `ROLLBACK_CONFLICT` | APK could not restore a file after a failure. It keeps the lock and the journal for recovery. |
+| `UNSAFE_PATH` | A path contains a symbolic link, is outside its expected folder, or has a part with an unexpected file type. |
+| `UNSAFE_FILE` | A file that APK reads is not a regular file, or it is larger than 1 MiB. |
+| `UNSUPPORTED_CONFIG` | A native configuration file has a structure or a value type that APK cannot change safely. |
+| `INVALID_JSON`, `INVALID_TOML` | A native configuration file is not valid JSON or TOML. |
+| `UNSUPPORTED_TOML_STRUCTURE`, `UNSUPPORTED_TOML_VALUE` | A TOML file uses a form that APK does not edit. |
+| `CHATGPT_CAP_ALIAS_CONFLICT` | The ChatGPT `config.toml` has the older `[agents] max_threads` setting. See the [assistants reference](../reference/assistants.md#chatgpt-codex). |
+| `PLATFORM_UNSUPPORTED` | APK cannot write on Windows. |
+| `EACCES`, `EPERM`, `ENOENT`, `ENOSPC`, `EIO`, `EROFS` | A file operation failed in the operating system. |
+| `SETUP_FAILED` | Another `setup` failure. `uninstall` reports another failure as `OPERATION_FAILED`. |
+| `native-home-override-unsupported` | The assistant uses a native folder that is not standard. `doctor` reports it as `NATIVE_HOME_OVERRIDE_UNSUPPORTED`. |
+| `client-not-selected` | `--client` names an assistant that the preferences do not include. |
+| `claude-force-model-conflict` | Claude Code forces one subagent model. |
+| `kimi-provisioned-models-required` and other `kimi-*` codes | Kimi needs model aliases or effort support that are not configured. |
+
+For recovery codes, see [Updates and removal](updates-and-removal.md#recover-from-an-interrupted-change). For the assistant-specific prerequisites, see the [assistants reference](../reference/assistants.md).
+
+## Related documents
+
+- [Getting started](getting-started.md): the first setup.
+- [Configurator](configurator.md): the page that generates the setup command.
+- [Preferences](preferences.md): the preferences JSON format.
+- [Updates and removal](updates-and-removal.md): change the release, uninstall and recover.

package/docs/guide/configurator.md

@@ -0,0 +1,163 @@
+# Configurator
+
+This document describes the configurator page: its four steps, the work modes, the top models switch, the per-assistant limits and the share links. It is for people who use the page to make a setup command. For a first setup from start to end, see [Getting started](getting-started.md).
+
+## Open the page
+
+Use one of these pages:
+
+- The hosted page for the current release: <https://agent-policy-kit.trymenow.io/>.
+- The hosted page for one release, for example <https://agent-policy-kit.trymenow.io/v/0.4.0/>.
+- The local file `site/index.html` from the APK package or repository.
+
+Use a current version of Google Chrome. The page is one self-contained HTML file. It has no backend and makes no requests while you use it. It never runs the command and never grants model access.
+
+Each page belongs to one configuration release. A *configuration release* is one APK package version with its presets, model catalog and role templates. The status line under step 4 shows the release, for example `Configuration release 0.4.0`. While the release notes mark the release as unreleased, the line shows a release-candidate notice instead. The [website document](../maintainers/website.md#release-status-on-the-page) tells when each line is shown.
+
+## Step 1: Subagent roles
+
+All six roles are selected when the page opens.
+
+- Click **×** on a role to remove it.
+- Click a role below the field to add it again. Click **Add all** to add all missing roles.
+- Click **?** on a role to read its description and the base prompt that APK saves.
+
+A green check on the step means that at least one role is selected. The [roles reference](../reference/roles.md) describes each role.
+
+## Step 2: AI assistants
+
+1. Click an assistant below the field to add it. **Add all** adds every assistant.
+2. Click **×** on an assistant to remove it.
+
+Assistants keep the order in which you add them. The command uses the same order.
+
+- With one assistant, you edit that assistant.
+- With two or more assistants, an **All** button appears and is active. **All** edits all selected assistants together.
+- Click one assistant to edit only that assistant. Its current mode shows under its name.
+
+When you select Gemini, the page shows a note: APK configures Antigravity, not Gemini CLI. The page does not check which assistants are installed. The CLI checks this when you run the command.
+
+## Step 3: Work mode
+
+A *work mode* sets the models, effort levels and parallel limit for an assistant. No mode is selected when the page opens. Each selected assistant needs a mode before the command is available.
+
+| Mode | Use |
+|---|---|
+| Light | Light models for every role. Limits last longest. |
+| Standard | Stronger models for code, review, tests and docs. Fits most plans. |
+| Top-tier | High-end models for most roles. Uses limits fastest. |
+| Custom | Your own models and effort. |
+
+The values of Light, Standard and Top-tier are in the [presets reference](../reference/presets.md).
+
+### Choose a mode for all assistants
+
+1. Make sure that **All** is active.
+2. Select a mode.
+
+If the change replaces edited values, different modes or unfinished choices, the page asks you to confirm. Click **Cancel** to keep your choices. The **All** view does not show the model table. To change models, click one assistant.
+
+### Choose a mode for one assistant
+
+1. Click the assistant in step 2.
+2. Select a mode.
+
+The first mode choice needs no confirmation. Later, the page asks you to confirm if other assistants are selected or if you edited this assistant. Other assistants keep their choices.
+
+For some assistants, every mode uses the same models. The page then says that the modes change only how many subagents run at once.
+
+### Change models and effort
+
+The **Models & effort** table shows one row for each selected role. It is visible only when you edit one assistant.
+
+1. Select a model in the **Model** list.
+2. To use a model that is not in the list, select **Custom model…** and type the native model ID. Gemini has no custom models. It accepts only its native tiers.
+3. Click an effort button. Only the levels that the model supports are shown. A dash (—) means that the model has no native effort setting.
+
+Any change to a model or effort sets the assistant to **Custom**. Selecting **Custom** without a change does not change any value. A model ID can have 1 to 128 ASCII characters and no spaces.
+
+For Kimi, roles that use the same model alias share one effort. A change to one of these roles changes all of them. For Grok, the page has no effort buttons. Grok subagents use the main session effort. The [assistants reference](../reference/assistants.md) explains these limits.
+
+### Use the top models switch
+
+The top models switch is shown in Top-tier mode for assistants that have a top model. Its label names each model and effort. When you edit one assistant, the label is `Use <model · effort> for code, review and tests`. In the **All** view, it is `Use top models (…) for code, review and tests` and lists the top model of each assistant.
+
+- Turn the switch on to use the top model for the Coder, Reviewer and Test writer roles.
+- Turn the switch off to go back to the Top-tier values.
+
+The switch changes only code roles that have no role-specific Top-tier value. The top model for each assistant is listed in the [presets reference](../reference/presets.md).
+
+### Set the parallel limit
+
+The **Parallel subagents** field sets the maximum number of subagents that run at once in one session. It is visible only when you edit one assistant.
+
+1. Click one assistant in step 2.
+2. Type a whole number from 1 to 32, or use **−** and **+**.
+
+Each assistant keeps its own limit. A change sets only that assistant to **Custom**. Selecting a mode restores the limit of that mode. For Kimi and Gemini, the label is **Max per session (advisory)**: these assistants get the limit as guidance, not as a native cap.
+
+## Step 4: Copy setup command
+
+When all steps are complete, the page shows the command and a summary, for example `3 subagent roles · 2 AI assistants`.
+
+1. Click **Copy command**.
+2. Paste the command into a terminal or a text editor.
+
+If the clipboard is not available, the page selects the command. Copy it with your keyboard. The green check on step 4 means that you copied the current command. It does not mean that APK is installed. A change to the form removes the check.
+
+If a step is missing, the page names it with a link. If a value is not valid, the page shows `Check your settings.` and the first problem. It then shows no command.
+
+### What the command contains
+
+The command always lists every selected assistant and role with its model and effort. A preset fills the form, but the command does not refer to the preset by name. For this reason, APK records the source of the setup as custom.
+
+A generated command has this form:
+
+```sh
+npx --yes --ignore-scripts --package agent-policy-kit@0.4.0 agent-policy setup \
+  --roles 'reviewer,explorer' \
+  --max-concurrent 3 \
+  --chatgpt 'reviewer=gpt-6.1-sol:high,explorer=gpt-6-luna:high' \
+  --claude 'reviewer=claude-sonnet-5-5:high,explorer=claude-haiku-5-5:medium' \
+  --apply
+```
+
+- The package version is the release of the page.
+- `--roles` lists the selected role IDs.
+- `--max-concurrent` is the shared limit. If the limits of the assistants differ, the assistants with a different limit also get `--TOOL-max-concurrent`.
+- Each assistant gets one argument with `role=model:effort` entries. Gemini and Grok entries have no effort.
+- `--avoid-TOOL` appears only when the list of models to avoid is not empty. A model that you select is removed from that list.
+- `--apply` is always the last line.
+
+The [Commands](commands.md#explicit-tool-arguments) reference describes this syntax. To preview without writes, delete the `--apply` line and the ` \` at the end of the line before it.
+
+## Reset the form
+
+Click **Reset form** under step 4. The page selects all six roles again and clears the assistants, the modes and the copy status. The address then holds only the six roles, as on a page that you open for the first time. Reset does not change files on your computer.
+
+## Check current settings
+
+At the bottom of the page, **Check current settings** has a **Copy** button. It copies a read-only `show` command for the release of the page. Run it in a terminal to see the roles, models, effort and parallel limits that your assistants use now. See [Commands](commands.md#show).
+
+## Share a setup
+
+The page saves the form in the address. Each change replaces the part after `#setup=`.
+
+1. Complete the form, or a part of it.
+2. Copy the page address from the browser.
+3. Send the address to the other person.
+
+The link contains the roles, the assistant order, the mode of each assistant, the model and effort choices, each limit and the assistant that you edit. It does not contain the copy status. The link stays in the browser. The page needs no database to open it.
+
+When someone opens the link, the page restores the form, including unfinished choices. The command is still blocked until all values are valid.
+
+- A link contains its release version. A link from another release opens only on the page of that release. The hosted page sends such a link to the page of its release, if that page is hosted. Otherwise, the page shows an error.
+- If a link is not valid, the page shows an error. Click **Reset form** to start again.
+- A link to a local file works only on the same computer.
+
+## Related documents
+
+- [Getting started](getting-started.md): the first setup from start to end.
+- [Commands](commands.md): run, preview and check the command.
+- [Presets reference](../reference/presets.md): the values of each mode.
+- [Privacy](privacy.md): what the page and the CLI read and send.