@event4u/agent-config 1.39.0 → 1.40.0

package/docs/contracts/orchestration-dsl-v1.md

@@ -0,0 +1,152 @@
+---
+stability: beta
+---
+
+# Orchestration DSL v1
+
+**Purpose.** Pin the YAML schema that the `/orchestrate` command
+reads to chain personas / skills / sub-agents into reproducible
+pipelines. A pipeline file is a deterministic, reviewable artifact
+that re-runs the same step sequence with the same inputs.
+
+**Scope.** Defines the file location, top-level shape, step kinds,
+input / output wiring, and the linter contract. Does **not** define
+the runtime semantics of each step kind — those live in the
+[`/orchestrate`](../../.agent-src.uncompressed/commands/orchestrate.md)
+command and the `work_engine` directive modules it delegates to.
+
+Last refreshed: 2026-05-11.
+
+## File location
+
+```
+.agent-config/orchestrations/<name>.yaml
+```
+
+`<name>` is kebab-case, matches the `name` field inside the file,
+and is unique across the consumer project's orchestrations directory.
+The directory is opt-in — `/orchestrate` falls back to the prompt
+when no file exists.
+
+## Top-level shape
+
+```yaml
+schema_version: 1
+name: pr-readiness-check
+description: |
+  Run the four review-lens judges against the current diff, then
+  consolidate verdicts into a single Markdown report.
+inputs:
+  - id: diff_target
+    description: Git ref to diff against. Default origin/main.
+    default: origin/main
+steps:
+  - id: bug
+    kind: skill
+    ref: judge-bug-hunter
+    with:
+      diff_target: ${{ inputs.diff_target }}
+  - id: security
+    kind: skill
+    ref: judge-security-auditor
+    with:
+      diff_target: ${{ inputs.diff_target }}
+  - id: tests
+    kind: skill
+    ref: judge-test-coverage
+    with:
+      diff_target: ${{ inputs.diff_target }}
+  - id: quality
+    kind: skill
+    ref: judge-code-quality
+    with:
+      diff_target: ${{ inputs.diff_target }}
+  - id: consolidate
+    kind: command
+    ref: review-changes
+    with:
+      verdicts:
+        - ${{ steps.bug.output }}
+        - ${{ steps.security.output }}
+        - ${{ steps.tests.output }}
+        - ${{ steps.quality.output }}
+outputs:
+  report: ${{ steps.consolidate.output }}
+```
+
+## Field semantics
+
+| Field | Type | Required | Meaning |
+|---|---|---|---|
+| `schema_version` | int | yes | Always `1`. Major bump on breaking changes. |
+| `name` | string | yes | Kebab-case identifier; matches filename. |
+| `description` | string | yes | One-paragraph statement of intent. |
+| `inputs[]` | list | no | Named pipeline inputs. Each has `id`, `description`, optional `default`. |
+| `steps[]` | list | yes | Ordered list of steps. Min 1, max 32. |
+| `steps[].id` | string | yes | Snake-case identifier; unique within the pipeline. |
+| `steps[].kind` | enum | yes | One of `skill` · `command` · `persona` · `subagent`. |
+| `steps[].ref` | string | yes | Reference id matching the `kind` namespace. |
+| `steps[].with` | map | no | Inputs to the step. Values MAY use `${{ inputs.X }}` / `${{ steps.Y.output }}` interpolation. |
+| `steps[].when` | string | no | Conditional expression — runs the step only if truthy. Limited to `${{ steps.X.output }}` equality and `success` / `failure` predicates. |
+| `outputs` | map | no | Named pipeline outputs. Surfaced in the final delivery report. |
+
+## Step kinds
+
+| `kind` | `ref` resolves to | Runtime |
+|---|---|---|
+| `skill` | `.agent-src.uncompressed/skills/<ref>/SKILL.md` | Dispatched via `work_engine` directive matching the skill's domain. |
+| `command` | `.agent-src.uncompressed/commands/<ref>.md` | Same dispatch path the slash-command takes when typed by the user. |
+| `persona` | `.agent-src.uncompressed/personas/<ref>.md` | Sets `roles.active_role` for the next dependent step; does not produce its own output. |
+| `subagent` | `subagent-orchestration` mode name | Spawned per [`subagent-orchestration`](../../.agent-src.uncompressed/skills/subagent-orchestration/SKILL.md). |
+
+## Interpolation
+
+Two namespaces only:
+
+```
+${{ inputs.<input-id> }}
+${{ steps.<step-id>.output }}
+```
+
+Unknown namespaces hard-fail at lint time. The interpolation engine
+does string substitution — there are no expressions, no arithmetic,
+no shell-out.
+
+## Linter contract
+
+`scripts/lint_orchestration_dsl.py` hard-fails on:
+
+- missing or malformed top-level keys (`schema_version`, `name`,
+  `description`, `steps`)
+- `schema_version != 1`
+- `name` not matching `[a-z][a-z0-9-]*` or not matching the filename
+- duplicate `steps[].id`
+- `steps[].kind` outside the enum
+- `steps[].ref` pointing at a non-existent skill / command / persona
+- `${{ ... }}` reference to an unknown input or step id
+- `steps[]` length > 32 or < 1
+- `outputs` referencing an unknown step
+
+Exit codes mirror [`lint_hook_manifest.py`](../../scripts/lint_hook_manifest.py): `0` clean, `1` failure, `2` schema-load error.
+
+## Privacy floor
+
+Pipeline files are committed artifacts. They MUST NOT contain:
+
+- Secrets, tokens, environment values.
+- Conversation bodies or transcripts.
+- File contents (only paths and refs).
+
+## Stability
+
+Beta. Breaking changes between v1 and v2 are allowed in a minor
+release if the change appears in `CHANGELOG.md` under a `### Breaking`
+heading. Engines MUST gate on `schema_version` and refuse unknown
+majors.
+
+## Cross-references
+
+- Command surface: [`/orchestrate`](../../.agent-src.uncompressed/commands/orchestrate.md).
+- Linter: [`lint_orchestration_dsl.py`](../../scripts/lint_orchestration_dsl.py).
+- Runtime dispatcher precedent: [`implement-ticket-flow.md`](implement-ticket-flow.md).
+- Subagent runtime: [`subagent-orchestration`](../../.agent-src.uncompressed/skills/subagent-orchestration/SKILL.md).

package/docs/getting-started.md

@@ -153,7 +153,7 @@ Your agent now understands slash commands:
 | `/quality-fix` | Run and fix all quality checks |
 | `/chat-history` | Inspect the persistent chat-history log (read-only `show`) |
 
-→ [Browse all 104 active commands](../.agent-src/commands/)
+→ [Browse all 105 active commands](../.agent-src/commands/)
 
 ---
 

package/docs/installation.md

@@ -3,6 +3,41 @@
 **Principle:** Project-installed by default, plugin-enhanced when available.
 No Task, no Make, no build tools required for installation.
 
+## Per-IDE setup — quick index
+
+Pick your editor, follow the linked page, done. Each page lists its
+own one-liner, verification, and troubleshooting. The mechanisms
+section below this index is reference material for advanced installs
+(Composer, npm, manual, plugin marketplaces).
+
+| Surface | One-liner | Per-IDE page |
+|---|---|---|
+| **Claude Code** | `npx @event4u/create-agent-config init --tools=claude-code` | [`per-ide/claude-code.md`](setup/per-ide/claude-code.md) |
+| **Claude Desktop** | (uses `~/.claude/skills/` from Claude Code global install) | [`per-ide/claude-desktop.md`](setup/per-ide/claude-desktop.md) |
+| **Cursor** | `npx @event4u/create-agent-config init --tools=cursor` | [`per-ide/cursor.md`](setup/per-ide/cursor.md) |
+| **Windsurf** | `npx @event4u/create-agent-config init --tools=windsurf` | [`per-ide/windsurf.md`](setup/per-ide/windsurf.md) |
+| **Cline** | `npx @event4u/create-agent-config init --tools=cline` | [`per-ide/cline.md`](setup/per-ide/cline.md) |
+| **Aider** | `npx @event4u/create-agent-config init --tools=aider` | [`per-ide/aider.md`](setup/per-ide/aider.md) |
+| **Codex CLI** | `npx @event4u/create-agent-config init --tools=codex` | [`per-ide/codex.md`](setup/per-ide/codex.md) |
+| **Gemini CLI** | `npx @event4u/create-agent-config init --tools=gemini` | [`per-ide/gemini-cli.md`](setup/per-ide/gemini-cli.md) |
+| **GitHub Copilot** | `npx @event4u/create-agent-config init --tools=copilot` | [`per-ide/copilot.md`](setup/per-ide/copilot.md) |
+| **All surfaces** | `npx @event4u/create-agent-config init` (default) | (each page above applies) |
+
+Combine surfaces by comma-separating: `--tools=claude-code,cursor,windsurf`.
+
+> Looking for **global** (cross-project) install? Each per-IDE page
+> documents its own `npx @event4u/agent-config global --tools=<ide>`
+> command.
+
+---
+
+## Mechanisms reference
+
+The rest of this page documents the underlying install mechanisms
+(Composer, npm, manual clone, plugin marketplaces). Most users want
+the per-IDE index above.
+
+
 > **Primary installer:** `scripts/install` — a small bash orchestrator that
 > runs the two real installer stages in order:
 >
@@ -42,6 +77,63 @@ No Task, no Make, no build tools required for installation.
 
 ---
 
+## Quickstart — one-liner entrypoints
+
+Try `@event4u/agent-config` in any directory in under 30 seconds, without
+`composer require` or `git clone` first. Both entrypoints are thin
+wrappers around `scripts/install` — same payload, same flags, no extra
+state.
+
+### `npx` (Node ≥ 18)
+
+```bash
+# Pick tools interactively (TTY checkbox prompt)
+npx @event4u/create-agent-config init
+
+# Pick tools explicitly, non-interactive
+npx @event4u/create-agent-config init --tools=claude-code,cursor --yes
+
+# Install everything (the default — backward-compatible)
+npx @event4u/create-agent-config init --tools=all --yes
+
+# Test a specific git ref (branch, tag, sha) instead of the latest npm tag
+npx @event4u/create-agent-config init --ref=main --yes
+```
+
+The `@event4u/create-agent-config` package is a thin wrapper: it
+downloads the latest `@event4u/agent-config` tarball into a temp
+directory, runs `bash scripts/install --target <cwd> ...`, and cleans
+up after itself. The project-local payload package
+(`@event4u/agent-config`) is unchanged.
+
+### `curl | bash` (no Node required)
+
+```bash
+# Defaults (interactive picker if your terminal is a TTY, else --tools=all)
+curl -sSL https://raw.githubusercontent.com/event4u-app/agent-config/main/setup.sh | bash
+
+# Explicit tools, non-interactive (same flags as scripts/install)
+curl -sSL https://raw.githubusercontent.com/event4u-app/agent-config/main/setup.sh \
+  | bash -s -- --tools=claude-code,cursor --yes
+
+# Install from a specific git ref
+curl -sSL https://raw.githubusercontent.com/event4u-app/agent-config/main/setup.sh \
+  | bash -s -- --ref=v1.39.0 --tools=cursor --yes
+```
+
+Requires `bash`, `tar`, `curl` (or `wget`), and Python ≥ 3.10 on the
+host. Mirrors the agent-os `setup.sh` pattern.
+
+### Interactive `--tools` picker
+
+When `scripts/install` runs without an explicit `--tools` flag in an
+interactive terminal (stdin + stdout both TTYs, `--yes` not passed), it
+prompts for a comma-separated tool selection. In CI / piped invocations
+the picker is skipped and the backward-compatible `all` default is
+used. Pass `--yes` (or `-y`) to force non-interactive mode anywhere.
+
+---
+
 ## Project-installed mode (recommended for teams)
 
 Install once in the project — available to everyone working on it.
@@ -426,6 +518,8 @@ Options:
   --quiet           Suppress non-error output
   --skip-sync       Skip payload sync (install.sh)
   --skip-bridges    Skip bridge files (install.py)
+  --global          Ship kernel rules + curated skills to user-scope dirs
+  --uninstall       With --global: remove the event4u/ namespace dir
   --help, -h        Show this help
 ```
 
@@ -434,6 +528,44 @@ The underlying stages keep their own CLI surfaces:
 
 ---
 
+## Global user-level install (`--global`)
+
+`--global` ships a curated subset of kernel rules + top-N skills into
+**per-tool user-scope directories**, so the agent has them in every
+project on the machine without a per-project install.
+
+```bash
+# Default: every supported surface, namespaced under event4u/.
+bash scripts/install --global
+
+# Scope to specific surfaces (mirrors the project install --tools flag).
+bash scripts/install --global --tools=claude-code,cursor
+
+# Remove only what we put there — never touches user files.
+bash scripts/install --global --uninstall
+```
+
+| Surface       | Target directory                                                |
+| ------------- | --------------------------------------------------------------- |
+| Claude Code   | `~/.claude/rules/event4u/`, `~/.claude/skills/event4u/`         |
+| Cursor        | `~/.cursor/rules/imported/event4u/{rules,skills}/`              |
+| Windsurf      | `~/.codeium/windsurf/global_workflows/event4u/{rules,skills}/`  |
+| Fallback      | `~/.config/agent-config/{rules,skills}/event4u/`                |
+
+The fallback path is always written so an editor we don't yet know
+about can still pick the files up.
+
+**Curation source:** `templates/global-install-manifest.yml`. Edit
+post-install to grow or shrink the global set; re-run `--global` to
+re-project. `--uninstall` only removes the `event4u/` namespace —
+user-added rules / skills under sibling paths stay untouched.
+
+**When to use:** running multiple unrelated projects where a per-project
+install is overkill, or wiring up a new editor (Claude Desktop, Cursor)
+that benefits from a baseline set of skills out of the box.
+
+---
+
 ## Updating
 
 When a new version of the package is published:

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

@@ -0,0 +1,48 @@
+# Aider Setup
+
+Aider reads `AGENTS.md` (and the legacy `CONVENTIONS.md` if present)
+from the repo root for project conventions.
+
+## Prerequisites
+
+- Aider installed: <https://aider.chat>.
+- Node.js ≥ 18 (for the install entrypoints).
+
+## Install
+
+```bash
+npx @event4u/create-agent-config init --tools=aider
+```
+
+Populates:
+
+- `AGENTS.md`             — agent self-orientation (Aider auto-loads)
+- `.agent-settings.yml`   — per-project knobs
+
+Aider's chat will read `AGENTS.md` on every session start. Add it to
+the chat explicitly if Aider doesn't pick it up:
+
+```bash
+aider AGENTS.md
+```
+
+## Verification
+
+```bash
+test -f AGENTS.md
+```
+
+In Aider: type `/tokens` — `AGENTS.md` should appear in the loaded
+files list.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `AGENTS.md` not auto-loaded | `aider --read AGENTS.md` or `/read AGENTS.md`. |
+| Conventions ignored | Aider reads `CONVENTIONS.md` legacy too — check `--auto-commits` flag. |
+
+## Cross-references
+
+- [`AGENTS.md`](../../../AGENTS.md) — canonical agent self-orientation.
+- [`docs/installation.md`](../../installation.md) — install matrix index.

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

@@ -0,0 +1,108 @@
+# Claude Code Setup
+
+Claude Code is the canonical agent surface for `event4u/agent-config`. It
+reads from `.claude/skills/`, `.claude/commands/`, `CLAUDE.md`,
+`.claude/hooks/`, and project-level MCP servers. Everything in this repo
+projects to those paths during install.
+
+## Prerequisites
+
+- Claude Code installed (CLI or VS Code extension): <https://claude.com/code>.
+- Node.js ≥ 18 (for the `npx` entrypoints).
+- Git working tree (the package is repository-aware).
+
+## Project install (recommended)
+
+```bash
+# Inside an existing repo:
+npx @event4u/create-agent-config init --tools=claude-code
+
+# Or with the curl entrypoint:
+curl -sSL https://raw.githubusercontent.com/event4u-app/agent-config/main/setup.sh \
+  | bash -s -- --tools=claude-code
+```
+
+Either form populates:
+
+- `.claude/skills/`         — symlinks into `.agent-src/skills/`
+- `.claude/commands/`       — symlinks into `.agent-src/commands/`
+- `CLAUDE.md`               — agent root pointer (auto-loaded by Claude Code)
+- `.agent-settings.yml`     — your per-project knobs (kept out of git)
+
+## Global install (cross-project skills)
+
+```bash
+npx @event4u/agent-config global --tools=claude-code
+```
+
+Seeds `~/.claude/skills/` with the curated top-N skills from
+[`templates/global-install-manifest.yml`](../../../templates/global-install-manifest.yml).
+Available across every project on the machine; project-level files
+always take precedence.
+
+Uninstall:
+
+```bash
+npx @event4u/agent-config global --uninstall
+```
+
+## Plugin marketplace (Claude Code 2026+)
+
+Claude Code 2026 supports plugin marketplaces via
+`.claude-plugin/marketplace.json`. The package ships one — once
+listed at the Anthropic marketplace (Phase 7 / S34) you can also:
+
+```bash
+claude plugin install event4u/agent-config
+```
+
+Today the npm/curl entrypoints above are the supported install path.
+
+## CLAUDE.md
+
+Auto-loaded by Claude Code from the repo root. The package's `CLAUDE.md`
+points to `AGENTS.md` (single source of truth for all agent surfaces);
+edit `AGENTS.md`, never `CLAUDE.md`.
+
+## Hooks
+
+Claude Code reads `.claude/hooks/` for pre/post tool hooks. The package
+ships a memory-extraction hook (Phase 7 of `road-to-mcp-full-coverage`).
+Local overrides go in `agents/overrides/.claude/hooks/`.
+
+## Skills you'll use most
+
+- `/work "<prompt>"` — refine → plan → implement → verify → report loop.
+- `/commit` — Conventional-Commit splitter with confirmation gate.
+- `/create-pr` — opens a structured PR from the current branch.
+- `/review-changes` — five-judge self-review before requesting human review.
+- `/agent-handoff` — produces a fresh-chat continuation summary.
+
+Full list: `ls .claude/skills/`.
+
+## Verification
+
+```bash
+ls -la .claude/skills/        # should symlink into .agent-src/skills/
+ls -la CLAUDE.md              # exists, points to AGENTS.md
+test -f .agent-settings.yml   # per-project settings rendered
+```
+
+In Claude Code itself: type `/` — the slash menu should list `work`,
+`commit`, `create-pr`, etc.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `/` menu empty | `ls .claude/skills/` — re-run installer if empty. |
+| Skills look stale after `git pull` | `task sync && task generate-tools`. |
+| Hook never fires | `claude --debug` and inspect hook output. |
+| Memory MCP missing | See `road-to-mcp-full-coverage` — Phase 3 ships read-only tools. |
+
+## Cross-references
+
+- [`docs/installation.md`](../../installation.md) — install matrix index.
+- [`docs/setup/per-ide/claude-desktop.md`](claude-desktop.md) — Desktop +
+  Cowork share the same `~/.claude/skills/` path; install once, both surfaces benefit.
+- [`AGENTS.md`](../../../AGENTS.md) — package self-orientation.

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.