@event4u/agent-config 2.25.0 → 3.0.0

package/CHANGELOG.md

@@ -16,6 +16,42 @@ Entry-shape contract: [`docs/contracts/CHANGELOG-conventions.md`](docs/contracts
 
 ## [Unreleased]
 
+**TypeScript CLI shell + local server foundation (`typescript-cli-and-local-gui-foundation`)** —
+Phase-5 cutover of the `agent-config` binary from a 955-line Bash
+dispatcher to a compiled TypeScript entry point. The shell handles
+native commands (`versions`, `doctor-shell`, `ui:serve`) and forwards
+every other subcommand to the legacy logic, now living at
+`scripts/_dispatch.bash`. New surfaces:
+
+- **TS bin entry** — `package.json#bin` flipped to
+  `dist/cli/agent-config.js`. `npm run build:cli` compiles and
+  `chmod +x`-es the entry; `scripts/prepack-check.mjs` runs on
+  `npm pack` / `npm publish` and asserts the compiled file exists,
+  is executable, and carries the Node shebang.
+- **Bash shim** — the old path `scripts/agent-config` is now a
+  ~30-line deprecation shim that forwards to the TS binary. The real
+  dispatch logic moved to `scripts/_dispatch.bash` to prevent the
+  forward-and-back loop. Doctor probes both paths.
+- **Embedded Fastify server** — `agent-config ui:serve` boots a
+  local server bound to `127.0.0.1`, on the first free port in
+  `41000–41999`. Wire shape locked in
+  [`docs/contracts/local-server-api.md`](docs/contracts/local-server-api.md)
+  (beta): per-process bearer token, Host-header guard, Origin
+  allow-list, `GET /api/v1/ping` liveness probe.
+- **CI gates** — `task lint-ts`, `task typecheck-ts`, `task test-ts`,
+  `task build-ts` wired into `task ci` and `task ci-strict`. New
+  GitHub Actions job `TypeScript Tests` runs the same harness across
+  `ubuntu-latest` and `macos-latest` on Node 20, including the
+  `prepack-check.mjs` gate.
+- **Test coverage** — 47 Vitest tests across
+  `tests/cli/{paths,registry,cli-e2e}.test.ts`,
+  `tests/server/{app,port,token}.test.ts`, and
+  `tests/ui/build.test.ts`. CLI-e2e exercises the shim → dispatcher
+  → TS round trip; server tests cover the auth gate and 421/403/401
+  failure modes.
+
+Decision record: [`docs/decisions/ADR-012-typescript-cli-shell.md`](docs/decisions/ADR-012-typescript-cli-shell.md).
+
 **Discovery polish — `--root` override, doctor diagnostics, install-mode marker (`step-8-discovery-polish`)** —
 follow-up to step-7 driven by AI Council review of PR #157. Adds an
 explicit escape hatch for monorepos, surfaces the resolution decision
@@ -695,224 +731,172 @@ our recommendation order, not its support status.
   users" tension without removing any path that an existing user
   might rely on.
 
-# Era: 2.20.x — current
+# Era: 3.0.x — current
 
-> Started at `2.20.0` (2026-05-16). Full entries live inline below.
+> Started at `3.0.0` (2026-05-21). Full entries live inline below.
 > The drift test caps this era at 200 lines of entry body; growth past
-> that forces a new era split (`# Era: 2.21.x`, etc.) — see
+> that forces a new era split (`# Era: 3.1.x`, etc.) — see
 > [`docs/contracts/CHANGELOG-conventions.md § Era splits`](docs/contracts/CHANGELOG-conventions.md).
 
-## [2.25.0](https://github.com/event4u-app/agent-config/compare/2.24.0...2.25.0) (2026-05-18)
-
-### Features
-
-* **rules:** add post-push-rewrite-discipline tier-2a guard ([1af51e1](https://github.com/event4u-app/agent-config/commit/1af51e1809de3522bd344453cc7e6206032f5d4a))
-* enforce roadmap CI-steps policy as Hard Gate ([a2ec868](https://github.com/event4u-app/agent-config/commit/a2ec868e81a9d9a4644d04704ff964b67754b2b2))
-* **provider-lifecycle:** tier adapters and enforce safety gates ([e9771e6](https://github.com/event4u-app/agent-config/commit/e9771e672e07804ff80b4f182c7b095acec6995d))
-* **policy:** add media governance policy layer ([4adc2ac](https://github.com/event4u-app/agent-config/commit/4adc2ac19fa31a6b0393ba4f662d91e85e6c63d0))
-
-### Bug Fixes
-
-* **ci:** extend portability skip-list with roadmap-ci-steps-policy files ([c68893d](https://github.com/event4u-app/agent-config/commit/c68893dfcb6189a951deb0ebab9802683e705d7a))
-* **ci:** repair archived-roadmap refs + bump smoke warn baseline ([11e181b](https://github.com/event4u-app/agent-config/commit/11e181b78a8303fc54cc4aa79138753b1c0c4148))
-
-### Performance
-
-* **roadmap:** batchable dashboard regen + parallel step reads in autonomous runs ([c1aa3a5](https://github.com/event4u-app/agent-config/commit/c1aa3a51cf1d99e71151f1d7116ab970d36cd85b))
-* **create-pr:** mandate single github-api call and parallel context fetch ([cbade08](https://github.com/event4u-app/agent-config/commit/cbade08df40b0d501791eeb6847e6452b2971d1d))
-
-### Documentation
-
-* **skills:** expand git-workflow with safe-squash and divergent-state recovery ([745859f](https://github.com/event4u-app/agent-config/commit/745859f100c1ffd6d607de81f701dacefb1feff0))
-* **roadmap:** add framework-neutrality-audit roadmap + scan evidence ([6daf8b8](https://github.com/event4u-app/agent-config/commit/6daf8b8a0a16880f02a7afb1fb07cf7526be3c28))
-* **adr:** record ADR-011 domain-pack readiness (Phase 6) ([830cefa](https://github.com/event4u-app/agent-config/commit/830cefafdbec8474d1f6f71421457d1761f746ab))
-* **roadmap:** file Phase 5 advisory issues #178-#180 and sync dashboard ([3859d08](https://github.com/event4u-app/agent-config/commit/3859d085ebf7cf9bc091ae55d3e8ad1e15893dcb))
-* **roadmap:** add universal-platform-refinement roadmap ([0912bb5](https://github.com/event4u-app/agent-config/commit/0912bb505dac59ac5d4cc5e25b42b2f1d6efa694))
-
-### Tests
-
-* **ai-video:** add blueprint, prompt-optimizer, adapter-contract suites (Phase 4) ([7762df7](https://github.com/event4u-app/agent-config/commit/7762df720412049f6d3b12bd328cd7c9a78b215b))
-
-### Chores
-
-* add claude rules ([744328d](https://github.com/event4u-app/agent-config/commit/744328d57b4ba3c502ab3b41ded10e25ba3db8cf))
-* compress 4 .md files into .agent-src/ ([96ef2f9](https://github.com/event4u-app/agent-config/commit/96ef2f94504661f71b86a3fb16762069c39caaa7))
-* regenerate compiled trees for new rule (82 to 83) ([8b8af6a](https://github.com/event4u-app/agent-config/commit/8b8af6a4a918e927dbaafaeadc4402e3a7220981))
-
-### Other
-
-* Clarify skills, rules, and commands description ([b586a0c](https://github.com/event4u-app/agent-config/commit/b586a0c6895da701a2719aeb4758f14cbe3fc2db))
-
-Tests: 4664 (+95 since 2.24.0)
-
-## [2.24.0](https://github.com/event4u-app/agent-config/compare/2.23.0...2.24.0) (2026-05-17)
-
-### Features
-
-* **settings:** add quality.local_auto_run / wait_for_remote_ci ([a463bf1](https://github.com/event4u-app/agent-config/commit/a463bf1925a7fb192707a80c696740ba73c30ff9))
-* **ai-video:** banana-arc reference project + shared prompt library ([f3afc6d](https://github.com/event4u-app/agent-config/commit/f3afc6dddff8d70cc17572d43a4839a157d62296))
-* **ai-video:** /video:* command cluster (from-script, scene, storyboard, stitch) ([272f2ec](https://github.com/event4u-app/agent-config/commit/272f2ec82539e58a0b8d14c63bf0806618d88c88))
-* **ai-video:** 3 specialist personas (hollywood-director, pixar-storyboard-artist, ai-video-technical-director) ([b16fb50](https://github.com/event4u-app/agent-config/commit/b16fb50c47336da6d0ad6d3864f9aaf489f91f68))
-* **ai-video:** 5 specialist skills + scene-blueprint schema ([b77ecd9](https://github.com/event4u-app/agent-config/commit/b77ecd9df6d894826f172739d534db54969f9818))
-* **ai-video:** adapter contract + 5 provider adapters + smoke test ([b86f1e5](https://github.com/event4u-app/agent-config/commit/b86f1e53661d6ff0e2a7154eee0136fe77ed6d24))
-
-### Bug Fixes
-
-* **schema:** trim ai-video-technical-director persona description to 148 chars ([b1afbb1](https://github.com/event4u-app/agent-config/commit/b1afbb1d8d94b62cb49e306d104ae33d84d06f09))
-
-### Chores
-
-* **ai-video:** wire pipeline into docs, ownership, schemas, marketplace ([18a98fa](https://github.com/event4u-app/agent-config/commit/18a98fa9098d9cc7a07782e9a6a07cf47e63d842))
-* move council audit ([54074f1](https://github.com/event4u-app/agent-config/commit/54074f18db69682f656719b4de231ea8b1cbd152))
-
-Tests: 4569 (+10 since 2.23.0)
-
-## [2.23.0](https://github.com/event4u-app/agent-config/compare/2.21.0...2.23.0) (2026-05-17)
-
-### Features
-
-* integrate anti-AI-slop heuristics into design skills ([f157d02](https://github.com/event4u-app/agent-config/commit/f157d02e56aa4abe139eaf042ad060de4815f36b))
-* add Honest Sparring Partner template and adversarial-review trigger ([122f0ad](https://github.com/event4u-app/agent-config/commit/122f0adfd3b6a334b1191e9fa58e6b3328c77365))
-* **skills:** refine-prompt + prompt-optimizer honor prompt_optimization setting ([9f8f20e](https://github.com/event4u-app/agent-config/commit/9f8f20e11627342c1e656d978d7a82ea30925cf3))
-* **settings:** add prompt_optimization block (off/mini/max, /raw bypass) ([c6d3715](https://github.com/event4u-app/agent-config/commit/c6d371510979d044e5724d5ed2d390be0af24562))
-
-### Bug Fixes
-
-* **refs:** suppress allowed council-ref links with ADR-decision-trace markers ([053bf9a](https://github.com/event4u-app/agent-config/commit/053bf9ae9c17a470f3838e989c597d66a24ac556))
-* **template:** bump agent_config_version pin to 2.21.0 ([58cc67f](https://github.com/event4u-app/agent-config/commit/58cc67f9eb4c7a3ca9b1adddbfdbefbbfe80fa3b))
-
-### Documentation
-
-* **guidelines:** add prompt-templates.md (12-template catalogue) ([ec91b31](https://github.com/event4u-app/agent-config/commit/ec91b31d71d7169f2aef6184d5e5f8d01b237f9b))
-* **roadmap:** close out step-16-caveman-substance (38/38, kill-criterion deferred) ([7a60f1e](https://github.com/event4u-app/agent-config/commit/7a60f1eddd66dfdf54bc2664b45c97954eb2b7e3))
-
-### Chores
-
-* **index:** regenerate agents/index.md + docs/catalog.md for new guideline ([f7b47e8](https://github.com/event4u-app/agent-config/commit/f7b47e870042abb3a33d26edb0caf9d0529c7828))
-* **changelog:** split era 2.17.x → pre-2.20.0 ([c842766](https://github.com/event4u-app/agent-config/commit/c8427660de6914505edf1a3d21c05ba2313ffbb7))
-
-### Other
-
-* 2.22.0 ([52aa59a](https://github.com/event4u-app/agent-config/commit/52aa59a40cf12146275c3e2a19f149703c585eae))
-
-Tests: 4559 (+0 since 2.21.0)
-
-## [2.22.0](https://github.com/event4u-app/agent-config/compare/2.21.0...2.22.0) (2026-05-17)
-
-### Features
-
-* integrate anti-AI-slop heuristics into design skills ([f157d02](https://github.com/event4u-app/agent-config/commit/f157d02e56aa4abe139eaf042ad060de4815f36b))
-* add Honest Sparring Partner template and adversarial-review trigger ([122f0ad](https://github.com/event4u-app/agent-config/commit/122f0adfd3b6a334b1191e9fa58e6b3328c77365))
-* **skills:** refine-prompt + prompt-optimizer honor prompt_optimization setting ([9f8f20e](https://github.com/event4u-app/agent-config/commit/9f8f20e11627342c1e656d978d7a82ea30925cf3))
-* **settings:** add prompt_optimization block (off/mini/max, /raw bypass) ([c6d3715](https://github.com/event4u-app/agent-config/commit/c6d371510979d044e5724d5ed2d390be0af24562))
-
-### Bug Fixes
+## [3.0.0](https://github.com/event4u-app/agent-config/compare/2.26.0...3.0.0) (2026-05-21)
 
-* **refs:** suppress allowed council-ref links with ADR-decision-trace markers ([053bf9a](https://github.com/event4u-app/agent-config/commit/053bf9ae9c17a470f3838e989c597d66a24ac556))
-* **template:** bump agent_config_version pin to 2.21.0 ([58cc67f](https://github.com/event4u-app/agent-config/commit/58cc67f9eb4c7a3ca9b1adddbfdbefbbfe80fa3b))
+### BREAKING CHANGES
 
-### Documentation
-
-* **guidelines:** add prompt-templates.md (12-template catalogue) ([ec91b31](https://github.com/event4u-app/agent-config/commit/ec91b31d71d7169f2aef6184d5e5f8d01b237f9b))
-* **roadmap:** close out step-16-caveman-substance (38/38, kill-criterion deferred) ([7a60f1e](https://github.com/event4u-app/agent-config/commit/7a60f1eddd66dfdf54bc2664b45c97954eb2b7e3))
-
-### Chores
-
-* **index:** regenerate agents/index.md + docs/catalog.md for new guideline ([f7b47e8](https://github.com/event4u-app/agent-config/commit/f7b47e870042abb3a33d26edb0caf9d0529c7828))
-* **changelog:** split era 2.17.x → pre-2.20.0 ([c842766](https://github.com/event4u-app/agent-config/commit/c8427660de6914505edf1a3d21c05ba2313ffbb7))
-
-Tests: 4559 (+0 since 2.21.0)
-
-## [2.21.0](https://github.com/event4u-app/agent-config/compare/2.20.1...2.21.0) (2026-05-17)
+* **wizard:** remove legacy /onboard chat skill and skill-bridge IPC ([04acd29](https://github.com/event4u-app/agent-config/commit/04acd290a0e50cb675b987b57ecfe2086dd2be04))
 
 ### Features
 
-* **telemetry:** caveman stats + per-conversation cost lens ([13300cc](https://github.com/event4u-app/agent-config/commit/13300cc2d709ec2cce58520621cf560fbd6414c3))
-* **memory:** input-side compression for always-loaded files ([abfd5b1](https://github.com/event4u-app/agent-config/commit/abfd5b120f2effd2abd68adea45c8b15f315dfec))
-* **bench:** add caveman v1 benchmark with terse-control arm ([1e37062](https://github.com/event4u-app/agent-config/commit/1e37062cada6f9be5bfa0dfe4083753ade87f2f2))
-* **security:** add safe-paths denylist and caveman carve-outs validators ([249114d](https://github.com/event4u-app/agent-config/commit/249114d900a9d6960aee7bbeda5c28f85be718ad))
+* **scripts:** add lint_agents_layout enforcing agents/ flat-file whitelist ([77070e4](https://github.com/event4u-app/agent-config/commit/77070e4a53873ad3a5e1425e119f5762e455efc0))
+* **storage:** default wizard writes to user-scope with legacy-read fallback ([974c4d9](https://github.com/event4u-app/agent-config/commit/974c4d9ca53fcbd7f36ac4f7e06f5125733f72cf))
+* **wizard:** move step nav from header chips to summary jump-list ([648824f](https://github.com/event4u-app/agent-config/commit/648824f57483945de78167aa5662ded65c8845e4))
+* **wizard:** dry-run mode, error handling, expanded schema help text ([8ea254b](https://github.com/event4u-app/agent-config/commit/8ea254baa2f8fab0bebdd6cbd494a7ebd1b014df))
+* **wizard:** add dry-run mode to setup, settings, and ui:serve ([d369553](https://github.com/event4u-app/agent-config/commit/d369553aa48486d8fe6a6ca4137df0004f9dfae8))
+* **ui:** 7-step wizard + Settings page + .agent-user.md panel ([135b35c](https://github.com/event4u-app/agent-config/commit/135b35ca11d6203f0111aaf2b9d89da58c9aa735))
+* **ui:** form primitives + schema-driven form renderer ([4dfde4e](https://github.com/event4u-app/agent-config/commit/4dfde4e5c6730b80350dd5b08ee665f26383044a))
+* **ui:** scaffold Preact SPA shell (entry + router + API client) ([cc1e395](https://github.com/event4u-app/agent-config/commit/cc1e395e9d48018b07cde68656f50c6b55a2f64e))
+* **cli:** add 'agent-config settings' subcommand ([e799119](https://github.com/event4u-app/agent-config/commit/e799119041114323c05ddf24a5033567295e81c7))
+* **server:** inline settings JSON-Schema + 7-step wizard count ([a46948c](https://github.com/event4u-app/agent-config/commit/a46948c0db2f833bd87859a308ef3df9fa4c2183))
+* **server:** GUI skill-bridge discovery files ([01b3889](https://github.com/event4u-app/agent-config/commit/01b388902585c18657ff46940f40363abe312180))
+* **cli:** add onboard:finish subcommand for chat-skill convergence ([ccac4f9](https://github.com/event4u-app/agent-config/commit/ccac4f900ae3906dcfc70d11f00b5d377bf576de))
+* **setup-wizard:** wire settings API into app + 2PC boot replay ([bf2b1c9](https://github.com/event4u-app/agent-config/commit/bf2b1c9028ac5f3698a7605d94b46727ea4f4c70))
+* **setup-wizard:** add settings API routes (settings, userMd, wizard, schema) ([f1256b1](https://github.com/event4u-app/agent-config/commit/f1256b11d47bc5a9d2e8b50291c8b076c1f8836e))
+* **setup-wizard:** add atomic IO primitives for 2PC wizard commit ([1b5dbda](https://github.com/event4u-app/agent-config/commit/1b5dbdad51cda3fcfa625f1053ec2da1286493f4))
+* **gui:** phase 0 — contracts (ADR-014, schemas, design tokens, API doc) ([96462e6](https://github.com/event4u-app/agent-config/commit/96462e6c25b104c94a2a036af29f9ab8122f982d))
+* **visibility:** R5 Phase 4 — docs, decay policy, roadmap archival ([4de0c22](https://github.com/event4u-app/agent-config/commit/4de0c224f58f125df803c15848a259bec5a159dc))
+* **visibility:** R5 Phase 3 — positioning consistency lint ([68daa4f](https://github.com/event4u-app/agent-config/commit/68daa4f6d0ec09939c424bfadfaf3382941e7c8f))
+* **visibility:** R5 Phase 2 — MCP registry manifest + lifecycle tracking ([e0b8f8b](https://github.com/event4u-app/agent-config/commit/e0b8f8b8ac7d78a603405429b179e9a0fd985735))
+* **visibility:** topics-as-code + about manifest + split sync/drift workflows ([d61c648](https://github.com/event4u-app/agent-config/commit/d61c648377b705b04b57a38246c52259e1f22d2a))
+* **explain-last:** wire halt + provider why-slots into trace and renderer ([92d5bfc](https://github.com/event4u-app/agent-config/commit/92d5bfc67f83b1dcd7242e3d85502915e195b29b))
+* **work-engine:** persist HookHalt events into state.halts for explainability ([68fe11e](https://github.com/event4u-app/agent-config/commit/68fe11e204c7b0fb94d1201eb867f0a41a443a90))
+* **explain:** wire 'last' subcommand into cmd_explain dispatcher ([f871d67](https://github.com/event4u-app/agent-config/commit/f871d67bcc3bc2104d3ae7b67643684ba912f3d1))
+* **explain:** add explain_last trace builder package ([af32423](https://github.com/event4u-app/agent-config/commit/af32423c7a4d1df382fcf98df018ad0d4859ff97))
+* **settings:** add explain.enable_last knob ([1c518d8](https://github.com/event4u-app/agent-config/commit/1c518d8948421eae86d3f02961b6bb6a186a712c))
+* **explain:** lock ExplainTrace v1 schema and lint surface (Phase 1) ([6f81f65](https://github.com/event4u-app/agent-config/commit/6f81f65c901a8b9ba6582b4218bb6a0c6cbf9c09))
+* **discovery:** add artefact frontmatter linter (Phase 6.1) ([ce49720](https://github.com/event4u-app/agent-config/commit/ce49720f0b0405c13e07ba2fff6cfc86cfc2f379))
+* **discovery:** wire release pipeline to ship manifest (Phase 5) ([61aea0a](https://github.com/event4u-app/agent-config/commit/61aea0a97991395b75a4b392e8fa789030dbdb73))
+* **discovery:** auto-strict scanner under CI (Phase 4.4) ([1b2b0b3](https://github.com/event4u-app/agent-config/commit/1b2b0b3472bda036be03cdfb3b649d2c19594b43))
+* **discovery:** annotate meta pack + quarantine scaffold templates ([941a5c4](https://github.com/event4u-app/agent-config/commit/941a5c4190cd507750fcb4ba090b735a684b33a4))
+* **discovery:** annotate vertical packs (product, gtm, finance, ops, founder, ai-video) ([5d96d37](https://github.com/event4u-app/agent-config/commit/5d96d37681772283ee8b4e236b6f6f21b742bcfc))
+* **discovery:** annotate language/framework packs ([9af770f](https://github.com/event4u-app/agent-config/commit/9af770ffc708fa402c513896c414bf5566fafeab))
+* **discovery/engineering-base:** annotate engineering-base pack ([a6f498f](https://github.com/event4u-app/agent-config/commit/a6f498fc389642acc3d9a1a4dea60ce8d96397ff))
+* **discovery/php:** annotate php pack (pilot) ([2f94b33](https://github.com/event4u-app/agent-config/commit/2f94b331ae317d9996d05bd1a87bacbd47f6eb6b))
+* **discovery:** Phase 4 annotation helper ([2d5b816](https://github.com/event4u-app/agent-config/commit/2d5b81610d1eea7e36f492d35efdd01a0fee26cb))
+* **discovery:** R3 Phase 3 — TS CLI subcommands + Fastify discovery route ([5d58a6d](https://github.com/event4u-app/agent-config/commit/5d58a6d5852b2d7058159df7241fb144251bde47))
+* **discovery:** R3 Phase 2 — release-time scanner + manifest tooling ([784d072](https://github.com/event4u-app/agent-config/commit/784d0720cbea94304d4b8f75edf64152b221686f))
+* **discovery:** R3 Phase 1 — workspace & pack vocabulary as YAML ([ca08f1e](https://github.com/event4u-app/agent-config/commit/ca08f1ea9de0f3b8d52cb5b9746fb9ee56d749f8))
+* **discovery:** R3 Phase 0 — frontmatter contract and manifest schema ([633973e](https://github.com/event4u-app/agent-config/commit/633973e810f7cbf4758afe4151c20f8b01cab959))
+* **ui:** Vite UI scaffold (placeholder) ([169edbd](https://github.com/event4u-app/agent-config/commit/169edbd53de0b7be1d6454df7d3c7e3e3cbbf0c6))
+* **server:** embed Fastify server with security guards ([8c2f9ff](https://github.com/event4u-app/agent-config/commit/8c2f9ffde3126681a63a8f1cd04397fda2e536f8))
+* **cli:** TypeScript entry binary as thin forwarder ([df6c92c](https://github.com/event4u-app/agent-config/commit/df6c92c3b3aa3b63fb6edf54670f8a5d166e57f9))
 
 ### Bug Fixes
 
-* **caveman-speak:** bullet-format prose lines to satisfy structural-density lock ([5c8006d](https://github.com/event4u-app/agent-config/commit/5c8006d8bd70fea93671361160e6b7c4399302c6))
-* **refs:** inline roadmap council citations + mark contract council-refs as ADR trace ([5a11951](https://github.com/event4u-app/agent-config/commit/5a11951ebff87ba95465c0a6b9b59fd9a4d4cee2))
-* **contracts:** drop roadmap reference from compression-default-kill-criterion ([f2b2124](https://github.com/event4u-app/agent-config/commit/f2b212495744dae1904b256aa11d47e230e7b534))
-* **contracts:** add stability frontmatter to caveman-telemetry + cost-summary-schema ([c7efa54](https://github.com/event4u-app/agent-config/commit/c7efa54cc3587f42f3a21ca18b783b5504c56e04))
-* **portability:** apply task-invocation fix in .agent-src/ projection ([be87c2b](https://github.com/event4u-app/agent-config/commit/be87c2be1637570a61b7a8863216288f3828609c))
-* **portability:** swap task invocations for script paths in compress-memory skill ([886f9f4](https://github.com/event4u-app/agent-config/commit/886f9f4a615fa2351b9261a62fd49173f8e87c2f))
-* **roadmap:** clarify agent-status is a command not a skill in step-16 ([96df39d](https://github.com/event4u-app/agent-config/commit/96df39de7a7562df946c37fea8bc42927851071f))
-* **template:** bump agent_config_version pin to 2.20.1 ([c275864](https://github.com/event4u-app/agent-config/commit/c2758641718077baaaaefea1191760d397f6b47e))
+* **ci:** sync compressed outputs (fetch description, failure-modes heading, agent-settings code block) ([6bb9b36](https://github.com/event4u-app/agent-config/commit/6bb9b363a46310ffe32d1859ed356eaf0cbd6b18))
+* **ci:** propagate path refactor into .agent-src/, trim ghostwriter description ([2747288](https://github.com/event4u-app/agent-config/commit/2747288b62ee4135d5f5459d2864f3a8fe0ce97a))
+* **ui:** surface field errors on wizard step nav and toggle/radio inputs ([3abd156](https://github.com/event4u-app/agent-config/commit/3abd1560691397a4bfbf85f1279b6f9146513418))
+* **roadmaps:** update wizard-install-py-wiring parent link to archive path ([a40ae6e](https://github.com/event4u-app/agent-config/commit/a40ae6e2da01e2b96120af3fe87f2a787dc9b076))
+* **ui:** close diff modal and focus first errored field on save failure ([dd5bc72](https://github.com/event4u-app/agent-config/commit/dd5bc7236e26757dc4f809f49ee8f600710baebf))
+* **server:** wrap userMd through commitMulti helper for parity ([752199c](https://github.com/event4u-app/agent-config/commit/752199cf3907fca27b8198989b9edbc5ce56c28a))
+* **server:** satisfy noUncheckedIndexedAccess in yamlIO.replaceScalar ([53e9759](https://github.com/event4u-app/agent-config/commit/53e97597e87b41744e939ae9dd4c6ff5d804ca86))
+* **server:** hoist inline import() types to top-level import type ([515ddda](https://github.com/event4u-app/agent-config/commit/515dddadf391410b76c93d5829e27a2948b011e5))
+* **readme:** keep line count under lint floor + drop archived-roadmap link ([2b5e63c](https://github.com/event4u-app/agent-config/commit/2b5e63c3f29d74a20c344455d015d89cec326abd))
+* **sync:** drop stale .pytest_cache hash entry ([31dcaa4](https://github.com/event4u-app/agent-config/commit/31dcaa4cf614566db36f566a2388dc3f1a4dba0f))
+* **discovery:** allow ADR-013 discovery frontmatter in JSON schemas ([4100ef4](https://github.com/event4u-app/agent-config/commit/4100ef45796144e3e3bbf8c1a9cfd704ac9749cb))
+* **discovery:** absorb +189 frontmatter into concentration allowlist ([d0e160d](https://github.com/event4u-app/agent-config/commit/d0e160db9b575b95c73c9423a089f2018bb76f92))
+* **discovery:** shift framework-leakage allowlist by +12 after frontmatter inject ([6deacba](https://github.com/event4u-app/agent-config/commit/6deacba9523f7519a17b65e79f9e5b5f88f96371))
+* **discovery:** mirror generated_at normalisation in manifest linter ([5a30bf6](https://github.com/event4u-app/agent-config/commit/5a30bf65b87d86655bddcc2598b13d8ad5d61c32))
+* **discovery:** exclude generated_at from manifest checksum ([84dd81a](https://github.com/event4u-app/agent-config/commit/84dd81ab6eeb886ed2cb449eaf975466f16a5cd5))
+* **discovery:** allow documented_unassigned in manifest schema ([357a817](https://github.com/event4u-app/agent-config/commit/357a817d30486d5dc420ac326c625d0ec1277e00))
+* **discovery:** defer strict mode to --strict flag only (Phase 4.4 gate) ([45c1d67](https://github.com/event4u-app/agent-config/commit/45c1d679d26c8eae2c2f666400973cd170813660))
+* **golden:** silence deprecation banner in capture runner ([a98ed4e](https://github.com/event4u-app/agent-config/commit/a98ed4eaebb32cab229e5bce038000abdbf13f50))
+* **ci:** build dist before test:ts + restore symlink-safe shim ([ebd64a6](https://github.com/event4u-app/agent-config/commit/ebd64a6dd77ba2c474982ff88d1e9ee429cfd9b1))
 
 ### Documentation
 
-* **readme:** compact banner and badge row to stay under 750-line lint budget ([2f411a7](https://github.com/event4u-app/agent-config/commit/2f411a78993260d3bd1f5fb819779cad2b19ed07))
-* **readme:** add hero banner and migrate count display to shields.io badges ([980fe1a](https://github.com/event4u-app/agent-config/commit/980fe1ac1c529e3c57c967db148f2b162240ff27))
-* **caveman:** v1 kill-criterion verdict + Suspended state ([ca1751e](https://github.com/event4u-app/agent-config/commit/ca1751e8957783fa4e40ddfb89172702619f12bc))
-
-### Chores
+* **wizard:** pivot onboarding-gate and consumer docs to agent-config setup ([be83c1b](https://github.com/event4u-app/agent-config/commit/be83c1b4a6aa16400a3c5f5ce80571bcbff26dbd))
+* **readme:** tighten quickstart wizard line to stay at 750-line cap ([9ebe01f](https://github.com/event4u-app/agent-config/commit/9ebe01f4b46f3a32c59a546243c1cf7023f7026b))
+* **setup-gui:** wizard guide + customization + contracts ([dcd1ecb](https://github.com/event4u-app/agent-config/commit/dcd1ecb68b7fa84060108ddb273b593983809b6b))
+* **contracts,customization:** document /onboard ↔ wizard convergence ([0a7c707](https://github.com/event4u-app/agent-config/commit/0a7c7074aff338c18517deeec006a051ddafc59a))
+* **skill:** rewrite /onboard to use agent-config onboard:finish ([2a0053d](https://github.com/event4u-app/agent-config/commit/2a0053dd71d4feb7d44bee70833f40607f9b143c))
+* **contracts:** add onboard-skill-wizard bridge IPC contract ([08b5e22](https://github.com/event4u-app/agent-config/commit/08b5e22928760f3677408989373ba14c0ccff125))
+* **roadmap:** carve out /onboard convergence as follow-up (council HARD-BLOCKER) ([16445fe](https://github.com/event4u-app/agent-config/commit/16445fe005e7f1545aa98c5318c770d99ac62e9a))
+* **readme:** condense explainability blurb to stay under 750-line lint floor ([f5e1882](https://github.com/event4u-app/agent-config/commit/f5e1882c304acabb2993d98ec0aad0b69fddd2b4))
+* **explain:** document 'explain last' in customization.md and README ([dc5fe30](https://github.com/event4u-app/agent-config/commit/dc5fe304bca51ade2d94a04c09bcd816399b991a))
+* **discovery:** point references at archived R3 roadmap + virtual-pack note + sha256 sidecar ([1437b82](https://github.com/event4u-app/agent-config/commit/1437b8289fbf8578ccda283eb8ce810012232676))
+* **discovery:** add Phase 4 annotation audit trail + fix archive ref ([9f034a8](https://github.com/event4u-app/agent-config/commit/9f034a8edd2d8009a931e30c600474e9b4d88935))
+* **roadmap:** mark R3 Phases 4-6 + council resolution complete ([1b0bb2d](https://github.com/event4u-app/agent-config/commit/1b0bb2d3c718c97f328496d65163081796f4ba65))
+* **discovery:** cross-link ADR-013 from AGENTS.md and customization (Phase 6.2) ([acd82af](https://github.com/event4u-app/agent-config/commit/acd82af601547bb4dfe48ec8ca59c01142e4a20a))
+* **adr:** add ADR-012 — TypeScript CLI shell ([29e6bc4](https://github.com/event4u-app/agent-config/commit/29e6bc45c06bcbc41c48d3e984128b6716b795c2))
+
+### Refactoring
+
+* relocate durable records (runtime→evidence, low-impact→decisions) ([6d72262](https://github.com/event4u-app/agent-config/commit/6d722620d1d289ccd18fa05010f134f9cf088595))
+* consolidate agents/ into privilege-first taxonomy ([d2ce674](https://github.com/event4u-app/agent-config/commit/d2ce6748872fcda71a58517202882b4d49b7f82f))
+* **agents:** relocate council to runtime/, audit bundles to audits/, ai-council config to settings/ ([8cee3b3](https://github.com/event4u-app/agent-config/commit/8cee3b3a4b8c43d1036047324d2c3e9ad1615fce))
+* relocate user-md schema to shared and drop gray-matter ([cd9dba7](https://github.com/event4u-app/agent-config/commit/cd9dba7511637a8ca858d416e6b20609c3097b10))
 
-* **ownership:** regenerate ownership matrix ([1331bce](https://github.com/event4u-app/agent-config/commit/1331bce63d223adb971a931babe5e163b5a8aa12))
-* **index:** regenerate agents/index.md + docs/catalog.md for compress-memory ([6d16e7f](https://github.com/event4u-app/agent-config/commit/6d16e7fb3ca0a2fbe76a18337a94e98607262d06))
-* **sync:** bump skill count 210 -> 211 (compress-memory) ([bb361ed](https://github.com/event4u-app/agent-config/commit/bb361edb4e5e65cbc4e7eb41382f88f1909e5583))
-* **roadmaps:** close step-16 caveman-substance + archive-phantom-scan ([9388f9b](https://github.com/event4u-app/agent-config/commit/9388f9be662da17b98eb4000f16ff8fcf376e626))
-
-Tests: 4559 (+24 since 2.20.1)
+### Tests
 
-## [2.20.1](https://github.com/event4u-app/agent-config/compare/2.20.0...2.20.1) (2026-05-16)
+* **command-suggester:** drop onboard-specific assertion ([61c925b](https://github.com/event4u-app/agent-config/commit/61c925b30399b7903847a53b7b04e2a008b5bf7c))
+* Phase 5 evidence — server routes, atomic writes, wizard state, UI pages ([b968d06](https://github.com/event4u-app/agent-config/commit/b968d06892a0ba8039811e33004fed20c6c27cea))
+* **ui:** wizard flow + resume acceptance gates ([e63b54d](https://github.com/event4u-app/agent-config/commit/e63b54d908c7b0a4d5abc96c97f46619f8993f37))
+* **server:** parity gate — onboard:finish ↔ wizard byte-identical ([4d4c7e4](https://github.com/event4u-app/agent-config/commit/4d4c7e48aa19bbda1814dc2058bc8e25d7be90bc))
+* **golden:** regenerate GT baselines after adding state.halts field ([0363256](https://github.com/event4u-app/agent-config/commit/036325610bd97ac911ea94fbc5be578efc4b6ed5))
+* **explain:** add 43-test coverage suite + fixtures ([765392c](https://github.com/event4u-app/agent-config/commit/765392c7a70d954caf6db7a4afd2a0c49ec5be7e))
+* **ts:** cover CLI forwarder, server, and UI build ([a4bc38b](https://github.com/event4u-app/agent-config/commit/a4bc38b3fde0bc77565caaf21fa681884c445f2f))
 
-### Bug Fixes
+### CI
 
-* **lint:** treat zero active roadmaps as pass in lint-roadmap-complexity ([ff814e2](https://github.com/event4u-app/agent-config/commit/ff814e262a25b9269ae5d1b66495602b5d8f457b))
-* **template:** bump agent_config_version pin to 2.20.0 ([ab3acfc](https://github.com/event4u-app/agent-config/commit/ab3acfc3eebd39e5fb7df919bd5b7a455e2f58ea))
+* **tests:** install jsonschema for explain-trace contract validation ([3448273](https://github.com/event4u-app/agent-config/commit/3448273d16115cbb4b57f73fef34a3a64cd0ee8f))
+* **ts:** wire TypeScript gates + ship local-server-api contract ([68bcf86](https://github.com/event4u-app/agent-config/commit/68bcf86ffec4b47c935f2db27fe0909002c1fb84))
 
 ### Chores
 
-* **changelog:** split era 2.16.x → pre-2.17.0 ([67b668e](https://github.com/event4u-app/agent-config/commit/67b668ee2298cc56478a808a716e965482bf199d))
-* **roadmaps:** close and archive all 8 open roadmaps (Total Dominance) ([c13359f](https://github.com/event4u-app/agent-config/commit/c13359f0b676f251a9b6c6b7ed11804fdeb84257))
-
-Tests: 4535 (+0 since 2.20.0)
-
-## [2.20.0](https://github.com/event4u-app/agent-config/compare/2.19.0...2.20.0) (2026-05-16)
-
-### Features
-
-* **product:** step-15 product refinement — profiles + packs + presets + explain CLI ([59e7d6f](https://github.com/event4u-app/agent-config/commit/59e7d6f3ddce025e558da08c1da1b4c8155e68eb))
-* **parity:** step-11 ruflo parity — smoke + ADR + cost + namespace + MCP ([521b4c6](https://github.com/event4u-app/agent-config/commit/521b4c62f5fe266f5c18dfcca2abf4e06d97c217))
-* **caveman:** step-10 default-kill criterion + parity roadmap ([dd7ec3c](https://github.com/event4u-app/agent-config/commit/dd7ec3cae4f8839b28b4d3ff9dbdbb316ec5d035))
-* **bench:** step-4 measurement + benchmark infrastructure ([981d0cd](https://github.com/event4u-app/agent-config/commit/981d0cd1c48e2d23eede29bd86e833cd826ddfd9))
-* **skills:** step-2 skill inventory rationalization ([3fa651d](https://github.com/event4u-app/agent-config/commit/3fa651d2496e4fc483cd7ed452bb39f41dd39365))
-
-### Bug Fixes
-
-* **adr-create:** restore Inspect keyword in step-1 heading ([46c40ad](https://github.com/event4u-app/agent-config/commit/46c40adf4741f1e13d8d275f9363f98047d4b733))
-* **audit_mcp_tools:** drop roadmap link from generated inventory ([d35459e](https://github.com/event4u-app/agent-config/commit/d35459e94d9be473bbb567f7c348be5bff4b5e9d))
-* **audit_mcp_tools:** emit stability frontmatter in generated inventory ([ba7af12](https://github.com/event4u-app/agent-config/commit/ba7af12cf26509f2ea0ddb867303f3b225fea866))
-* **no-cheap-questions:** trim to clear concentration cap ([3516283](https://github.com/event4u-app/agent-config/commit/351628301aa168c31130b62ee306858944ecf9f2))
-* **onboard:** move recommendation off inline (recommended) tag ([6a77a06](https://github.com/event4u-app/agent-config/commit/6a77a06c014d8820662906ca6ab0ee55ac847e05))
-* **refs:** suppress legitimate council-response audit links ([d764329](https://github.com/event4u-app/agent-config/commit/d764329d8718124d150deafcce52bdd206ada740))
-* **contracts:** drop roadmap-file links from stable artefacts ([96ea60f](https://github.com/event4u-app/agent-config/commit/96ea60f8f6e85c6ce04e8042d9d2535938f75d9f))
-* **contracts:** bring beta-review markers into the 90-day window ([4be4a47](https://github.com/event4u-app/agent-config/commit/4be4a47cc30532fa20d1ea7c3311d7eaa154d7e6))
-* **contracts:** add stability frontmatter to 6 new contracts ([8b27577](https://github.com/event4u-app/agent-config/commit/8b27577bc6b4b28c36ccfbea48b4e92e35372fbd))
-* **portability:** replace task cost:* with direct script invocations ([0225f60](https://github.com/event4u-app/agent-config/commit/0225f60d0157edf4b4f74fe8fc1266295d5b90f2))
-* **rules:** restore no-cheap-questions Iron Law block ([e95315f](https://github.com/event4u-app/agent-config/commit/e95315f96323d1ef32328b1c8a630b5aacafee84))
-
-### Documentation
-
-* **readme:** restore three-audience headings, tighten user-types blurb ([fdb03bf](https://github.com/event4u-app/agent-config/commit/fdb03bf314acb1a7a570400c1ba3cadb8098b943))
-* **readme:** restore browse-all-commands canonical line ([d91f6e0](https://github.com/event4u-app/agent-config/commit/d91f6e0d99230792f570b02fab6a1b30a744187c))
-* **readme:** extract profile detail + featured commands to /docs ([e8745f3](https://github.com/event4u-app/agent-config/commit/e8745f33f1da089aefd763cc659be4568177dd07))
-* **roadmap:** regenerate dashboard + cross-roadmap link refresh ([f6b7085](https://github.com/event4u-app/agent-config/commit/f6b7085d3419f1a8b57daf9b949bd55312c17b9b))
-* **roadmap:** step-5 schema rigor + test cleanup ([b043230](https://github.com/event4u-app/agent-config/commit/b043230291222f6d6287d73e0807ea772e227e98))
-
-### Chores
+* untrack agents/runtime/ as volatile local-only ([2b87436](https://github.com/event4u-app/agent-config/commit/2b87436e7916fb145a5db16ed9e71e7e9d1f4046))
+* capture 2026-05-18 AI council responses for taxonomy convergence ([821def9](https://github.com/event4u-app/agent-config/commit/821def9e687d29db3e41b49c89bd3bed81274223))
+* **roadmap:** land onboarding-wizard-takeover and regenerated indexes ([5d26671](https://github.com/event4u-app/agent-config/commit/5d26671223c3d8244bac4f3d00aabc04a20b2667))
+* **rules:** trim auto-rule descriptions to fit 95% augment budget ([7a3fa4a](https://github.com/event4u-app/agent-config/commit/7a3fa4a00343603c3ab4155458f2c74d4c7ce770))
+* **roadmap:** close unified-setup-and-settings-gui + archive + sibling frontmatter ([6bfc11e](https://github.com/event4u-app/agent-config/commit/6bfc11e045d7b40cd27268f9ea517a05c5111d15))
+* **roadmap:** close phases 1-4 of unified-setup-and-settings-gui + carve out install.py wiring ([a460ef4](https://github.com/event4u-app/agent-config/commit/a460ef434f1b7ca78e7109e90e7a785fdc2abe8e))
+* **build:** wire Preact + Signals + happy-dom for GUI ([483630b](https://github.com/event4u-app/agent-config/commit/483630b693b86dc1591b59ace22ee881c1a8df83))
+* **roadmap:** archive completed convergence roadmap ([9b5f9fe](https://github.com/event4u-app/agent-config/commit/9b5f9fe7ee86f5c6415c77589cba716ee0d73ca3))
+* **policy:** add project-local TypeScript-first engineering policy ([9b4f0b8](https://github.com/event4u-app/agent-config/commit/9b4f0b85734d4ec6e73cd1cf361fd880bd7614f9))
+* **rules:** add pre-PR freshness gate to prevent stale-base conflicts ([c913a7f](https://github.com/event4u-app/agent-config/commit/c913a7fa3ab78bbb090c4203e3d291063a90be57))
+* **sync:** regenerate compressed mirrors + hashes for trimmed descriptions ([fe8c7c2](https://github.com/event4u-app/agent-config/commit/fe8c7c23e9127a5031ece5b0f85e68dcbde59c2a))
+* **rules:** trim 4 over-budget rule descriptions to ≤150 chars ([326f7d1](https://github.com/event4u-app/agent-config/commit/326f7d1f68d1fd2e438d1e6d5caf7c0b2ddc09dc))
+* **ownership:** regenerate file-ownership matrix ([aaabe42](https://github.com/event4u-app/agent-config/commit/aaabe4220edebea9f52185bf9322893cb5540f6c))
+* **lint:** allowlist 2 pre-existing multi-stack enumerations ([e192281](https://github.com/event4u-app/agent-config/commit/e1922817e251aeb2b9fd0e47735b93ca08fb26ad))
+* **roadmap:** mark phase 0 done on onboard-skill-wizard-convergence ([9c642f3](https://github.com/event4u-app/agent-config/commit/9c642f37e0fcc9e25f0f39ddc61ba6dc216a95a2))
+* **roadmap:** close and archive explainability-v2-explain-last ([5016b20](https://github.com/event4u-app/agent-config/commit/5016b202dbf2015461f13ea8786ad0ccb2538a2d))
+* **roadmap:** mark Phase 3 of explainability-v2-explain-last complete ([b7bbed7](https://github.com/event4u-app/agent-config/commit/b7bbed775a279ca7179a9433cd0c33b1395ac102))
+* **roadmap:** close and archive R3 — automated-pack-workspace-and-skill-discovery ([f67f0ec](https://github.com/event4u-app/agent-config/commit/f67f0ecff81ce35b99a396b55a2b99d80d11db9d))
+* **templates:** bump agent_config_version pin to 2.26.0 ([ad0f30f](https://github.com/event4u-app/agent-config/commit/ad0f30f9f219636a3a711ee86bafd2b3456eacf8))
+* **index:** regenerate after Phase 4 annotation lands ([25ec177](https://github.com/event4u-app/agent-config/commit/25ec1773bf0518931e7c39abf292af4a0e074e79))
+* **roadmap:** flip R3 Phases 0–3 + regenerate progress dashboard ([03d0b26](https://github.com/event4u-app/agent-config/commit/03d0b266dc4ff85bbb400373f43227c54ed4d694))
+* **roadmap:** persist progress-sync rule across autonomous runs ([db06aae](https://github.com/event4u-app/agent-config/commit/db06aae4f8e60b2a92925057902cce241c723a2b))
+* **roadmaps:** archive typescript-cli-and-local-gui-foundation (delivered in PR #187) ([d87e5ff](https://github.com/event4u-app/agent-config/commit/d87e5ffb42099ca9664538a7c057f7b434548501))
+* **deps:** scaffold TypeScript toolchain for CLI shell ([453dcdd](https://github.com/event4u-app/agent-config/commit/453dcddb638a175b6cdcdb99ba31e476dcae2968))
+* **roadmaps:** archive framework-neutrality-audit (shipped in 2.26.0) ([4935c26](https://github.com/event4u-app/agent-config/commit/4935c2640c80557ec949ac3c841a3bb5d2b335e6))
+
+Tests: 4697 (+52 since 2.26.0)
+
+# Era: pre-3.0.0 — archived
+
+> All entries from `2.26.0` and `2.25.0` live in
+> [`docs/archive/CHANGELOG-pre-3.0.0.md`](docs/archive/CHANGELOG-pre-3.0.0.md).
+> The archive is read-only; git tags `2.26.0` and prior remain the
+> canonical source for what shipped. Splitting these out of the main
+> file keeps the active era under the 200-line drift cap enforced by
+> `tests/test_changelog_eras.py`.
 
-* **changelog:** split era 2.15.x → pre-2.16.0 ([88b81ba](https://github.com/event4u-app/agent-config/commit/88b81bac54ae5f9558a1087c81d453c47d3039bb))
-* **mcp:** regenerate MCP tool inventory ([bce3169](https://github.com/event4u-app/agent-config/commit/bce3169b353c2d240df610e4bf01c91c96d23e0d))
-* **ownership:** regenerate ownership matrix after no-cheap-questions trim ([dbe58a9](https://github.com/event4u-app/agent-config/commit/dbe58a9dfafbca487f11b2501b1f1dabb1053a8d))
-* **template:** bump agent_config_version pin to 2.19.0 ([cfc4c59](https://github.com/event4u-app/agent-config/commit/cfc4c59e288862eccf4e7b9d215adf30e527f5a0))
-* **build:** wire step-2/4/11/15 tooling into Taskfile + gitignore ([0acc9e7](https://github.com/event4u-app/agent-config/commit/0acc9e77515e611eb685c58aeba91f3d5af9423f))
+# Era: pre-2.25.0 — archived
 
-Tests: 4535 (+42 since 2.19.0)
+> All entries from `2.24.0` through `2.20.0` live in
+> [`docs/archive/CHANGELOG-pre-2.25.0.md`](docs/archive/CHANGELOG-pre-2.25.0.md).
+> The archive is read-only; git tags `2.24.0` and prior remain the
+> canonical source for what shipped. Splitting these out of the main
+> file keeps the active era under the 200-line drift cap enforced by
+> `tests/test_changelog_eras.py`.
 
 # Era: pre-2.20.0 — archived
 

package/CONTRIBUTING.md

@@ -308,6 +308,67 @@ a provenance attestation. If the workflow file is renamed or moved, the
 trust link on npm must be updated accordingly or the publish step will
 fail.
 
+## Visibility surface
+
+The repository's outward-facing metadata (GitHub Topics, the *About*
+description and homepage, and the MCP-registry manifest) is
+**visibility-as-code**: every external claim about the package lives
+in a checked-in file under `.github/` or `dist/mcp/`, and a lint
+asserts agreement with the README. **Never edit Topics, description,
+or homepage in the GitHub UI** — those edits are overwritten on the
+next sync.
+
+Sources of truth:
+
+- [`.github/topics.yml`](.github/topics.yml) — the topic list +
+  optional paraphrase map consumed by the positioning lint.
+- [`.github/about.yml`](.github/about.yml) — description + homepage.
+- `dist/mcp/registry-manifest.json` — registry listings (lifecycle
+  status per entry); see
+  [`docs/distribution/mcp-submission-checklist.md`](docs/distribution/mcp-submission-checklist.md).
+
+Tooling:
+
+- `task lint-topics-yaml` — shape gate (slug regex, length, dupes).
+- `task build-mcp-registry-manifest` — render
+  `dist/mcp/registry-manifest.json` + the rendered payloads
+  (awesome-mcp-servers row, Cloudflare catalogue entry). Wired into
+  `npm prepack` so every published tarball carries the manifest.
+- `task lint-mcp-registry-manifest` — schema + payload-shape gate.
+- `task lint-positioning` — asserts the README H1 anchor
+  (*"Universal AI Agent OS"*) appears in `package.json.description`
+  and `.github/about.yml`, and that every topic in
+  `.github/topics.yml` is discoverable in the README body (literal
+  or via the optional `equivalents:` map).
+- `task sync-github-topics` — dry-run diff against the live remote;
+  pass `-- --apply` to mutate (requires `GITHUB_TOKEN` with
+  `administration: write`).
+- `task visibility-check` — runs every visibility lint in sequence
+  (topics + MCP registry + positioning). Run this before opening any
+  PR that touches `.github/topics.yml`, `.github/about.yml`,
+  `package.json.description`, or the README tagline.
+
+Adding a new external registry (e.g. `awesome-claude-code`) follows
+the same contract: extend the schema vocabulary, add a renderer in
+`scripts/build_mcp_registry_manifest.py`, and follow the per-registry
+procedure in
+[`docs/distribution/mcp-submission-checklist.md`](docs/distribution/mcp-submission-checklist.md).
+Never a UI edit.
+
+**Security trade-off (`administration: write`).** The
+[`sync-visibility.yml`](.github/workflows/sync-visibility.yml)
+workflow holds `administration: write` because
+`PUT /repos/{owner}/{repo}/topics` requires it. That same permission
+allows renaming the repo, changing visibility, or deleting it. The
+workflow is therefore `workflow_dispatch`-only (never auto-triggered)
+and runs under the `production-visibility` environment, which gates
+manual approval. The read-only drift detector
+([`check-visibility-drift.yml`](.github/workflows/check-visibility-drift.yml))
+holds only `contents: read` + `metadata: read` and runs on every
+push / PR. If `administration: write` becomes unacceptable, swap to
+a fine-grained PAT in repo secrets and document the rotation cadence
+here.
+
 ## License of contributions
 
 By contributing you agree that your contributions are licensed under the