@event4u/agent-config 2.2.1 → 2.3.0

package/.agent-src/rules/external-reference-deep-dive.md

@@ -0,0 +1,69 @@
+---
+type: "auto"
+tier: "2b"
+description: "When the user names an external repo, file, URL, or artifact as a reference — fetch the actual tree and inspect, never summarize from README or metadata"
+alwaysApply: false
+source: package
+triggers:
+  - intent: "look at how X does it"
+  - intent: "compare with reference repo"
+  - intent: "use as template / vorlage"
+  - intent: "wie macht es X"
+  - intent: "vergleiche mit Y"
+  - intent: "schau dir Z an"
+  - intent: "study this competitor"
+  - keyword: "github.com/"
+  - keyword: "source of truth"
+  - phrase: "reference repo"
+---
+
+# external-reference-deep-dive
+
+## The Iron Law
+
+```
+EXTERNAL REFERENCE NAMED → DEEP-DIVE FIRST.
+NO README-ONLY SUMMARIES. NO METADATA GUESSES.
+INSPECT THE TREE, THE FRONTMATTER, THE CONFIGS, THE CODE.
+ABSENCE-OF-EVIDENCE IS NOT EVIDENCE — FETCH BEFORE CLAIMING.
+```
+
+Triggered when the user points to an external artifact (repo URL, `owner/repo`, file path, website, archive) **and** asks to analyze, compare, mirror, use as template, or "see how they do it". The user invested in naming the source — answer from the source, not from the cover.
+
+## Mandatory before drawing any conclusion
+
+1. **Use `/analyze-reference-repo`** (the canonical flow) when the artifact is a repo. Its Steps 2–5 are not optional shortcuts — they are the deep-dive contract: fetch listings (not just README), inspect key directories (`skills/`, `rules/`, `commands/`, `scripts/`, `.github/workflows/`, install configs, frontmatter samples), classify each axis adopt/adapt/reject/already.
+2. **For single files / websites** — fetch the actual content, not a summary. PDFs/DOCX/XLSX → `markitdown` first.
+3. **Cite verbatim** — every finding lands with a file path, line range, or URL fragment. "The README says X" is **not** a finding about implementation; it's a finding about marketing copy.
+4. **Surface what was inspected** — list the files / directories actually fetched, so the user can audit coverage.
+5. **"Not found" beats "probably not there"** — if a fetch budget was hit, say which subtrees are still un-inspected and ask before concluding absence.
+
+## Forbidden patterns
+
+- Reading only the README / homepage / package description and reporting capabilities.
+- Declaring "they don't support X" without listing the directories actually inspected.
+- Repeating a surface-level claim across turns without re-fetching when the user pushes back.
+- Treating `package.json` / `composer.json` keywords as evidence of behavior.
+- Summarizing a competitor's installer story from prose instead of reading `scripts/install*`, `bin/*`, or the npm `bin` field.
+
+## Failure mode catalog
+
+| Pattern | Why it fails | Fix |
+|---|---|---|
+| **README-summary-as-analysis** | Marketing prose ≠ implementation. Capabilities listed there may be aspirational, deprecated, or differently scoped. | Fetch the directory listing + 1–2 representative files per axis. |
+| **"Nothing matches" without enumeration** | Claims absence without proof. The user has to re-prompt to force the real lookup. | Before saying "no X", list the directories scanned. If the budget caps, ask which to expand. |
+| **Repeat-the-guess after pushback** | User says "really look" → agent re-paraphrases the same surface read. Burns trust. | On any pushback that names the source again, restart from a tree listing, not from prior notes. |
+| **Cross-tool path inference from a single example** | One config file ≠ a convention. | Inspect ≥2 unrelated tool integrations before claiming a pattern is the project's universal anchor strategy. |
+
+**Case-zero anchor.** May 2026 — `nextlevelbuilder/ui-ux-pro-max-skill` was named as the source of truth for 23 AI-tool anchors. Three rounds of "we have no content for these tools" were reported from README inference. The actual `tool-configs/*.json` files in the reference repo gave the exact directory layout per tool in one fetch. Cost: ~2 hours of user frustration. Lesson: when an external source is named, the first action is `GET /repos/{o}/{r}/contents/{interesting-subtree}` — not paraphrase.
+
+## Escape hatch
+
+User explicitly fences the scope (*"quick scan only"*, *"just glance at the README"*, *"don't fetch the whole thing"*) → quick-scan path is allowed. Say so up front: *"Quick-scan mode per your scope — README + top-level layout only, not a full analysis."*
+
+## See also
+
+- Command [`/analyze-reference-repo`](../commands/analyze-reference-repo.md) — canonical deep-dive flow.
+- Rule [`think-before-action`](think-before-action.md) — sibling Iron Law for code paths in **this** repo; this rule is its mirror for **external** artifacts.
+- Rule [`ask-when-uncertain`](ask-when-uncertain.md) — when a fetch budget caps, ask which subtree to expand instead of guessing.
+- Skill [`markitdown`](../skills/markitdown/SKILL.md) — convert binary office formats before analysis.

package/.agent-src/templates/copilot-instructions.md

@@ -25,11 +25,18 @@ This repository contains {{project_description_oneline}}.
 > rules, guidelines) and `AGENTS.md`. The instructions below are
 > self-contained for Copilot Code Review.
 >
+> For multi-step workflows (refactors, new features, bug investigations),
+> switch Copilot Chat to **Agent mode** — it can read this file plus
+> `.augment/` and orchestrate tools. **Ask mode** and inline **Edit mode**
+> stay local to the current selection.
+>
 > For most tickets — feature, bug fix, or refactor — start with
 > `/implement-ticket` (see `.augment/commands/implement-ticket.md`). It drives
 > the linear flow `refine → memory → analyze → plan → implement → test →
 > verify → report`, blocks on ambiguity instead of guessing, and never
 > commits, pushes, or opens PRs on its own.
+>
+> See `docs/setup/per-ide/copilot.md` for the full activation guide.
 
 ## ✅ Scope Control
 

package/.claude-plugin/marketplace.json

@@ -6,12 +6,38 @@
   },
   "metadata": {
     "description": "Shared agent configuration \u2014 skills for AI coding tools (Claude Code, Augment, Cursor, Cline, Windsurf, Gemini CLI).",
-    "version": "2.2.1"
+    "version": "2.3.0",
+    "keywords": [
+      "agent-config",
+      "skills",
+      "rules",
+      "claude-code",
+      "augment",
+      "cursor",
+      "cline",
+      "windsurf",
+      "gemini",
+      "copilot",
+      "laravel",
+      "php",
+      "ai-coding"
+    ]
   },
   "plugins": [
     {
       "name": "agent-config",
       "description": "Full skill catalog \u2014 writing, reviewing, managing, and analyzing agent content, plus stack-specific skills for Laravel, PHP, Docker, AWS, Playwright, and more.",
+      "keywords": [
+        "skills",
+        "rules",
+        "commands",
+        "laravel",
+        "php",
+        "review",
+        "testing",
+        "infrastructure",
+        "documentation"
+      ],
       "source": "./",
       "strict": false,
       "skills": [

package/CHANGELOG.md

@@ -343,6 +343,63 @@ our recommendation order, not its support status.
   users" tension without removing any path that an existing user
   might rely on.
 
+## [2.3.0](https://github.com/event4u-app/agent-config/compare/2.2.2...2.3.0) (2026-05-13)
+
+### Features
+
+* **prune:** add --resume-uninstall for focused crash recovery ([1c98454](https://github.com/event4u-app/agent-config/commit/1c9845404f1e629f802494c732f7438aa4335c8e))
+* **dev:** add dev:install-global and dev:link tasks for local development ([db4bdc9](https://github.com/event4u-app/agent-config/commit/db4bdc9794752791bb93235cc9cc3179df9b88df))
+* **install:** manifest schema v2 + doctor + conflict detection + inline tag ([50c0892](https://github.com/event4u-app/agent-config/commit/50c0892bf01eb904e48dd786ef03c519f82be485))
+* **cli:** add prune command for orphaned bridge markers ([d16abff](https://github.com/event4u-app/agent-config/commit/d16abff8ac9fd55ccd501d319785f463eb7cbeee))
+* **cli:** add uninstall/versions subcommands and --offline mode ([12a8e75](https://github.com/event4u-app/agent-config/commit/12a8e75945f1d26c1412d17331788c8e51601cea))
+* **install:** add workflow-mode activation hints to IDE bridges ([5e09e17](https://github.com/event4u-app/agent-config/commit/5e09e17f0de62b4113bd68839d6ce55a1527d4b1))
+* **rules:** add external-reference-deep-dive hardening rule ([0d2c80c](https://github.com/event4u-app/agent-config/commit/0d2c80c0f418b80a67d08c4577cfe67ab6abe3db))
+* **install:** expand global content deployment to 23 AI tools ([3ef13a7](https://github.com/event4u-app/agent-config/commit/3ef13a7c2ae16b95da9e5a49ec3a19c5cb211357))
+
+### Bug Fixes
+
+* **install:** normalise manifest paths + surface doctor remediation hint ([b4662b6](https://github.com/event4u-app/agent-config/commit/b4662b609db6b1b4660652facc0efb10b36a5d51))
+* **test:** patch USERPROFILE in isolated_lock fixture for Windows ([ac1c924](https://github.com/event4u-app/agent-config/commit/ac1c924e08822e09471c0cf0077ad69be531d7b5))
+
+### Documentation
+
+* **readme:** remove stale vX.0 breaking-change notice ([d6aef9a](https://github.com/event4u-app/agent-config/commit/d6aef9acce3e5409f0ffc641ecf026af1f9bb863))
+* **roadmap:** sharpen Phase 6 deferred trigger — name the collision ([d0a6dd2](https://github.com/event4u-app/agent-config/commit/d0a6dd28294c011d4135b4047e4e5252008fcf05))
+* **roadmap:** close + archive multi-package coexistence ([3ef464f](https://github.com/event4u-app/agent-config/commit/3ef464fd6123ead7ca755542a1459e6a9e8e270b))
+* **roadmap:** plan + close phases 1-5 of multi-package coexistence ([34967a5](https://github.com/event4u-app/agent-config/commit/34967a5e6525d4d742155ee3bd3fe0bb80d852bf))
+* **install:** add installed-tools-lockfile wire contract ([c352db3](https://github.com/event4u-app/agent-config/commit/c352db383f6bf6dc328159289fa4d96abb2594c4))
+* **setup:** add per-IDE activation guides for 14 tools ([6379a49](https://github.com/event4u-app/agent-config/commit/6379a49fed6ac3256c23ac8e04c69fa0d4f85aa2))
+
+### Tests
+
+* **e2e:** cover shared JSON merges, sole-owner cleanup, conflict chain ([0ff50ae](https://github.com/event4u-app/agent-config/commit/0ff50ae617d878138376e535fc8b5c22a7677356))
+* **install:** e2e multi-package coexistence scenario ([081318e](https://github.com/event4u-app/agent-config/commit/081318ea8e3c872548839d100117cbd9b4a1343a))
+* **cli:** cover prune — orphans, dry-run, json, hard-floor ([0261ea2](https://github.com/event4u-app/agent-config/commit/0261ea2e1687e6904bdcb3083cb0d700b6ef82e5))
+
+### CI
+
+* **tests:** bump per-shard parallelism explicitly to beat macOS nproc=3 ([83a3b4d](https://github.com/event4u-app/agent-config/commit/83a3b4d3bf6eefe10963d84525469aeb8e3b8abe))
+* **tests:** bump install-tests shards 3→4 to keep macOS under 2min ([dd4d5bc](https://github.com/event4u-app/agent-config/commit/dd4d5bc385282d344809a057d015a968811d4a3b))
+* **tests:** shard install-tests matrix to hit 1-2min/job target ([6a56416](https://github.com/event4u-app/agent-config/commit/6a564161f0a74601fe077d34c76f2f5a27657893))
+* **tests:** parallelize install-tests + fix Windows UTF-8 encoding ([e346a26](https://github.com/event4u-app/agent-config/commit/e346a26e91be633a63e8c7d46fb09a3a6cdf800e))
+* **tests:** bootstrap .augment/ projection before pytest ([e40371e](https://github.com/event4u-app/agent-config/commit/e40371ea7b0c345ee59eba8ba5e47328bf6aebe9))
+
+### Chores
+
+* finalize changes ([7cbbe68](https://github.com/event4u-app/agent-config/commit/7cbbe6881e040d67fd0598df73b82b3fbd1278c0))
+* regenerate router.json after kernel/tier rebuild ([ff5f10e](https://github.com/event4u-app/agent-config/commit/ff5f10e0589f46782ec6381a84377f22b90d7edc))
+* **marketplace:** refresh marketplace.json manifest ([eb9b934](https://github.com/event4u-app/agent-config/commit/eb9b934f5b4573ec1fcde19f91f6a20637b8dbeb))
+
+Tests: 3490 (+140 since 2.2.2)
+
+## [2.2.2](https://github.com/event4u-app/agent-config/compare/2.2.1...2.2.2) (2026-05-12)
+
+### Bug Fixes
+
+* allow --global installs from agent-config source repo ([1be1b44](https://github.com/event4u-app/agent-config/commit/1be1b4429e8fa3ff3fb2981a1368138aa34186ac))
+
+Tests: 3350 (+0 since 2.2.1)
+
 ## [2.2.1](https://github.com/event4u-app/agent-config/compare/2.2.0...2.2.1) (2026-05-12)
 
 ### Documentation

package/README.md

@@ -1,12 +1,5 @@
 # Agent Config — Governed Agent System
 
-> ⚠️ **Breaking change in vX.0** — `agent-config` now ships as an
-> **npx-only runtime**. `composer require` / `npm install --save-dev`
-> are gone, the `--global` symlink scheme is retired. Existing
-> consumers: run `npx @event4u/agent-config migrate`
-> ([guide](docs/migration/v1-to-v2.md)). New consumers: jump to
-> [Quickstart](#quickstart).
-
 > **agent-config is not a runtime, but it ships a deterministic orchestration contract / state machine for host agents.**
 
 Give your AI agents an audit-disciplined orchestration contract — testing, Git, CI, code review, and **120+ stack-aware skills** — with quality guardrails built in.
@@ -14,7 +7,7 @@ Give your AI agents an audit-disciplined orchestration contract — testing, Git
 > Your agent picks up the project's stack, runs tests, prepares PRs, fixes CI — and follows your team's coding standards while doing it. Stack-aware skill sets ship for PHP (Laravel · Symfony · Zend/Laminas), JavaScript (Next.js · React · Node), and cross-stack concerns (API · testing · security · observability).
 
 <p align="center">
-  <strong>174 Skills</strong> · <strong>60 Rules</strong> · <strong>106 Commands</strong> · <strong>70 Guidelines</strong> · <strong>8 AI Tools</strong>
+  <strong>174 Skills</strong> · <strong>61 Rules</strong> · <strong>106 Commands</strong> · <strong>70 Guidelines</strong> · <strong>8 AI Tools</strong>
 </p>
 
 ---

package/docs/architecture.md

@@ -143,7 +143,7 @@ fails on any source-side violation, without producing artifacts.
 | Layer | Count | Purpose |
 |---|---|---|
 | **Skills** | 174 | On-demand expertise — stack analysis (Laravel · Symfony · Zend / Laminas · Next.js · React · Node), testing, Docker, API design, security, observability, … |
-| **Rules** | 60 | Always-active constraints — coding standards, scope control, verification, language-and-tone, agent-authority |
+| **Rules** | 61 | Always-active constraints — coding standards, scope control, verification, language-and-tone, agent-authority |
 | **Commands** | 106 | Slash-command workflows — `/commit`, `/create-pr`, `/fix ci`, `/optimize skills`, `/feature plan`, `/work`, `/implement-ticket`, `/compress`, … |
 | **Guidelines** | 70 | Reference material cited by skills — PHP patterns, Eloquent, Playwright, agent-infra, … |
 | **Templates** | 7 | Scaffolds for features, roadmaps, contexts, skills, overrides |

package/docs/contracts/installed-tools-lockfile.md

@@ -0,0 +1,138 @@
+# Installed-Tools Lockfile — Wire Contract
+
+Canonical wire-format spec for `agents/installed-tools.lock` — the
+project-committed bill of materials for AI tooling installed into this
+repository.
+
+- **Authoritative module:** [`scripts/_lib/installed_tools.py`](../../scripts/_lib/installed_tools.py)
+- **ADR:** [`docs/decisions/ADR-008-installed-tools-manifest.md`](../decisions/ADR-008-installed-tools-manifest.md)
+- **Workflow guide:** [`docs/guidelines/agent-infra/installed-tools-manifest.md`](../guidelines/agent-infra/installed-tools-manifest.md)
+- **Active roadmap:** P1.1 of [`agents/roadmaps/road-to-multi-package-coexistence.md`](../../agents/roadmaps/road-to-multi-package-coexistence.md)
+
+## Versions
+
+| Version | Status | Writer | Reader |
+|---|---|---|---|
+| **1** | legacy | not emitted by current code | tolerated by `read_manifest` |
+| **2** | current | `write_manifest` always emits this | tolerated by `read_manifest` |
+
+`SCHEMA_VERSION = 2` · `SCHEMA_VERSIONS_SUPPORTED = (1, 2)`. The reader
+must accept any version in `SCHEMA_VERSIONS_SUPPORTED`; the writer must
+always emit the highest. Bumps are breaking on the writer side and
+require a migration plan.
+
+## Schema v2 — wire format
+
+```yaml
+schema_version: 2
+agent_config_version: "2.2.0"
+deploy_roots:                          # optional, top-level (P1.1)
+  - .augment/rules
+  - .cursor/rules
+tools:
+  - name: claude-code                  # one of _VALID_TOOLS
+    scope: global                      # global | project
+    bridge_marker: ~/.claude/PROJECT_MANAGED_BY_AGENT_CONFIG
+    installed_at: "2026-05-12"
+    status: installed                  # optional: installed | uninstalling (P2.2)
+    files:                             # optional, per-tool (P1.1)
+      - path: .augment/rules/r1.md
+        kind: deployed                 # one of FILE_KINDS
+        sha256: "<64 hex chars>"
+      - path: .cursorrules
+        kind: bridge
+        sha256: null                   # null permitted for non-content markers
+    merged_keys:                       # optional, per-tool (P1.1)
+      - file: .mcp.json
+        json_pointer: "/mcpServers/agent-config"
+```
+
+### Top-level fields
+
+| Field | Type | Owner | Notes |
+|---|---|---|---|
+| `schema_version` | int | machine | always `2` on write |
+| `agent_config_version` | str | machine | last writer's package version |
+| `deploy_roots` | list[str] | machine | optional; directories the doctor command surveys for foreign files. Omitted when empty. Falls back to `DEFAULT_DEPLOY_ROOTS` when consumers need a survey scope and no explicit list is present. |
+| `tools` | list[obj] | machine | install-order preserved, not alphabetised |
+
+### Per-tool fields
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `name` | str | yes | one of `_VALID_TOOLS` in `scripts/install.py` |
+| `scope` | str | yes | `global` (user-home) or `project` (workspace bridge) |
+| `bridge_marker` | str | yes | absolute / `~`-prefixed for global; repo-relative for project |
+| `installed_at` | str | yes | ISO date; informational only |
+| `status` | str | no | `installed` (default when absent) or `uninstalling`; two-phase uninstall (P2.2). A crashed uninstall leaves the entry in `uninstalling` — `agent-config prune --resume-uninstall` sweeps only those entries' `files[]` without touching healthy tools or unmanaged drift. |
+| `files` | list[obj] | no | content the installer deployed for this tool |
+| `merged_keys` | list[obj] | no | named keys this tool inserted into shared JSON files |
+
+### `files[]` entries
+
+| Field | Type | Notes |
+|---|---|---|
+| `path` | str | repo-relative for project-scope, `~`-prefixed for global |
+| `kind` | str | one of `FILE_KINDS = {bridge, deployed, marker}` |
+| `sha256` | str / null | 64 hex chars of the file's SHA-256 at install time, or `null` for markers / pointers without content |
+
+`kind` semantics:
+
+- **`bridge`** — team-pointer marker like `.cursorrules` or `.windsurf/PROJECT_MANAGED_BY_AGENT_CONFIG`. Existence-tracked, content-untracked.
+- **`deployed`** — bundle content the installer wrote (e.g. `.augment/rules/*.md`). Content-tracked via `sha256` so drift is detectable.
+- **`marker`** — one-off sentinel (e.g. `claude-desktop` install marker). Existence-only.
+
+### `merged_keys[]` entries
+
+| Field | Type | Notes |
+|---|---|---|
+| `file` | str | repo-relative path to the shared file (e.g. `.mcp.json`) |
+| `json_pointer` | str | RFC 6901 pointer. **Constraint:** must target an object key, never an array index. Array-index pointers shift on neighbour-tool uninstall and corrupt other packages' ownership. |
+
+The pointer constraint is enforced at write time in P1.5; readers in v2.x
+must reject manifests that contain array-index pointers.
+
+## Compatibility — reader tolerance
+
+- `read_manifest` accepts both v1 and v2 wire formats.
+- When `pyyaml` is available, v2 round-trips fully.
+- When `pyyaml` is missing, the manual fallback parser extracts v1-equivalent fields (top-level scalars + per-tool scalar fields) and **silently drops** v2 nested fields (`files`, `merged_keys`, `deploy_roots`). Callers that need full v2 fidelity must ensure `pyyaml` is on the path.
+
+## Compatibility — writer behaviour
+
+- `write_manifest(path, version, tools, *, deploy_roots=None)` always emits `schema_version: 2`.
+- Optional v2 fields (`deploy_roots`, per-tool `files` / `merged_keys` / `status`) are emitted only when non-empty, so a v1-shaped call produces a v2 file that is structurally minimal and v1-readable for the core fields.
+- All writes are crash-safe via [`scripts/_lib/fs_atomic.py`](../../scripts/_lib/fs_atomic.py) (`write_atomic`: tmp + fsync + rename + parent-dir fsync). See P1.0 of the multi-package roadmap.
+
+## Determinism
+
+Required by P1.3 (not yet enforced in v2.0 of the writer):
+
+1. `tools[]` order = install order (no re-sort).
+2. `files[]` order within a tool = sorted by `path` ascending.
+3. `merged_keys[]` order within a tool = sorted by `(file, json_pointer)` ascending.
+4. `deploy_roots[]` order = as supplied by the writer (caller-controlled).
+
+Determinism is what lets the doctor command produce stable diffs across team members.
+
+## Inline package tag (P5 — non-authoritative)
+
+Deployed Markdown files may carry a frontmatter tag that records provenance for human readers:
+
+```yaml
+---
+title: My rule
+package: event4u/agent-config
+source_path: config/rules/general.md
+---
+```
+
+Properties:
+
+- **Optional.** Files without a leading `---` frontmatter block are deployed as-is; no synthetic frontmatter is added (P5.1).
+- **Human-readable only.** The lockfile remains the single source of truth for ownership, prune, and uninstall decisions. Removing or hand-editing the inline tag does **not** alter prune / uninstall semantics (P5.3).
+- **Surfaced by doctor.** A frontmatter-bearing file whose `package:` value disagrees with this writer's identifier — or whose `package:` key has been removed — appears under the `tag-drift` category of `agent-config doctor` (P5.2). Tag-drift exit code = 1, same as other drift; fix hint points at `--force` re-install.
+- **Idempotent.** Re-installation rewrites the same `package:` / `source_path:` values; running install twice produces byte-identical Markdown.
+- **`source_path:` (not `source:`).** The injected provenance-path key is named `source_path:` to avoid collision with the established `source: package` origin-type marker used by 200+ rule files in this and downstream packages. The injector treats `source:` as a foreign key and never rewrites it.
+
+Neighbour packages writing into the same project SHOULD use their own `package:` identifier so doctor can distinguish authored ownership at a glance, but they MUST still register their files in the manifest — the inline tag is a UX affordance, not a substitute for the lockfile entry.

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

@@ -46,6 +46,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/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/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.