@event4u/agent-config 9.8.0 → 9.9.0

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

@@ -1,207 +0,0 @@
-# Claude Desktop — agent-config setup
-
-The fastest path to running our skills, rules, and (optionally) the MCP
-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 current global-only scheme follows ADR-007 +
-> [ADR-020](../../decisions/ADR-020-global-only-consumer-scope.md) 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).
-- 10 minutes (most of it is clicking through the Customize panel once).
-
-## Step 1 — generate the ZIP bundles
-
-Run once per user. Writes the per-skill ZIPs into the namespace dir:
-
-```bash
-npx @event4u/agent-config init --tools=claude-desktop --global
-```
-
-The init writes:
-
-```
-~/.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
-```
-
-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 — `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.
-
-## Step 2b — optional: project-local install for Claude Code
-
-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
-
-Claude Desktop also speaks MCP. Wiring up your own self-hosted
-`agent-config-mcp` Cloudflare Worker exposes the **full** skill / rule /
-command catalog (~480 items) on demand, on top of the 15 you installed
-in Step 1.
-
-Deploy the Worker first per [`../mcp-cloud-setup.md`](../mcp-cloud-setup.md) — your
-URL will be `https://agent-config-mcp.<your-account>.workers.dev`
-(or a custom domain you wire up in Step 7). Replace
-`https://your-worker.workers.dev` below with that URL.
-
-Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
-(macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows /
-Linux is `~/.config/Claude/claude_desktop_config.json`):
-
-```json
-{
-  "mcpServers": {
-    "agent-config": {
-      "command": "npx",
-      "args": ["-y", "mcp-remote", "https://your-worker.workers.dev"]
-    }
-  }
-}
-```
-
-If you set the `MCP-Token` secret on the Worker (recommended — see
-[`../mcp-cloud-setup.md`](../mcp-cloud-setup.md) § Bearer auth), add the header:
-
-```json
-{
-  "mcpServers": {
-    "agent-config": {
-      "command": "npx",
-      "args": [
-        "-y", "mcp-remote", "https://your-worker.workers.dev",
-        "--header", "Authorization: Bearer ${MCP_TOKEN}"
-      ],
-      "env": { "MCP_TOKEN": "paste-token-here" }
-    }
-  }
-}
-```
-
-A pre-wired template ships at
-[`src/templates/claude_desktop_config.json.template`](../../../templates/claude_desktop_config.json.template) —
-copy, swap the placeholder URL for your deploy, and uncomment the MCP
-block.
-
-Restart Claude Desktop. The 🔌 icon shows the connector under
-**Settings → Connectors**. Full transport details (mcp-remote vs.
-native HTTP) and per-client Bearer-auth snippets live in
-[`../mcp-client-config.md`](../mcp-client-config.md).
-
-## 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) **inherits the
-Desktop session**. Once Steps 1 + 1b + 3 are done in Desktop:
-
-- 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.
-
-If a feature works in Desktop but not in Cowork, check that you're on
-a paid plan — Cowork is gated, Desktop's free tier has the full
-client-side feature set.
-
-## Uninstall
-
-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
-
-- Project-local install — [`../../installation.md`](../../installation.md)
-- MCP client transports — [`../mcp-client-config.md`](../mcp-client-config.md)

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

@@ -1,43 +0,0 @@
-# Cline Setup
-
-Cline (formerly Claude Dev) reads `.clinerules` (single-file aggregate)
-and `AGENTS.md`.
-
-## Prerequisites
-
-- Cline VS Code extension: <https://github.com/cline/cline>.
-- Node.js ≥ 18.
-
-## Install
-
-```bash
-npx @event4u/agent-config init --tools=cline
-```
-
-Populates:
-
-- `.clinerules`           — single-file aggregate (rules)
-- `AGENTS.md`             — agent self-orientation
-- `.agent-settings.yml`   — per-project knobs
-
-## Verification
-
-```bash
-test -f .clinerules
-test -f AGENTS.md
-```
-
-In VS Code: open the Cline panel — it should pick up the rules
-automatically. Run `/help` in the chat to verify rule loading.
-
-## Troubleshooting
-
-| Symptom | Fix |
-|---|---|
-| Rules not picked up | Reload VS Code window after `task generate-tools`. |
-| `.clinerules` missing | Re-run `npx @event4u/agent-config init --tools=cline`. |
-
-## Cross-references
-
-- [`AGENTS.md`](../../../AGENTS.md) — canonical agent self-orientation.
-- [`docs/installation.md`](../../installation.md) — install matrix index.

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

@@ -1,63 +0,0 @@
-# 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.

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

@@ -1,46 +0,0 @@
-# OpenAI Codex CLI Setup
-
-OpenAI's Codex CLI (the `codex` command) reads `AGENTS.md` from the
-repo root for project context.
-
-## Prerequisites
-
-- Codex CLI installed: <https://github.com/openai/codex>.
-- Node.js ≥ 18 (for the install entrypoints).
-
-## Install
-
-```bash
-npx @event4u/agent-config init --tools=codex
-```
-
-Populates:
-
-- `AGENTS.md`             — agent self-orientation (Codex auto-loads)
-- `.agent-settings.yml`   — per-project knobs
-
-Codex CLI reads `AGENTS.md` automatically when invoked from the repo
-root. No additional configuration needed.
-
-## Verification
-
-```bash
-test -f AGENTS.md
-codex --help            # confirm CLI installed
-```
-
-In a Codex CLI session, the loaded `AGENTS.md` content informs every
-turn — verify by asking *"what is this repo?"* and confirming the
-answer matches `AGENTS.md`'s emergency-triage block.
-
-## Troubleshooting
-
-| Symptom | Fix |
-|---|---|
-| Codex ignores `AGENTS.md` | Run from repo root, not a subdirectory. |
-| Out-of-date context | `codex` re-reads on each session start — quit and restart. |
-
-## Cross-references
-
-- [`AGENTS.md`](../../../AGENTS.md) — canonical agent self-orientation.
-- [`docs/installation.md`](../../installation.md) — install matrix index.

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

@@ -1,68 +0,0 @@
-# Continue.dev Setup
-
-Continue.dev (VS Code + JetBrains extension) auto-discovers
-`.continue/rules/*.md` as system-level rules per project.
-
-## Prerequisites
-
-- Continue extension: <https://continue.dev>.
-- Node.js ≥ 18 for the install entrypoints.
-
-## Install
-
-Project scope (default):
-
-```bash
-npx @event4u/agent-config init --tools=continue
-```
-
-Global scope (cross-project, deploys the universal skill bundle to
-`~/.continue/`):
-
-```bash
-npx @event4u/agent-config init --tools=continue --global
-```
-
-Populates (project):
-
-- `.continue/rules/agent-config.md` — auto-discovered rule marker
-- `AGENTS.md`                       — canonical agent self-orientation
-- `.agent-settings.yml`             — per-project knobs
-
-## How to use
-
-- Rules under `.continue/rules/*.md` load automatically on every
-  Continue session — no manual action required.
-- Continue exposes **Chat**, **Edit** (inline) and **Autocomplete**
-  surfaces. All three honor the rules; Chat is the surface that
-  reads `AGENTS.md` and the skill bundle.
-- Slash commands and skills live under `.augment/commands/` and
-  `.augment/skills/`. Continue does not register them natively —
-  invoke them by name in chat (e.g. *"run the create-pr command"*).
-- For repository-aware orchestration, use **`@codebase`** in
-  Continue chat alongside the named command/skill so Continue
-  retrieves the relevant files first.
-
-## Verification
-
-```bash
-test -f .continue/rules/agent-config.md
-test -f AGENTS.md
-```
-
-In VS Code or JetBrains: open the Continue panel and ask
-*"What is this repo?"* — the answer should cite the AGENTS.md
-emergency triage block.
-
-## Troubleshooting
-
-| Symptom | Fix |
-|---|---|
-| Rules not picked up | Reload the IDE window after install. |
-| Marker missing | Re-run `npx @event4u/agent-config init --tools=continue --force`. |
-| Continue ignores `@codebase` results | Index the workspace once via the Continue settings panel. |
-
-## Cross-references
-
-- [`AGENTS.md`](../../../AGENTS.md) — canonical agent self-orientation.
-- [`docs/installation.md`](../../installation.md) — install matrix index.

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

@@ -1,80 +0,0 @@
-# GitHub Copilot Setup
-
-GitHub Copilot Chat (VS Code, JetBrains, Neovim, `gh copilot` CLI)
-reads `.github/copilot-instructions.md` for project-level guidance and
-falls back to `AGENTS.md` where supported.
-
-## Prerequisites
-
-- GitHub Copilot subscription (Individual, Business, or Enterprise).
-- Copilot Chat enabled in your IDE.
-- Node.js ≥ 18 for the install entrypoints.
-
-## Install
-
-```bash
-npx @event4u/agent-config init --tools=copilot
-```
-
-Populates:
-
-- `.github/copilot-instructions.md` — Copilot's project-level prompt
-- `AGENTS.md`                       — canonical agent self-orientation
-- `.agent-settings.yml`             — per-project knobs
-
-The package keeps `.github/copilot-instructions.md` deliberately thin
-(it points back to `AGENTS.md`) so all surfaces share a single source
-of truth.
-
-## VS Code Copilot Chat
-
-Auto-loads `.github/copilot-instructions.md` once you reload the VS
-Code window after install. Verify in the Copilot Chat panel —
-*"What is this repo?"* should answer using the AGENTS.md emergency
-triage block.
-
-## JetBrains Copilot
-
-JetBrains Copilot 1.5+ reads the same `.github/copilot-instructions.md`
-file. No extra steps; reload the project after install.
-
-## Neovim Copilot
-
-`copilot.lua` and `CopilotChat.nvim` honor
-`.github/copilot-instructions.md`. No extra config needed.
-
-## `gh copilot` CLI
-
-The `gh copilot` plugin (`gh extension install github/gh-copilot`)
-reads the repo context including `AGENTS.md` and
-`.github/copilot-instructions.md` when invoked from the repo root.
-
-## Suppressing Copilot PR review noise
-
-Copilot's PR auto-review can flag the package's own kernel rules as
-"unusual phrasing". The package ships a Copilot-suppression rule
-([`augment-portability`](../../../.augment/rules/augment-portability.md))
-that documents this trade-off.
-
-## Verification
-
-```bash
-test -f .github/copilot-instructions.md
-test -f AGENTS.md
-gh copilot --version             # if you want CLI plugin
-```
-
-## Troubleshooting
-
-| Symptom | Fix |
-|---|---|
-| Copilot ignores the file | Reload the IDE window after install. |
-| File missing after install | Re-run `npx @event4u/agent-config init --tools=copilot`. |
-| Copilot PR review too noisy | See the `copilot-config` skill for suppression patterns. |
-
-## Cross-references
-
-- [`AGENTS.md`](../../../AGENTS.md) — canonical agent self-orientation.
-- [`.augment/skills/copilot-config/SKILL.md`](../../../.augment/skills/copilot-config/SKILL.md)
-  — tuning Copilot output and suppressing review noise.
-- [`docs/installation.md`](../../installation.md) — install matrix index.

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

@@ -1,125 +0,0 @@
-# Cursor Setup
-
-Cursor reads two rule formats:
-
-- **Modern (`.mdc`)** — `.cursor/rules/<rule>.mdc` with YAML frontmatter
-  (`description`, `globs`, `alwaysApply`). Preferred for any 2025+
-  Cursor build.
-- **Legacy (`.cursorrules`)** — single-file aggregate at the repo root.
-  Still read by older Cursor versions; the package keeps it for
-  backward compatibility.
-
-The package ships **both** so you don't have to pick.
-
-## Prerequisites
-
-- Cursor 0.45+ (any 2025/2026 build): <https://cursor.com>.
-- Node.js ≥ 18.
-
-## Project install
-
-```bash
-npx @event4u/agent-config init --tools=cursor
-```
-
-This populates:
-
-- `.cursor/rules/*.mdc`     — one file per rule, modern frontmatter format
-- `.cursor/commands/*.md`   — slash commands mirrored from `dist/agent-src/commands/`
-- `.cursorrules`            — legacy single-file aggregate
-- `.agent-settings.yml`     — per-project knobs
-
-Combine surfaces if you use both Cursor and Claude Code:
-
-```bash
-npx @event4u/agent-config init --tools=cursor,claude-code
-```
-
-## Global install
-
-```bash
-npx @event4u/agent-config global --tools=cursor
-```
-
-Seeds `~/.cursor/rules/imported/event4u/` with the curated kernel +
-top-N skills. Cursor merges global + workspace rules — workspace wins
-on conflicts.
-
-## Modern `.mdc` frontmatter
-
-Each `.mdc` file has the Cursor-shaped header:
-
-```mdc
----
-description: Scope control — no unsolicited architectural changes
-globs:
-alwaysApply: true
----
-
-# Scope Control
-...
-```
-
-- `alwaysApply: true` ↔ source `type: "always"` (kernel rules).
-- `alwaysApply: false` ↔ Cursor model decides per turn (auto rules).
-- `globs:` is intentionally empty in the package's projection — apply
-  per-rule if you need path-scoped rules in your fork.
-
-## Cursor commands
-
-`.cursor/commands/<slug>.md` mirrors `.claude/commands/`. Nested
-clusters (e.g. `council/default.md`) flatten to `council-default.md` so
-Cursor's command palette stays flat.
-
-## Marketplace install (planned — Phase 7 / S35)
-
-The Cursor marketplace listing is filed in
-`road-to-simplicity-and-everywhere.md` Phase 7. Once accepted you'll
-be able to install via Cursor's Extensions panel without `npx`.
-
-## MCP block (when MCP Phase 3 ships)
-
-Add to `.cursor/mcp.json` (Cursor's project-scoped MCP config):
-
-```json
-{
-  "mcpServers": {
-    "event4u-agent-config": {
-      "command": "npx",
-      "args": ["-y", "@event4u/agent-config-mcp"]
-    }
-  }
-}
-```
-
-Track <https://github.com/event4u-app/agent-config> for the actual
-release tag — until `road-to-mcp-full-coverage` Phase 3 ships, this
-block is informational.
-
-## Verification
-
-```bash
-ls -la .cursor/rules/   | head -5      # *.mdc files exist
-ls -la .cursor/commands/| head -5      # *.md command files exist
-test -f .cursorrules                   # legacy aggregate exists
-```
-
-In Cursor itself: open the chat panel — settings should show the rules
-under **Project Rules**.
-
-## Troubleshooting
-
-| Symptom | Fix |
-|---|---|
-| Rules not picked up | Cursor < 0.45 — upgrade or rely on `.cursorrules`. |
-| Modern + legacy duplicate triggers | Disable `.cursorrules` in Cursor settings. |
-| Command missing in palette | `task generate-tools` then reload Cursor window. |
-| Global rules ignored | Cursor needs `~/.cursor/rules/` — check OS path expansion. |
-
-## Cross-references
-
-- [`docs/installation.md`](../../installation.md) — install matrix index.
-- [`AGENTS.md`](../../../AGENTS.md) — package self-orientation; Cursor
-  reads it via the projected rules.
-- [`src/templates/cursor-rule.mdc.j2`](../../../templates/cursor-rule.mdc.j2) —
-  template used by the projection generator.