@event4u/agent-config 2.3.0 → 2.4.1

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)
 

package/docs/guidelines/agent-infra/installed-tools-manifest.md

@@ -105,7 +105,7 @@ the next commit.
 |---|---|---|
 | `agents/installed-tools.lock` | **which AIs?** (this guideline) | bill of materials |
 | `.agent-project-settings.yml` | **how do agents behave?** | layered-settings (team file) |
-| `~/.config/agent-config/installed.lock` | **which package version did I install globally?** | per-developer global lockfile (Phase 1) |
+| `~/.event4u/agent-config/installed.lock` | **which package version did I install globally?** | per-developer global lockfile (Phase 1; legacy `~/.config/agent-config/installed.lock` read as fallback) |
 | `.agent-settings.yml` | **what are my personal preferences in this project?** | layered-settings (developer file) |
 
 Each file has one job. They never overlap. The two `.lock` files look

package/docs/guidelines/agent-infra/layered-settings.md

@@ -18,7 +18,7 @@ on user request.
 | File | Git | Scope | Owner | Example values |
 |---|---|---|---|---|
 | `.agent-project-settings.yml` | **committed** | team / repo | lead maintainer | `project.stack`, `quality.php.tools`, `memory.dogfood` |
-| `~/.config/agent-config/agent-settings.yml` | **n/a** (outside repo) | individual developer · cross-project | individual | `name`, `ide`, `cost_profile`, `personal.bot_icon`, `personal.autonomy`, `caveman.speak_scope` |
+| `~/.event4u/agent-config/agent-settings.yml` | **n/a** (outside repo) | individual developer · cross-project | individual | `name`, `ide`, `cost_profile`, `personal.bot_icon`, `personal.autonomy`, `caveman.speak_scope` (legacy `~/.config/agent-config/agent-settings.yml` read as fallback) |
 | `.agent-settings.yml` | **gitignored** | individual developer · this project | individual | `personal.ide`, `personal.user_name`, `subagents.max_parallel`, `onboarding.onboarded` |
 
 All three are YAML. Schemas:
@@ -34,7 +34,7 @@ Lowest priority → highest priority:
 
 ```
 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. .agent-project-settings.yml                        (team file, committed)
 4. .agent-settings.yml                                (developer file, gitignored)
 ```
@@ -67,8 +67,10 @@ Loader contract:
   back to the next tier without raising.
 - **Silent on out-of-whitelist keys.** `verbose=True` logs which keys
   were dropped for debugging; default mode is silent.
-- **Never auto-creates `~/.config/agent-config/`.** That directory
-  pre-exists from key installation; `/onboard` `mkdir -p`s on opt-in.
+- **Never auto-creates `~/.event4u/agent-config/`** (nor the legacy
+  `~/.config/agent-config/`). The new directory is created by the
+  migration shim or by `/onboard` on opt-in; key installation also
+  `mkdir -p`s as needed.
 
 ## Lock semantics
 

package/docs/installation.md

@@ -11,8 +11,9 @@ committed to a repo. No Task, no Make, no build tools required.
 > to **project**. Pass `--scope=global` or `--scope=project` to override
 > detection. See `--scope` in the CLI help for the full matrix.
 
-A global install records itself in `~/.config/agent-config/installed.lock`
-(schema_version, agent_config_version, installed_at, tools[]). `npx
+A global install records itself in `~/.event4u/agent-config/installed.lock`
+(schema_version, agent_config_version, installed_at, tools[]; the legacy
+`~/.config/agent-config/installed.lock` is read as a fallback). `npx
 @event4u/agent-config update` keeps that manifest in lockstep
 with the project pin in `.agent-settings.yml`. A version-mismatched
 re-run of `init --scope=global` is refused with exit code 1 until you

package/docs/migration/v1-to-v2.md

@@ -91,8 +91,53 @@ npx @event4u/agent-config doctor    # P3 — runtime sanity check
 
 Expected: pin resolved, no v1 markers detected, `update_check` reachable.
 
+## v2 → v2.4 — `~/.event4u/agent-config/` namespace move
+
+v2.4 relocates package-owned user-scope state from
+`~/.config/agent-config/` to `~/.event4u/agent-config/`. Tool anchors
+(`~/.claude/`, `~/.augment/`, `~/.cursor/`, `~/.codeium/windsurf/`) are
+**not** moved — those belong to their host tools.
+
+### What moves
+
+| 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/`                   |
+
+### Migration — zero action required
+
+A one-shot auto-migration shim runs on the first `init` / `update` /
+`uninstall` after upgrading to ≥ 2.4:
+
+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 a
+   subsequent install overwrites the new path.
+
+Override the target dir with `EVENT4U_HOME=/some/path` if you keep a
+non-standard home (`$HOME` substitute) or want to test the migration
+against a sandbox.
+
+### Claude Desktop — new bundle output
+
+v2.4 ships a real Claude Desktop deployment instead of the
+marker-only stub. Running `npx @event4u/agent-config init
+--tools=claude-desktop` (or any superset that includes it) now produces
+one ZIP per `.claude/skills/<name>/` under
+`~/.event4u/agent-config/claude-desktop/bundles/`. Import them via
+Claude Desktop → Customize → Skills → Upload. See
+[`docs/setup/per-ide/claude-desktop.md`](../setup/per-ide/claude-desktop.md)
+for the click-through.
+
 ## See also
 
 - [`docs/architecture.md` § Distribution model](../architecture.md#distribution-model--npx-only--version-pin-governance) — Q1 council rejection + override + pin substitution.
 - [`agents/roadmaps/road-to-portable-runtime-and-update-check.md`](../../agents/roadmaps/road-to-portable-runtime-and-update-check.md) — full delivery plan and acceptance criteria.
+- [`agents/roadmaps/road-to-event4u-namespace-and-claude-desktop.md`](../../agents/roadmaps/road-to-event4u-namespace-and-claude-desktop.md) — v2.4 namespace + bundle delivery plan.
 - [`docs/installation.md`](../installation.md) — v2 install reference.

package/docs/setup/per-ide/claude-desktop.md

@@ -1,65 +1,97 @@
 # Claude Desktop — agent-config setup
 
 The fastest path to running our skills, rules, and (optionally) the MCP
-server inside Claude Desktop. macOS / Windows / Linux. ~5 minutes.
-
-> **TL;DR** — Claude Desktop reads from `~/.claude/` (global only, no
-> project-local discovery on macOS). Run `npx @event4u/agent-config
-> global --tools=claude-desktop` once per user, or
-> `npx @event4u/agent-config init --tools=claude-code` per project
-> (Claude Code's project install also covers Desktop on macOS via the
-> shared `~/.claude/` location seeded during `init`). The v1 npm /
-> composer install scheme is retired; the new global-first scheme is
-> ADR-007 and writes through `~/.config/agent-config/installed.lock`.
+server inside Claude Desktop. macOS / Windows / Linux. ~10 minutes.
+
+> **TL;DR** — Claude Desktop does **not** auto-discover skills from any
+> filesystem path. It loads skills only after they are uploaded through
+> **Settings → Customize → Skills → Upload**. The package generates one
+> ZIP per skill under
+> `~/.event4u/agent-config/claude-desktop/bundles/` so you can drag /
+> drop them into the Customize panel. The v1 npm / composer install
+> scheme is retired; the new global-first scheme is ADR-007 and writes
+> through `~/.event4u/agent-config/installed.lock` (legacy
+> `~/.config/agent-config/installed.lock` read as fallback).
 
 ## Prerequisites
 
 - Claude Desktop installed (free or paid plan — same install path).
 - Node ≥ 18 (`npx` resolves the package per-project).
-- 5 minutes.
+- 10 minutes (most of it is clicking through the Customize panel once).
 
-## Step 1 — project-local install
+## Step 1 — generate the ZIP bundles
 
-Run inside each project that should be visible to Claude Desktop:
+Run once per user. Writes the per-skill ZIPs into the namespace dir:
 
 ```bash
-npx @event4u/agent-config init --tools=claude-code
+npx @event4u/agent-config init --tools=claude-desktop --global
 ```
 
-> `--tools=claude-code` covers both Claude Code **and** Claude
-> Desktop — the two surfaces share the project's `.claude/`
-> directory. Pass `--tools=claude-code,cursor,windsurf` to seed
-> additional surfaces in the same run.
-
 The init writes:
 
 ```
-.claude/
-├── rules/      # active rules for the project
-├── skills/     # active skills for the project
-└── commands/   # slash commands
+~/.event4u/agent-config/
+├── claude-desktop/
+│   ├── bundles/          # one <skill-name>.zip per .claude/skills/* folder
+│   └── claude-desktop.md # human-readable marker with the import flow
+├── agent-settings.yml
+├── installed.lock
+└── installed-tools.yml
 ```
 
-`.agent-settings.yml` carries the `agent_config_version` pin so every
-`npx` invocation resolves the same runtime.
+Re-running is safe: each ZIP carries a SHA-256 sidecar. Bundles whose
+content didn't change are skipped (idempotent).
+
+## Step 1b — import skills into Customize
+
+Claude Desktop does not read the bundle dir directly — you upload each
+ZIP through the **Customize** panel.
+
+1. Open Claude Desktop → **Settings** (`Cmd+,` on macOS).
+2. Pick **Customize** in the left sidebar, then the **Skills** tab.
+3. Click **Upload** (the button shown next to the search box).
+4. Navigate to `~/.event4u/agent-config/claude-desktop/bundles/` and
+   either:
+   - drag-drop the ZIPs you want into the upload zone, or
+   - select multiple ZIPs in the file picker (`Cmd-click` on macOS,
+     `Ctrl-click` on Windows / Linux) and confirm.
+5. The skills appear in the Customize list. Toggle each one **On**
+   (the toggle is the gate Claude Desktop uses at runtime, not the
+   upload itself).
+
+> The bundles dir prints in the install summary so you can paste-copy
+> it into Finder / Explorer. The marker file at the same path
+> (`claude-desktop.md`) repeats the click-through instructions.
 
 ## Step 2 — verify
 
-1. Restart Claude Desktop (full quit, not just window close).
-2. Open the project folder in a new conversation.
-3. Type `/` — the curated skills (`/work`, `/commit`, `/create-pr`,
-   `/quality-fix`, `/review-changes`, `/agent-handoff`,
-   `/project-analyze`, …) appear in the slash-command menu.
-4. Open Settings → Connectors. The kernel rules count appears under
-   "rules loaded".
+1. Restart Claude Desktop (full quit, not just window close — `Cmd+Q`
+   on macOS).
+2. Open a new conversation.
+3. Type `/` — the uploaded skills appear in the slash-command menu.
+4. **Settings → Customize → Skills** should list every skill you
+   uploaded, each with its **On** toggle live.
+
+If a skill is missing from `/`:
+
+- Confirm the **On** toggle is enabled in Customize → Skills.
+- Re-upload that specific ZIP — partial uploads can show up listed but
+  disabled.
+- Quit Claude Desktop fully (the menubar process on macOS caches old
+  skill state). Re-open and re-check.
 
-If the menu is empty:
+## Step 2b — optional: project-local install for Claude Code
 
-- Check `ls .claude/skills/` inside the project — should list the
-  curated skills.
-- Quit Claude Desktop (`Cmd+Q` on macOS, **not** just close the
-  window — the menubar process keeps the old skills cached).
-- Re-open and try `/` again.
+If you also use **Claude Code** in the same project, install the
+project-local config in the same run:
+
+```bash
+npx @event4u/agent-config init --tools=claude-code
+```
+
+Claude Code reads `.claude/` directly from the project — no upload
+step required. Pass `--tools=claude-code,claude-desktop,cursor,…` to
+seed multiple surfaces with one invocation.
 
 ## Step 3 — optional MCP server
 
@@ -116,34 +148,39 @@ Restart Claude Desktop. The 🔌 icon shows the connector under
 native HTTP) and per-client Bearer-auth snippets live in
 [`../mcp-client-config.md`](../mcp-client-config.md).
 
-## Claude Desktop ↔ Claude Code config sharing
-
-Both surfaces read **the same project `.claude/` directory**. Anything
-the `npx … init` writes for one is automatically picked up by the
-other when the project folder is opened:
-
-| File / dir                       | Shared by Desktop & Code? |
-| -------------------------------- | ------------------------- |
-| `<project>/.claude/CLAUDE.md`    | yes — project system prompt |
-| `<project>/.claude/rules/`       | yes — written by `npx … init` |
-| `<project>/.claude/skills/`      | yes — written by `npx … init` |
-| `<project>/.claude/commands/`    | yes — slash commands      |
-| `<project>/.claude/hooks/`       | yes — lifecycle hooks     |
-| `claude_desktop_config.json`     | Desktop only (MCP)        |
-| `~/.claude.json` (CLI config)    | Code only                 |
-
-Translation: run `npx @event4u/agent-config init` once per project,
-both clients pick the files up. Cross-link to
-[`claude-code.md`](claude-code.md) for the CLI-side view.
+## Claude Desktop ↔ Claude Code — what is shared, what is not
+
+Claude Code reads `.claude/` directly from the project. Claude Desktop
+does **not** auto-discover from any filesystem path — skills must be
+uploaded through Customize → Skills (Step 1b). MCP configuration is
+shared via `claude_desktop_config.json`.
+
+| Surface                          | Loaded by Desktop?           | Loaded by Code?            |
+| -------------------------------- | ---------------------------- | -------------------------- |
+| `<project>/.claude/CLAUDE.md`    | no                           | yes — project system prompt |
+| `<project>/.claude/rules/`       | no                           | yes — written by `npx … init` |
+| `<project>/.claude/skills/`      | no (upload via Customize)    | yes — written by `npx … init` |
+| `<project>/.claude/commands/`    | no                           | yes — slash commands       |
+| `<project>/.claude/hooks/`       | no                           | yes — lifecycle hooks      |
+| `~/.event4u/agent-config/claude-desktop/bundles/*.zip` | imported via Customize → Skills | not used                  |
+| `claude_desktop_config.json`     | yes — MCP servers            | no                          |
+| `~/.claude.json` (CLI config)    | no                           | yes — CLI session state    |
+
+Translation: run `npx @event4u/agent-config init --tools=claude-desktop
+--global` once per user to refresh the bundles, then re-upload through
+Customize → Skills whenever a bundle is rebuilt. Run
+`npx @event4u/agent-config init --tools=claude-code` per project for
+the Code-side files. Cross-link to [`claude-code.md`](claude-code.md)
+for the CLI-side view.
 
 ## Claude Cowork
 
-Claude Cowork (paid plans only — Pro / Max / Team) **shares the
-Desktop config**. Once Step 1 + Step 3 are done in Desktop:
+Claude Cowork (paid plans only — Pro / Max / Team) **inherits the
+Desktop session**. Once Steps 1 + 1b + 3 are done in Desktop:
 
-- Skills and rules under `~/.claude/` are picked up automatically.
-- MCP servers under `claude_desktop_config.json` are available
-  inside Cowork sessions without a separate install.
+- Uploaded skills from Customize are available inside Cowork.
+- MCP servers under `claude_desktop_config.json` are available inside
+  Cowork sessions without a separate install.
 - Cowork-specific limit (per Anthropic docs): MCP tools that write to
   the local filesystem are sandboxed — read-only tools (the entire
   `agent-config-mcp` Worker surface) work fine.
@@ -154,9 +191,14 @@ client-side feature set.
 
 ## Uninstall
 
-Remove the project's `.claude/`, `.agent-settings.yml`, and any bridge
-files written by `npx … init`. Nothing lives under `~/.claude/` from
-this package any more.
+1. Open Claude Desktop → Settings → Customize → Skills, toggle off and
+   delete each skill you uploaded.
+2. Delete `~/.event4u/agent-config/claude-desktop/` to remove the local
+   bundles. The legacy `~/.config/agent-config/` path can stay; the
+   loader treats it as read-only fallback.
+3. Run `npx @event4u/agent-config uninstall --tools=claude-desktop` to
+   refresh `installed.lock` (or `--all` to fully remove the user-scope
+   state).
 
 ## See also