@event4u/agent-config 2.2.2 → 2.4.0

package/CHANGELOG.md

@@ -343,6 +343,85 @@ our recommendation order, not its support status.
   users" tension without removing any path that an existing user
   might rely on.
 
+## [2.4.0](https://github.com/event4u-app/agent-config/compare/2.3.0...2.4.0) (2026-05-13)
+
+### Features
+
+* **install:** Claude Desktop ZIP bundle deployment ([9f2a00c](https://github.com/event4u-app/agent-config/commit/9f2a00cfd752232abdcf16c6e3440c46f5c9d596))
+* **install:** event4u namespace and auto-migration shim ([a58570e](https://github.com/event4u-app/agent-config/commit/a58570ecff885a7d50350c4281e675d7ff34f912))
+
+### Bug Fixes
+
+* **agent_settings:** align source with template via relative import ([a85b6c8](https://github.com/event4u-app/agent-config/commit/a85b6c82284310876d075a924918052fc7dbabdb))
+* **work_engine:** vendor user_global_paths into template for self-contained import ([f111c4e](https://github.com/event4u-app/agent-config/commit/f111c4e60de6cd60fbe81635029f9f34437a5ead))
+* **migrate:** atomic per-entry write with partial-debris purge ([5bd5aad](https://github.com/event4u-app/agent-config/commit/5bd5aadf0085657ec98eee049dda440d05b06801))
+
+### Documentation
+
+* **roadmap:** mark Steps 5-6 done (commit + PR opened) ([8492b7f](https://github.com/event4u-app/agent-config/commit/8492b7fd3cfd76075a64d5de770db2c5013e02dd))
+* **adr:** ADR-009 rollback section + AI Council convergence ([cc78adc](https://github.com/event4u-app/agent-config/commit/cc78adc0a9d0fbc51b2a65f35d8e0f13c1456a2f))
+* **contracts:** mark installed-tools-lockfile as beta ([90991da](https://github.com/event4u-app/agent-config/commit/90991da2f840ebae978fc4df9996c01324816404))
+* **adr:** ADR-009 event4u namespace + Claude Desktop ZIP bundles ([c707bd3](https://github.com/event4u-app/agent-config/commit/c707bd31211f94ace858738b7aee8d3898f0da88))
+* **roadmap:** add road-to-event4u-namespace-and-claude-desktop ([d92706b](https://github.com/event4u-app/agent-config/commit/d92706bd53621ff3a225db6eb9ee490f17f613d2))
+
+### Chores
+
+* **onboard:** rephrase 'event4u-owned' as 'package-owned' ([4bdd43b](https://github.com/event4u-app/agent-config/commit/4bdd43b7a6637a36cfa377045b6cd0f3f51b0fd1))
+* **template:** bump agent_config_version pin to 2.3.0 ([1180bf2](https://github.com/event4u-app/agent-config/commit/1180bf263f2f33fb5b41b13439c92cfbdc3a70d8))
+* **index:** regenerate index + catalog for accurate counts ([655a5eb](https://github.com/event4u-app/agent-config/commit/655a5eb81ce6744548a6f50451f66576a7c2b5ac))
+* **sync:** regenerate derived outputs for event4u namespace ([c277a94](https://github.com/event4u-app/agent-config/commit/c277a94f881ad4702ed2e97cebf6c5a7c8471a35))
+
+Tests: 3521 (+31 since 2.3.0)
+
+## [2.3.0](https://github.com/event4u-app/agent-config/compare/2.2.2...2.3.0) (2026-05-13)
+
+### Features
+
+* **prune:** add --resume-uninstall for focused crash recovery ([1c98454](https://github.com/event4u-app/agent-config/commit/1c9845404f1e629f802494c732f7438aa4335c8e))
+* **dev:** add dev:install-global and dev:link tasks for local development ([db4bdc9](https://github.com/event4u-app/agent-config/commit/db4bdc9794752791bb93235cc9cc3179df9b88df))
+* **install:** manifest schema v2 + doctor + conflict detection + inline tag ([50c0892](https://github.com/event4u-app/agent-config/commit/50c0892bf01eb904e48dd786ef03c519f82be485))
+* **cli:** add prune command for orphaned bridge markers ([d16abff](https://github.com/event4u-app/agent-config/commit/d16abff8ac9fd55ccd501d319785f463eb7cbeee))
+* **cli:** add uninstall/versions subcommands and --offline mode ([12a8e75](https://github.com/event4u-app/agent-config/commit/12a8e75945f1d26c1412d17331788c8e51601cea))
+* **install:** add workflow-mode activation hints to IDE bridges ([5e09e17](https://github.com/event4u-app/agent-config/commit/5e09e17f0de62b4113bd68839d6ce55a1527d4b1))
+* **rules:** add external-reference-deep-dive hardening rule ([0d2c80c](https://github.com/event4u-app/agent-config/commit/0d2c80c0f418b80a67d08c4577cfe67ab6abe3db))
+* **install:** expand global content deployment to 23 AI tools ([3ef13a7](https://github.com/event4u-app/agent-config/commit/3ef13a7c2ae16b95da9e5a49ec3a19c5cb211357))
+
+### Bug Fixes
+
+* **install:** normalise manifest paths + surface doctor remediation hint ([b4662b6](https://github.com/event4u-app/agent-config/commit/b4662b609db6b1b4660652facc0efb10b36a5d51))
+* **test:** patch USERPROFILE in isolated_lock fixture for Windows ([ac1c924](https://github.com/event4u-app/agent-config/commit/ac1c924e08822e09471c0cf0077ad69be531d7b5))
+
+### Documentation
+
+* **readme:** remove stale vX.0 breaking-change notice ([d6aef9a](https://github.com/event4u-app/agent-config/commit/d6aef9acce3e5409f0ffc641ecf026af1f9bb863))
+* **roadmap:** sharpen Phase 6 deferred trigger — name the collision ([d0a6dd2](https://github.com/event4u-app/agent-config/commit/d0a6dd28294c011d4135b4047e4e5252008fcf05))
+* **roadmap:** close + archive multi-package coexistence ([3ef464f](https://github.com/event4u-app/agent-config/commit/3ef464fd6123ead7ca755542a1459e6a9e8e270b))
+* **roadmap:** plan + close phases 1-5 of multi-package coexistence ([34967a5](https://github.com/event4u-app/agent-config/commit/34967a5e6525d4d742155ee3bd3fe0bb80d852bf))
+* **install:** add installed-tools-lockfile wire contract ([c352db3](https://github.com/event4u-app/agent-config/commit/c352db383f6bf6dc328159289fa4d96abb2594c4))
+* **setup:** add per-IDE activation guides for 14 tools ([6379a49](https://github.com/event4u-app/agent-config/commit/6379a49fed6ac3256c23ac8e04c69fa0d4f85aa2))
+
+### Tests
+
+* **e2e:** cover shared JSON merges, sole-owner cleanup, conflict chain ([0ff50ae](https://github.com/event4u-app/agent-config/commit/0ff50ae617d878138376e535fc8b5c22a7677356))
+* **install:** e2e multi-package coexistence scenario ([081318e](https://github.com/event4u-app/agent-config/commit/081318ea8e3c872548839d100117cbd9b4a1343a))
+* **cli:** cover prune — orphans, dry-run, json, hard-floor ([0261ea2](https://github.com/event4u-app/agent-config/commit/0261ea2e1687e6904bdcb3083cb0d700b6ef82e5))
+
+### CI
+
+* **tests:** bump per-shard parallelism explicitly to beat macOS nproc=3 ([83a3b4d](https://github.com/event4u-app/agent-config/commit/83a3b4d3bf6eefe10963d84525469aeb8e3b8abe))
+* **tests:** bump install-tests shards 3→4 to keep macOS under 2min ([dd4d5bc](https://github.com/event4u-app/agent-config/commit/dd4d5bc385282d344809a057d015a968811d4a3b))
+* **tests:** shard install-tests matrix to hit 1-2min/job target ([6a56416](https://github.com/event4u-app/agent-config/commit/6a564161f0a74601fe077d34c76f2f5a27657893))
+* **tests:** parallelize install-tests + fix Windows UTF-8 encoding ([e346a26](https://github.com/event4u-app/agent-config/commit/e346a26e91be633a63e8c7d46fb09a3a6cdf800e))
+* **tests:** bootstrap .augment/ projection before pytest ([e40371e](https://github.com/event4u-app/agent-config/commit/e40371ea7b0c345ee59eba8ba5e47328bf6aebe9))
+
+### Chores
+
+* finalize changes ([7cbbe68](https://github.com/event4u-app/agent-config/commit/7cbbe6881e040d67fd0598df73b82b3fbd1278c0))
+* regenerate router.json after kernel/tier rebuild ([ff5f10e](https://github.com/event4u-app/agent-config/commit/ff5f10e0589f46782ec6381a84377f22b90d7edc))
+* **marketplace:** refresh marketplace.json manifest ([eb9b934](https://github.com/event4u-app/agent-config/commit/eb9b934f5b4573ec1fcde19f91f6a20637b8dbeb))
+
+Tests: 3490 (+140 since 2.2.2)
+
 ## [2.2.2](https://github.com/event4u-app/agent-config/compare/2.2.1...2.2.2) (2026-05-12)
 
 ### Bug Fixes

package/README.md

@@ -1,12 +1,5 @@
 # Agent Config — Governed Agent System
 
-> ⚠️ **Breaking change in vX.0** — `agent-config` now ships as an
-> **npx-only runtime**. `composer require` / `npm install --save-dev`
-> are gone, the `--global` symlink scheme is retired. Existing
-> consumers: run `npx @event4u/agent-config migrate`
-> ([guide](docs/migration/v1-to-v2.md)). New consumers: jump to
-> [Quickstart](#quickstart).
-
 > **agent-config is not a runtime, but it ships a deterministic orchestration contract / state machine for host agents.**
 
 Give your AI agents an audit-disciplined orchestration contract — testing, Git, CI, code review, and **120+ stack-aware skills** — with quality guardrails built in.
@@ -14,7 +7,7 @@ Give your AI agents an audit-disciplined orchestration contract — testing, Git
 > Your agent picks up the project's stack, runs tests, prepares PRs, fixes CI — and follows your team's coding standards while doing it. Stack-aware skill sets ship for PHP (Laravel · Symfony · Zend/Laminas), JavaScript (Next.js · React · Node), and cross-stack concerns (API · testing · security · observability).
 
 <p align="center">
-  <strong>174 Skills</strong> · <strong>60 Rules</strong> · <strong>106 Commands</strong> · <strong>70 Guidelines</strong> · <strong>8 AI Tools</strong>
+  <strong>174 Skills</strong> · <strong>61 Rules</strong> · <strong>106 Commands</strong> · <strong>70 Guidelines</strong> · <strong>8 AI Tools</strong>
 </p>
 
 ---

package/config/agent-settings.template.yml

@@ -237,8 +237,9 @@ worktrees:
 # roadmap, diff, prompt, or file set. Council members never see the
 # host agent's reasoning — only the artefact + a neutral system prompt.
 #
-# Tokens are NEVER stored here. They live in ~/.config/agent-config/
-# <provider>.key (mode 0600), installed via:
+# Tokens are NEVER stored here. They live in ~/.event4u/agent-config/
+# <provider>.key (mode 0600; legacy ~/.config/agent-config/<provider>.key
+# is read as a fallback), installed via:
 #   bash scripts/install_anthropic_key.sh
 #   bash scripts/install_openai_key.sh
 #
@@ -396,7 +397,8 @@ memory:
 # two-line banner to stderr **after** the subcommand finishes; CI,
 # non-TTY stdout, and `AGENT_CONFIG_NO_UPDATE_CHECK=1` always suppress
 # it regardless of this flag. State is persisted at
-# `~/.config/agent-config/update-check.json` (mode 0600) with a 24 h
+# `~/.event4u/agent-config/update-check.json` (mode 0600; legacy
+# `~/.config/agent-config/update-check.json` read as fallback) with a 24 h
 # cadence. See docs/customization.md § "Update check" for the suppression
 # matrix and the road-to-portable-runtime-and-update-check roadmap (P2).
 update_check:

package/docs/architecture.md

@@ -143,7 +143,7 @@ fails on any source-side violation, without producing artifacts.
 | Layer | Count | Purpose |
 |---|---|---|
 | **Skills** | 174 | On-demand expertise — stack analysis (Laravel · Symfony · Zend / Laminas · Next.js · React · Node), testing, Docker, API design, security, observability, … |
-| **Rules** | 60 | Always-active constraints — coding standards, scope control, verification, language-and-tone, agent-authority |
+| **Rules** | 61 | Always-active constraints — coding standards, scope control, verification, language-and-tone, agent-authority |
 | **Commands** | 106 | Slash-command workflows — `/commit`, `/create-pr`, `/fix ci`, `/optimize skills`, `/feature plan`, `/work`, `/implement-ticket`, `/compress`, … |
 | **Guidelines** | 70 | Reference material cited by skills — PHP patterns, Eloquent, Playwright, agent-infra, … |
 | **Templates** | 7 | Scaffolds for features, roadmaps, contexts, skills, overrides |

package/docs/catalog.md

@@ -1,6 +1,6 @@
 # agent-config — Public Catalog
 
-Consumer-facing catalog of all **406 public artefacts** shipped by
+Consumer-facing catalog of all **408 public artefacts** shipped by
 this package. Internal package-maintenance rules and deprecation shims
 are excluded.
 
@@ -186,7 +186,7 @@ are excluded.
 | skill | [`voc-extract`](../.agent-src/skills/voc-extract/SKILL.md) |  | Use when extracting Voice-of-Customer themes from existing artefacts — GH issues, PR threads, Sentry patterns. Triggers on 'what are users saying', 'recurring complaints', 'top themes'. |
 | skill | [`websocket`](../.agent-src/skills/websocket/SKILL.md) |  | Use when building real-time features — WebSocket broadcasting, live updates, presence channels, connection state — even when the user just says 'push this to the client live'. |
 
-## Rules (57)
+## Rules (58)
 
 | kind | name | type | description |
 |---|---|---|---|
@@ -210,6 +210,7 @@ are excluded.
 | rule | [`domain-adoption-policy`](../.agent-src/rules/domain-adoption-policy.md) | auto | Adopting a new domain track (mobile, ML, blockchain, IoT, gaming) — gates import on demand, ownership, CI fit, Sunset compatibility BEFORE harvest |
 | rule | [`downstream-changes`](../.agent-src/rules/downstream-changes.md) | auto | After EVERY code edit, find ALL downstream changes needed to existing files, including callers, tests, imports, types, and documentation |
 | rule | [`e2e-testing`](../.agent-src/rules/e2e-testing.md) | auto | Playwright E2E tests — locators, assertions, Page Objects, fixtures, CI, and flaky test prevention |
+| rule | [`external-reference-deep-dive`](../.agent-src/rules/external-reference-deep-dive.md) | auto | When the user names an external repo, file, URL, or artifact as a reference — fetch the actual tree and inspect, never summarize from README or metadata |
 | rule | [`guidelines`](../.agent-src/rules/guidelines.md) | manual | Writing or reviewing code — check relevant guideline before writing or reviewing code |
 | rule | [`improve-before-implement`](../.agent-src/rules/improve-before-implement.md) | auto | Before implementing features or architectural changes — validate the request against existing code, challenge weak requirements, suggest improvements |
 | rule | [`invite-challenge`](../.agent-src/rules/invite-challenge.md) | auto | Before executing a complex plan or non-trivial design — ask 'am I solving the right problem?' and pause for user confirmation, even when no ambiguity |
@@ -359,7 +360,7 @@ are excluded.
 | command | [`upstream-contribute`](../.agent-src/commands/upstream-contribute.md) |  | Contribute a learning, skill, rule, or fix from a consumer project back to the shared agent-config package |
 | command | [`work`](../.agent-src/commands/work.md) |  | Drive a free-form prompt end-to-end through refine → score → plan → implement → test → verify → report — Option-A loop over the `work_engine` Python engine, confidence-band gated, no auto-git. |
 
-## Guidelines (69)
+## Guidelines (70)
 
 | kind | name | category | description |
 |---|---|---|---|
@@ -374,6 +375,7 @@ are excluded.
 | guideline | [`direct-answers-demos`](../docs/guidelines/agent-infra/direct-answers-demos.md) | agent-infra |  |
 | guideline | [`engineering-memory-data-format`](../docs/guidelines/agent-infra/engineering-memory-data-format.md) | agent-infra |  |
 | guideline | [`first-principles`](../docs/guidelines/agent-infra/first-principles.md) | agent-infra |  |
+| guideline | [`installed-tools-manifest`](../docs/guidelines/agent-infra/installed-tools-manifest.md) | agent-infra |  |
 | guideline | [`inversion-thinking`](../docs/guidelines/agent-infra/inversion-thinking.md) | agent-infra |  |
 | guideline | [`ios-simulator-guide`](../docs/guidelines/agent-infra/ios-simulator-guide.md) | agent-infra |  |
 | guideline | [`language-and-tone-examples`](../docs/guidelines/agent-infra/language-and-tone-examples.md) | agent-infra |  |

package/docs/contracts/installed-tools-lockfile.md

@@ -0,0 +1,142 @@
+---
+stability: beta
+---
+
+# Installed-Tools Lockfile — Wire Contract
+
+Canonical wire-format spec for `agents/installed-tools.lock` — the
+project-committed bill of materials for AI tooling installed into this
+repository.
+
+- **Authoritative module:** [`scripts/_lib/installed_tools.py`](../../scripts/_lib/installed_tools.py)
+- **ADR:** [`docs/decisions/ADR-008-installed-tools-manifest.md`](../decisions/ADR-008-installed-tools-manifest.md)
+- **Workflow guide:** [`docs/guidelines/agent-infra/installed-tools-manifest.md`](../guidelines/agent-infra/installed-tools-manifest.md)
+- **Active roadmap:** P1.1 of [`agents/roadmaps/road-to-multi-package-coexistence.md`](../../agents/roadmaps/road-to-multi-package-coexistence.md)
+
+## Versions
+
+| Version | Status | Writer | Reader |
+|---|---|---|---|
+| **1** | legacy | not emitted by current code | tolerated by `read_manifest` |
+| **2** | current | `write_manifest` always emits this | tolerated by `read_manifest` |
+
+`SCHEMA_VERSION = 2` · `SCHEMA_VERSIONS_SUPPORTED = (1, 2)`. The reader
+must accept any version in `SCHEMA_VERSIONS_SUPPORTED`; the writer must
+always emit the highest. Bumps are breaking on the writer side and
+require a migration plan.
+
+## Schema v2 — wire format
+
+```yaml
+schema_version: 2
+agent_config_version: "2.2.0"
+deploy_roots:                          # optional, top-level (P1.1)
+  - .augment/rules
+  - .cursor/rules
+tools:
+  - name: claude-code                  # one of _VALID_TOOLS
+    scope: global                      # global | project
+    bridge_marker: ~/.claude/PROJECT_MANAGED_BY_AGENT_CONFIG
+    installed_at: "2026-05-12"
+    status: installed                  # optional: installed | uninstalling (P2.2)
+    files:                             # optional, per-tool (P1.1)
+      - path: .augment/rules/r1.md
+        kind: deployed                 # one of FILE_KINDS
+        sha256: "<64 hex chars>"
+      - path: .cursorrules
+        kind: bridge
+        sha256: null                   # null permitted for non-content markers
+    merged_keys:                       # optional, per-tool (P1.1)
+      - file: .mcp.json
+        json_pointer: "/mcpServers/agent-config"
+```
+
+### Top-level fields
+
+| Field | Type | Owner | Notes |
+|---|---|---|---|
+| `schema_version` | int | machine | always `2` on write |
+| `agent_config_version` | str | machine | last writer's package version |
+| `deploy_roots` | list[str] | machine | optional; directories the doctor command surveys for foreign files. Omitted when empty. Falls back to `DEFAULT_DEPLOY_ROOTS` when consumers need a survey scope and no explicit list is present. |
+| `tools` | list[obj] | machine | install-order preserved, not alphabetised |
+
+### Per-tool fields
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `name` | str | yes | one of `_VALID_TOOLS` in `scripts/install.py` |
+| `scope` | str | yes | `global` (user-home) or `project` (workspace bridge) |
+| `bridge_marker` | str | yes | absolute / `~`-prefixed for global; repo-relative for project |
+| `installed_at` | str | yes | ISO date; informational only |
+| `status` | str | no | `installed` (default when absent) or `uninstalling`; two-phase uninstall (P2.2). A crashed uninstall leaves the entry in `uninstalling` — `agent-config prune --resume-uninstall` sweeps only those entries' `files[]` without touching healthy tools or unmanaged drift. |
+| `files` | list[obj] | no | content the installer deployed for this tool |
+| `merged_keys` | list[obj] | no | named keys this tool inserted into shared JSON files |
+
+### `files[]` entries
+
+| Field | Type | Notes |
+|---|---|---|
+| `path` | str | repo-relative for project-scope, `~`-prefixed for global |
+| `kind` | str | one of `FILE_KINDS = {bridge, deployed, marker}` |
+| `sha256` | str / null | 64 hex chars of the file's SHA-256 at install time, or `null` for markers / pointers without content |
+
+`kind` semantics:
+
+- **`bridge`** — team-pointer marker like `.cursorrules` or `.windsurf/PROJECT_MANAGED_BY_AGENT_CONFIG`. Existence-tracked, content-untracked.
+- **`deployed`** — bundle content the installer wrote (e.g. `.augment/rules/*.md`). Content-tracked via `sha256` so drift is detectable.
+- **`marker`** — one-off sentinel (e.g. `claude-desktop` install marker). Existence-only.
+
+### `merged_keys[]` entries
+
+| Field | Type | Notes |
+|---|---|---|
+| `file` | str | repo-relative path to the shared file (e.g. `.mcp.json`) |
+| `json_pointer` | str | RFC 6901 pointer. **Constraint:** must target an object key, never an array index. Array-index pointers shift on neighbour-tool uninstall and corrupt other packages' ownership. |
+
+The pointer constraint is enforced at write time in P1.5; readers in v2.x
+must reject manifests that contain array-index pointers.
+
+## Compatibility — reader tolerance
+
+- `read_manifest` accepts both v1 and v2 wire formats.
+- When `pyyaml` is available, v2 round-trips fully.
+- When `pyyaml` is missing, the manual fallback parser extracts v1-equivalent fields (top-level scalars + per-tool scalar fields) and **silently drops** v2 nested fields (`files`, `merged_keys`, `deploy_roots`). Callers that need full v2 fidelity must ensure `pyyaml` is on the path.
+
+## Compatibility — writer behaviour
+
+- `write_manifest(path, version, tools, *, deploy_roots=None)` always emits `schema_version: 2`.
+- Optional v2 fields (`deploy_roots`, per-tool `files` / `merged_keys` / `status`) are emitted only when non-empty, so a v1-shaped call produces a v2 file that is structurally minimal and v1-readable for the core fields.
+- All writes are crash-safe via [`scripts/_lib/fs_atomic.py`](../../scripts/_lib/fs_atomic.py) (`write_atomic`: tmp + fsync + rename + parent-dir fsync). See P1.0 of the multi-package roadmap.
+
+## Determinism
+
+Required by P1.3 (not yet enforced in v2.0 of the writer):
+
+1. `tools[]` order = install order (no re-sort).
+2. `files[]` order within a tool = sorted by `path` ascending.
+3. `merged_keys[]` order within a tool = sorted by `(file, json_pointer)` ascending.
+4. `deploy_roots[]` order = as supplied by the writer (caller-controlled).
+
+Determinism is what lets the doctor command produce stable diffs across team members.
+
+## Inline package tag (P5 — non-authoritative)
+
+Deployed Markdown files may carry a frontmatter tag that records provenance for human readers:
+
+```yaml
+---
+title: My rule
+package: event4u/agent-config
+source_path: config/rules/general.md
+---
+```
+
+Properties:
+
+- **Optional.** Files without a leading `---` frontmatter block are deployed as-is; no synthetic frontmatter is added (P5.1).
+- **Human-readable only.** The lockfile remains the single source of truth for ownership, prune, and uninstall decisions. Removing or hand-editing the inline tag does **not** alter prune / uninstall semantics (P5.3).
+- **Surfaced by doctor.** A frontmatter-bearing file whose `package:` value disagrees with this writer's identifier — or whose `package:` key has been removed — appears under the `tag-drift` category of `agent-config doctor` (P5.2). Tag-drift exit code = 1, same as other drift; fix hint points at `--force` re-install.
+- **Idempotent.** Re-installation rewrites the same `package:` / `source_path:` values; running install twice produces byte-identical Markdown.
+- **`source_path:` (not `source:`).** The injected provenance-path key is named `source_path:` to avoid collision with the established `source: package` origin-type marker used by 200+ rule files in this and downstream packages. The injector treats `source:` as a foreign key and never rewrites it.
+
+Neighbour packages writing into the same project SHOULD use their own `package:` identifier so doctor can distinguish authored ownership at a glance, but they MUST still register their files in the manifest — the inline tag is a UX affordance, not a substitute for the lockfile entry.

package/docs/customization.md

@@ -48,12 +48,14 @@ Six **DX-comfort** keys can be carried across every project that uses
 `event4u/agent-config` by storing them once in a user-global file at:
 
 ```
-~/.config/agent-config/agent-settings.yml
+~/.event4u/agent-config/agent-settings.yml
 ```
 
-The path is XDG-style and matches the existing
-`~/.config/agent-config/` directory used for `anthropic.key`,
-`openai.key`, and `council-spend.jsonl`.
+The path namespaces every event4u-owned user-global artefact under one
+root — same place where `anthropic.key`, `openai.key`, and
+`council-spend.jsonl` now live. Pre-2.4 installs that still keep these
+files under `~/.config/agent-config/` are read as a fallback until the
+namespace migration shim moves them.
 
 **Whitelist (locked, exact dotted paths)** — only these six keys are
 mergeable from the user-global file; every other key is silently ignored:
@@ -71,7 +73,7 @@ caveman.speak_scope
 
 ```
 1. Package defaults                                   (shipped by event4u/agent-config)
-2. ~/.config/agent-config/agent-settings.yml          (user-global · whitelist-filtered)
+2. ~/.event4u/agent-config/agent-settings.yml         (user-global · whitelist-filtered · legacy ~/.config/agent-config/ read as fallback)
 3. <repo-root>/.agent-settings.yml                    (project-wide · all keys)
 4. <intermediate-dir>/.agent-settings.yml             (subsystem-scoped · all keys · optional)
 5. <CWD>/.agent-settings.yml                          (deepest · all keys · wins)
@@ -126,7 +128,7 @@ Rules:
   consumers should pin.
 - **Owned by the project, not the developer.** Lives in
   `.agent-settings.yml` (committed), reviewed in PRs like any other
-  config change. Never merged from `~/.config/agent-config/agent-settings.yml`.
+  config change. Never merged from `~/.event4u/agent-config/agent-settings.yml`.
 - **Resolver enforcement.** `npx @event4u/agent-config <cmd>`
   compares the resolved CLI version against the pin; mismatch
   triggers a re-exec at the pinned version
@@ -150,22 +152,23 @@ Rules:
 | `chat_history.on_overflow` | per profile | `rotate` drops oldest, `compress` marks for summarization (see matrix below). |
 | `onboarding.onboarded` | `false` | Whether `/onboard` has run. The `onboarding-gate` rule prompts for `/onboard` while this is `false`. |
 | `ai_council.enabled` | `false` | Master switch for the `/council` command. Even when enabled, every consultation asks before spending tokens. |
-| `ai_council.members.<provider>.enabled` | `false` | Per-provider opt-in (`anthropic`, `openai`). Tokens live in `~/.config/agent-config/<provider>.key` (mode 0600), never in this file. |
+| `ai_council.members.<provider>.enabled` | `false` | Per-provider opt-in (`anthropic`, `openai`). Tokens live in `~/.event4u/agent-config/<provider>.key` (mode 0600), never in this file. Legacy `~/.config/agent-config/<provider>.key` is read as a fallback. |
 | `ai_council.members.<provider>.model` | per provider | Which model the provider sends the query to (e.g. `claude-sonnet-4-5`, `gpt-4o`). |
 | `ai_council.cost_budget.max_input_tokens` | `50000` | Hard cap on summed input tokens per `/council` invocation. |
 | `ai_council.cost_budget.max_output_tokens` | `20000` | Hard cap on summed output tokens per `/council` invocation. |
 | `ai_council.cost_budget.max_calls` | `10` | Maximum council members per invocation. |
 | `ai_council.cost_budget.max_total_usd` | `0.0` | Per-invocation USD ceiling. `0` disables (token caps still apply). |
-| `ai_council.cost_budget.daily_limit_usd` | `0.0` | Rolling 24h USD ceiling across all `/council` calls. `0` disables. Ledger lives at `~/.config/agent-config/council-spend.jsonl` (mode 0600). |
+| `ai_council.cost_budget.daily_limit_usd` | `0.0` | Rolling 24h USD ceiling across all `/council` calls. `0` disables. Ledger lives at `~/.event4u/agent-config/council-spend.jsonl` (mode 0600). |
 | `ai_council.session_retention_days` | `14` | Auto-prune for `agents/council-sessions/` audit folders. Older session directories are removed on the next `save()`. `0` disables (keep forever). |
 
 > **Experimental.** AI Council is not yet validated by external users. API costs apply per consultation.
 
 Council API tokens are installed via `./agent-config keys:install-anthropic`
 and `./agent-config keys:install-openai` — they prompt on `/dev/tty`, write to
-`~/.config/agent-config/<provider>.key` with mode `0600`, and never accept env
-vars. The `/council` command refuses to run if the key file's permissions
-drift.
+`~/.event4u/agent-config/<provider>.key` with mode `0600`, and never accept env
+vars. Pre-2.4 installs at `~/.config/agent-config/<provider>.key` are still
+honoured by the loaders as a fallback. The `/council` command refuses to run
+if the key file's permissions drift.
 
 ### Cost profiles
 
@@ -316,9 +319,10 @@ shadowed.
 | `agents/roadmaps/` | ❌ No — project-rooted only. | ❌ No. | Active delivery plans. |
 | `agents/state/`, `agents/memory/`, `agents/work_engine/`, `agents/.agent-prices.md`, `agents/council-*/` | ❌ No — stateful / session-scoped. | ❌ No. | Per-session state, not shareable. |
 
-**User-global asymmetry.** `~/.config/agent-config/agents/overrides/`
-is the only user-global overlay path consulted by the loader. Files
-under `~/.config/agent-config/agents/contexts/` or
+**User-global asymmetry.** `~/.event4u/agent-config/agents/overrides/`
+is the only user-global overlay path consulted by the loader (the
+legacy `~/.config/agent-config/agents/overrides/` tree is read as a
+fallback). Files under `~/.event4u/agent-config/agents/contexts/` or
 `.../agents/decisions/` are silently skipped — these kinds are
 project-shaped and must not leak across projects.
 
@@ -343,9 +347,11 @@ finished. There is no prompt — the user updates when they want with
     Update: npx @event4u/agent-config update
 ```
 
-State is persisted at `~/.config/agent-config/update-check.json`
-(mode `0600`) — sibling of `anthropic.key`, `council-spend.jsonl`.
-The fetch is hard-capped at 1 s and silent on any error.
+State is persisted at `~/.event4u/agent-config/update-check.json`
+(mode `0600`; the legacy `~/.config/agent-config/update-check.json`
+is read as a fallback) — sibling of `anthropic.key`,
+`council-spend.jsonl`. The fetch is hard-capped at 1 s and silent on
+any error.
 
 ### Suppression matrix
 

package/docs/decisions/ADR-007-agent-discovery-scopes.md

@@ -10,6 +10,12 @@ phase: post-v2.1.0 · simplicity-and-everywhere
 
 # ADR-007 — Agent Discovery Scopes: Global-Default Install Model
 
+> **Update (v2.4, 2026-05-13):** the user-scope dir was relocated from
+> `~/.config/agent-config/` to `~/.event4u/agent-config/` by
+> [`ADR-009`](ADR-009-event4u-namespace.md). The legacy path is still
+> read as a back-compat fallback. The discovery-scope contract in this
+> ADR is otherwise unchanged.
+>
 > **Note (post-acceptance):** the one-shot installer command was later
 > renamed from `npx @event4u/create-agent-config init` to
 > `npx @event4u/agent-config init` when the standalone wrapper package

package/docs/decisions/ADR-009-event4u-namespace.md

@@ -0,0 +1,188 @@
+---
+adr: 009
+status: accepted
+date: 2026-05-13
+decision: event4u-namespace-and-claude-desktop-zip-bundles
+supersedes: —
+superseded_by: —
+phase: v2.4 · namespace-and-claude-desktop
+---
+
+# ADR-009 — `~/.event4u/agent-config/` namespace + Claude Desktop ZIP bundles
+
+## Status
+
+**Accepted** · 2026-05-13 · signed off by Matze after the user ask
+*"auf globaler ebene sollen unsere dateien in einem
+.event4u/agent-config Folder im user ordner landen"* combined with the
+Claude Desktop deployment gap surfaced in the same turn (the v1
+`marker-only` integration did not actually make any skill visible to
+the Customize → Skills panel). Implementation tracked in
+[`agents/roadmaps/road-to-event4u-namespace-and-claude-desktop.md`](../../agents/roadmaps/road-to-event4u-namespace-and-claude-desktop.md).
+
+## Context
+
+ADR-007 made global-first install the default and seeded the
+user-scope state at `~/.config/agent-config/` (XDG-style). Two pain
+points surfaced in production use:
+
+1. **Namespace collision risk.** `~/.config/agent-config/` is a
+   generic-sounding path. Future tools owned by event4u (or
+   third-party suites named `agent-config`) would step on the same
+   prefix. The user requested a vendor-owned umbrella:
+   `~/.event4u/agent-config/`.
+2. **Claude Desktop deployment was a stub.** `scripts/install.py`
+   wrote a `claude-desktop.md` marker file under
+   `~/.config/agent-config/claude-desktop/` and called it done. Claude
+   Desktop does **not** auto-discover skills from any filesystem path
+   — the user must upload each skill through **Settings → Customize →
+   Skills → Upload**. Research against `nextlevelbuilder/ui-ux-pro-max-skill`
+   and the Anthropic Skills API docs confirmed there is no public
+   bulk-upload API for personal installs (the `/v1/skills` endpoint is
+   workspace + code-execution gated).
+
+Tool anchors (`~/.claude/`, `~/.augment/`, `~/.cursor/`,
+`~/.codeium/windsurf/`) are owned by the host tool and must **not** be
+moved — those paths are conventionalised by the tool itself.
+
+## Decision
+
+Two coordinated moves:
+
+### 1. Package-owned user-scope state lives under `~/.event4u/agent-config/`
+
+| Old path                                            | New path                                                |
+|-----------------------------------------------------|---------------------------------------------------------|
+| `~/.config/agent-config/agent-settings.yml`         | `~/.event4u/agent-config/agent-settings.yml`            |
+| `~/.config/agent-config/installed.lock`             | `~/.event4u/agent-config/installed.lock`                |
+| `~/.config/agent-config/installed-tools.yml`        | `~/.event4u/agent-config/installed-tools.yml`           |
+| `~/.config/agent-config/update-check.json`          | `~/.event4u/agent-config/update-check.json`             |
+| `~/.config/agent-config/ai-council/`                | `~/.event4u/agent-config/ai-council/`                   |
+
+Path resolution lives in `scripts/_lib/user_global_paths.py`:
+
+- `event4u_root()` — primary path; honours `EVENT4U_HOME` override.
+- `legacy_xdg_root()` — read-only fallback for unmigrated installs.
+- `resolve(name)` — returns the primary path; if absent and the legacy
+  copy exists, returns the legacy path. Writes always target the
+  primary path.
+
+A one-shot auto-migration shim runs on first post-upgrade
+`init`/`update`/`uninstall`:
+
+1. If `~/.event4u/agent-config/` already exists → no-op.
+2. Otherwise, copy every file from `~/.config/agent-config/` to the
+   new path, preserving mtimes.
+3. Drop a `MIGRATED.md` breadcrumb in the legacy dir pointing at the
+   new home. Legacy files stay readable; loaders fall back to them
+   until the next install overwrites the primary path.
+
+Tool anchors are **untouched**. The umbrella applies only to
+package-owned files.
+
+### 2. Claude Desktop deployment = per-skill ZIP bundles
+
+`scripts/_lib/claude_desktop_bundler.py` walks `.claude/skills/`,
+dereferences symlinks, and packs each `<skill-name>/` folder into a
+self-contained ZIP under
+`~/.event4u/agent-config/claude-desktop/bundles/<skill-name>.zip`.
+
+- Exclusions: `__pycache__/`, `.git*`, `*.pyc`, `.DS_Store`.
+- Atomic writes via `tempfile` + `os.replace`.
+- SHA-256 sidecar (`<name>.zip.sha256`) drives content-hash idempotency.
+- Repeat runs write 0 bundles when source unchanged; `--force` rebuilds.
+
+The user imports the ZIPs manually via Claude Desktop → Settings →
+Customize → Skills → Upload. The install summary surfaces the bundle
+path and count so the user can paste it into Finder / Explorer.
+
+## Consequences
+
+### Positive
+
+- **Vendor namespace is reserved.** Future event4u-owned packages can
+  drop sibling dirs under `~/.event4u/` without colliding with the
+  XDG-shape of other suites.
+- **Claude Desktop integration is real.** v2.4 produces 276 ZIPs from
+  the package's own `.claude/skills/` and the import flow is
+  click-through, no terminal.
+- **Migration is zero-action.** Existing users keep working — the
+  shim copies on first install and the legacy fallback covers any
+  loader that hasn't been re-run yet.
+- **Override-friendly.** `EVENT4U_HOME` lets CI / sandbox / multi-tenant
+  layouts redirect the root without monkey-patching.
+
+### Negative
+
+- **Manual upload step for Claude Desktop.** Until Anthropic ships a
+  public per-user Skills API, every fresh install / bundle refresh
+  requires the user to re-upload through Customize. The bundle count
+  in the install summary is the closest we can get to closing this loop.
+- **Two read paths during transition.** Loaders must consult both
+  `event4u_root()` and `legacy_xdg_root()` for the next two minor
+  versions. Once usage telemetry shows the legacy dir is consistently
+  empty, we can retire the fallback.
+- **Symlink semantics differ across platforms.** The bundler
+  `dereferences` symlinks during ZIP creation; on Windows this means
+  skills must not rely on cross-volume symlinks at pack time.
+
+### Neutral
+
+- Tool anchors (`~/.claude/`, `~/.augment/`, …) keep their owner. This
+  ADR explicitly does **not** propose moving them under
+  `~/.event4u/`.
+
+## Rollback / kill-switch
+
+If the migration corrupts user state, the rollback path is **manual but
+zero-data-loss** by design:
+
+1. **Legacy tree is never auto-deleted.** Even after the breadcrumb is
+   written, `~/.config/agent-config/` retains every file. The user can
+   reinstate it by deleting `~/.event4u/agent-config/` and re-running
+   `bash install.sh --global` — the shim will re-copy from the legacy
+   tree if the new root is absent.
+2. **Per-entry atomic write.** Each top-level entry is copied to a
+   sibling `<name>.event4u-partial-<pid>` and then `os.replace`'d into
+   place. A crash mid-copy leaves `*.event4u-partial-*` debris that the
+   next run purges before retrying — a partial subdirectory is never
+   mistaken for a completed copy.
+3. **`EVENT4U_HOME` env override.** A user who needs to point the
+   resolver at a known-good state (e.g. a restored backup) can set
+   `EVENT4U_HOME=/path/to/restored/agent-config` without editing any
+   config file.
+4. **Bundler is hash-gated.** If `claude_desktop_bundler.py` ever
+   produces a corrupt ZIP, the SHA-256 sidecar diverges from the source
+   manifest and the next run rewrites it. `--force` forces a full
+   rebuild from scratch.
+5. **Out-of-scope failure modes.** Disk exhaustion mid-copy, permission
+   bit corruption on cross-filesystem moves, and unicode-NFC normalisation
+   drift on macOS HFS+ → APFS migrations are **not** auto-recovered.
+   Users hit by those run the manual rollback in step 1.
+
+## Alternatives considered
+
+1. **Symlink `~/.event4u/agent-config/` ↔ `~/.config/agent-config/`.**
+   Rejected: doubles the surface (loaders still need both paths in
+   memory) and creates a removal hazard (`rm -rf ~/.config/agent-config`
+   wipes the new home too).
+2. **Anthropic `/v1/skills` API client for Claude Desktop.** Rejected:
+   the endpoint is workspace + code-execution gated, not viable for
+   personal installs. Captured as a follow-up if user demand surfaces.
+3. **Single mega-ZIP of all skills.** Rejected: Customize → Skills
+   imports one skill per ZIP. A combined archive would require the
+   user to extract + re-zip locally, defeating the purpose.
+4. **Hard-cut migration (delete legacy on first run).** Rejected: a
+   crash mid-copy would leave the user with neither path readable.
+   The current shim is copy-then-breadcrumb, leaving the legacy dir
+   intact for at least one more cycle.
+
+## References
+
+- [`agents/roadmaps/road-to-event4u-namespace-and-claude-desktop.md`](../../agents/roadmaps/road-to-event4u-namespace-and-claude-desktop.md)
+- [`scripts/_lib/user_global_paths.py`](../../scripts/_lib/user_global_paths.py)
+- [`scripts/_lib/claude_desktop_bundler.py`](../../scripts/_lib/claude_desktop_bundler.py)
+- [`docs/setup/per-ide/claude-desktop.md`](../setup/per-ide/claude-desktop.md)
+- [`docs/migration/v1-to-v2.md`](../migration/v1-to-v2.md) § v2 → v2.4
+- ADR-007 (predecessor — global-first install scopes)
+- ADR-008 (sibling — installed-tools manifest)

package/docs/decisions/INDEX.md

@@ -12,6 +12,7 @@ _Auto-generated by `scripts/adr/regenerate_index.py`. Do not edit._
 | [ADR-006](ADR-006-skill-tools-python-pilot.md) | Skill Tools Python Pilot Pass | accepted | 2026-05-09 | — |
 | [ADR-007](ADR-007-agent-discovery-scopes.md) | Global Default Install With Export Subcommand | accepted | 2026-05-12 | — |
 | [ADR-008](ADR-008-installed-tools-manifest.md) | Committed Installed Tools Manifest Separate From Settings | proposed | 2026-05-12 | — |
+| [ADR-009](ADR-009-event4u-namespace.md) | Event4U Namespace And Claude Desktop Zip Bundles | accepted | 2026-05-13 | — |
 
 ## Unnumbered (legacy)