@event4u/agent-config 1.38.0 → 1.40.0

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

@@ -0,0 +1,148 @@
+# 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** — install the package globally with `--global` so the
+> kernel rules and the curated top-N skills land in `~/.claude/`,
+> then restart Claude Desktop. The slash-command menu picks them up
+> automatically.
+
+## Prerequisites
+
+- Claude Desktop installed (free or paid plan — same install path).
+- Node ≥ 18 *or* a clone of the `event4u/agent-config` repo
+  (either route can run `--global`).
+- 5 minutes.
+
+## Step 1 — global install
+
+Pick whichever entrypoint matches your environment. Both seed the same
+files under `~/.claude/`.
+
+```bash
+# Node — no clone needed.
+npx @event4u/create-agent-config --global --tools=claude-code
+
+# Or via curl (no Node).
+curl -fsSL https://raw.githubusercontent.com/event4u/agent-config/main/setup.sh \
+  | bash -s -- --global --tools=claude-code
+
+# Or from a local clone.
+bash scripts/install --global --tools=claude-code
+```
+
+> `--tools=claude-code` covers both Claude Code **and** Claude
+> Desktop — the two surfaces share `~/.claude/`. Pass
+> `--tools=claude-code,cursor,windsurf` if you want Cursor / Windsurf
+> globally seeded in the same run.
+
+After the install you'll have:
+
+```
+~/.claude/
+├── rules/event4u/      # 9 kernel rules (Iron-Law set)
+└── skills/event4u/     # 15 curated top-N skills
+```
+
+Curation lives in
+[`templates/global-install-manifest.yml`](../../../templates/global-install-manifest.yml).
+Edit and re-run `--global` to grow or shrink the set.
+
+## Step 2 — verify
+
+1. Restart Claude Desktop (full quit, not just window close).
+2. Open 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".
+
+If the menu is empty:
+
+- Check `ls ~/.claude/skills/event4u/` — should list 15 directories.
+- 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.
+
+## Step 3 — optional MCP server
+
+Claude Desktop also speaks MCP. Wiring up the hosted `agent-config-mcp`
+Worker exposes the **full** skill / rule / command catalog (~480 items)
+on demand, on top of the 15 you installed in Step 1.
+
+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://agent-config-mcp.event4u.workers.dev"]
+    }
+  }
+}
+```
+
+A pre-wired template ships at
+[`templates/claude_desktop_config.json.template`](../../../templates/claude_desktop_config.json.template) —
+copy + uncomment the MCP block.
+
+Restart Claude Desktop. The 🔌 icon shows the connector under
+**Settings → Connectors**. Full transport details (mcp-remote vs.
+native HTTP) live in
+[`../mcp-client-config.md`](../mcp-client-config.md).
+
+## Claude Desktop ↔ Claude Code config sharing
+
+Both surfaces read **the same `~/.claude/` directory**. Anything you
+install for one is automatically available in the other:
+
+| File / dir                       | Shared by Desktop & Code? |
+| -------------------------------- | ------------------------- |
+| `~/.claude/CLAUDE.md`            | yes — global system prompt |
+| `~/.claude/rules/event4u/`       | yes — installed by `--global` |
+| `~/.claude/skills/event4u/`      | yes — installed by `--global` |
+| `~/.claude/commands/`            | yes — slash commands      |
+| `~/.claude/hooks/`               | yes — lifecycle hooks     |
+| `claude_desktop_config.json`     | Desktop only (MCP)        |
+| `~/.claude.json` (CLI config)    | Code only                 |
+
+Translation: run `--global` once, both clients pick the files up.
+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:
+
+- 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.
+- Cowork-specific limit (per Anthropic docs): MCP tools that write to
+  the local filesystem are sandboxed — read-only tools (the entire
+  hosted `agent-config-mcp` 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
+
+```bash
+bash scripts/install --global --uninstall --tools=claude-code
+```
+
+Removes only `~/.claude/{rules,skills}/event4u/`. Anything you added
+under sibling paths (custom rules, your own slash commands) stays.
+
+## See also
+
+- Project-local install — [`../../installation.md`](../../installation.md)
+- Global install reference — [`../../installation.md#global-user-level-install---global`](../../installation.md#global-user-level-install---global)
+- MCP client transports — [`../mcp-client-config.md`](../mcp-client-config.md)
+- Curation manifest — [`../../../templates/global-install-manifest.yml`](../../../templates/global-install-manifest.yml)

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

@@ -0,0 +1,43 @@
+# 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/create-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/create-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/codex.md

@@ -0,0 +1,46 @@
+# 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/create-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/copilot.md

@@ -0,0 +1,80 @@
+# 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/create-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/create-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

@@ -0,0 +1,125 @@
+# 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/create-agent-config init --tools=cursor
+```
+
+This populates:
+
+- `.cursor/rules/*.mdc`     — one file per rule, modern frontmatter format
+- `.cursor/commands/*.md`   — slash commands mirrored from `.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/create-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.
+- [`templates/cursor-rule.mdc.j2`](../../../templates/cursor-rule.mdc.j2) —
+  template used by the projection generator.

package/docs/setup/per-ide/gemini-cli.md

@@ -0,0 +1,45 @@
+# Gemini CLI Setup
+
+Google's Gemini CLI reads `GEMINI.md` (which is a symlink to `AGENTS.md`
+in the package's projection) for project context.
+
+## Prerequisites
+
+- Gemini CLI installed: <https://github.com/google-gemini/gemini-cli>.
+- Node.js ≥ 18 (for the install entrypoints).
+
+## Install
+
+```bash
+npx @event4u/create-agent-config init --tools=gemini
+```
+
+Populates:
+
+- `GEMINI.md` → `AGENTS.md` — symlink so Gemini CLI loads the same
+  self-orientation as Codex / Aider / Augment.
+- `AGENTS.md`             — canonical content (single source of truth).
+- `.agent-settings.yml`   — per-project knobs.
+
+## Verification
+
+```bash
+test -L GEMINI.md && readlink GEMINI.md   # → AGENTS.md
+gemini --version                           # confirm CLI installed
+```
+
+In a Gemini CLI session: `GEMINI.md` informs every turn — verify by
+asking *"what is this repo?"* and confirming the answer matches
+`AGENTS.md`'s emergency-triage block.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| Gemini CLI doesn't see `GEMINI.md` | Some Gemini versions require absolute paths — `gemini --context $(pwd)/GEMINI.md`. |
+| Symlink broken on Windows | Re-run installer; on Windows the projection may emit a copy instead of a symlink. |
+
+## Cross-references
+
+- [`AGENTS.md`](../../../AGENTS.md) — canonical agent self-orientation.
+- [`docs/installation.md`](../../installation.md) — install matrix index.

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

@@ -0,0 +1,120 @@
+# Windsurf Setup
+
+Windsurf reads two rule formats:
+
+- **Wave-8 (`.windsurf/rules/`)** — per-rule `.md` files with
+  `trigger`, `description`, `globs` frontmatter. Preferred for
+  Windsurf 1.5+.
+- **Legacy (`.windsurfrules`)** — single-file aggregate at the repo
+  root. Older Windsurf builds and the Cascade chat fallback both still
+  read it.
+
+The package ships **both**.
+
+## Prerequisites
+
+- Windsurf 1.0+ (Codeium): <https://codeium.com/windsurf>.
+- Node.js ≥ 18.
+
+## Project install
+
+```bash
+npx @event4u/create-agent-config init --tools=windsurf
+```
+
+Populates:
+
+- `.windsurf/rules/*.md`        — modern Wave-8 per-rule files
+- `.windsurf/workflows/*.md`    — slash-command workflows
+- `.windsurfrules`              — legacy single-file aggregate
+- `.agent-settings.yml`         — per-project knobs
+
+Combine with other surfaces:
+
+```bash
+npx @event4u/create-agent-config init --tools=windsurf,claude-code,cursor
+```
+
+## Global install
+
+```bash
+npx @event4u/agent-config global --tools=windsurf
+```
+
+Seeds `~/.codeium/windsurf/global_workflows/` with the curated
+workflow set (see [`templates/global-install-manifest.yml`](../../../templates/global-install-manifest.yml)).
+Available across every project; per-workspace `.windsurf/workflows/`
+takes precedence on slug collisions.
+
+## Wave-8 frontmatter
+
+Each rule under `.windsurf/rules/` has the Windsurf-shaped header:
+
+```md
+---
+trigger: always_on
+description: Scope control — no unsolicited architectural changes
+globs:
+---
+
+# Scope Control
+...
+```
+
+- `trigger: always_on` ↔ source `type: "always"` (kernel rules).
+- `trigger: model_decision` ↔ Cascade decides per turn (auto rules).
+- `globs:` is intentionally empty in the package's projection — set
+  per-rule in your fork if you want path-scoped triggering.
+
+## Workflows
+
+`.windsurf/workflows/<slug>.md` mirrors `.claude/commands/`. Cluster
+commands flatten to `<cluster>-<name>.md`. Cascade lists all workflow
+files in its workflow palette.
+
+## Cascade integration
+
+Cascade (Windsurf's built-in agent) reads `.windsurf/rules/` and
+`.windsurf/workflows/` automatically. No separate registration step is
+needed once the files are on disk.
+
+When Cascade asks a clarifying question, the package's `user-interaction`
+rule (kernel, `always_on`) applies — Cascade will surface numbered
+options with a single recommendation.
+
+## Workspace vs global precedence
+
+| Layer | Path | Precedence |
+|---|---|---|
+| Workspace | `.windsurf/rules/` + `.windsurf/workflows/` | wins on conflicts |
+| Global | `~/.codeium/windsurf/global_workflows/` | falls back when workspace silent |
+
+Reuse the same `--tools=windsurf` flag for both — `init` writes
+workspace, `global` writes user-level.
+
+## Verification
+
+```bash
+ls .windsurf/rules/     | head -5      # *.md per-rule files
+ls .windsurf/workflows/ | head -5      # *.md workflow files
+test -f .windsurfrules                 # legacy aggregate exists
+```
+
+In Windsurf itself: open Cascade → Workflows panel — listed workflows
+should match `ls .windsurf/workflows/`.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| Rules not picked up | Windsurf < 1.0 — upgrade or rely on `.windsurfrules`. |
+| Workflow not in Cascade panel | Reload window after `task generate-tools`. |
+| Global workflows missing | Check `~/.codeium/windsurf/global_workflows/` exists. |
+| Frontmatter parse error | Re-run `python3 scripts/compress.py --generate-tools`. |
+
+## Cross-references
+
+- [`docs/installation.md`](../../installation.md) — install matrix index.
+- [`templates/windsurf-rule.md.j2`](../../../templates/windsurf-rule.md.j2)
+  — template used by the projection generator.
+- [`AGENTS.md`](../../../AGENTS.md) — package self-orientation.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "1.38.0",
+    "version": "1.40.0",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,