@event4u/agent-config 1.41.2 → 2.1.0

package/docs/contracts/command-clusters.md

@@ -11,7 +11,7 @@ stability: beta
 The agent-config command surface collapses related atomic commands
 into **verb clusters**. A cluster is a single top-level command
 (e.g. `/fix`) that dispatches to sub-commands (e.g. `/fix ci`,
-`/fix pr`). Old atomic commands stay one release as deprecation
+`/fix pr-comments`). Old atomic commands stay one release as deprecation
 shims, then disappear.
 
 This file is the **locked source of truth** for which clusters
@@ -27,7 +27,7 @@ column 1 of this table.
 
 | Cluster | Phase | Sub-commands | Replaces |
 |---|:-:|---|---|
-| `fix` | 1 | `ci` · `pr` · `pr-bots` · `pr-developers` · `portability` · `refs` · `seeder` | `fix-ci` · `fix-pr-comments` · `fix-pr-bot-comments` · `fix-pr-developer-comments` · `fix-portability` · `fix-references` · `fix-seeder` |
+| `fix` | 1 | `ci` · `pr-comments` · `pr-bot-comments` · `pr-developer-comments` · `portability` · `refs` · `seeder` | `fix-ci` · `fix-pr-comments` · `fix-pr-bot-comments` · `fix-pr-developer-comments` · `fix-portability` · `fix-references` · `fix-seeder` |
 | `optimize` | 1 | `agents-dir` · `augmentignore` · `rtk` · `skills` | `optimize-augmentignore` · `optimize-rtk-filters` · `optimize-skills` · former `/optimize agents` and `/optimize agents-md` moved to the `/agents` file-family cluster 2026-05-09; `/agents prepare/audit/cleanup` collapsed into the single `/optimize agents-dir` (flags or wizard) per the agent-doc consolidation |
 | `feature` | 1 | `explore` · `plan` · `refactor` · `roadmap` · `dev` | `feature-explore` · `feature-plan` · `feature-refactor` · `feature-roadmap` · `feature-dev` |
 | `chat-history` | 2 | `show` · `import` · `learn` | `chat-history` (legacy status) — `resume` / `clear` / `checkpoint` removed in `road-to-chat-history-hook-only` (auto-adopt + structural hooks); `import` (verbatim cross-session render) and `learn` (project-improving learning extraction) added in the v4 stateless schema |
@@ -84,7 +84,7 @@ every new sub-command added to an existing cluster.
    cluster's primary verb (e.g. `/roadmap:create` + `process-*`
    composites).
 
-3. **Sub-name format.** kebab-case (`pr-bots`, `process-phase`),
+3. **Sub-name format.** kebab-case (`pr-bot-comments`, `process-phase`),
    ≤ 24 chars, no leading verb that duplicates the cluster name
    (use `/fix:ci`, not `/fix:fix-ci`).
 

package/docs/contracts/file-ownership-matrix.json

@@ -261,19 +261,19 @@
       "load_context": [],
       "load_context_eager": []
     },
-    ".agent-src.uncompressed/commands/fix/pr-bots.md": {
+    ".agent-src.uncompressed/commands/fix/pr-bot-comments.md": {
       "kind": "command",
       "rule_type": null,
       "load_context": [],
       "load_context_eager": []
     },
-    ".agent-src.uncompressed/commands/fix/pr-developers.md": {
+    ".agent-src.uncompressed/commands/fix/pr-comments.md": {
       "kind": "command",
       "rule_type": null,
       "load_context": [],
       "load_context_eager": []
     },
-    ".agent-src.uncompressed/commands/fix/pr.md": {
+    ".agent-src.uncompressed/commands/fix/pr-developer-comments.md": {
       "kind": "command",
       "rule_type": null,
       "load_context": [],
@@ -3088,22 +3088,22 @@
       "depth": 0
     },
     {
-      "source": ".agent-src.uncompressed/commands/fix/pr-bots.md",
-      "target": ".agent-src.uncompressed/commands/fix/pr-bots.md",
+      "source": ".agent-src.uncompressed/commands/fix/pr-bot-comments.md",
+      "target": ".agent-src.uncompressed/commands/fix/pr-bot-comments.md",
       "type": "WRITE",
       "via": "self",
       "depth": 0
     },
     {
-      "source": ".agent-src.uncompressed/commands/fix/pr-developers.md",
-      "target": ".agent-src.uncompressed/commands/fix/pr-developers.md",
+      "source": ".agent-src.uncompressed/commands/fix/pr-comments.md",
+      "target": ".agent-src.uncompressed/commands/fix/pr-comments.md",
       "type": "WRITE",
       "via": "self",
       "depth": 0
     },
     {
-      "source": ".agent-src.uncompressed/commands/fix/pr.md",
-      "target": ".agent-src.uncompressed/commands/fix/pr.md",
+      "source": ".agent-src.uncompressed/commands/fix/pr-developer-comments.md",
+      "target": ".agent-src.uncompressed/commands/fix/pr-developer-comments.md",
       "type": "WRITE",
       "via": "self",
       "depth": 0

package/docs/customization.md

@@ -67,30 +67,76 @@ personal.autonomy
 caveman.speak_scope
 ```
 
-**Merge order** (lowest → highest precedence):
+**Merge order** (lowest → highest precedence; every layer optional):
 
 ```
 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)
+3. <repo-root>/.agent-settings.yml                    (project-wide · all keys)
+4. <intermediate-dir>/.agent-settings.yml             (subsystem-scoped · all keys · optional)
+5. <CWD>/.agent-settings.yml                          (deepest · all keys · 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)
+`<repo-root>` is the nearest ancestor of the CWD that contains a `.git`
+directory **or** file (submodule support). The walk stops there — it
+never drifts into a parent repo or `$HOME`. Callers that omit the
+``cwd`` argument get the legacy two-layer behaviour (user-global +
+single project file) — back-compat is hard.
+
+Project-local values **always win** over user-global. 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.
+
+**Whitelist asymmetry.** The six-key whitelist applies **only** to the
+user-global layer. Non-root in-project layers (intermediate +
+``<CWD>``) carry arbitrary keys — they live inside the project
+boundary, are tracked in git, and reviewed in PRs like any other
+config. Use a subdirectory `.agent-settings.yml` to scope a single
+field (e.g. a `cost_profile` override for `services/heavy-ml/`) without
+duplicating the root file.
+
+The user-global 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.
 
+### Agent config version pin
+
+The top-level `agent_config_version` key pins the project to an exact
+release of `@event4u/agent-config`. Under the npx-only distribution
+model (see [`docs/architecture.md`](architecture.md) §
+*"npx-only distribution + version-pin governance"*), there is no
+local `node_modules/` or `vendor/` lockfile to anchor the runtime —
+the pin is the substitute mechanism.
+
+```yaml
+agent_config_version: "2.0.3"   # exact semver, no ranges
+```
+
+Rules:
+
+- **Exact semver only.** Ranges (`^2.0`, `~2.0.3`, `>=2.0`) are
+  rejected — the pin must be reproducible across the team.
+- **Empty string = unpinned.** The resolver picks the latest release
+  on every invocation. Only safe for greenfield projects; production
+  consumers should pin.
+- **Owned by the project, not the developer.** Lives in
+  `.agent-settings.yml` (committed), reviewed in PRs like any other
+  config change. Never merged from `~/.config/agent-config/agent-settings.yml`.
+- **Resolver enforcement.** `npx @event4u/agent-config <cmd>`
+  compares the resolved CLI version against the pin; mismatch
+  triggers a re-exec at the pinned version
+  (`npx @event4u/agent-config@<pin> <cmd>`).
+
 ### Available settings
 
 | Setting | Default | Description |
 |---|---|---|
+| `agent_config_version` | *(empty)* | Exact semver pin of the agent-config release (see above). Empty = unpinned. |
 | `cost_profile` | `minimal` | Token budget (`minimal`, `balanced`, `full`, `custom`) |
 | `personal.user_name` | *(empty)* | User's first name for personalized responses |
 | `personal.minimal_output` | `true` | Suppress intermediate output |
@@ -254,6 +300,76 @@ agents/
 
 Module-level documentation goes into `app/Modules/*/agents/`.
 
+### `agents/` overlay cascade
+
+A subset of `agents/` subdirs participates in the same deepest-wins
+cascade as `.agent-settings.yml` (see *"User-global DX-comfort
+defaults"* above). The cascade is **per-file** by basename — the
+deepest existing `agents/<kind>/<name>.md` wins; the rest are silently
+shadowed.
+
+| Subdir | Cascade? | User-global allowed? | Why |
+|---|---|---|---|
+| `agents/overrides/` | ✅ Yes — deepest wins by basename. | ✅ Yes — weakest layer. | Personal developer overrides. |
+| `agents/contexts/` | ✅ Yes — deepest wins by basename. | ❌ No — project-shaped. | Shared knowledge; would leak across projects. |
+| `agents/decisions/` | ✅ Yes — deepest wins by basename. | ❌ No — project-shaped ADRs. | Decisions are repo-bound. |
+| `agents/roadmaps/` | ❌ No — project-rooted only. | ❌ No. | Active delivery plans. |
+| `agents/state/`, `agents/memory/`, `agents/work_engine/`, `agents/.agent-prices.md`, `agents/council-*/` | ❌ No — stateful / session-scoped. | ❌ No. | Per-session state, not shareable. |
+
+**User-global asymmetry.** `~/.config/agent-config/agents/overrides/`
+is the only user-global overlay path consulted by the loader. Files
+under `~/.config/agent-config/agents/contexts/` or
+`.../agents/decisions/` are silently skipped — these kinds are
+project-shaped and must not leak across projects.
+
+The resolver lives at
+[`scripts/_lib/agents_overlay.py`](../scripts/_lib/agents_overlay.py)
+and is enforced by `scripts/check_overlay_cascade_subdirs.py` — drift
+between the code constants (`CASCADE_ELIGIBLE_KINDS`,
+`USER_GLOBAL_OVERLAY_KINDS`) and the table above breaks the build.
+
+---
+
+## Update check
+
+`npx @event4u/agent-config <cmd>` checks the npm registry once per
+24 h for a newer release of the package and, when one is available,
+writes a two-line banner to **stderr** *after* the subcommand has
+finished. There is no prompt — the user updates when they want with
+`npx @event4u/agent-config update` (Phase 3).
+
+```
+ℹ️  agent-config 1.42.0 available (you have 1.38.0).
+    Update: npx @event4u/agent-config update
+```
+
+State is persisted at `~/.config/agent-config/update-check.json`
+(mode `0600`) — sibling of `anthropic.key`, `council-spend.jsonl`.
+The fetch is hard-capped at 1 s and silent on any error.
+
+### Suppression matrix
+
+The banner is silently skipped when **any** of the following match:
+
+| Condition | Reason |
+|---|---|
+| `CI=1` / `CI=true` / `GITHUB_ACTIONS=true` | CI noise, breaks log scrapers. |
+| `stdout` is not a TTY | Piped / redirected output must stay clean. |
+| `AGENT_CONFIG_NO_UPDATE_CHECK=1` | Per-invocation escape hatch. |
+| `update_check.enabled: false` in `.agent-settings.yml` | Project / user opt-out. |
+| Registry call exceeds 1 s | Network must never delay `npx`. |
+| Registry call raises any exception | Best-effort — failure is silent. |
+
+`update_check.enabled` is a **project-scoped** key — it is *not* on
+the user-global whitelist (see [§ Agent Settings](#agent-settings)).
+Each project decides; the user-global file cannot flip it on or off
+for unrelated projects.
+
+The decision logic lives at
+[`scripts/_lib/update_check.py`](../scripts/_lib/update_check.py); the
+dispatcher integration lives in [`scripts/agent-config`](../scripts/agent-config)
+(`run_update_check_banner`).
+
 ---
 
 ← [Back to README](../README.md)

package/docs/getting-started.md

@@ -1,33 +1,23 @@
 # Getting Started
 
 `agent-config` is a stack-agnostic orchestration contract for coding
-agents. The installer detects the project shape (Composer / npm / both /
-neither) and wires the matching glue. **Pick the entrypoint that
-matches the project**, not the language you happen to prefer.
+agents. Installation is npx-first; the package itself is npm-published
+and works in any project regardless of language.
 
 ## Installation
 
-The installer is the same orchestrator across stacks — it reads
-`composer.json` and/or `package.json`, syncs the payload, and generates
-the tool-specific glue. Pick one entrypoint:
+Pick one entrypoint:
 
 ```bash
-# Composer-based projects (PHP / Laravel / Symfony / Zend / Laminas)
-composer require --dev event4u/agent-config
-php vendor/bin/install.php
-# Equivalent: bash vendor/event4u/agent-config/scripts/install
-
-# npm-based projects (Next.js / React / Node / Vue / plain JS/TS)
-npm install --save-dev @event4u/agent-config
-# Postinstall runs the orchestrator. Re-run or pick a profile:
-# bash node_modules/@event4u/agent-config/scripts/install --profile=balanced
-
-# Mixed Composer + npm projects (Laravel + Inertia, Symfony + Vue, …)
-# Run both — the orchestrator merges results, no double-write.
-
-# Stack-less or polyglot repos (no Composer, no npm)
-git clone https://github.com/event4u-app/agent-config /tmp/agent-config
-bash /tmp/agent-config/scripts/install --target "$PWD"
+# Recommended — one-shot, no local dependency
+npx @event4u/create-agent-config init --tools=claude-code,cursor
+
+# No-Node fallback — curl | bash entrypoint (downloads a tarball)
+curl -sSL https://raw.githubusercontent.com/event4u-app/agent-config/main/setup.sh | bash
+
+# Global CLI (one install per machine, all projects)
+npm install -g @event4u/agent-config
+agent-config --help
 ```
 
 That's it. Your agent now follows your team's standards. The orchestrator
@@ -49,9 +39,10 @@ so you can run a few package scripts without installing `go-task`,
 ./agent-config help                # full command list
 ```
 
-The wrapper is regenerated on every `npm install` / `composer install`
-and delegates to the copy under `node_modules/@event4u/agent-config/`
-or `vendor/event4u/agent-config/`.
+The wrapper is regenerated on every install and delegates to (in order):
+`$AGENT_CONFIG_MASTER`, `./node_modules/@event4u/agent-config/`,
+`agent-config` on `$PATH` (global npm install), or
+`npx @event4u/agent-config@latest`.
 
 ## First Run
 

package/docs/installation.md

@@ -31,6 +31,41 @@ Combine surfaces by comma-separating: `--tools=claude-code,cursor,windsurf`.
 
 ---
 
+## Upgrading from v1
+
+v2 is a breaking change: the local-install scheme (Composer
+`require-dev`, npm `devDependency`, the `--global` symlink namespace
+under `~/.claude/`, `~/.cursor/`, `~/.codeium/windsurf/`,
+`~/.config/agent-config/`) is **retired**. v2 is npx-only — the
+runtime is resolved per invocation, pinned by
+`agent_config_version` in `.agent-settings.yml`.
+
+One command does the cutover, idempotently:
+
+```bash
+./agent-config migrate              # remove legacy install signals
+./agent-config migrate --dry-run    # detect only, no writes
+```
+
+What `migrate` cleans up:
+
+| What | Action |
+|---|---|
+| `package.json` → `devDependencies.@event4u/agent-config` | Removed (lockfile updated on next `npm install`). |
+| `composer.json` → `require*.event4u/agent-config` | Removed (lockfile updated on next `composer update`). |
+| Symlinks `.augment/`, `.claude/`, `.cursor/`, `.clinerules/`, `.windsurfrules` pointing into `vendor/` or `node_modules/` | Deleted. User-owned links are preserved with a warning. |
+| `.agent-settings.yml` | Written fresh if missing, with `agent_config_version` pinned. |
+| `.gitignore` agent-config block | Refreshed. |
+
+After `migrate` runs, you can drop the now-unreferenced
+`node_modules/@event4u/agent-config/` and `vendor/event4u/agent-config/`
+directories with `npm prune` and `composer update` respectively.
+
+Full contract sketch + the retired `--global` namespace teardown:
+[`docs/migration/v1-to-v2.md`](migration/v1-to-v2.md).
+
+---
+
 ## Mechanisms reference
 
 The rest of this page documents the underlying install mechanisms
@@ -46,9 +81,9 @@ the per-IDE index above.
 > 2. `scripts/install.py` — bridge files (`.agent-settings.yml`, VSCode /
 >    Augment / Copilot JSON descriptors).
 >
-> `bin/install.php` and `scripts/postinstall.sh` are thin wrappers that
-> delegate to `scripts/install`. Both underlying stages remain callable
-> directly for advanced use; see their `--help`.
+> `npx @event4u/create-agent-config init` and `setup.sh` (curl-based)
+> are thin wrappers that delegate to `scripts/install`. Both underlying
+> stages remain callable directly for advanced use; see their `--help`.
 >
 > Python 3.10+ is required for bridges. If it is missing, the orchestrator
 > prints a warning and continues with the payload sync only.
@@ -80,9 +115,9 @@ the per-IDE index above.
 ## 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.
+adding it as a dev dependency or cloning the repo first. Both
+entrypoints are thin wrappers around `scripts/install` — same payload,
+same flags, no extra state.
 
 ### `npx` (Node ≥ 18)
 
@@ -139,41 +174,26 @@ used. Pass `--yes` (or `-y`) to force non-interactive mode anywhere.
 Install once in the project — available to everyone working on it.
 The package is versioned with the project. Settings are committed once.
 
-### Composer (PHP projects)
+### npx (recommended for any project)
 
 ```bash
-composer require --dev event4u/agent-config
-php vendor/bin/install.php
+npx @event4u/create-agent-config init --tools=claude-code,cursor
 ```
 
-Composer does **not** run a post-install hook for this package — the
-installer is an explicit step. `bin/install.php` is a thin wrapper that
-calls `scripts/install` (the bash orchestrator). To pick a non-default
-profile:
+The wrapper downloads the latest `@event4u/agent-config` tarball into a
+temp dir, runs `scripts/install` with the selected tools, and cleans up
+afterwards. Nothing is added to `package.json`.
 
-```bash
-php vendor/bin/install.php --profile=balanced
-```
-
-The `--profile` flag controls the initial `cost_profile` value written
-to `.agent-settings.yml`.
-
-### npm (JavaScript/TypeScript projects)
+### Global CLI (one install per machine)
 
 ```bash
-npm install --save-dev @event4u/agent-config
+npm install -g @event4u/agent-config
+agent-config --help
 ```
 
-npm runs `scripts/postinstall.sh` automatically, which invokes
-`scripts/install` — the same orchestrator every other entry point uses.
-
-If your setup disables install scripts (`npm config set ignore-scripts
-true` or similar), nothing happens and the command prints no warning.
-Re-run the installer manually in that case:
-
-```bash
-bash node_modules/@event4u/agent-config/scripts/install
-```
+The global install puts `agent-config` on `$PATH` so the project
+wrapper (`./agent-config`) can fall through to it when no
+`node_modules/@event4u/agent-config/` exists.
 
 ### Installer orchestrator (`scripts/install`)
 
@@ -188,12 +208,6 @@ bash scripts/install --skip-sync      # bridges only
 bash scripts/install --dry-run        # show payload sync plan, skip bridges
 ```
 
-PHP users can use the Composer wrapper, which forwards all flags:
-
-```bash
-php vendor/bin/install.php --profile=balanced
-```
-
 Under the hood:
 
 - `scripts/install.sh` — payload sync (callable directly for sync-only runs).
@@ -518,8 +532,6 @@ 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
 ```
 
@@ -528,41 +540,16 @@ 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.
+## Global user-level install — retired
 
-**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.
+The previous `--global` symlink scheme (kernel rules + curated skills
+copied into `~/.claude/`, `~/.cursor/`, `~/.codeium/windsurf/`, and
+`~/.config/agent-config/` under an `event4u/` namespace) has been
+**retired** under the npx-only distribution model. Run
+`npx @event4u/agent-config init` per project instead; the
+`agent_config_version` pin in `.agent-settings.yml` keeps every
+invocation reproducible. See [`migration/v1-to-v2.md`](migration/v1-to-v2.md)
+for the upgrade path.
 
 ---
 
@@ -571,15 +558,12 @@ that benefits from a baseline set of skills out of the box.
 When a new version of the package is published:
 
 ```bash
-composer update event4u/agent-config
-php vendor/bin/install.php          # refresh bridges + symlinks
-```
+# npx (one-shot, recommended) — always uses the latest tarball
+npx @event4u/create-agent-config init --tools=claude-code,cursor
 
-Or for npm projects:
-
-```bash
-npm update @event4u/agent-config
-bash node_modules/@event4u/agent-config/scripts/install
+# Global CLI
+npm install -g @event4u/agent-config@latest
+agent-config --help
 ```
 
 The installer is idempotent — re-running it after an update refreshes

package/docs/migration/v1-to-v2.md

@@ -0,0 +1,98 @@
+# Migration — v1 → v2 (npx-only runtime)
+
+> **Status:** skeleton. The one-shot `npx @event4u/agent-config migrate`
+> is implemented in P3.5 of
+> [`road-to-portable-runtime-and-update-check`](../../agents/roadmaps/road-to-portable-runtime-and-update-check.md);
+> this document tracks the user-facing cutover contract so consumers can
+> rehearse the change before the command lands.
+
+## Why this change
+
+v2 retires the local-install scheme (Composer dependency, npm
+`postinstall`, `--global` symlink namespace under `~/.claude/`,
+`~/.cursor/`, `~/.codeium/windsurf/`, `~/.config/agent-config/`) in
+favour of an **npx-only runtime**. The trade-off and the council's Q1
+rejection + the user's override are recorded in
+[`docs/architecture.md` § Distribution model](../architecture.md#distribution-model--npx-only--version-pin-governance).
+
+## TL;DR
+
+```bash
+npx @event4u/agent-config migrate
+```
+
+One command, idempotent. Re-runs on an already-migrated repo do nothing.
+
+## What disappears from the consumer
+
+| Path / entry                                          | Reason                                  |
+|-------------------------------------------------------|-----------------------------------------|
+| `composer.json` → `require-dev.event4u/agent-config`  | No Composer dependency under v2.        |
+| `composer.lock` line for `event4u/agent-config`       | Same; lockfile updated by Composer.     |
+| `package.json` → `devDependencies.@event4u/agent-config` | No npm dependency under v2.          |
+| `package-lock.json` / `pnpm-lock.yaml` entries        | Same.                                   |
+| `node_modules/@event4u/agent-config/`                 | Removed by the package manager once the `package.json` entry is gone. |
+| `vendor/event4u/agent-config/`                        | Removed by Composer once the require entry is gone. |
+| `~/.claude/{rules,skills}/event4u/`                   | Retired `--global` namespace dir.       |
+| `~/.cursor/rules/imported/event4u/`                   | Same.                                   |
+| `~/.codeium/windsurf/global_workflows/event4u/`       | Same.                                   |
+| `~/.config/agent-config/{rules,skills}/event4u/`      | Same (fallback path).                   |
+| Legacy `.gitignore` block lines marked `event4u/agent-config (legacy local install)` | Replaced by the v2 block written by `sync-gitignore`. |
+
+The retired `templates/global-install-manifest.yml` shipped inside the
+package and is gone in v2; consumers never carried it directly.
+
+## What appears in the consumer
+
+| Path / entry                                          | Owner / shape                           |
+|-------------------------------------------------------|-----------------------------------------|
+| `.agent-settings.yml` → `agent_config_version: "<pin>"` | Project version pin, reviewed in PRs. |
+| `.agent-settings.yml` → `update_check:` block         | Defaults shipped by `init`; opt-out per knob. |
+| Updated `.gitignore` block                            | v2 entries written by `sync-gitignore`. |
+
+The per-tool glue (`.claude/`, `.cursor/`, `.clinerules/`,
+`.windsurfrules`, `GEMINI.md`, `.github/copilot-instructions.md`,
+`.augment/`, `.vscode/settings.json`) keeps the same shape as v1 — only
+the source that writes them changed (from `vendor/` /
+`node_modules/` scripts to the npx-resolved runtime).
+
+## The `migrate` command — contract sketch
+
+```bash
+npx @event4u/agent-config migrate              # interactive, default
+npx @event4u/agent-config migrate --dry-run    # plan only, no writes
+npx @event4u/agent-config migrate --yes        # non-interactive
+```
+
+Order of operations (locked once P3.5 lands):
+
+1. Detect pre-v2 markers: `composer.json` require entry,
+   `package.json` devDependency, `vendor/event4u/agent-config/`,
+   `node_modules/@event4u/agent-config/`, legacy `.gitignore` lines,
+   `~/.claude/{rules,skills}/event4u/` and siblings.
+2. Print the planned change set (file removals, file writes, pin
+   value). Stop here under `--dry-run`.
+3. Remove dependency entries via the appropriate package manager
+   (`composer remove`, `npm uninstall` / `pnpm remove` / `yarn remove`).
+4. Wipe the retired user-scope `event4u/` namespace dirs.
+5. Write / update `.agent-settings.yml` with the new shape +
+   `agent_config_version` pin.
+6. Re-run `sync-gitignore` to refresh the project `.gitignore` block.
+7. Print a one-screen post-migration verification list.
+
+Idempotency: each step is a no-op when the v1 marker is absent. Re-runs
+print *"already on v2 — nothing to do"* and exit 0.
+
+## Verification after migration
+
+```bash
+npx @event4u/agent-config doctor    # P3 — runtime sanity check
+```
+
+Expected: pin resolved, no v1 markers detected, `update_check` reachable.
+
+## See also
+
+- [`docs/architecture.md` § Distribution model](../architecture.md#distribution-model--npx-only--version-pin-governance) — Q1 council rejection + override + pin substitution.
+- [`agents/roadmaps/road-to-portable-runtime-and-update-check.md`](../../agents/roadmaps/road-to-portable-runtime-and-update-check.md) — full delivery plan and acceptance criteria.
+- [`docs/installation.md`](../installation.md) — v2 install reference.

package/docs/migrations/commands-1.15.0.md

@@ -15,9 +15,9 @@ invocation and are removed in `1.16.0`.
 | Old command | New invocation | Removed in |
 |---|---|---|
 | `/fix-ci` | `/fix ci` | 1.16.0 |
-| `/fix-pr-comments` | `/fix pr` | 1.16.0 |
-| `/fix-pr-bot-comments` | `/fix pr-bots` | 1.16.0 |
-| `/fix-pr-developer-comments` | `/fix pr-developers` | 1.16.0 |
+| `/fix-pr-comments` | `/fix pr-comments` | 1.16.0 |
+| `/fix-pr-bot-comments` | `/fix pr-bot-comments` | 1.16.0 |
+| `/fix-pr-developer-comments` | `/fix pr-developer-comments` | 1.16.0 |
 | `/fix-portability` | `/fix portability` | 1.16.0 |
 | `/fix-references` | `/fix refs` | 1.16.0 |
 | `/fix-seeder` | `/fix seeder` | 1.16.0 |

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

@@ -29,23 +29,6 @@ Either form populates:
 - `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