@event4u/agent-config 2.2.2 → 2.4.0

package/docs/development.md

@@ -115,6 +115,43 @@ task install -- --target <dir> # Run the installer orchestrator on a target
 task install-hooks             # Install git hooks (pre-commit marketplace lint, pre-push sync check, chat-history bridges)
 ```
 
+### Local dev install (no release)
+
+Use these tasks to run the working tree as if it were a published
+release — useful for testing changes before `task release` cuts an npm
+version.
+
+```bash
+task dev:install-global        # Refresh ~/.claude, ~/.cursor, ~/.augment, … from this working tree (--force)
+task dev:link                  # Symlink this repo as the global @event4u/agent-config (npm link)
+task dev:unlink                # Remove the global symlink
+```
+
+**Typical flow:**
+
+1. In this repo: `task dev:link` — once. The `agent-config` bin on PATH
+   now resolves into the working tree.
+2. In this repo: `task dev:install-global` — every time you want
+   user-scope content (`~/.claude/rules`, `~/.cursor/`, …) refreshed.
+3. In a consumer project that uses `@event4u/agent-config` from npm,
+   opt in to the linked dev tree:
+
+   ```bash
+   cd /path/to/consumer-project
+   npm link @event4u/agent-config
+   ```
+
+   `npx @event4u/agent-config …` and `node_modules/.bin/agent-config`
+   in that project now resolve into the dev tree. Undo with
+   `npm unlink @event4u/agent-config` (project) and `task dev:unlink`
+   (this repo).
+
+**Caveat — npx outside a linked project:** `npx @event4u/agent-config`
+in a directory without a linked `node_modules/@event4u/agent-config`
+fetches the published version from the registry. Either run `npm link
+@event4u/agent-config` in that project first, or call the global
+`agent-config` bin directly (which `task dev:link` puts on PATH).
+
 ---
 
 ## Project Structure

package/docs/getting-started.md

@@ -106,7 +106,7 @@ Your agent is now:
 - **Respecting your codebase** — no conflicting patterns
 - **Following standards** — consistent code quality
 
-This is enforced automatically by 60 rules. No configuration needed.
+This is enforced automatically by 61 rules. No configuration needed.
 
 ---
 

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
@@ -46,6 +47,20 @@ section below this index is reference material for advanced installs
 | **Codex CLI** | `npx @event4u/agent-config init --tools=codex` | [`per-ide/codex.md`](setup/per-ide/codex.md) |
 | **Gemini CLI** | `npx @event4u/agent-config init --tools=gemini` | [`per-ide/gemini-cli.md`](setup/per-ide/gemini-cli.md) |
 | **GitHub Copilot** | `npx @event4u/agent-config init --tools=copilot` | [`per-ide/copilot.md`](setup/per-ide/copilot.md) |
+| **Augment Code** | `npx @event4u/agent-config init --tools=augment` | [`per-ide/augment.md`](setup/per-ide/augment.md) |
+| **Roo Code** | `npx @event4u/agent-config init --tools=roocode` | [`per-ide/roocode.md`](setup/per-ide/roocode.md) |
+| **Kilo Code** | `npx @event4u/agent-config init --tools=kilocode` | [`per-ide/kilocode.md`](setup/per-ide/kilocode.md) |
+| **Continue.dev** | `npx @event4u/agent-config init --tools=continue` | [`per-ide/continue.md`](setup/per-ide/continue.md) |
+| **Kiro** | `npx @event4u/agent-config init --tools=kiro` | [`per-ide/kiro.md`](setup/per-ide/kiro.md) |
+| **Zed** | `npx @event4u/agent-config init --tools=zed` | [`per-ide/zed.md`](setup/per-ide/zed.md) |
+| **JetBrains AI** | `npx @event4u/agent-config init --tools=jetbrains --global` | [`per-ide/jetbrains.md`](setup/per-ide/jetbrains.md) |
+| **Qoder** | `npx @event4u/agent-config init --tools=qoder --global` | [`per-ide/qoder.md`](setup/per-ide/qoder.md) |
+| **OpenCode** | `npx @event4u/agent-config init --tools=opencode --global` | [`per-ide/opencode.md`](setup/per-ide/opencode.md) |
+| **Trae** | `npx @event4u/agent-config init --tools=trae --global` | [`per-ide/trae.md`](setup/per-ide/trae.md) |
+| **Antigravity** | `npx @event4u/agent-config init --tools=antigravity --global` | [`per-ide/antigravity.md`](setup/per-ide/antigravity.md) |
+| **CodeBuddy** | `npx @event4u/agent-config init --tools=codebuddy --global` | [`per-ide/codebuddy.md`](setup/per-ide/codebuddy.md) |
+| **Droid (Factory)** | `npx @event4u/agent-config init --tools=droid --global` | [`per-ide/droid.md`](setup/per-ide/droid.md) |
+| **Warp** | `npx @event4u/agent-config init --tools=warp --global` | [`per-ide/warp.md`](setup/per-ide/warp.md) |
 | **All surfaces** | `npx @event4u/agent-config init` (default) | (each page above applies) |
 
 Combine surfaces by comma-separating: `--tools=claude-code,cursor,windsurf`.

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/antigravity.md

@@ -0,0 +1,63 @@
+# Antigravity Setup
+
+Antigravity (Google's agentic IDE) reads the Anthropic-shaped
+markdown skill bundle from its user-scope anchor `~/.agents/`. The
+package deploys via the universal skill convention; project-scope
+bridge is not yet wired (Phase 2.4 anchor).
+
+## Prerequisites
+
+- Antigravity IDE.
+- Node.js ≥ 18 for the install entrypoints.
+
+## Install
+
+Global only (canonical scope):
+
+```bash
+npx @event4u/agent-config init --tools=antigravity --global
+```
+
+Populates:
+
+- `~/.agents/skills/`   — Anthropic-shaped skill bundle
+- `~/.agents/rules/`    — kernel + tier-1/2 rules
+- `~/.agents/personas/` — review-lens personas
+
+(Project-scope `--tools=antigravity` is rejected with exit code 1
+— Antigravity has no documented project-discovery convention yet.)
+
+## How to use
+
+- Antigravity reads the skill bundle from `~/.agents/skills/` on
+  every session — no manual action required.
+- Slash commands (`/work`, `/implement-ticket`, `/commit`,
+  `/create-pr`, …) ship inside the skill bundle as named skills.
+  Invoke them by name in chat.
+- Antigravity ships an agent-orchestration surface; point it at
+  the project root so the agent can locate `AGENTS.md` and the
+  project's own `agents/` overlay.
+
+## Verification
+
+```bash
+test -d ~/.agents/skills
+test -d ~/.agents/rules
+```
+
+In Antigravity: ask *"What is this repo?"* — the answer should
+cite the AGENTS.md emergency triage block when the workspace is
+open.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| Skills not listed | Re-run `npx @event4u/agent-config init --tools=antigravity --global --force`. |
+| `--tools=antigravity` rejected | Add `--global` (Antigravity has global-only scope). |
+| `~/.agents/` collides with another tool | The anchor is shared by convention; coexists with other agents that use the same path. |
+
+## Cross-references
+
+- [`AGENTS.md`](../../../AGENTS.md) — canonical agent self-orientation.
+- [`docs/installation.md`](../../installation.md) — install matrix index.

package/docs/setup/per-ide/augment.md

@@ -0,0 +1,77 @@
+# Augment Code Setup
+
+Augment Code is the **substrate** for this package — every other tool
+mirrors content from the canonical `.augment/` tree. The Augment
+extension (VS Code, JetBrains) reads `.augment/rules/`,
+`.augment/skills/`, `.augment/commands/`, `.augment/personas/`, and
+`.augment/contexts/` directly.
+
+## Prerequisites
+
+- Augment Code extension: <https://www.augmentcode.com/>.
+- Node.js ≥ 18 for the install entrypoints.
+
+## Install
+
+Project scope (default):
+
+```bash
+npx @event4u/agent-config init --tools=augment
+```
+
+Global scope (cross-project, deploys the full bundle to `~/.augment/`):
+
+```bash
+npx @event4u/agent-config init --tools=augment --global
+```
+
+Populates (project):
+
+- `.augment/rules/`     — kernel (9 Iron-Law rules) + tier-1/2 routed rules
+- `.augment/skills/`    — domain skills
+- `.augment/commands/`  — slash commands
+- `.augment/personas/`  — review-lens personas
+- `.augment/contexts/`  — knowledge-layer contexts
+- `.augment/templates/` — scaffolds for AGENTS.md, copilot-instructions, etc.
+- `AGENTS.md`           — canonical agent self-orientation
+- `.agent-settings.yml` — per-project knobs
+
+## How to use
+
+- Augment auto-discovers `.augment/` on every session — no manual
+  action required.
+- The kernel rules (always-on Iron Laws) load first; tier-1/2
+  rules are routed by the rule-router based on intent.
+- Slash commands (`/work`, `/implement-ticket`, `/commit`,
+  `/create-pr`, `/refine-ticket`, …) are registered as Augment
+  Skills and surfaced in the agent's available-skills list.
+- Personas are review-lens voices; invoke them per `/mode` or by
+  name inside `/work` and `/implement-ticket` plans.
+- `.agent-settings.yml` controls per-project knobs (autonomy
+  default, cost profile, role-mode, learning opt-out).
+
+## Verification
+
+```bash
+test -d .augment/rules
+test -d .augment/skills
+test -d .augment/commands
+test -f AGENTS.md
+```
+
+Open the Augment panel and ask *"What is this repo?"* — the answer
+should cite the AGENTS.md emergency triage block.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| Skills not surfaced | Reload the Augment workspace; skills are indexed on session start. |
+| Symlinked sub-dirs missing | `.augment/skills` is a symlink to `.agent-src/skills`; run `task sync` to rebuild. |
+| Iron Laws not firing | Confirm `.augment/rules/` contains 9 kernel files (`task ci` validates the kernel count). |
+
+## Cross-references
+
+- [`AGENTS.md`](../../../AGENTS.md) — canonical agent self-orientation.
+- [`docs/architecture.md`](../../architecture.md) — kernel + router + projection pipeline.
+- [`docs/installation.md`](../../installation.md) — install matrix index.

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
 

package/docs/setup/per-ide/codebuddy.md

@@ -0,0 +1,63 @@
+# CodeBuddy Setup
+
+CodeBuddy (Tencent's AI coding assistant) reads the Anthropic-shaped
+markdown skill bundle from its user-scope anchor `~/.codebuddy/`.
+The package deploys via the universal skill convention; project-scope
+bridge is not yet wired (Phase 2.4 anchor).
+
+## Prerequisites
+
+- CodeBuddy extension / CLI.
+- Node.js ≥ 18 for the install entrypoints.
+
+## Install
+
+Global only (canonical scope):
+
+```bash
+npx @event4u/agent-config init --tools=codebuddy --global
+```
+
+Populates:
+
+- `~/.codebuddy/skills/`   — Anthropic-shaped skill bundle
+- `~/.codebuddy/rules/`    — kernel + tier-1/2 rules
+- `~/.codebuddy/personas/` — review-lens personas
+
+(Project-scope `--tools=codebuddy` is rejected with exit code 1 —
+CodeBuddy has no documented project-discovery convention yet.)
+
+## How to use
+
+- CodeBuddy reads the skill bundle from `~/.codebuddy/skills/` on
+  every session — no manual action required.
+- Slash commands (`/work`, `/implement-ticket`, `/commit`,
+  `/create-pr`, …) ship inside the skill bundle as named skills.
+  Invoke them by name in chat.
+- For repository-aware work, open the project root in CodeBuddy
+  so the agent can locate `AGENTS.md` and the project's own
+  `agents/` overlay.
+
+## Verification
+
+```bash
+test -d ~/.codebuddy/skills
+test -d ~/.codebuddy/rules
+```
+
+In CodeBuddy: open the chat panel and ask *"What is this repo?"*
+— the answer should cite the AGENTS.md emergency triage block
+when the workspace is open.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| Skills not listed | Re-run `npx @event4u/agent-config init --tools=codebuddy --global --force`. |
+| `--tools=codebuddy` rejected | Add `--global` (CodeBuddy has global-only scope). |
+| AGENTS.md not picked up | Open the project root in CodeBuddy; the agent reads `AGENTS.md` from the workspace. |
+
+## Cross-references
+
+- [`AGENTS.md`](../../../AGENTS.md) — canonical agent self-orientation.
+- [`docs/installation.md`](../../installation.md) — install matrix index.