agent-policy-kit 0.3.0 → 0.5.0

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.

package/docs/maintainers/model-review.md

@@ -0,0 +1,101 @@
+# Review models and presets
+
+This document gives the procedure to review the model catalog and the presets for a configuration release. It is for maintainers. It tells you which inputs to collect, what to check for each assistant, how to record sources and dates, and which files to update together. The [2026-11-01 model review](../research/2026-11-01-model-review.md) is an example of the result.
+
+## Principles
+
+- The six roles stay stable: Coder, Reviewer, Code explorer, Test writer, Docs writer and Task runner. Models and effort levels are data in `policies/*.json`, `src/release.mjs` and `models/catalog.json`. A review changes this data, not the role responsibilities.
+- The presets and the catalog belong to one npm version. A changed preset is a new configuration release. See [release](release.md).
+- A newer model is not automatically better for every role, account or plan limit. Each change needs evidence.
+- Native choices and API capabilities are different facts. Record them in different catalog fields. Aliases and session modes are not additional versioned models.
+- A configuration test is not a model-quality evaluation. Do not present test results as quality results.
+- Installed configurations do not change after a release. Users apply a release explicitly. See [updates and removal](../guide/updates-and-removal.md).
+
+## When to review
+
+Do a review in these cases:
+
+- Before a release that changes presets or the catalog.
+- When a vendor releases, retires or renames a model that a native client offers for subagents.
+- When a native client changes how subagents get a model or an effort.
+
+## Inputs
+
+Collect these inputs before you compare anything:
+
+1. The installed version of each native client: Codex CLI, Claude Code, Kimi Code CLI, Antigravity CLI and Grok Build.
+2. The current vendor documentation for models, subagents, effort, pricing, plans and model lifecycle. The table in [Checks per assistant](#checks-per-assistant) lists the pages.
+3. The current repository data: `policies/fast.json`, `policies/balanced.json`, `policies/quality.json`, the `topModels` entry of `PRESETS` in `src/release.mjs`, and `models/catalog.json`.
+4. The previous research document in `docs/research/`.
+5. Independent benchmark publications, for example Artificial Analysis and Vals AI, for the models that the presets use.
+
+## Privacy rules
+
+- Do not record account data. Do not write what one signed-in account can or cannot use.
+- Record product facts. For example, "a signed-in catalog observed on 2026-11-01 lists 8 visible models" is a product fact. When a fact depends on the account or plan, write that it varies and whether you verified it.
+- Do not record credentials, raw configuration files, home-directory paths or local cache contents.
+- When you read provisioned metadata, read only the model fields. Do not print credentials.
+- `npm run check` refuses packaged files that contain private paths or token patterns. This check does not replace your own review.
+
+## Checks per assistant
+
+Read client data only. Do not change native settings during the review.
+
+| Assistant | Client data to read | Documentation to read | What to check |
+|---|---|---|---|
+| ChatGPT (Codex) | `codex --version`; the bundled catalog (`codex debug models --bundled`); the catalog that a signed-in client receives from the server; release notes | [Codex models](https://learn.chatgpt.com/docs/models), [Codex subagents](https://learn.chatgpt.com/docs/agent-configuration/subagents), [Codex pricing](https://learn.chatgpt.com/docs/pricing), [Codex changelog](https://learn.chatgpt.com/docs/changelog), [API pricing](https://developers.openai.com/api/docs/pricing) | Visible and hidden selectors, native efforts, default effort in the bundled and server catalogs, retirements, credits per token, subagent guidance |
+| Claude (Claude Code) | `claude --version`; `claude --help`; release notes of each version since the last review | [Model configuration](https://code.claude.com/docs/en/model-config), [Subagents](https://code.claude.com/docs/en/sub-agents), [Costs](https://code.claude.com/docs/en/costs), [Models overview](https://platform.claude.com/docs/en/about-claude/models/overview), [Pricing](https://platform.claude.com/docs/en/about-claude/pricing), [Model deprecations](https://platform.claude.com/docs/en/about-claude/model-deprecations), [Claude pricing](https://claude.com/pricing) | Model IDs, efforts and defaults, subagent model and effort order, new environment variables, lifecycle dates, plan billing for each model |
+| Kimi (Kimi Code) | `kimi --version`; release notes; provisioned model metadata (model fields only) | [Models](https://www.kimi.com/code/docs/en/kimi-code/models.html), [Membership](https://www.kimi.com/code/docs/en/kimi-code/membership.html), [What's New](https://www.kimi.com/code/docs/en/kimi-code/whats-new.html), [Kimi Code releases](https://github.com/MoonshotAI/kimi-code/releases) | Model IDs and aliases, efforts and defaults, quota multipliers, plan requirements, subagent changes |
+| Gemini (Antigravity) | `agy --version`; `agy --help`; `agy changelog`; the tier values that the agent parser accepts | [Antigravity subagents](https://antigravity.google/docs/subagents), [Gemini API models](https://ai.google.dev/gemini-api/docs/models) | Accepted tiers against documented tiers, per-role effort, whether Google documents the tier-to-model resolution |
+| Grok (Grok Build) | `grok --version`; the user guide that ships with the client (subagents and configuration reference chapters); the client model list | [xAI models](https://docs.x.ai/developers/models), [Grok Build subagents](https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-pager/docs/user-guide/16-subagents.md) | Model IDs, reasoning levels, subagent effort order, what `[subagents.models]` can set |
+
+Vendor pages can disagree with each other or lag behind the clients. Older help pages are a known risk. For example, an old Kimi help page listed only four models while the current Kimi Code documentation and the provisioned metadata listed six. When two sources disagree, record both and say which one the catalog follows.
+
+## Procedure
+
+1. Record the review date (UTC) and the client versions.
+2. For each assistant, do the checks in [Checks per assistant](#checks-per-assistant). Compare the results with `models/catalog.json`.
+3. List each catalog fact that changed: new or retired models, efforts, defaults, lifecycle dates, plan requirements and notes.
+4. Collect benchmark and guidance evidence for each preset cell that a change could affect. Mark each source as primary or secondary. See [Record sources and dates](#record-sources-and-dates).
+5. Compare the evidence with the current [presets](../reference/presets.md). For each proposed change, write the old value, the new value, the evidence and a confidence level (high, medium or low).
+6. Do not change a preset cell on secondary sources alone. Mark such a cell as a candidate for local verification instead.
+7. Write the cells that you leave unchanged on purpose, with the reason.
+8. Write the open questions that need local verification.
+9. Get the owner decision on the proposed changes.
+10. Update the files in [Files to update together](#files-to-update-together).
+11. Do the checks in [Verify](#verify).
+
+## Record sources and dates
+
+- Write the research result to `docs/research/<YYYY-MM-DD>-model-review.md`. Use the review date.
+- Give each number a source URL and the type primary or secondary. Primary sources are vendor documentation and announcements, the native clients, independent benchmark operators and research papers. Secondary sources are aggregators, blogs and press.
+- Say when a value is derived. For example, cost per solved task is the cost per attempt divided by the success rate.
+- Say when you read a page only through a summary or did not read it directly.
+- Do not link to private notes or to files outside Git.
+- In `models/catalog.json`, set `reviewedAt` to the review date. Update `observedClientVersion`, `observation`, `note`, `source` and `lifecycle` where they changed.
+
+## Files to update together
+
+| File | What to update |
+|---|---|
+| `policies/fast.json`, `policies/balanced.json`, `policies/quality.json` | Preset models, efforts and parallel limits |
+| `src/release.mjs` | The `topModels` choices of the top models switch |
+| `models/catalog.json` | Review date, client versions, models, efforts, defaults, exclusions, lifecycle, notes and sources |
+| [docs/reference/presets.md](../reference/presets.md) | Preset tables, design principles and short reasons. `test/catalog.test.mjs` compares every table cell with the preset data. |
+| [docs/reference/model-catalog.md](../reference/model-catalog.md) | Inventory per assistant and catalog fields |
+| [docs/reference/assistants.md](../reference/assistants.md) | Native limits and prerequisites, when a client changed them |
+| `docs/research/<YYYY-MM-DD>-model-review.md` | The new research document |
+| [CHANGELOG.md](../../CHANGELOG.md) | The changed cells, the reasons, who should update, client requirements, and migration and rollback limits |
+| `site/index.html` | The configuration page, built with `npm run build:site` |
+
+Use the release process in [release](release.md) for the version number and the changelog date. The page build is in [website](website.md).
+
+## Verify
+
+Run these commands in the repository root:
+
+1. Build the page: `npm run build:site`.
+2. Run the checks: `npm run check`.
+3. Run the tests: `npm test`.
+
+`npm run check` also confirms that the built page matches the release data. `npm test` includes the comparison of the preset tables with the preset data. For setup and hooks, see [development](development.md). Record native format checks in [verification](verification.md).

package/docs/maintainers/release.md

@@ -0,0 +1,114 @@
+# Release
+
+This document tells maintainers how to prepare, verify and publish a configuration release of Agent Policy Kit (APK). It also explains the host-build guard and why a change to presets or to the catalog needs a new version. For the review of models and presets before a release, see the [model review procedure](model-review.md). For the deployment of the page, see [website](website.md).
+
+## Rules
+
+- One package version is one configuration release. [Architecture](architecture.md) lists what a release contains.
+- The owner authorizes each publication. Nothing publishes automatically.
+- New pull requests stay draft. Only the owner merges them.
+- Publish only from reviewed commits that are already on `main`.
+- Never rewrite a published version. See the [npm publication rules](https://docs.npmjs.com/cli/v11/commands/npm-publish/).
+
+## Choose the version
+
+| Change | Version |
+|---|---|
+| A correction of documentation or a configuration bug | Patch |
+| An intentional change of a recommendation, for example a preset value | Minor, with release notes that describe it |
+| An incompatible change of native ownership, layout or IDs | A documented migration boundary. Below 1.0, a minor version marks it (0.3.0 did this for the renamed assistant IDs) |
+
+## Why a preset or catalog change needs a new version
+
+The pinned command `agent-policy-kit@VERSION` installs the presets and the catalog of that npm package. The archived page `/v/VERSION/` is a fixed copy from the release tag. If `main` changed the presets under the same version, the latest page would show values that the pinned command does not install.
+
+The host build prevents this. `npm run build:host` (`scripts/build-host.mjs`) stops with one of these codes:
+
+| Code | Cause |
+|---|---|
+| `HOST_RELEASE_TAG_REQUIRED` | The current `package.json` version has no tag (`vVERSION` or `VERSION`) that is reachable from `HEAD` |
+| `UNRELEASED_HOST_CONFIGURATION` | A configuration-sensitive file on `HEAD` differs from the same file at that tag |
+
+The configuration-sensitive files are:
+
+- `policies/fast.json`, `policies/balanced.json`, `policies/quality.json`
+- `models/catalog.json`
+- `src/roles.mjs`, `src/release.mjs`, `src/explicit.mjs`, `src/policy.mjs`
+- `schema/policy.schema.json`
+
+These files define what the page embeds and which commands the published package accepts. `src/release.mjs` holds the preset labels and the top models switch (`PRESETS`).
+
+The native templates (`src/native.mjs`, `src/install.mjs`) are not in the list. The page does not embed them, and the pinned command always runs the templates of the published package, so the page cannot disagree with them. A template change still reaches people only through a new version: bump the version to publish it.
+
+Interface changes to the page template do not need a release. The latest root page is rebuilt from `main`.
+
+## Prepare the release
+
+Do these steps on a branch. Open a draft pull request.
+
+1. Review models and presets as the [model review procedure](model-review.md) describes.
+2. Set `version` in `package.json` and in `package-lock.json`.
+3. Set `homepage` in `package.json` to `https://agent-policy-kit.trymenow.io/v/VERSION/`.
+4. Update the preset files, the catalog and its `reviewedAt` date as needed.
+5. Add the changelog entry with the heading `## VERSION — Unreleased`.
+6. Update the pinned commands (`agent-policy-kit@VERSION`) in `README.md`, `AGENT_INSTALL.md` and the documents in `docs/` that contain them.
+7. Run `npm run build:site`. For the release status that the page then shows, see [website](website.md#release-status-on-the-page).
+8. Run `npm run check` and `npm test`. See [development](development.md).
+
+After the owner merges this pull request, the deployment workflow skips with the notice that the version is not tagged and published yet. The run does not fail.
+
+## Write the changelog entry
+
+Each entry in `CHANGELOG.md` records these items:
+
+- The date. Write it when you cut the release.
+- Why this release exists.
+- Who should update.
+- Changed models, efforts and role instructions, and why they fit the work.
+- Native client requirements.
+- Migration and rollback limits.
+- The catalog date and sources.
+
+Keep configuration checks separate from model-quality evaluation. Do not claim performance or cost numbers without evidence.
+
+## Cut the release
+
+Do these steps on a second branch, `release/VERSION`. Open a draft pull request.
+
+1. Change the changelog heading to `## VERSION — YYYY-MM-DD`. Complete the notes.
+2. Add the verification record for this version to [verification](verification.md).
+3. Run `npm run build:site`. The page status changes as [website](website.md#release-status-on-the-page) describes.
+4. Run `npm run check` and `npm test`.
+
+The owner merges this pull request.
+
+## Verify before publication
+
+Do these steps on the merge commit on `main`.
+
+1. Fetch `origin`.
+2. Run `git merge-base --is-ancestor HEAD origin/main`. It must succeed.
+3. Review `npm pack --dry-run --json --ignore-scripts`.
+4. Review `npm publish --dry-run --ignore-scripts`.
+5. Make the final tarball with `npm pack`. Record its integrity.
+6. Make sure that the package contains no private evidence and no configuration from a real account.
+
+The package contains `CHANGELOG.md` and the matching page. No lifecycle install script changes native settings.
+
+## Publish
+
+Do these steps only after the owner explicitly authorizes the publication.
+
+1. Publish the exact reviewed tarball through the normal authenticated npm process.
+2. Create the tag `vVERSION` on the reviewed `main` commit and push it.
+3. Create the GitHub release with the reviewed changelog text.
+
+Publish to npm before you push the tag. The tag push starts Verify package and then the deployment. The host build requires that npm serves the version, and fails with `HOST_RELEASE_NOT_PUBLISHED` if it does not. If this happens, use the manual retry of the deployment workflow after the publication. See [website](website.md).
+
+## Check the result
+
+1. Check that the npm registry serves the version with the expected contents.
+2. Check that `https://agent-policy-kit.trymenow.io/` and `https://agent-policy-kit.trymenow.io/v/VERSION/` serve the new page.
+3. Check the links in the published README.
+
+Do not merge, mark a draft ready or enable auto-merge as part of a release.

package/docs/maintainers/verification.md

@@ -0,0 +1,110 @@
+# Verification
+
+This document is the verification log of Agent Policy Kit (APK): the evidence recorded for each configuration release. It is for maintainers who cut a release and for readers who want to know what was checked. [Release](release.md) tells when to add a record.
+
+## How to read a record
+
+A record keeps these results separate:
+
+- **Configuration checks:** tests, package checks and the files that APK writes.
+- **Native loading:** a native client reads the files.
+- **Model execution:** a provider runs a model with the settings.
+
+A configuration check does not prove native loading. Native loading does not prove model execution, account access or model quality. `NOT CHECKED` means that the record has no evidence for that layer.
+
+Each record names the platform and the date. Browser evidence, temporary homes, raw configuration fixtures and logs stay outside Git and npm.
+
+## 0.5.0
+
+macOS arm64, 2026-11-01.
+
+| Layer | Evidence |
+|---|---|
+| Full Node 26.5.1 suite | PASS: 381/381. New tests cover the Grok role effort (frontmatter, explicit `role=model:effort`, share links, `show`, a rebuilt 0.4.0 install), the Standard Claude Coder at high and its default subagent effort, the Claude 4.5 lifecycle data, the undo box and the share-address rule |
+| Hosted CI | PASS on main 19844f5: macOS Node 22.13.0 and Ubuntu Node 24 suites and the site build ([run](https://github.com/automatis-tools/agent-policy-kit/actions/runs/41377664489)) |
+| Published 0.4.0 to 0.5.0 | PASS in isolated homes with the npm 0.4.0 package and the 0.5.0 tarball, Standard preset. ChatGPT, Claude, Gemini and Grok upgrade to 0.5.0 and move back to 0.4.0 in place. Kimi NOT CHECKED with a provisioned model pool: both versions return a prerequisite in an empty home |
+| Grok role effort | PASS: an explicit `worker=grok-4.7:xhigh` writes `effort: xhigh` in `apk-worker.md`; moving back to 0.4.0 removes the line. A non-live `grok inspect --json` with an isolated profile lists the generated agents. That the effort reaches a model request is NOT CHECKED with a live task |
+| Browser | PASS in a local Chromium preview: no share fragment on first load or with steps 1–2 only, a fragment after a mode is chosen, none after Reset form; Standard Claude Coder at Sonnet 5.5 high; Grok 4.7 effort buttons; the undo box with the 0.5.0 uninstall command and its copy button |
+| Native ChatGPT, Claude, Kimi, Gemini and Grok loading and provider execution | NOT CHECKED for 0.5.0. No live model tasks were used as configuration proof |
+| npm packaging | PASS: `npm pack --dry-run` lists 50 files. No private evidence or configuration |
+| Model catalog | Reviewed on 2026-11-02; see the [model review](../research/2026-11-01-model-review.md). Configuration tests do not establish account access or model quality |
+
+## 0.4.0
+
+macOS arm64, 2026-11-01.
+
+| Layer | Evidence |
+|---|---|
+| Full Node 26.5.1 suite | PASS: 371/371. The suite includes the real-tarball tests with source access denied, the Claude default subagent effort capped at high and its receipt ownership, top choices with a model and an effort in share links and link restore, and the host guard for `src/release.mjs` |
+| Hosted CI | PASS on main 8bf7681: macOS Node 22.13.0 and Ubuntu Node 24 suites and the site build ([run](https://github.com/automatis-tools/agent-policy-kit/actions/runs/41368583940)) |
+| Two synthetic releases | PASS: the actual 0.4.0 tarball and a synthetic next-version tarball. A to B to A, mixed applied versions, drift safety and restoration of the original user values |
+| Published 0.3.0 to 0.4.0 | PASS in isolated homes with the npm 0.3.0 package and the 0.4.0 tarball, Top-tier preset. ChatGPT, Gemini and Grok upgrade to 0.4.0 and move back to 0.3.0 in place. Claude upgrades in place; `doctor` reports release 0.4.0, source `release`, preset `quality`. The Claude move back to 0.3.0 reports `INVALID_RECEIPT` and changes nothing; after `uninstall --client claude --apply` with 0.4.0, setup with 0.3.0 succeeds. Kimi NOT CHECKED with a provisioned model pool: both versions return a prerequisite in an empty home |
+| Written values | PASS: after the upgrade, ChatGPT `apk-explorer` has `model_reasoning_effort = "medium"`; Claude `apk-worker` has Opus 5.5 at high, `apk-explorer` Opus 5.5 at medium, and `settings.json` has `CLAUDE_CODE_SUBAGENT_EFFORT` = `high` |
+| Browser | PASS in a local Chromium preview: the Top-tier mode with the top models switch off and on, its label with model and effort, and the Claude details with Opus 5.5 at XHigh for code, review and tests |
+| Native ChatGPT, Claude, Kimi, Gemini and Grok loading and provider execution | NOT CHECKED for 0.4.0. No live model tasks were used as configuration proof |
+| npm packaging | PASS: `npm pack --dry-run` and `npm publish --dry-run` list 50 files. No private evidence or configuration |
+| Model catalog | Reviewed on 2026-11-01; see the [model review](../research/2026-11-01-model-review.md). Configuration tests do not establish account access or model quality |
+
+## 0.3.0
+
+macOS arm64, 2026-11-01.
+
+| Layer | Evidence |
+|---|---|
+| Full Node 26.5.1 suite | PASS: 368/368. The suite includes the real-tarball tests with source access denied, desktop app bundle detection and the renamed `chatgpt` and `gemini` IDs. A second run with `/Applications` replaced by a missing directory also passed 368/368, so no test depends on apps installed on the host |
+| Hosted CI | PASS on main e8c6ac3: macOS Node 22.13.0 and Ubuntu Node 24 suites and the site build ([run](https://github.com/automatis-tools/agent-policy-kit/actions/runs/41348755442)) |
+| Two synthetic releases | PASS: the actual 0.3.0 tarball and a synthetic 0.4.0 tarball. A to B to A, mixed applied versions, drift safety and restoration of the original user values |
+| Published 0.2.0 to 0.3.0 | PASS in an isolated HOME with the npm 0.2.0 package. ChatGPT (Codex) reports `OWNERSHIP_CONFLICT` in both directions until the creating version removes its settings. Then setup succeeds. Claude upgrades to 0.3.0 and moves back to 0.2.0 in place. Grok upgrades in place. Kimi NOT CHECKED with a provisioned model pool |
+| Desktop app detection | PASS with the installed apps and a `PATH` without CLIs: the bundled `codex-cli 0.166.0-alpha.5.1` of ChatGPT Desktop and the bundled Claude Code 2.1.309 of Claude Desktop, both reported as `desktop_app` |
+| Browser | PASS in local Chromium previews: the "AI assistants" step empty and with two assistants, its note, the All scope and the generated `--chatgpt` command |
+| Native ChatGPT, Claude, Kimi, Gemini and Grok loading and provider execution | NOT CHECKED for 0.3.0. No live model tasks were used as configuration proof |
+| npm packaging | PASS: `npm pack --dry-run` and `npm publish --dry-run` list 45 files. No private evidence or configuration |
+| Model catalog | Unchanged from 0.2.0, apart from the `chatgpt` and `gemini` keys and the general labels: ChatGPT 9 selectors, Claude 19 selectors, Kimi 6 preferred aliases, Gemini 4 Antigravity tiers, Grok 4 model IDs. Configuration tests do not establish account access or model quality |
+
+## 0.2.0
+
+macOS arm64, 2026-11-01.
+
+| Layer | Evidence |
+|---|---|
+| Full Node 26.5.1 suite | PASS: 350/350. The suite includes the real-tarball tests with source access denied, native generation for selected roles, Grok Build files under an isolated `GROK_HOME`, per-tool limits and expanded page commands |
+| Hosted CI | PASS on main 7f8666d: macOS Node 22.13.0 and Ubuntu Node 24 suites and the site build ([run](https://github.com/automatis-tools/agent-policy-kit/actions/runs/41283600922)) |
+| Two synthetic releases | PASS: the actual 0.2.0 tarball and a synthetic 0.3.0 tarball. A to B to A, mixed applied versions, drift safety and restoration of the original user values |
+| Page command through npx | PASS: the generated multiline command runs through a real shell and npx with the local tarball. Independent Codex 5 and Claude 2 limits and the Grok Build values are read back from the native files |
+| Preset audit | PASS: an independent review compared every preset, tool and role with the catalog and the documentation. It found no data defects. Wording fixes were applied, and a test keeps the documentation tables in sync |
+| Grok Build discovery | PASS: `grok inspect --json` with Grok Build 1.0.70 lists an `apk-*` agent from an isolated `GROK_HOME`. Model selection and execution NOT CHECKED |
+| Native Codex, Claude, Kimi and Antigravity loading and provider execution | NOT CHECKED for 0.2.0. No live model tasks were used as configuration proof |
+| Browser | The owner reviewed local previews manually. No automated browser run for 0.2.0 |
+| npm packaging | PASS: `npm pack --dry-run` and `npm publish --dry-run` list 42 files. No private evidence or configuration |
+| Model catalog | Codex 9 selectors, Claude 19 selectors, Kimi 6 preferred aliases, Antigravity CLI 4 tiers, Grok Build 4 model IDs. Configuration tests do not establish account access or model quality |
+
+## 0.1.0
+
+macOS arm64, 2026-10-30.
+
+| Layer | Evidence |
+|---|---|
+| Full Node 26.5.1 suite | PASS: 248/248. The suite includes both real-tarball tests with source access denied, native generation for selected roles, v2, v3 and v4 ownership and expanded page commands |
+| Minimum Node 22.13.0 suite | PASS: 248/248, with the checksum-verified official runtime outside the denied source checkout |
+| Two synthetic releases | PASS: actual 0.1.0 and 0.2.0 tarballs with a changed model and changed shared role and instruction definitions. A to B to A, mixed applied versions, rollback of a late replacement, drift safety and restoration of the original user values |
+| Selected page roles through npx | PASS: the shipped page formatter produced explicit Reviewer and Researcher options (Researcher is now Code explorer) for selected Codex and Claude fixtures, including independent effort. The actual multiline command ran offline through a real shell and npx with the local tarball. Installed tools that were not selected stayed unchanged. A later reduction and removal of roles succeeded. A late failure after a role deletion restored the complete earlier installation |
+| Package and state removal | PASS: the native files and standalone consumer fixtures stay readable without the package, the source and the state |
+| Desktop Google Chrome | PASS: the approved four-step layout, the empty, missing, error and ready states, per-tool modes, append order, automatic All and manual scope, synchronized role rows, visible per-tool model and effort arguments, actual clipboard copy, the fallback for a denied clipboard and protection against a stale copy |
+| Custom input browser regression | PASS: real typing followed directly by an effort click or a Copy click, without Tab, works with reduced motion. The earlier lost-click case was reproduced before the fix. Normal, reduced and fallback motion checks are recorded separately from model execution |
+| Independent review | PASS: an independent review of the URL codec and the controller, and a scoped final review of animation, hover and the label cache. The review of the preset and role integration found fixes for the six-role schema bounds and the live Custom Fable notices, and verified them. Fresh targeted checks passed 76/76. Full suites passed 248/248 on both runtimes |
+| URL and checklist behavior | PASS in local HTTP Chrome tabs. The exact command is restored from a shared link. An imported copy stays incomplete. Reset clears the state and the hash. No mode is selected by default. The first mode choice shows no warning. Selecting only Custom shows no overwrite warning, while genuine edits, mixed bases and the limit stay protected. Navigation that only changes the view keeps the copy status. Settings changes clear it. Invalid links do not produce a command. Hint and marker keyframes hold at offsets 0 to 0.5 and fade by offset 1 over 4000 ms |
+| Model catalog | Dated release snapshot: Codex 9 selectors, Claude 19 selectors, Kimi 6 preferred aliases, Antigravity CLI 4 tiers. API effort metadata is separate. Configuration tests do not establish account access or model quality |
+| Native Codex and Antigravity loading | Only historical parser and listing checks with positive and malformed negative controls. The new subset behavior has file and consumer fixtures, not fresh proof that the vendor clients load it |
+| Native Claude and Kimi loading and provider execution | NOT CHECKED. No live model tasks were used as configuration proof |
+| Six-role compatibility | PASS: inspection of legacy four-role v2, v3 and v4 receipts, owned removal, explicit expansion to six roles, drift refusal and late rollback. Six-alias Kimi v4 plans, inspects and removes 14 bounded operations |
+| npm packaging | PASS: inspection of the 38 package files and consumption of the real local tarball. No npm publication |
+| Hosted macOS and Linux CI | The public workflow runs are linked from the GitHub release. The local results above do not establish hosted CI |
+| Deployment and publication | The GitHub release records the public status and the downloadable artifacts. The package checks in this record apply to the reviewed tarball |
+
+Notes for 0.1.0:
+
+- At 0.1.0, the 0.2.0 packages were synthetic test fixtures, not public releases.
+- Expanded commands keep the selected limit and the avoid lists. `:native` round-trips an unpinned effort.
+- A matrix of 2835 cases over presets, roles and tools produces identical native role files and routing instructions.
+- Real-shell tests keep IDs with colons, `@` and brackets, and prevent pathname expansion.
+- The same pinned command consumes the published npm release. The verified local tarball supports tests before publication.

package/docs/maintainers/website.md

@@ -0,0 +1,112 @@
+# Website
+
+This document tells maintainers how the configuration page is built, how the hosted copy at https://agent-policy-kit.trymenow.io/ is assembled and deployed, and which guards and credentials the deployment uses. For how people use the page, see [configurator](../guide/configurator.md). For the release steps that start a deployment, see [release](release.md).
+
+## The page file
+
+`npm run build:site` runs `scripts/build-site.mjs` and writes `site/index.html`. This file is one self-contained HTML page. It has no backend, no telemetry and no external asset requests. It does not access a native account.
+
+The build puts these items into `site/template.html`:
+
+- The release data: version, presets, catalog, role definitions and release notes.
+- The command codec `src/explicit.mjs` and the share-link codec `src/share.mjs`, without their `export` keywords.
+- `site/base.css`, a snapshot of a shared base style. Its header names the source.
+- The Public Sans font from `site/fonts/` as base64, and its license text.
+- The limit illustration from `scripts/build-limits-chart.mjs`, and a link to [how it was measured](../research/limits-evidence.md).
+- Author and project metadata from `package.json`.
+
+Each marker must occur exactly once in the template, or the build fails. `npm run check` fails when `site/index.html` is stale.
+
+## Release status on the page
+
+The page takes its release status from `CHANGELOG.md` when `npm run build:site` runs. It does not ask npm. `scripts/build-site.mjs` looks for the exact heading `## VERSION — Unreleased`, where `VERSION` is the `version` in `package.json`:
+
+| `CHANGELOG.md` at build time | Status line on the page |
+|---|---|
+| Has the heading `## VERSION — Unreleased` | `Release candidate · npm command available after publication.` |
+| Has no such heading, for example `## VERSION — YYYY-MM-DD` | `Configuration release VERSION` |
+
+The status line therefore does not show whether npm serves the version. A changed heading has an effect only after the next build. [Release](release.md) describes when to change the heading.
+
+## Metadata and footer
+
+The `author` field in `package.json` supplies the visible byline, the page title, the author link and the static JSON-LD data for the person, the project and the page. The build requires an author name and an HTTPS profile URL. The `repository` and `homepage` fields must also be public HTTPS URLs.
+
+The footer credits Mykola Maksymenko, links to his LinkedIn profile, and links to the related projects Agents Can Communicate and Automatis Skills. These links load only when a person follows them. The page has no social widgets and requests no metadata at runtime.
+
+The canonical URL of a release page is `/v/VERSION/` on the homepage origin. The hosted root page uses the root URL as canonical.
+
+## Motion
+
+- Role and assistant changes use native View Transitions. With reduced motion, or without View Transitions, the update is immediate.
+- A changed hint, step marker, scope label or mode caption keeps a soft highlight for 2 seconds and fades for 2 seconds (4000 ms in total).
+- The collapsed "Why" section opens and closes in 200 ms and follows the reduced-motion setting.
+- The page installs no animation dependency.
+
+## Hosted site
+
+`npm run build:host` runs `npm run build:site` and then `scripts/build-host.mjs`. The result is the `dist/` folder:
+
+| Path | Content |
+|---|---|
+| `/` | The latest page, rendered from the current `main` with the root as canonical URL and the list of hosted releases |
+| `/v/VERSION/` | `site/index.html` from each reachable release tag, copied byte for byte |
+| `_headers` | Security headers: a strict Content Security Policy, `nosniff`, `no-referrer`, a restrictive Permissions Policy and `no-cache` |
+
+Archived pages are not rebuilt with the latest template. A share link from an older release that opens on the root page redirects only to a known archived release on the same origin. A malformed link, a link to an unknown release and a link opened from a local file show an error and do not redirect.
+
+The host build needs the full Git history with tags and anonymous access to the npm registry. It stops before it replaces `dist/` when a check fails:
+
+| Code | Cause |
+|---|---|
+| `HOST_RELEASE_TAG_REQUIRED`, `UNRELEASED_HOST_CONFIGURATION` | The release guard. See [release](release.md) |
+| `HOST_RELEASE_NOT_PUBLISHED` | npm does not serve the current version |
+| `HOST_REGISTRY_UNAVAILABLE` | The registry did not answer after three attempts |
+| `INVALID_HOST_RELEASE` | A tag has an invalid `package.json`, its version does not match the tag, or two tags name the same version |
+| `UNSAFE_HOST_OUTPUT` | `dist/` contains an unknown file, an unknown folder or a symbolic link |
+| `INVALID_HOST_PAGE` | The rendered page is empty |
+
+## Automatic deployment
+
+The workflow Deploy configurator (`.github/workflows/deploy-site.yml`) deploys `dist/` to an existing Cloudflare Worker. It starts after a successful Verify package run, or manually with `workflow_dispatch`.
+
+1. The workflow runs only when the Verify package run is a push in this repository, on `main` or on a tag that starts with `v`.
+2. It always checks out `main`, never the code of the triggering branch or tag.
+3. `scripts/deploy-guard.mjs` checks the context. For a tag trigger, the tag must point to the triggering commit and be an ancestor of `origin/main`. The checked-out commit must be the latest `main`, and Verify package must have passed for that commit as a push on `main`.
+4. The guard skips when the current version has no release tag. The run reports `Package version VERSION is not tagged and published yet.` and does not fail.
+5. The workflow runs `npm run check` and `npm run build:host`.
+6. It installs Wrangler 4.151.3 with lifecycle scripts disabled, before any credential is available.
+7. `scripts/prepare-site-deploy.mjs` writes an asset-only Wrangler configuration. It accepts only the Worker name `agent-policy-kit` and the `./dist` folder, and it removes the routes.
+8. The guard runs again immediately before the upload. A run for an older commit skips.
+9. Wrangler uploads the assets.
+10. `scripts/verify-hosted-site.mjs` fetches `/` and each `/v/VERSION/` over HTTPS and compares the bytes with `dist/`.
+
+Deployments are serialized in the concurrency group `production-configurator`. A failed check before the upload keeps the current deployment. A mismatch after the upload fails the workflow and needs investigation.
+
+A merged version bump does not deploy until its release is tagged. The tag push after the npm publication starts the deployment. See [release](release.md).
+
+## Credentials
+
+The GitHub environment `production` allows only the `main` branch. It has no required reviewers, so a merge needs no manual approval of the deployment.
+
+The environment stores two encrypted secrets:
+
+- `CLOUDFLARE_ACCOUNT_ID`
+- `CLOUDFLARE_API_TOKEN`, with the permission Workers Scripts edit for the target account
+
+The token needs no zone, DNS, KV or R2 permission, because the CI configuration excludes routing. Cloudflare can scope Workers Scripts edit to the account and not to one Worker. For this reason, the workflow fixes the Worker name and runs only trusted `main` code.
+
+Use a separate deployment token. Do not store the interactive Wrangler OAuth token or refresh token in CI. Keep the token value out of Git, npm, logs and artifacts. Pull request test jobs get no Cloudflare secrets.
+
+## Domain changes
+
+The domain route `agent-policy-kit.trymenow.io` is in `wrangler.jsonc`. The workers.dev address stays enabled for earlier links. CI never changes routing. Make a domain-only change as a separate infrastructure operation with `wrangler triggers deploy`, and compare the deployment and version IDs before and after.
+
+## Retry
+
+Use the manual run of Deploy configurator on `main` in these cases:
+
+- A service failed for a short time.
+- The tag push ran before npm served the version.
+
+The workflow never merges a pull request, creates a tag or publishes an npm package.