agent-policy-kit 0.3.0 → 0.5.0

package/docs/model-updates.md

@@ -1,22 +0,0 @@
-# Keeping model choices current
-
-The task roles stay stable: worker for implementation, reviewer for findings, explorer for discovery, tester for tests, writer for documentation and routine for prescribed execution. Models and effort values are separate data in policies and models/catalog.json and can evolve without changing those responsibilities.
-
-Named presets and the dated model/effort catalog follow the npm package version. Record model-choice changes and their review date/sources in CHANGELOG.md when releasing a revised preset. Version 0.1.0 is a starting example, not a live ranking or a benchmark of model quality. Native format checks are recorded in [verification](verification.md).
-
-## Before setup or an authorized update
-
-The installing AI agent should:
-
-1. Read the saved preferences and installed client versions. Preserve explicit user choices.
-2. Cross-check the provider's current dedicated model docs with native catalogs or schemas. Older official help pages can lag: Kimi's old help page omitted K3.1 Pro while its current Code Docs and provisioned metadata included it. Keep API capabilities separate from native choices; aliases and session modes are not additional versioned models. Check provisioned aliases without printing credentials.
-3. Compare proposed choices with the saved setup. A newer model is not automatically better for every task, account or usage constraint.
-4. Apply requested changes through the coordinated [preferences update procedure](../AGENT_INSTALL.md). Package installation alone must not rewrite native settings.
-
-No background updater, live model catalog request, or automatic model replacement runs during normal client use. Existing configured values stay saved until another configuration operation changes them.
-
-Provider aliases can still resolve to a newer model independently of APK. For example, Claude documents that its [model aliases update over time](https://code.claude.com/docs/en/model-config#model-aliases). Use available versioned identifiers where reproducibility matters and the client/provider supports them. A configured identifier remains distinct from proof of the actual provider model.
-
-## Maintainer release check
-
-Update the preset data, source/date notes and configuration fixtures together. Recheck native schemas, preserve main-session behavior, and run unit plus packed-package acceptance. Do not present configuration tests as model-quality evaluations. All preferences continue to apply only when the main agent chooses to delegate.

package/docs/npm-release.md

@@ -1,27 +0,0 @@
-# Prepare a configuration release
-
-One version: package.json version identifies presets, model catalog, native templates, instructions and page. No second preset-version system. The owner authorizes each publication; nothing publishes automatically. New pull requests must remain draft, and only the owner merges them.
-
-## Record what and why
-
-For every release, update CHANGELOG.md with: date, changed models/efforts/role instructions, why the changes fit the work, who should update, native/client requirements and migration/rollback limits. Record catalog source/date and distinguish configuration checks from model-quality evaluation. Do not claim performance/cost numbers without evidence.
-
-Patch releases can correct documentation/configuration bugs; intentional recommendation changes deserve clearly described release notes (normally a minor release); incompatible native ownership/layouts require a documented migration boundary. Never rewrite a published version. See [npm publication rules](https://docs.npmjs.com/cli/v11/commands/npm-publish/).
-
-## Build and verify before tagging
-
-1. Confirm npm name ownership and set actual repository/bugs/homepage URLs once they exist. Do not invent them.
-2. Update package version and lockfile, preset JSON, model catalog/source date and this version's changelog entry. Fill the actual release date when cutting it.
-3. Run npm run build:site. The generated single HTML file embeds that version's exact data and command.
-4. Run npm run check and npm test. Required tarball gates deny source access, remove package/state, and prove two synthetic versions can upgrade/downgrade changed models AND templates safely. Synthetic 0.2.0 is not a real release.
-5. Review npm pack --dry-run --json --ignore-scripts, npm publish --dry-run --ignore-scripts, and the final npm pack tarball/integrity. Private evidence/configs must stay out.
-
-The package includes CHANGELOG.md and its matching page. Its CLI requires no compilation; only the page data is regenerated. No lifecycle install script mutates native settings.
-
-After explicit publication authorization, create the corresponding git version tag/release with the reviewed changelog text and publish that exact tarball through npm's normal authenticated process. Publish application and npm releases only from reviewed commits already present in main. Before publication, fetch origin and require git merge-base --is-ancestor HEAD origin/main to succeed. Never merge, mark a draft ready or enable auto-merge. Recheck registry contents and public page links after an authorized release.
-
-## Static page
-
-The latest site deploys automatically from reviewed main after CI, while each published /v/VERSION/ page remains an exact tagged snapshot. npm publication stays explicit. See [website deployment](deployment.md) for configuration guards, archive preservation, credentials and main-only retry.
-
-The public domain is https://agent-policy-kit.trymenow.io/. The workers.dev address remains available for earlier links. Domain-only infrastructure changes use wrangler triggers deploy and compare deployment/version IDs before and after. CI website deployment deliberately omits routing changes and does not publish npm packages.

package/docs/policy.md

@@ -1,16 +0,0 @@
-# Configuration preferences
-
-Start with policies/balanced.json or another preset in the selected release. The [JSON Schema](../schema/policy.schema.json) describes data shape; the configuration validator also checks the release catalog's known model/effort compatibility.
-
-- schemaVersion1; maxConcurrent is the shared fallback, from 1 to 32. Optional clients[tool].maxConcurrent overrides it for one tool. Older policies without overrides keep their shared behavior.
-- clients contains chatgpt (Codex), claude (Claude Code), kimi (Kimi Code), gemini (Antigravity) and/or grok (Grok Build). Version 0.2.0 and earlier used the keys codex and agy. They are not accepted.
-- Optional top-level selectedRoles is a nonempty unique array of worker, reviewer, explorer, tester, writer and routine IDs. Omit it for all six roles in the executing release. Only selected roles receive native files and routing instructions.
-- code/light hold default model+effort pairs.
-- Optional roles inside each client overrides each selected role independently. Worker/reviewer/tester otherwise use code; explorer/writer/routine use light. Public presets also contain role-specific overrides.
-- avoidModels is delegation guidance. An explicit page choice removes itself from that avoid list.
-
-Effort null means native behavior without an explicit effort override. Codex effort depends on the native model selector. Claude supports low through max as documented per model. Kimi actual aliases must declare the requested non-null effort. Antigravity's role field supports model tiers, with no per-role effort pin. Grok Build accepts any model ID and always uses effort null.
-
-A known model cannot request an effort excluded by the release catalog. Custom IDs can use the client's native level set, subject to actual native availability. Kimi can merge null with one explicit pin for a selected shared alias. Contradictory explicit pins are refused. Unselected role defaults do not require Kimi aliases or acquire pins. A section-wide effort conflicting with mixed default/pinned alias behavior is a prerequisite rather than a silent rewrite.
-
-[Presets/catalog](model-catalog.md) describe recommendations and sources. [Release usage](releases.md) explains explicit default/preset/custom replacement. Only when the main agent chooses delegation do any of these role preferences apply. No subagent feature is enabled by the configurator.

package/docs/privacy.md

@@ -1,9 +0,0 @@
-# Privacy
-
-The configurator reads local preferences and native configuration, probes CLI version/help identity, writes owned native settings and exits. It does not read transcripts or send prompts to a classifier, proxy or telemetry endpoint. It does not provision or transfer credentials.
-
-Client settings can contain existing secrets. Transaction backups and receipts are private local state and must never be published. CLI summaries omit configuration bodies, raw executable output, private paths and raw errors.
-
-There is no runtime audit, session tracking or token journal. Normal agent operation does not call package code. Native clients retain their own provider/account behavior.
-
-The npm package uses a files allowlist. Tests, development notes, private profiles, evidence and tarballs stay outside it. The acceptance gate uses fresh profiles with fake secret sentinels and denies source access. Fixtures do not establish live account or provider execution.

package/docs/recovery.md

@@ -1,13 +0,0 @@
-# Recovery
-
-Do not remove a lock or pending journal merely to make configuration proceed. Another operation may own it, or a failed transaction may need its backups.
-
-The installer stages changes and rechecks the complete read set. A failed commit restores matching postimages. A competing edit is preserved and yields a recovery conflict.
-
-Private state contains pending.json, .install.lock and backups/TRANSACTION_ID/index.json. Keep the journal and backup index together. The retained lock ID can identify the index if recreating pending.json failed.
-
-For recovery, ensure no configurator is active, make a private copy of affected files/state, compare current files with recorded preimages/postimages, and reconcile only owned changes. Preserve every later unrelated edit. Remove only the resolved transaction's blocking markers, then rerun a plan. Do not publish config bodies or backup indexes.
-
-Owned file/block/scalar drift stops removal. Reconcile that exact change rather than restoring a stale whole-file backup. Unknown experimental runtime receipts require the older version's owned uninstall first; never delete arbitrary hooks based on their text.
-
-Removing or moving the npm package after successful setup is safe. Native files have no package dependency. Reinstall or invoke the configurator with npx for future updates/removal. Preserve private receipts if owned removal is desired.

package/docs/releases.md

@@ -1,40 +0,0 @@
-# Choose and apply a configuration release
-
-**APK package version = configuration release.** Each published package freezes its named presets/model catalog/efforts, native role templates, instructions, changelog and static configuration page. There is no second preset-version system.
-
-## Default settings from a specific release
-
-Inspect the release and preview its plan:
-
-```sh
-npx --yes --ignore-scripts --package agent-policy-kit@0.3.0 agent-policy release
-npx --yes --ignore-scripts --package agent-policy-kit@0.3.0 agent-policy setup --release
-```
-
-Apply explicitly:
-
-```sh
-npx --yes --ignore-scripts --package agent-policy-kit@0.3.0 agent-policy setup --release --preset balanced --apply
-```
-
-The package you select supplies both preferences and native templates. --release is a boolean, not another version argument. --preset selects fast/balanced/quality; its identity is stored alongside release/source. The same pattern selects an older compatible release for downgrade. Installing/updating an npm package alone does not change native files. Before publication, use that release's verified .tgz instead of the registry package spec.
-
-## Your own choices
-
-Open this release's [configuration page](../site/index.html) in Google Chrome. Its fully expanded per-tool command is pinned to the page's package version. It applies your chosen models through that release's templates. Generated explicit commands record custom provenance, including when the form used a preset. The --release workflow retains named preset provenance.
-
---config is bounded canonical base64url UTF-8 JSON. It is data, not executable shell content. Explicit tool arguments, --release/--preset, --config and --policy are alternative input modes. Explicit arguments, --config and --release permit replacement of owned configuration. --policy without those options remains conservative for advanced saved-file workflows.
-
-## What happens during an update
-
-APK verifies old owned files, reconstructs the original user baseline in memory, renders the target, and commits one final change per file. There is no physical uninstall gap. Native prerequisites and drift refuse changes; late failure rolls back the previous installed release. Later unrelated user edits survive. Final uninstall restores original user values rather than the previous APK version's values.
-
-Transactions are per client. Missing, unsupported or blocked clients retain their actual previous release; successful independent clients may advance. setup results and doctor report each client's applied version/source. The shared state policy is the latest requested snapshot, not proof every client applied it. Doctor verifies receipts without needing that snapshot or today's templates.
-
-Current native receipt v4 records the selected subset of six bounded role filenames. Native v3 and v2 snapshots remain bounded to their historical four roles and remain supported. An explicit replacement with selectedRoles omitted can expand an earlier setup to all six roles in the chosen release; implicit setup keeps the existing installation unchanged. v2 has unknown release provenance. An older executable can reject v4. Use a receipt-compatible executable before an incompatible downgrade. Unknown future schemas/layouts are refused. An incompatible migration must explain its supported path in that release's notes.
-
-## What a release does not freeze
-
-A release reproduces declared settings and templates. Provider aliases/tiers can resolve to new models, old model IDs can retire, and account access can change. See [model maintenance](model-updates.md). No runtime updater or model gateway is installed.
-
-Read [CHANGELOG](../CHANGELOG.md) for what changed, why, who should update and migration limits. Versions 0.1.0 and 0.2.0 are published and 0.3.0 is being prepared; synthetic versions in acceptance tests are not real releases.

package/docs/use-cases.md

@@ -1,25 +0,0 @@
-# Examples
-
-## Add only reviewers and researchers
-
-Choose Reviewer and Researcher in the page, then select your AI assistants. APK creates only apk-reviewer and apk-explorer. Later additions can expand this set. Removing a selected role removes its earlier owned definition while preserving unrelated files and edits.
-
-## One role scheme across AI assistants
-
-Choose models for the six focused roles: implementation, review, discovery, tests, documentation and prescribed execution. Presets provide role-specific starting choices. Each tool receives native definitions and delegation instructions; no central dispatcher runs between it and its provider.
-
-## Keep your main model
-
-Apply the shared preferences to delegated helpers while preserving each tool's main model, account, permissions and unrelated setup.
-
-## Configure and discard the installer
-
-Run detected setup with --apply, verify native files, remove the npm package, and start your AI assistants normally. Saved role files and settings keep working through native features.
-
-## Customize model choices
-
-Use init --policy FILE, choose models/efforts actually available in each account, then apply through the AI guide. Kimi needs provisioned aliases; agy choices are tiers. Higher-priority native settings can override global preferences.
-
-## Remove after other settings changed
-
-A later unrelated theme setting remains during owned uninstall. An edited generated role or managed block produces a drift conflict; the configurator preserves it for reconciliation.

package/docs/verification.md

@@ -1,61 +0,0 @@
-# Verification record
-
-Configuration checks, native loading and model execution are separate results.
-
-## 0.3.0
-
-macOS arm64, 2026-11-01.
-
-| Layer | Current evidence |
-|---|---|
-| Full Node 26.5.1 suite | PASS: 368/368, including source-denied real-tarball gates, 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 plus 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 original-user restoration |
-| 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 it, 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: ChatGPT Desktop's bundled `codex-cli 0.166.0-alpha.5.1` and Claude Desktop's bundled Claude Code 2.1.309, 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/Grok loading and provider execution | NOT CHECKED for 0.3.0; no live model tasks used as configuration proof |
-| npm packaging | PASS: `npm pack --dry-run` and `npm publish --dry-run` list 45 files; no private evidence or configuration |
-| Current model catalog | Unchanged from 0.2.0 apart from the `chatgpt`/`gemini` keys and general labels: ChatGPT 9 selectors, Claude 19 selectors, Kimi 6 preferred aliases, Gemini 4 Antigravity tiers, Grok 4 model IDs. Account access and model quality are not established by configuration tests. |
-
-## 0.2.0
-
-macOS arm64, 2026-11-01.
-
-| Layer | Current evidence |
-|---|---|
-| Full Node 26.5.1 suite | PASS: 350/350, including source-denied real-tarball gates, selected-role native generation, 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 plus 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 original-user restoration |
-| Page command via 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 Grok Build values are read back from native files |
-| Preset audit | PASS: an independent review compared every preset, tool and role with the catalog and documentation and 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/Antigravity loading and provider execution | NOT CHECKED for 0.2.0; no live model tasks 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 |
-| Current model catalog | Codex 9 selectors, Claude 19 selectors, Kimi 6 preferred aliases, Antigravity CLI 4 tiers, Grok Build 4 model IDs. Account access and model quality are not established by configuration tests. |
-
-## 0.1.0
-
-macOS arm64, 2026-10-30.
-
-| Layer | Current evidence |
-|---|---|
-| Full Node 26.5.1 suite | PASS: 248/248, including both source-denied real-tarball gates, selected-role native generation, v2/v3/v4 ownership and expanded page commands |
-| Minimum Node 22.13.0 suite | PASS: 248/248, using the checksum-verified official runtime outside the denied source checkout |
-| Two synthetic releases | PASS: actual 0.1.0/0.2.0 tarballs, changed model and shared role/instruction definitions, A to B to A, mixed applied versions, late replacement rollback, drift safety and original-user restoration |
-| Page-selected roles via npx | PASS: the shipped page formatter produced explicit Reviewer/Researcher options for selected Codex/Claude fixtures, including independent effort. The actual multiline command ran through a real shell and npx with the local tarball offline. Unselected installed tools stayed unchanged. Later role reduction/removal succeeded. A late failure after role deletion restored the complete prior installation. |
-| Package/state removal | PASS: native files and standalone consumer fixtures remain readable without package/source/state |
-| Desktop Google Chrome | PASS: approved four-step layout, empty/missing/error/ready states, per-tool modes, append order, automatic All/manual scope, synced role rows, visible per-tool model/effort arguments, actual clipboard copy, denied-clipboard fallback and stale-copy protection |
-| Custom input browser regression | PASS: real typing followed directly by effort or Copy clicks, without Tab, works with reduced motion. The earlier lost-click case was reproduced before the fix. Normal/reduced/fallback motion checks are recorded separately from model execution. |
-| Independent review | PASS: independent URL codec/controller review and scoped final animation/hover/label-cache review. Preset/role integration review found and verified fixes for six-role schema bounds and live Custom Fable notices. Fresh targeted checks passed 76/76; full suites passed 248/248 on both runtimes. |
-| URL/checklist behavior | PASS in local HTTP Chrome tabs: exact command restored from a shared link, imported copy remains incomplete, Reset clears state/hash, no default radio, first mode choice skips warning, Custom-only toggle skips unnecessary overwrite warning while genuine edits/mixed bases/cap remain protected, view-only navigation preserves copy, settings changes clear it, invalid links remain non-applicable. Hint/marker keyframes hold at offsets 0–0.5 and fade by offset 1 over 4000 ms. |
-| Current model catalog | Dated release snapshot: Codex 9 selectors, Claude 19 selectors, Kimi 6 preferred aliases, Antigravity CLI 4 tiers. API effort metadata is separate. Account access and model quality are not established by configuration tests. |
-| Native Codex/Antigravity loading | Historical parser/listing positive and malformed negative controls only. New subset behavior has file/consumer fixtures, not fresh vendor-client loading proof. |
-| Native Claude/Kimi loading and provider execution | NOT CHECKED; no live model tasks used as configuration proof |
-| Six-role compatibility | PASS: legacy four-role v2/v3/v4 inspection, owned removal, explicit expansion to six, drift refusal and late rollback; six-alias Kimi v4 plans/inspects/removes 14 bounded operations. |
-| npm packaging | PASS: 38-file package-content inspection and real local tarball consumption. No npm publication. |
-| Hosted macOS/Linux CI | See the public workflow runs linked from the GitHub release; local results above do not establish hosted CI. |
-| Deployment/publication | Public status and downloadable artifacts are recorded in the GitHub release; package checks below concern the reviewed tarball. |
-
-At 0.1.0, the 0.2.0 packages were synthetic test fixtures, not public releases. Browser evidence, disposable homes, raw configuration fixtures and logs stay outside Git/npm. Expanded commands preserve the selected cap and avoid lists; :native round-trips unpinned effort. A 2835-case preset/role/tool matrix produces identical native role files and routing instructions. Real-shell tests preserve colon/@/bracket IDs and prevent pathname expansion. The same pinned command consumes the published npm release. The verified local tarball supports testing before publication.