agent-policy-kit 0.3.0 → 0.4.0

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.4.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 and Grok accept 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.4.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.4.0 agent-policy setup --policy ./preferences.json
+   ```
+
+2. Apply it:
+
+   ```sh
+   npx --yes --ignore-scripts --package agent-policy-kit@0.4.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.4.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.4.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.4.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 to 0.3.0 or earlier | `INVALID_RECEIPT` | 0.4.0 |
+| 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 to an older release.** A 0.4.0 Claude receipt 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 0.4.0:
+
+   ```sh
+   npx --yes --ignore-scripts --package agent-policy-kit@0.4.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.4.0 agent-policy uninstall
+   ```
+
+2. Read the preview.
+3. Remove the configuration:
+
+   ```sh
+   npx --yes --ignore-scripts --package agent-policy-kit@0.4.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 0.4.0 Claude receipt that owns `CLAUDE_CODE_SUBAGENT_EFFORT`. Remove these settings with 0.4.0.
+
+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.

package/docs/maintainers/development.md

@@ -0,0 +1,93 @@
+# Development
+
+This document tells maintainers and contributors how to set up the repository, run the checks and tests, enable the pre-push hook, and meet the sandbox requirement of the package tests. For the module structure, see [architecture](architecture.md).
+
+## Requirements
+
+- Node.js 22.x (22.13 or later) or 24 and later. The `engines` field in `package.json` sets this range.
+- npm.
+- For the package tests: `sandbox-exec` on macOS or bubblewrap (`bwrap`) on Linux.
+
+The CLI has no build step. Only the configuration page is generated.
+
+## Set up a clone
+
+1. Install the dependencies without lifecycle scripts:
+
+   ```sh
+   npm ci --ignore-scripts --no-audit --no-fund
+   ```
+
+2. Prime the dependency cache for the offline package tests:
+
+   ```sh
+   npm run test:cache
+   ```
+
+3. Enable the pre-push hook once per clone:
+
+   ```sh
+   git config core.hooksPath .githooks
+   ```
+
+`npm run test:cache` installs the dependencies into a temporary directory and removes it after. On a new machine, `npm ci` can cache the tarballs without the registry metadata that a separate offline consumer needs. This step adds that metadata.
+
+## Checks and tests
+
+| Command | What it does |
+|---|---|
+| `npm run check` | Validates `policies/balanced.json`, checks the JavaScript syntax in `src/`, `bin/` and `scripts/`, rejects a stale `site/index.html`, and inspects the package contents |
+| `npm run test:unit` | Runs every test file whose name does not contain `package` |
+| `npm run test:package` | Runs the installed-tarball tests (`test/*package*.test.mjs`) |
+| `npm test` | Runs all tests, unit and package |
+| `npm run build:site` | Regenerates `site/index.html` |
+
+`npm run check` also rejects package files that are larger than 1 MiB, test files, archives, private folders, user home paths and token-like strings. It checks that every relative link in a packaged Markdown file points to a packaged file. For this reason, packaged documents do not link to `scripts/`, `test/`, `.github/` or `.githooks/`. Write those paths as code.
+
+Run `npm run build:site` after a change to the page template, `site/base.css`, the role definitions, the command codec, the version, the presets, the catalog or the changelog.
+
+## Package tests and the sandbox
+
+The package tests pack the real tarball, install it in a temporary consumer and run it with access to the source checkout denied. They use `sandbox-exec` on macOS and bubblewrap on Linux. If neither is available, the tests fail. They never skip.
+
+A managed sandbox can forbid a nested sandbox. In that case, run the package tests on a normal host that the owner approves.
+
+The package tests also check these results:
+
+- Setup works with the package, the source and the state removed after setup, and standalone consumers still read the native files.
+- Two synthetic versions upgrade and downgrade changed models and templates safely. A synthetic version is a test fixture, not a release.
+
+Consumer fixtures read files. They do not prove that a native client loads the files or that a model runs.
+
+## Test environment
+
+- Use temporary home directories. Do not touch the real home directory.
+- Detection looks for desktop app bundles in `/Applications`. Set `AGENT_POLICY_APPLICATIONS_DIR` to another absolute directory to replace it. The tests set this variable, so apps on the host do not change the results.
+- `AGENT_POLICY_HOME` sets the state directory. The [ownership reference](../reference/ownership.md#state-directory) gives the selection order and the default.
+- Keep the existing checks for transactions, the complete read set, rollback, ownership, symbolic links and privacy.
+
+## Pre-push hook
+
+`.githooks/pre-push` runs `npm run check` and `npm run test:unit` before each push that updates a branch or a tag. A push that only deletes refs skips both. The hook stops with a message if `node_modules` is missing.
+
+The hook is not packaged. It is a contributor check and has no relation to the settings that APK generates.
+
+## Continuous integration
+
+| Workflow | Trigger | Jobs |
+|---|---|---|
+| Verify package (`ci.yml`) | Every push and pull request | `test` on macOS with Node 22.13.0 and on Ubuntu 22.04 with Node 24 runs `npm run test:cache`, `npm run check` and `npm test`. `site-build` runs after `test`. When the version has a `v` tag, it builds the hosted site and checks the upload with a Wrangler dry run, without credentials |
+| Lint (`lint.yml`) | Pull requests and pushes to `main` | `Lint` runs `npm run check` |
+| Deploy configurator (`deploy-site.yml`) | After Verify package, or manual | See [website](website.md) |
+
+The `main` ruleset requires the `Lint` check.
+
+## What not to add
+
+Do not add hooks, wrappers, plugins, daemons, runtime audits or package paths to generated settings. Receipts and backups belong only to configuration operations.
+
+## Related documents
+
+- [Release](release.md): prepare and publish a configuration release.
+- [Verification](verification.md): the evidence record for each release.
+- [Assistants](../reference/assistants.md): native files and limits per assistant.