@event4u/agent-config 1.38.0 → 1.40.0

package/docs/customization.md

@@ -42,6 +42,51 @@ The `.agent-settings.yml` file in the consumer project configures agent behavior
 It is written as YAML with section-level grouping; dotted keys below reference
 those sections.
 
+### User-global DX-comfort defaults (cross-project)
+
+Six **DX-comfort** keys can be carried across every project that uses
+`event4u/agent-config` by storing them once in a user-global file at:
+
+```
+~/.config/agent-config/agent-settings.yml
+```
+
+The path is XDG-style and matches the existing
+`~/.config/agent-config/` directory used for `anthropic.key`,
+`openai.key`, and `council-spend.jsonl`.
+
+**Whitelist (locked, exact dotted paths)** — only these six keys are
+mergeable from the user-global file; every other key is silently ignored:
+
+```
+name
+ide
+cost_profile
+personal.bot_icon
+personal.autonomy
+caveman.speak_scope
+```
+
+**Merge order** (lowest → highest precedence):
+
+```
+1. Package defaults                                   (shipped by event4u/agent-config)
+2. ~/.config/agent-config/agent-settings.yml          (user-global · whitelist-filtered)
+3. <project>/.agent-settings.yml                      (project-local · always wins)
+```
+
+Project-local values **always win**. The user-global file is a
+fallback, never a lock. Non-whitelisted keys in the user-global file
+are dropped without error — adding `personal.theme` there has no
+effect.
+
+The file is created **only on explicit opt-in via `/onboard`**. The
+loader at [`scripts/_lib/agent_settings.py`](../scripts/_lib/agent_settings.py)
+is **read-only** — no script can create or mutate it without an
+explicit `/onboard` confirmation. Edit the file by hand for mid-life
+changes; `/sync-agent-settings` stays project-scoped and never touches
+user-global state.
+
 ### Available settings
 
 | Setting | Default | Description |

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/guidelines/agent-infra/layered-settings.md

@@ -1,37 +1,74 @@
 # Layered Settings
 
-Two-file settings model: **team defaults** (committed) and
-**developer overrides** (git-ignored). Lets a project pin decisions
-without forcing every developer to work the same way.
+Three-file settings model: **team defaults** (committed),
+**user-global DX-comfort defaults** (per-developer, cross-project), and
+**developer overrides** (per-project, git-ignored). Lets a project pin
+decisions, a developer carry DX preferences across every project, and
+project-local choices always win.
 
-Referenced by `road-to-project-memory.md` Phase 0. Consumed by the
-settings loader, the `/onboard` command, and any agent that edits
-`.agent-settings.yml` on user request.
+Referenced by `road-to-project-memory.md` Phase 0 and
+`road-to-portable-dev-preferences.md`. Consumed by the centralized
+settings loader at
+[`scripts/_lib/agent_settings.py`](../../../scripts/_lib/agent_settings.py),
+the `/onboard` command, and any agent that edits `.agent-settings.yml`
+on user request.
 
-## The two files
+## The three files
 
 | File | Git | Scope | Owner | Example values |
 |---|---|---|---|---|
 | `.agent-project-settings.yml` | **committed** | team / repo | lead maintainer | `project.stack`, `quality.php.tools`, `memory.dogfood` |
-| `.agent-settings.yml` | **gitignored** | developer workstation | individual | `personal.ide`, `personal.user_name`, `subagents.max_parallel` |
+| `~/.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` |
+| `.agent-settings.yml` | **gitignored** | individual developer · this project | individual | `personal.ide`, `personal.user_name`, `subagents.max_parallel`, `onboarding.onboarded` |
 
-Both are YAML. Schema is documented in
-[`agent-settings.md`](../../templates/agent-settings.md) (dev layer)
-and [`agent-project-settings.example.yml`](../../templates/agents/agent-project-settings.example.yml)
-(team layer).
+All three are YAML. Schemas:
+
+- Developer (project-local): [`agent-settings.md`](../../templates/agent-settings.md).
+- Team: [`agent-project-settings.example.yml`](../../templates/agents/agent-project-settings.example.yml).
+- User-global: six exact dotted paths — whitelist in
+  [`scripts/_lib/agent_settings.py`](../../../scripts/_lib/agent_settings.py).
 
 ## Merge order
 
 Lowest priority → highest priority:
 
 ```
-1. Package defaults       (shipped by event4u/agent-config)
-2. .agent-project-settings.yml   (team file, committed)
-3. .agent-settings.yml           (developer file, gitignored)
+1. Package defaults                                   (shipped by event4u/agent-config)
+2. ~/.config/agent-config/agent-settings.yml          (user-global · whitelist-filtered)
+3. .agent-project-settings.yml                        (team file, committed)
+4. .agent-settings.yml                                (developer file, gitignored)
+```
+
+Keys from higher layers win unless a lower layer marks them
+`locked` (team file only). The user-global file does **not** support
+`locked` — its purpose is cross-project comfort, never policy.
+
+## User-global whitelist
+
+Only these exact dotted paths are mergeable from the user-global file;
+every other key is silently dropped by the loader. The whitelist is
+intentionally tiny — adding a key requires an ADR.
+
+```
+name
+ide
+cost_profile
+personal.bot_icon
+personal.autonomy
+caveman.speak_scope
 ```
 
-Keys from higher layers win unless the lower layer marks them
-`locked`. Locked keys cannot be shadowed by a higher layer.
+Loader contract:
+
+- **Read-only.** The loader never creates, modifies, or deletes the
+  user-global file. Writes are the exclusive responsibility of the
+  `/onboard` command on explicit user opt-in.
+- **Tolerant.** Missing file, malformed YAML, empty file — all fall
+  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.
 
 ## Lock semantics
 

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/mcp-client-config.md

@@ -0,0 +1,152 @@
+# MCP Client Config — Remote agent-config
+
+Connect any MCP-capable client to the hosted `agent-config-mcp` Worker
+at `https://agent-config-mcp.event4u.workers.dev`. Read-only,
+identity-stable per release, no auth.
+
+For URL shapes (latest vs. pinned `/v<X.Y.Z>`) see
+[`mcp-cloud-endpoints.md`](mcp-cloud-endpoints.md). For operator
+setup of your own deployment see [`mcp-cloud-setup.md`](mcp-cloud-setup.md).
+
+## Transport note
+
+The Worker speaks JSON-RPC over HTTP POST. Clients that support
+HTTP transport natively (Claude Code, Cursor) talk to it directly.
+Clients that only support stdio (Claude Desktop, Zed) need the
+[`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge from
+npm — invoked via `npx`, no install required.
+
+## Where settings live — `.agent-settings.yml` vs. MCP config
+
+These are **two different files** for two different layers. Don't
+look for MCP server config inside `.agent-settings.yml`.
+
+| File | Where | Who reads it | Purpose |
+|---|---|---|---|
+| MCP client config (this page) | client-specific path per section above | the MCP client at startup | which MCP servers to talk to (name + URL / command) |
+| `.agent-settings.yml` | consumer project root (`<repo>/.agent-settings.yml`) | the agent at runtime (Claude / Cursor / …) | per-developer preferences: `name`, `ide`, `cost_profile`, `personal.autonomy`, `pipelines.skill_improvement`, `caveman.speak_scope`, … |
+
+The hosted MCP is **stateless** and **project-agnostic** — it serves
+the same skill / rule / command catalog to every client. Personalization
+happens agent-side after the MCP delivers its content blob; the Worker
+itself does not read `.agent-settings.yml`.
+
+First-time setup of `.agent-settings.yml` runs through `/onboard`;
+template drift is handled by `/sync-agent-settings`.
+
+## Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
+(macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "agent-config": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://agent-config-mcp.event4u.workers.dev"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The connector appears in the dropdown.
+
+Newer builds also support **Settings → Connectors → Add Custom
+Connector** with the URL directly — no `mcp-remote` wrapper needed.
+
+## Claude Code
+
+Native HTTP transport — one command:
+
+```bash
+claude mcp add --transport http agent-config https://agent-config-mcp.event4u.workers.dev
+```
+
+Verify:
+
+```bash
+claude mcp list
+```
+
+## Cursor
+
+`~/.cursor/mcp.json` (global) or `<repo>/.cursor/mcp.json`
+(project-local):
+
+```json
+{
+  "mcpServers": {
+    "agent-config": {
+      "url": "https://agent-config-mcp.event4u.workers.dev"
+    }
+  }
+}
+```
+
+Reload Cursor (`Cmd+Shift+P → Reload Window`).
+
+## Zed
+
+`~/.config/zed/settings.json`:
+
+```json
+{
+  "context_servers": {
+    "agent-config": {
+      "source": "custom",
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://agent-config-mcp.event4u.workers.dev"]
+    }
+  }
+}
+```
+
+Zed has no native remote-MCP transport yet, so the `mcp-remote`
+bridge is required.
+
+## Continue
+
+`~/.continue/config.yaml` (or `<repo>/.continue/config.yaml`):
+
+```yaml
+mcpServers:
+  - name: agent-config
+    command: npx
+    args: ["-y", "mcp-remote", "https://agent-config-mcp.event4u.workers.dev"]
+```
+
+## Verify
+
+After reload, every client should:
+
+1. List `agent-config` under connectors / tools with a release-key
+   matching the live deploy. Probe the endpoint to see the current
+   release:
+
+   ```bash
+   curl https://agent-config-mcp.event4u.workers.dev
+   # → { "ok": true, "release_key": "v…", "signature": "…", … }
+   ```
+
+2. Expose skill + command prompts under URIs like `skill://…` and
+   `command://…`.
+3. Expose rule + guideline + context resources under `rule://…`,
+   `guideline://…`, `context://…`.
+
+If the client shows the connector but no prompts / resources,
+re-probe the URL — a 5xx from the Worker indicates the deploy is
+mid-roll, retry after a minute.
+
+## Local stdio alternative
+
+If you have the repo cloned and prefer running the MCP server
+locally (faster startup, no network), the stdio kernel under
+`scripts/mcp_server/` is the same wire surface. Setup:
+`task mcp:setup`, run details in [`../mcp-server.md`](../mcp-server.md).
+
+## See also
+
+- URL shapes & DNS — [`mcp-cloud-endpoints.md`](mcp-cloud-endpoints.md)
+- Operator setup (your own deploy) — [`mcp-cloud-setup.md`](mcp-cloud-setup.md)
+- A0-cloud contract — [`../contracts/mcp-cloud-scope.md`](../contracts/mcp-cloud-scope.md)

package/docs/setup/mcp-cloud-endpoints.md

@@ -10,6 +10,21 @@ by `docs/contracts/mcp-cloud-scope.md` (A0-cloud) and Phase 5.2 of
 shapes below are pinned for the lifetime of the *experimental* window;
 breaking changes require a stability-label bump.
 
+## Scope — Lite surface
+
+The hosted endpoint exposes the **read-only governance surface**
+(skills, commands, rules, guidelines, contexts) as MCP prompts +
+resources. `tools/list` returns two **deprecated stubs**
+(`lint_skills`, `chat_history_append`) that point at their local-stdio
+successors; `tools/call` against either returns `isError=true`. No
+script execution, no FS access, no shell.
+
+Full power — the ~112 Python scripts (linters, audits, `task ci`,
+work-engine hooks) — requires the local install. See
+[`../contracts/mcp-cloud-scope.md`](../contracts/mcp-cloud-scope.md)
+for the execution-safety boundary and the Phase-7-DEFERRED gate that
+governs any future tool restoration.
+
 ## URL shapes (pinned)
 
 Two surfaces, both serve identical wire contracts (JSON-RPC over POST,
@@ -88,6 +103,7 @@ serving on `/latest/`.
 
 ## See also
 
+- Per-client config snippets: [`mcp-client-config.md`](mcp-client-config.md)
 - A0-cloud contract: `docs/contracts/mcp-cloud-scope.md`
 - R2 bootstrap: `docs/setup/mcp-r2-bootstrap.md`
 - Local stdio fallback: `scripts/mcp_server/` (unchanged)

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.