agent-policy-kit 0.3.0 → 0.5.0

package/docs/guide/getting-started.md

@@ -0,0 +1,121 @@
+# Getting started
+
+This guide shows the first setup of Agent Policy Kit (APK): choose settings on the configurator page, preview the command, apply it, check the result and remove the npm package. It also shows common scenarios. It is for people who use APK with their AI assistants.
+
+## What APK does
+
+APK writes native subagent settings for the coding agent of each AI assistant, then exits:
+
+| AI assistant | Coding agent that APK configures |
+|---|---|
+| ChatGPT | Codex |
+| Claude | Claude Code |
+| Kimi | Kimi Code |
+| Gemini | Antigravity (not Gemini CLI) |
+| Grok | Grok Build |
+
+A *subagent* is a helper agent that your main agent can start for one task. A *role* is a named subagent definition, for example `apk-reviewer`. APK gives each role a model and, where the assistant supports it, an effort level. The [roles reference](../reference/roles.md) describes the six roles.
+
+Your main agent and its model do not change. The main agent still decides when to delegate. The settings apply only when it delegates. APK installs no proxy, hook or background process. For the files APK writes in each assistant, see the [assistants reference](../reference/assistants.md).
+
+## Before you start
+
+Make sure that you have:
+
+- Node.js 22.13 or later in the 22 line, or Node.js 24 or later. The setup command uses `npx`.
+- At least one supported AI assistant installed. APK does not install assistants, sign in or accept terms for you.
+- A macOS or Linux computer. On Windows, a preview works, but APK refuses to write files. See [Platforms](../reference/assistants.md#platforms).
+
+## Set up with the configurator
+
+1. Open the configurator: <https://agent-policy-kit.trymenow.io/>.
+2. In step 1, keep or remove subagent roles. All six roles are selected when the page opens.
+3. In step 2, add the AI assistants that you use.
+4. In step 3, choose a work mode: **Light**, **Standard** or **Top-tier**. The mode sets how much of your plan limits subagents can use. The [presets reference](../reference/presets.md) lists the values of each mode.
+5. In step 4, click **Copy command**.
+6. Paste the command into a text editor.
+7. To get a preview first, delete the last line (`--apply`). Also delete the ` \` at the end of the line before it.
+8. Run the preview command in a terminal. A preview writes no files.
+9. Read the result. Each assistant shows what APK would change, or why it cannot continue.
+10. Run the full command, with `--apply`.
+11. Open a new session in each configured assistant. A session that was open before setup can keep the old settings.
+
+You can undo the setup later. Step 4 of the page shows the `uninstall` command for its release. The removal restores the settings that you had before APK and keeps your unrelated edits. See [Remove APK settings after other changes](#remove-apk-settings-after-other-changes).
+
+For each control on the page, see [Configurator](configurator.md).
+
+## Check the result
+
+1. Run `doctor` to verify the configuration that APK owns:
+
+   ```sh
+   npx --yes --ignore-scripts --package agent-policy-kit@0.5.0 agent-policy doctor
+   ```
+
+2. Run `show` to read the subagent settings that your assistants use now, including settings that you made yourself:
+
+   ```sh
+   npx --yes --ignore-scripts --package agent-policy-kit@0.5.0 agent-policy show
+   ```
+
+A verified configuration does not prove that a provider runs a specific model. For all command options, see [Commands](commands.md).
+
+## Remove the npm package
+
+The native files do not depend on the APK package. After a successful setup, you can remove the package:
+
+- If you used `npx`, npm keeps a copy in its cache. No global package is installed.
+- If you installed APK with `npm install`, uninstall it with npm.
+
+Keep the APK state directory (`~/.agent-policy-kit` by default). It contains private receipts. A *receipt* records what APK owns, so that APK can update or remove only its own changes later. For details, see the [ownership reference](../reference/ownership.md).
+
+## Common scenarios
+
+### Add only some roles
+
+1. In step 1 of the page, remove the roles that you do not want. For example, keep only **Reviewer** and **Code explorer**.
+2. Complete the other steps and apply the command.
+
+APK creates files only for the selected roles, for example `apk-reviewer` and `apk-explorer`. A later setup with a different role selection replaces the earlier set of APK roles. It keeps files that APK does not own.
+
+### Use one role scheme across several assistants
+
+1. In step 2, add all the assistants that you use.
+2. In step 3, choose a mode for all of them with **All** selected, or click one assistant to give it a different mode.
+3. Apply the command.
+
+Each assistant gets its own native role files and instructions. No central service runs between the assistants and their providers.
+
+### Apply the release defaults without the page
+
+Run setup with the release input mode:
+
+```sh
+npx --yes --ignore-scripts --package agent-policy-kit@0.5.0 agent-policy setup --release
+```
+
+This previews the Standard mode. Add `--preset fast` for Light or `--preset quality` for Top-tier. Add `--apply` to write the files. For details, see [Commands](commands.md#release-presets---release-and---preset).
+
+### Choose your own models
+
+Use one of these methods:
+
+- On the page, open one assistant and change its models and effort. The mode changes to **Custom**.
+- Write a preferences file. See [Preferences](preferences.md).
+
+Choose only models that your account can use. APK does not grant model access.
+
+### Use the macOS desktop apps
+
+On macOS, APK also finds the Codex copy in ChatGPT Desktop and the Claude Code copy in the Code tab of Claude Desktop. These copies read the same settings as their CLIs. For the limits, see the [assistants reference](../reference/assistants.md).
+
+### Remove APK settings after other changes
+
+Run `uninstall` to preview the removal, then `uninstall --apply`. APK restores your original values and keeps unrelated changes, for example a later theme setting. If you edited a file or block that APK owns, removal stops for that assistant and keeps your edit. For the full procedure, see [Updates and removal](updates-and-removal.md).
+
+## Related documents
+
+- [Configurator](configurator.md): every step and control of the page.
+- [Commands](commands.md): the full CLI reference.
+- [Updates and removal](updates-and-removal.md): change the release, uninstall and recover.
+- [Privacy](privacy.md): what APK reads, writes and never sends.

package/docs/guide/preferences.md

@@ -0,0 +1,168 @@
+# Preferences
+
+This document describes the preferences JSON format and its validation rules. It also shows how to create, check and apply a preferences file. It is for advanced users who want to keep their APK choices in a file instead of in a configurator command.
+
+## What preferences are
+
+*Preferences* are JSON data that select the roles and, for each assistant, the models, effort levels, parallel limit and models to avoid. APK reads preferences, checks them, and writes native files from them. Preferences contain data only, never commands or credentials.
+
+APK checks preferences in two ways:
+
+- The [JSON Schema](../../schema/policy.schema.json) describes the shape.
+- The validator in APK also checks the models and effort levels against the model catalog of the release.
+
+Preferences apply only when the main agent decides to delegate. They do not turn on a subagent feature.
+
+## Create a preferences file
+
+1. Create a file with the Standard preset of the release:
+
+   ```sh
+   npx --yes --ignore-scripts --package agent-policy-kit@0.5.0 agent-policy init --policy ./preferences.json
+   ```
+
+2. Edit the file. Use the rules below.
+
+`init` never replaces an existing file. The other presets of the release are in the `policies/` folder of the package: `fast.json` (Light), `balanced.json` (Standard) and `quality.json` (Top-tier).
+
+## Format
+
+### Top level
+
+| Field | Required | Value |
+|---|---|---|
+| `schemaVersion` | Yes | `1` |
+| `maxConcurrent` | Yes | A whole number from 1 to 32. The shared parallel limit. |
+| `clients` | Yes | An object with at least one assistant. |
+| `selectedRoles` | No | A list of role IDs. If you omit it, APK configures all six roles of the release. |
+
+No other field is allowed.
+
+### Assistants
+
+The keys of `clients` are `chatgpt` (Codex), `claude` (Claude Code), `kimi` (Kimi Code), `gemini` (Antigravity) and `grok` (Grok Build). An assistant that is not in `clients` is not configured. The keys `codex` and `agy` from version 0.2.0 and earlier are not accepted.
+
+Each assistant has these fields:
+
+| Field | Required | Value |
+|---|---|---|
+| `code` | Yes | A choice. The default for the Coder, Reviewer and Test writer roles. |
+| `light` | Yes | A choice. The default for the Code explorer, Docs writer and Task runner roles. |
+| `roles` | No | An object with a choice for one or more role IDs. It replaces `code` or `light` for that role. |
+| `avoidModels` | Yes | A list of model IDs, at most 32, without duplicates. It can be empty. |
+| `maxConcurrent` | No | A whole number from 1 to 32. It replaces the shared `maxConcurrent` for this assistant. |
+
+The [roles reference](../reference/roles.md) describes each role and its ID.
+
+### Choices
+
+A *choice* is an object with exactly two fields:
+
+| Field | Value |
+|---|---|
+| `model` | A model ID. 1 to 128 characters: letters, digits and `. _ : @ / [ ] -`. It starts with a letter or digit. |
+| `effort` | An effort level, or `null`. `null` sets no explicit effort, so the assistant uses its native default. |
+
+### Example
+
+```json
+{
+  "schemaVersion": 1,
+  "maxConcurrent": 3,
+  "selectedRoles": ["worker", "reviewer", "explorer"],
+  "clients": {
+    "claude": {
+      "code": {"model": "claude-sonnet-5-5", "effort": "medium"},
+      "light": {"model": "claude-haiku-5-5", "effort": "low"},
+      "roles": {
+        "reviewer": {"model": "claude-sonnet-5-5", "effort": "high"}
+      },
+      "avoidModels": ["claude-fable-5-1"]
+    },
+    "gemini": {
+      "maxConcurrent": 2,
+      "code": {"model": "pro", "effort": null},
+      "light": {"model": "flash", "effort": null},
+      "avoidModels": []
+    }
+  }
+}
+```
+
+This example configures three roles in Claude Code and Antigravity. The Claude Reviewer uses high effort. The other Claude code roles use the `code` choice. Antigravity runs at most two subagents at once, as guidance.
+
+## Validation rules
+
+APK refuses preferences that break one of these rules:
+
+- `selectedRoles`, if present, is not empty, has no duplicates and contains only `worker`, `reviewer`, `explorer`, `tester`, `writer` and `routine`.
+- The effort is `null` or a native level of the assistant. Gemini accepts only `null`. Grok accepts the levels that Grok Build reads from an agent file, limited by the catalog for a known model: Grok 4.7 accepts `low` to `xhigh`, and the other Grok models only `null`. The [model catalog reference](../reference/model-catalog.md) lists the levels of each assistant.
+- If the model is in the release catalog, the effort is a level of that model. A model that is not in the catalog can use any native level of the assistant. The assistant must still support it.
+- A Gemini model is a native tier: `pro`, `flash`, `flash_lite` or `inherit`.
+- A Kimi model is not `primary`.
+- For Kimi, selected roles that use the same alias do not request different explicit efforts. [Roles](../reference/roles.md#how-effort-applies) gives the full Kimi effort rules.
+- No selected role uses a model from `avoidModels` of the same assistant.
+
+`avoidModels` is routing guidance in the APK instructions. It does not block a model in the assistant.
+
+Some conditions can only be checked against the native files, for example missing Kimi aliases. APK reports them as prerequisites when you run setup. The [assistants reference](../reference/assistants.md) lists them.
+
+## Check a preferences file
+
+APK has no separate validation command. A preview checks the file and writes nothing:
+
+```sh
+npx --yes --ignore-scripts --package agent-policy-kit@0.5.0 agent-policy setup --policy ./preferences.json
+```
+
+If the file is not valid, the command fails with `INVALID_POLICY`. The file must be a regular file of at most 64 KiB, not a symbolic link.
+
+## Apply a preferences file
+
+Use one of these methods.
+
+### First setup, or the same values again
+
+1. Preview the setup:
+
+   ```sh
+   npx --yes --ignore-scripts --package agent-policy-kit@0.5.0 agent-policy setup --policy ./preferences.json
+   ```
+
+2. Apply it:
+
+   ```sh
+   npx --yes --ignore-scripts --package agent-policy-kit@0.5.0 agent-policy setup --policy ./preferences.json --apply
+   ```
+
+`--policy` is conservative. If APK already has a setup with other values, it stops with `INSTALLATION_CONFLICT` or `POLICY_CONFLICT`.
+
+### Replace an earlier setup
+
+To replace saved values with the values of a file, send the file as `--config`:
+
+1. Encode the file as base64url:
+
+   ```sh
+   node -e 'process.stdout.write(Buffer.from(JSON.stringify(JSON.parse(require("fs").readFileSync(process.argv[1],"utf8")))).toString("base64url"))' ./preferences.json
+   ```
+
+2. Preview the setup with the encoded value:
+
+   ```sh
+   npx --yes --ignore-scripts --package agent-policy-kit@0.5.0 agent-policy setup --config ENCODED_VALUE
+   ```
+
+3. Run the same command with `--apply`.
+
+The decoded JSON can be at most 64 KiB. For all input modes, see [Commands](commands.md#input-modes).
+
+## Saved preferences
+
+After a setup with `--apply`, APK saves the latest requested preferences as `policy.json` in the state directory. A setup without an input mode uses this file. This file is a request, not proof of what each assistant has. If one assistant failed, its receipt still records its earlier values. The [ownership reference](../reference/ownership.md) explains receipts and the state directory.
+
+## Related documents
+
+- [Commands](commands.md): all input modes and options.
+- [Presets reference](../reference/presets.md): the values of the release presets.
+- [Model catalog reference](../reference/model-catalog.md): known models and effort levels.

package/docs/guide/privacy.md

@@ -0,0 +1,76 @@
+# Privacy
+
+This document lists what APK reads, what it writes and what it never sends, for the CLI and for the configurator page. It is for everyone who uses APK or wants to check it before use.
+
+## Summary
+
+- APK runs on your computer, writes native settings and exits.
+- APK sends no data to a server. It has no telemetry, no proxy and no background process.
+- APK does not read your conversations, and it does not sign in or call a model.
+- The APK state directory can contain secrets from your existing settings. Keep it private.
+
+## What the CLI reads
+
+| Source | When | Why |
+|---|---|---|
+| Preferences: a preset of the release, the saved `policy.json`, a `--policy` file or a `--config` value | `setup`, `install` | To know what to configure. |
+| Native configuration of each assistant: its settings file, role files and instructions file | `setup`, `install`, `show`, `doctor`, `uninstall` | To plan changes, to show current settings and to verify ownership. |
+| The APK state directory: receipts, saved preferences, journal and backups | `setup`, `install`, `show`, `doctor`, `uninstall` | To know what APK owns. |
+| Assistant executables | `setup`, `install`, `detect`, `doctor` | To find installed assistants. |
+| Environment variables, for example `PATH`, the native-home variables and the Claude subagent variables | All commands that read assistants | To find executables and the active native folders. |
+
+To find an assistant, APK starts each candidate executable with `--version`. For Kimi and Antigravity, it can also use `--help`. These probes have a time limit and an output limit. APK does not start a session or send a task.
+
+APK does not read transcripts, session history, prompts or project files. The [assistants reference](../reference/assistants.md) lists the files that APK reads and writes for each assistant.
+
+## What the CLI writes
+
+The CLI writes only with `--apply`, or with `init`:
+
+- The native settings, role files and instruction block that APK owns, in the user folders of each assistant.
+- Private files in the state directory: receipts, saved preferences, a lock, a journal and transaction backups. Folders are readable only by you, and files are readable and writable only by you.
+- `init` creates one new preferences file.
+
+With `--config`, APK writes the decoded preferences to a private temporary file. It removes that file when the command ends.
+
+APK does not provision, copy or transfer credentials. It does not change your main model, sign-in, permissions or unrelated settings.
+
+## What the CLI prints
+
+- Paths appear as `~/...` or `<state-dir>/...`, not as full private paths.
+- Errors appear as codes, not as raw error text.
+- The output does not contain configuration bodies or raw executable output.
+- `show` does not print prompts or credentials. It refuses values that look like tokens or private paths and marks the read as incomplete.
+
+## The state directory
+
+The state directory contains copies of earlier versions of your native files. These copies can contain secrets that were already in your settings.
+
+- Keep the state directory private.
+- Never publish receipts, backups or backup indexes.
+- Do not share the content of the state directory to report a problem. Share the error codes instead.
+
+The [ownership reference](../reference/ownership.md#state-directory) tells where the state directory is and what it contains.
+
+## The configurator page
+
+- The page is one static HTML file. It has no backend.
+- It makes no requests while you use it and has no telemetry. Its fonts and data are inside the file.
+- Your choices stay in the browser. A share link stores them in the part of the address after `#`. Browsers do not send this part to the server.
+- Links to other sites load only when you click them.
+- The page never runs the command and has no access to your accounts or files.
+
+Your browser loads the hosted page like any other web page.
+
+## What other software does
+
+APK does not change how other software handles your data:
+
+- `npx` downloads the APK package from the npm registry.
+- Each assistant keeps its own provider and account behavior. When it runs a subagent, it uses its own connection to its provider.
+
+## Related documents
+
+- [Getting started](getting-started.md): the first setup.
+- [Commands](commands.md): what each command reads and writes.
+- [Ownership reference](../reference/ownership.md): receipts, state and backups.

package/docs/guide/updates-and-removal.md

@@ -0,0 +1,188 @@
+# Updates and removal
+
+This document shows how to choose a configuration release, upgrade or downgrade to it, remove APK and recover from an interrupted change. It also lists what a release does not freeze. It is for people who already use APK and want to change or remove their setup.
+
+## Configuration releases
+
+A *configuration release* is one version of the APK npm package. Each version freezes these parts:
+
+- The named presets: Light, Standard and Top-tier.
+- The model catalog with its effort levels.
+- The native role templates and the delegation instructions.
+- The release notes and the configurator page.
+
+There is no separate preset version. The package version is the release version. Published versions are not changed later.
+
+Installing or updating the npm package does not change your native files. Only `setup` or `uninstall` with `--apply` changes them.
+
+## Choose a release
+
+1. Read the [release notes](../../CHANGELOG.md). Each entry says why the release exists, who should update and how to migrate or roll back.
+2. Show the release and its notes with the `release` command:
+
+   ```sh
+   npx --yes --ignore-scripts --package agent-policy-kit@0.5.0 agent-policy release
+   ```
+
+3. Check the installed versions of your assistants and the models that your account can use.
+
+A newer release or model is not always better for your work, your account or your limits. APK never changes your models without a setup command.
+
+A release that is not published yet has the heading `VERSION — Unreleased` in the release notes. Its `npx` command does not work until npm serves the version. To list the published versions, run `npm view agent-policy-kit versions`. The [website document](../maintainers/website.md#release-status-on-the-page) tells what the configurator page shows for a release that is not published.
+
+## Upgrade or downgrade
+
+### To the defaults of a release
+
+1. Preview the setup with the release that you want:
+
+   ```sh
+   npx --yes --ignore-scripts --package agent-policy-kit@0.5.0 agent-policy setup --release
+   ```
+
+2. To select another preset, add `--preset fast` (Light) or `--preset quality` (Top-tier). The default is `balanced` (Standard).
+3. Read the preview.
+4. Run the same command with `--apply`.
+
+To downgrade, use the same steps with an older version in `--package agent-policy-kit@VERSION`. Before you downgrade, read [Migration boundaries](#migration-boundaries). Some changes need a removal first.
+
+### To your own choices
+
+1. Open the configurator page of the release, for example <https://agent-policy-kit.trymenow.io/v/0.4.0/>.
+2. Make your choices and copy the command. The command is pinned to the release of the page.
+3. Preview and apply it as described in [Getting started](getting-started.md#set-up-with-the-configurator).
+
+You can also apply a preferences file with `--config`. See [Preferences](preferences.md#replace-an-earlier-setup).
+
+### What happens during an update
+
+Explicit tool arguments, `--release`, `--preset` and `--config` can replace an earlier APK setup in one step. There is no removal before the new setup.
+
+- APK checks that the files it owns still have the values it wrote.
+- It rebuilds your original values in memory and writes the new release on top of them.
+- If a check fails or a prerequisite is missing, it changes nothing for that assistant. The earlier release stays.
+- If a write fails late, it rolls back to the earlier release.
+- Unrelated changes that you made later stay.
+
+Each assistant has its own transaction. One assistant can move to the new release while another keeps its earlier release. Read the result of each assistant. Run `doctor` to see the release that each assistant has now.
+
+The [ownership reference](../reference/ownership.md#updates) describes the transaction steps.
+
+### Migration boundaries
+
+A *migration boundary* is a release change that setup cannot do in place. At a boundary, setup stops for the affected assistant and changes nothing. First remove the APK settings of that assistant with a release that can read its receipt. Then set up with the other release. The release notes record each boundary in the entry of the newer release.
+
+These boundaries are known:
+
+| Assistant | Change | Setup without removal | Remove with |
+|---|---|---|---|
+| Claude | From 0.4.0 or later to 0.3.0 or earlier | `INVALID_RECEIPT` | The installed release, 0.4.0 or later |
+| ChatGPT and Gemini | From 0.2.0 or earlier to 0.3.0 or later | `OWNERSHIP_CONFLICT` | The release that created the settings, for example 0.2.0 |
+| ChatGPT and Gemini | From 0.3.0 or later to 0.2.0 or earlier | `OWNERSHIP_CONFLICT` | The release that created the settings, for example 0.4.0 |
+
+**Claude, 0.4.0 or later to 0.3.0 or earlier.** A Claude receipt from 0.4.0 or later owns `CLAUDE_CODE_SUBAGENT_EFFORT` when the effort of the default subagent role is pinned. Every preset pins it. Releases 0.3.0 and earlier do not know this setting, so they refuse the receipt. To move Claude back to 0.3.0:
+
+1. Remove the Claude settings with the installed release (0.4.0 or later), for example:
+
+   ```sh
+   npx --yes --ignore-scripts --package agent-policy-kit@0.5.0 agent-policy uninstall --client claude --apply
+   ```
+
+2. Set up Claude with 0.3.0.
+
+ChatGPT, Kimi, Gemini and Grok move from 0.4.0 to 0.3.0 in place.
+
+**ChatGPT and Gemini, 0.2.0 and 0.3.0.** Release 0.3.0 renamed the assistant IDs `codex` to `chatgpt` and `agy` to `gemini`. Releases 0.3.0 and later do not read receipts under the old IDs, and releases 0.2.0 and earlier do not know the new IDs. To move from 0.2.0 to a later release:
+
+1. Remove the settings with 0.2.0:
+
+   ```sh
+   npx --yes --ignore-scripts --package agent-policy-kit@0.2.0 agent-policy uninstall --client codex --apply
+   npx --yes --ignore-scripts --package agent-policy-kit@0.2.0 agent-policy uninstall --client agy --apply
+   ```
+
+2. Set up ChatGPT and Gemini with the later release.
+
+In the other direction, remove them with `--client chatgpt` and `--client gemini` and the newer release. Claude, Kimi and Grok keep their IDs.
+
+Preview each removal without `--apply` first. The [ownership reference](../reference/ownership.md#receipt-formats) explains the receipt formats. The [release notes](../../CHANGELOG.md) of 0.3.0 and 0.4.0 give the details.
+
+## What a release does not freeze
+
+A release reproduces the declared settings and templates. It does not control the providers:
+
+- A model alias can resolve to a newer model. For example, Claude documents that its [model aliases update over time](https://code.claude.com/docs/en/model-config#model-aliases).
+- An old model ID can be retired.
+- Your account access can change.
+
+Where reproducibility is important, use a versioned model ID if the assistant supports it. A configured model ID does not prove which model the provider runs.
+
+APK has no background updater and requests no live model catalog. Your configured values stay until you run another setup.
+
+## Remove APK
+
+1. Preview the removal:
+
+   ```sh
+   npx --yes --ignore-scripts --package agent-policy-kit@0.5.0 agent-policy uninstall
+   ```
+
+2. Read the preview.
+3. Remove the configuration:
+
+   ```sh
+   npx --yes --ignore-scripts --package agent-policy-kit@0.5.0 agent-policy uninstall --apply
+   ```
+
+4. Run `show` to check the current settings.
+
+If you used `--home` or `--state-dir` for setup, use the same values here. To remove APK from one assistant only, add `--client ID`.
+
+Uninstall uses the receipts in the state directory. It needs no assistant executable and no preferences. It restores the values that you had before the first APK setup, also after release changes. It keeps unrelated later changes. It removes the receipts, but keeps the saved preferences and the private backups in the state directory.
+
+You do not need the release that you used for setup. Any release that can read the receipt can remove it. There are two known exceptions:
+
+- Releases 0.3.0 and later do not read the ChatGPT and Gemini receipts of 0.2.0 and earlier. Remove these settings with the release that created them.
+- Releases 0.3.0 and earlier cannot read a Claude receipt from 0.4.0 or later that owns `CLAUDE_CODE_SUBAGENT_EFFORT`. Remove these settings with 0.4.0 or a later release.
+
+See [Migration boundaries](#migration-boundaries) and the [ownership reference](../reference/ownership.md#receipt-formats).
+
+## Handle local edits
+
+APK owns these parts:
+
+- The `apk-ROLE` role files that it created.
+- The block between `<!-- BEGIN agent-policy-kit -->` and `<!-- END agent-policy-kit -->` in the instructions file of the assistant.
+- The settings that it set in the native configuration file of the assistant, if the assistant has one.
+
+If you change one of these parts, APK calls this *drift*. Update and removal then stop for that assistant with `OWNED_DRIFT`. APK does not overwrite your edit.
+
+1. Find your edit in the APK part.
+2. Undo the edit, or move your change outside the APK part.
+3. Run the command again.
+
+Do not restore an old backup of the whole file. It can remove other changes that you made later. The [assistants reference](../reference/assistants.md#settings-in-the-configuration-file) lists the owned settings for each assistant. The [ownership reference](../reference/ownership.md#drift) explains how APK detects drift.
+
+## Recover from an interrupted change
+
+APK stops with one of these codes if an earlier change did not finish:
+
+- `INSTALL_LOCKED`: another APK operation holds the lock.
+- `RECOVERY_REQUIRED`: an interrupted transaction left a journal in the state directory.
+
+Do not delete the lock or the journal only to make APK continue. Another operation can own it, or the backups can be necessary.
+
+1. Make sure that no other APK command runs.
+2. Make a private copy of the affected native files and of the state directory.
+3. Compare the current files with the before and after values that the transaction recorded.
+4. Fix only the changes that APK owns. Keep every unrelated change.
+5. Remove only the markers of the transaction that you fixed.
+6. Run a preview again.
+
+The state directory can contain secrets from your existing settings. Never publish configuration files, backups or backup indexes. The [ownership reference](../reference/ownership.md) describes the journal, the lock and the backup files.
+
+## Related documents
+
+- [Commands](commands.md): all options of `setup`, `release`, `doctor` and `uninstall`.
+- [Release notes](../../CHANGELOG.md): what changed in each release.
+- [Ownership reference](../reference/ownership.md): receipts, state, drift and transactions.

package/docs/maintainers/architecture.md

@@ -0,0 +1,71 @@
+# Architecture
+
+This document describes how Agent Policy Kit (APK) is built: its modules, how data moves from the preset files to the native files, and why one package version is one configuration release. It is for maintainers who change the code. For the files that APK writes per assistant, see [assistants](../reference/assistants.md). For receipts and transactions, see [ownership](../reference/ownership.md).
+
+## Design rules
+
+- APK runs only when a person or an agent starts a configuration command. It detects the installed command-line tools, reads the requested preferences, writes native files and exits.
+- APK adds no hook, proxy, launcher, plugin, daemon, runtime audit or background updater. A native client never imports or starts APK.
+- Generated native files contain no reference to the npm package, the source checkout or the APK state directory. They keep working after the package is removed.
+- The role files and routing instructions apply only when the main agent decides to delegate. APK keeps the main model and does not enable a disabled subagent feature.
+
+## One version is one configuration release
+
+The `version` field in `package.json` identifies one configuration release. That release contains these items:
+
+| Item | Source |
+|---|---|
+| Presets Light, Standard and Top-tier (ids `fast`, `balanced`, `quality`) | `policies/*.json`, labels and the top models switch in `src/release.mjs` |
+| Model catalog snapshot | `models/catalog.json` |
+| Role names, descriptions and prompts | `src/roles.mjs` |
+| Native file templates and routing instructions | `src/native.mjs` |
+| Preferences validation | `src/policy.mjs`, `schema/policy.schema.json` |
+| Command codec | `src/explicit.mjs` |
+| Release notes | `CHANGELOG.md` |
+| Configuration page | `site/index.html`, generated from the items above |
+
+There is no second version number for presets or for the catalog. A change to any of these items needs a new package version. [Release](release.md) explains why the host build enforces this rule.
+
+## Modules
+
+| Module | Responsibility |
+|---|---|
+| `bin/agent-policy.mjs` | Parses the command line, selects the input mode, writes temporary preferences for `--config` and explicit arguments, and prints JSON or readable text |
+| `src/detect.mjs` | Finds each assistant's executable on `PATH`, at known locations and, on macOS, in the ChatGPT Desktop and Claude Desktop bundles. It confirms identity from `--version` and, for Kimi and Gemini, from `--help` |
+| `src/policy.mjs` | Validates preferences: schema version, limits 1 to 32, selected roles, model identifiers, efforts that the catalog allows, avoid lists |
+| `src/roles.mjs` | Defines the six roles. The page and native generation use the same definitions |
+| `src/release.mjs` | Exposes the package version, the presets, the catalog and the release notes |
+| `src/explicit.mjs` | Converts explicit tool arguments to preferences (CLI) and preferences to a command (page) |
+| `src/share.mjs` | Encodes and decodes the page form state in the URL fragment |
+| `src/native.mjs` | Renders role files and the instruction block for each assistant, and gives the native paths |
+| `src/install.mjs` | Plans, applies, inspects and removes owned changes in transactions, and writes receipts |
+| `src/toml.mjs` | Reads and edits TOML values through the one runtime dependency, `toml-eslint-parser` |
+| `src/setup.mjs` | Runs detection, then plans and applies for each selected client in sequence, and collects per-client results |
+| `src/inspect.mjs` | Reads current user-level subagent settings for `show`, without writes and without starting executables |
+| `src/output.mjs` | Formats readable terminal output. Captured output stays JSON |
+
+The CLI needs no compilation step. Only the configuration page is generated.
+
+## Data flow for a setup command
+
+1. `bin/agent-policy.mjs` accepts one input mode: explicit tool arguments, `--release` with an optional `--preset`, `--config`, or `--policy`. A combination of modes fails with `CONFLICTING_OPTIONS`.
+2. The CLI converts the input to preferences and validates them with `validatePolicy`. Explicit arguments always contain a complete map of selected roles. The required `code` and `light` fields copy the first selected role, and the complete map overrides them.
+3. `setupDetected` in `src/setup.mjs` detects the clients. Only clients that the preferences list are selected.
+4. For each selected and detected client, `planInstall` builds a plan from the native templates. Without `--apply`, the plan is the result.
+5. With `--apply`, `applyInstall` commits the plan in a transaction and writes the receipt. Plans and transactions run one client at a time, because one transaction can change shared state that the next plan reads.
+6. The result has one entry per client. One client can fail while another succeeds.
+
+The first selected role in role-definition order (`src/roles.mjs`) supplies the native default subagent. An effort of `null` means no explicit pin. [Roles](../reference/roles.md) documents the per-assistant details.
+
+## Data flow for the configuration page
+
+1. `npm run build:site` runs `scripts/build-site.mjs`.
+2. The script embeds the release data, the presets, the catalog, the role definitions, `src/explicit.mjs`, `src/share.mjs`, `site/base.css`, the font and the limit illustration into `site/template.html`.
+3. The result is one self-contained file, `site/index.html`. It needs no backend and sends no request to compose a command.
+4. The page always writes the full explicit command, also when a preset filled the form. The CLI validates the command again.
+
+[Website](website.md) covers the page build and the hosted copy.
+
+## Ownership in short
+
+Receipt format v4 stores the selected roles, bounded ownership snapshots and the applied release, source and preset. Receipts are the applied truth. `policy.json` in the state directory is only the latest requested snapshot. A replacement virtually undoes the owned changes to the original user values, renders the target and commits against the current file contents. Removal restores the original user values and keeps unrelated later edits. [Ownership](../reference/ownership.md) is the canonical description.