@event4u/agent-config 1.41.2 → 2.1.0

package/.agent-src/commands/fix/{pr-bots.md → pr-bot-comments.md}

@@ -1,7 +1,7 @@
 ---
-name: fix:pr-bots
+name: fix:pr-bot-comments
 cluster: fix
-sub: pr-bots
+sub: pr-bot-comments
 skills: [php-coder, quality-tools]
 description: Fix and reply to bot review comments (Copilot, Augment, Greptile, etc.) on a GitHub PR
 disable-model-invocation: true
@@ -11,7 +11,7 @@ suggestion:
   trigger_context: "open PR with bot review comments unresolved"
 ---
 
-# /fix pr-bots
+# /fix pr-bot-comments
 ## Input
 
 The user may or may not provide a PR URL.

package/.agent-src/commands/fix/{pr.md → pr-comments.md}

@@ -1,7 +1,7 @@
 ---
-name: fix:pr
+name: fix:pr-comments
 cluster: fix
-sub: pr
+sub: pr-comments
 skills: [php-coder]
 description: Fix and reply to all open review comments (bots + human reviewers) on a GitHub PR
 disable-model-invocation: true
@@ -11,8 +11,8 @@ suggestion:
   trigger_context: "open PR with unresolved comments (bot + human)"
 ---
 
-# /fix pr
-This command runs `/fix pr-bots` and `/fix pr-developers` in sequence on the same PR.
+# /fix pr-comments
+This command runs `/fix pr-bot-comments` and `/fix pr-developer-comments` in sequence on the same PR.
 
 ## Input
 
@@ -45,14 +45,14 @@ The chosen mode applies to **both** phases.
 
 ### Phase 1: Bot comments
 
-Follow the full `/fix pr-bots` instructions (see `commands/fix/pr-bots.md`).
+Follow the full `/fix pr-bot-comments` instructions (see `commands/fix/pr-bot-comments.md`).
 Use the already-confirmed PR and mode — do not ask again.
 
 Report when done: "Bot comments done. Continuing with reviewer comments..."
 
 ### Phase 2: Developer comments
 
-Follow the full `/fix pr-developers` instructions (see `commands/fix/pr-developers.md`).
+Follow the full `/fix pr-developer-comments` instructions (see `commands/fix/pr-developer-comments.md`).
 Use the same PR and mode.
 
 ### After both phases

package/.agent-src/commands/fix/{pr-developers.md → pr-developer-comments.md}

@@ -1,7 +1,7 @@
 ---
-name: fix:pr-developers
+name: fix:pr-developer-comments
 cluster: fix
-sub: pr-developers
+sub: pr-developer-comments
 skills: [php-coder]
 description: Fix and reply to human reviewer comments on a GitHub PR
 disable-model-invocation: true
@@ -11,7 +11,7 @@ suggestion:
   trigger_context: "open PR with unresolved human-reviewer comments"
 ---
 
-# /fix pr-developers
+# /fix pr-developer-comments
 ## Input
 
 The user may or may not provide a PR URL.

package/.agent-src/commands/fix.md

@@ -22,9 +22,9 @@ with a single entry point + sub-command dispatch.
 | `/fix refs` | `commands/fix/refs.md` | Find and fix broken cross-references in `.augment/` and `agents/` |
 | `/fix portability` | `commands/fix/portability.md` | Find and fix project-specific references in shared `.augment/` files |
 | `/fix seeder` | `commands/fix/seeder.md` | Scan seeder data files for broken FK references |
-| `/fix pr` | `commands/fix/pr.md` | Fix and reply to **all** open review comments (bots + humans) |
-| `/fix pr-bots` | `commands/fix/pr-bots.md` | Fix and reply to **bot** review comments only |
-| `/fix pr-developers` | `commands/fix/pr-developers.md` | Fix and reply to **human** reviewer comments only |
+| `/fix pr-comments` | `commands/fix/pr-comments.md` | Fix and reply to **all** open review comments (bots + humans) |
+| `/fix pr-bot-comments` | `commands/fix/pr-bot-comments.md` | Fix and reply to **bot** review comments only |
+| `/fix pr-developer-comments` | `commands/fix/pr-developer-comments.md` | Fix and reply to **human** reviewer comments only |
 
 Sub-command names match the locked contract in
 [`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md).
@@ -41,9 +41,9 @@ Sub-command names match the locked contract in
    > 2. refs — fix broken cross-refs in agent docs
    > 3. portability — purge project-specific refs from shared package
    > 4. seeder — scan seeders for broken FK references
-   > 5. pr — address all open review comments
-   > 6. pr-bots — address bot reviewer comments only
-   > 7. pr-developers — address human reviewer comments only
+   > 5. pr-comments — address all open review comments
+   > 6. pr-bot-comments — address bot reviewer comments only
+   > 7. pr-developer-comments — address human reviewer comments only
 
 ## Rules
 

package/.agent-src/contexts/communication/rules-auto/slash-command-routing-policy-mechanics.md

@@ -4,7 +4,7 @@ Lookup table for the `slash-command-routing-policy` rule. Lists the
 locked clusters and their sub-commands so the rule itself can stay at
 its current LOC while still reflecting the full surface. Source of
 truth for the cluster names is
-[`docs/contracts/command-clusters.md`](../../../../../../docs/contracts/command-clusters.md);
+[`docs/contracts/command-clusters.md`](../../../../../docs/contracts/command-clusters.md);
 this file mirrors that contract for runtime lookup. Linter:
 `scripts/check_cluster_patterns.py` (verifies dispatcher shape).
 
@@ -12,7 +12,7 @@ this file mirrors that contract for runtime lookup. Linter:
 
 | 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` · `augmentignore` · `rtk` · `skills` | `/optimize-agents` · `/optimize-augmentignore` · `/optimize-rtk-filters` · `/optimize-skills`                                                   |
 | `/feature` | 1 | `explore` · `plan` · `refactor` · `roadmap` | `/feature-explore` · `/feature-plan` · `/feature-refactor` · `/feature-roadmap`                                                                 |
 | `/chat-history` | 2 | `show` | `/chat-history` (legacy status) — `resume` / `clear` / `checkpoint` removed in `road-to-chat-history-hook-only`                                 |

package/.agent-src/templates/agents/agent-project-settings.example.yml

@@ -26,6 +26,20 @@
 
 schema_version: 1
 
+# --- Agent config version pin (project-shared) ---
+#
+# Exact semver of @event4u/agent-config this project commits to. The
+# `npx @event4u/agent-config` dispatcher re-execs at this version when
+# the developer's locally-resolved version differs — so every
+# contributor runs the same agent surface regardless of their npm
+# cache state. Bump this together with a tested upgrade. Empty string
+# disables the pin (resolver picks the latest release; only safe for
+# greenfield projects). Ranges (^, ~, >=) are NOT supported.
+# CI guard: a release bump of `package.json` must update this value
+# in lockstep — see scripts/check_template_pin_drift.py (road-to-
+# portable-runtime-and-update-check P3.3).
+agent_config_version: "1.41.2"
+
 # --- Project identity ---
 project:
   # Short slug used in agent output, prompts, and PR metadata. Keep it

package/.agent-src/templates/scripts/work_engine/_lib/agent_settings.py

@@ -3,17 +3,24 @@
 Phase 1 of road-to-portable-dev-preferences. Single source of truth for
 how scripts read agent settings — replaces ~15 ad-hoc loaders in P3.
 
-Resolution order (project wins, user-global fills gaps for whitelisted
-keys only):
+Resolution order (deepest wins; user-global is whitelist-filtered only):
 
-  1. Project ``./.agent-settings.yml``                  (full file, all keys)
-  2. ``~/.config/agent-config/agent-settings.yml``      (whitelist only)
-  3. Built-in defaults                                  (currently empty)
+  N. ``~/.config/agent-config/agent-settings.yml``  (user-global; whitelist only)
+N-1. ``<repo-root>/.agent-settings.yml``            (project-wide; all keys)
+N-2. ``<intermediate-dir>/.agent-settings.yml``     (subsystem-scoped; all keys)
+  1. ``<CWD>/.agent-settings.yml``                  (deepest, wins; all keys)
+
+``<repo-root>`` is the nearest ancestor that contains ``.git`` (directory
+**or** file — submodule support). The walk stops there — it never drifts
+into a parent repo or ``$HOME``. When ``cwd`` is ``None`` (default), the
+loader behaves identically to the pre-cascade contract: project file +
+user-global only, no ancestor walk. Back-compat is hard.
 
 Whitelisted keys (``MERGEABLE_KEYS``) are exact dotted paths. A
 non-whitelisted key in the user-global file is silently ignored — the
 ``verbose=True`` flag surfaces ignored paths via ``logging.info`` for
-debugging.
+debugging. Non-root in-project layers (intermediate + CWD) are **not**
+whitelist-filtered — they live inside the project boundary.
 
 Contract — pure, read-only, tolerant:
 
@@ -28,7 +35,7 @@ from __future__ import annotations
 
 import logging
 from pathlib import Path
-from typing import Any
+from typing import Any, Iterator
 
 logger = logging.getLogger(__name__)
 
@@ -53,10 +60,70 @@ MERGEABLE_KEYS: tuple[str, ...] = (
 _DEFAULTS: dict[str, Any] = {}
 
 
+def find_project_root(start: Path) -> Path | None:
+    """Walk up from ``start`` looking for ``.git`` (file or directory).
+
+    Returns the first ancestor that contains ``.git`` as a file (submodule
+    pointer) or directory (regular checkout), or ``None`` if the walk
+    reaches the filesystem root without finding one. The walk stops at
+    the project boundary — it never drifts into a parent repo or
+    ``$HOME``.
+
+    Pure read-only; never touches the filesystem beyond ``exists()``
+    probes on the ``.git`` entry.
+    """
+    current = start.resolve() if start.exists() else start
+    # ``Path.parents`` excludes ``current`` itself, so probe it first.
+    for candidate in [current, *current.parents]:
+        git_marker = candidate / ".git"
+        if git_marker.exists():
+            return candidate
+    return None
+
+
+def _resolve_cascade_paths(
+    cwd: Path | None,
+    project_path: Path | str | None,
+) -> list[Path]:
+    """Return the ordered cascade of in-project settings files (shallow → deep).
+
+    When ``cwd`` is provided and ``find_project_root(cwd)`` succeeds, the
+    list contains every ``<dir>/.agent-settings.yml`` from the repo root
+    down to ``cwd`` (inclusive on both ends), shallowest first. When
+    ``cwd`` is ``None`` or no ``.git`` is reached, falls back to the
+    single legacy project path — back-compat with the pre-cascade
+    loader.
+    """
+    if cwd is None:
+        legacy = Path(project_path) if project_path else Path(DEFAULT_PROJECT_FILE)
+        return [legacy]
+
+    root = find_project_root(cwd)
+    if root is None:
+        legacy = Path(project_path) if project_path else Path(DEFAULT_PROJECT_FILE)
+        return [legacy]
+
+    cwd_resolved = cwd.resolve()
+    # Build the chain root → … → cwd (shallowest first, deepest last).
+    chain: list[Path] = []
+    cursor = cwd_resolved
+    while True:
+        chain.append(cursor)
+        if cursor == root:
+            break
+        parent = cursor.parent
+        if parent == cursor:
+            break
+        cursor = parent
+    chain.reverse()
+    return [d / DEFAULT_PROJECT_FILE for d in chain]
+
+
 def load_agent_settings(
     project_path: Path | str | None = None,
     user_global_path: Path | str | None = None,
     verbose: bool = False,
+    cwd: Path | None = None,
 ) -> dict[str, Any]:
     """Return the merged settings dict.
 
@@ -65,10 +132,16 @@ def load_agent_settings(
     ``~/.config/agent-config/agent-settings.yml``. Both arguments accept
     ``Path`` or ``str``. Pass ``verbose=True`` to log keys present in
     user-global that are not on the whitelist.
+
+    ``cwd`` enables the in-project cascade: when provided **and**
+    ``find_project_root(cwd)`` reaches a ``.git`` ancestor, the loader
+    walks every ``.agent-settings.yml`` from the repo root down to
+    ``cwd`` and merges them shallowest → deepest (deepest wins).
+    Non-root layers are **not** whitelist-filtered (they live inside the
+    project boundary). When ``cwd`` is ``None`` (default), the loader
+    falls back to the single ``project_path`` behaviour — back-compat
+    with pre-cascade callers.
     """
-    project = _read_yaml(
-        Path(project_path) if project_path else Path(DEFAULT_PROJECT_FILE),
-    ) or {}
     user_global_raw = _read_yaml(
         Path(user_global_path) if user_global_path else DEFAULT_USER_GLOBAL_FILE,
     ) or {}
@@ -82,12 +155,48 @@ def load_agent_settings(
             sorted(ignored),
         )
 
+    cascade = _resolve_cascade_paths(cwd, project_path)
+
     merged: dict[str, Any] = _deep_copy_defaults(_DEFAULTS)
     _deep_merge(merged, user_global_filtered)
-    _deep_merge(merged, project)
+    for path in cascade:
+        layer = _read_yaml(path) or {}
+        if layer:
+            _deep_merge(merged, layer)
     return merged
 
 
+def iter_setting_overrides(
+    project_path: Path | str | None = None,
+    user_global_path: Path | str | None = None,
+    cwd: Path | None = None,
+) -> Iterator[tuple[str, Any, Path]]:
+    """Yield ``(dotted_key, value, source_path)`` for every leaf setting.
+
+    Walks the same cascade as :func:`load_agent_settings` and emits one
+    tuple per leaf observed at each layer (user-global → repo-root →
+    intermediates → CWD). Callers can detect overrides by grouping
+    tuples on ``dotted_key`` — the deepest tuple per group wins. Useful
+    for ``task settings:trace`` and other banner-only diagnostics.
+    Never blocks, never raises on missing files.
+    """
+    user_global_path_resolved = (
+        Path(user_global_path) if user_global_path else DEFAULT_USER_GLOBAL_FILE
+    )
+    user_global_raw = _read_yaml(user_global_path_resolved) or {}
+    user_global_filtered, _ = _filter_whitelist(user_global_raw, MERGEABLE_KEYS)
+    if user_global_filtered:
+        for key in _leaf_paths(user_global_filtered):
+            yield key, _get_dotted(user_global_filtered, key), user_global_path_resolved
+
+    for path in _resolve_cascade_paths(cwd, project_path):
+        layer = _read_yaml(path)
+        if not layer:
+            continue
+        for key in _leaf_paths(layer):
+            yield key, _get_dotted(layer, key), path
+
+
 def _read_yaml(path: Path) -> dict[str, Any] | None:
     """Best-effort YAML read; never raises. Returns ``None`` on any failure."""
     if not path.is_file():

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Shared agent configuration \u2014 skills for AI coding tools (Claude Code, Augment, Cursor, Cline, Windsurf, Gemini CLI).",
-    "version": "1.41.2"
+    "version": "2.1.0"
   },
   "plugins": [
     {
@@ -112,9 +112,9 @@
         "./.claude/skills/fix",
         "./.claude/skills/fix-ci",
         "./.claude/skills/fix-portability",
-        "./.claude/skills/fix-pr",
-        "./.claude/skills/fix-pr-bots",
-        "./.claude/skills/fix-pr-developers",
+        "./.claude/skills/fix-pr-bot-comments",
+        "./.claude/skills/fix-pr-comments",
+        "./.claude/skills/fix-pr-developer-comments",
         "./.claude/skills/fix-refs",
         "./.claude/skills/fix-seeder",
         "./.claude/skills/flux",

package/CHANGELOG.md

@@ -318,6 +318,60 @@ our recommendation order, not its support status.
   users" tension without removing any path that an existing user
   might rely on.
 
+## [2.1.0](https://github.com/event4u-app/agent-config/compare/2.0.0...2.1.0) (2026-05-12)
+
+### Features
+
+* **wrapper:** add npx fallback and sanitize wrapper error test ([9f4326b](https://github.com/event4u-app/agent-config/commit/9f4326bffc59d79e4421b0cd8966c99348afe1e6))
+* **installer:** add source-repo guard and drop composer/global paths ([5388de2](https://github.com/event4u-app/agent-config/commit/5388de2598ea668a8671f49bd7bacd4866ed1c33))
+
+### Documentation
+
+* **installation:** add Upgrading from v1 section ([f35df4b](https://github.com/event4u-app/agent-config/commit/f35df4b9667eb848ce2ec47f4a7c550b1bba4054))
+* align install guides with v2 npx-only flow ([e841a14](https://github.com/event4u-app/agent-config/commit/e841a14cdbb6691433976c57ff9b28b3ec4992ad))
+* **readme:** collapse plugin-install table to one-liner ([b3407bb](https://github.com/event4u-app/agent-config/commit/b3407bb2fda39a8a57c0e2f72c8b430bed4fd012))
+
+### Refactoring
+
+* **cli:** rename fix:pr sub-commands for clarity ([fbdf636](https://github.com/event4u-app/agent-config/commit/fbdf636a50a06f3b35fe5c3d5fb108e9c15e6266))
+
+### Tests
+
+* **install:** drop composer-detection tests retired in v2 ([e37ad99](https://github.com/event4u-app/agent-config/commit/e37ad99beaebbb5f6a98b41e02ecefd6b0d39453))
+
+### Build
+
+* **tasks:** add npm:login + npm:publish-installer ([22639f8](https://github.com/event4u-app/agent-config/commit/22639f877feee33a3cbadb9147941cfb32fb6c9e))
+
+### Chores
+
+* remove retired setup.sh and global-install test surface ([3eebcf7](https://github.com/event4u-app/agent-config/commit/3eebcf72bcc45af168df4fd4b172a2484901a793))
+
+Tests: 3253 (-4 since 2.0.0)
+
+## [2.0.0](https://github.com/event4u-app/agent-config/compare/1.41.2...2.0.0) (2026-05-12)
+
+### BREAKING CHANGES
+
+* **install:** drop composer + npm postinstall, go npx-only ([6bc6c99](https://github.com/event4u-app/agent-config/commit/6bc6c99f57d2a2bcdab03bfacab429ce146dd9b9))
+
+### Features
+
+* **cli:** add update + migrate commands, version-pin resolver, CI drift guard ([b1e34fc](https://github.com/event4u-app/agent-config/commit/b1e34fcd7a03d38266e40dd053414fc9d20c9024))
+* **update-check:** add daily npm-registry version probe + banner ([2c4d752](https://github.com/event4u-app/agent-config/commit/2c4d752d5eb28f1c460470668704f5cf403c4046))
+* **settings:** add hierarchical project-settings cascade + agents overlay ([3296885](https://github.com/event4u-app/agent-config/commit/32968855ca17210b1594cea2e79778acb0476f0a))
+
+### Tests
+
+* **install:** drop postinstall.sh test cases removed in P0 ([d4e7750](https://github.com/event4u-app/agent-config/commit/d4e7750bcd13b021caa4ccaccff821dc0ae8e537))
+
+### Chores
+
+* **template:** mirror agent_settings cascade into work_engine template ([92f4716](https://github.com/event4u-app/agent-config/commit/92f471662c463efec0df591099a3507919396d77))
+* **roadmap:** archive completed portable-runtime-and-update-check ([91e2e4e](https://github.com/event4u-app/agent-config/commit/91e2e4ef75042d2d19a528874ebcac4b94c4046a))
+
+Tests: 3257 (+84 since 1.41.2)
+
 ## [1.41.2](https://github.com/event4u-app/agent-config/compare/1.41.1...1.41.2) (2026-05-12)
 
 ### Documentation

package/README.md

@@ -1,5 +1,12 @@
 # 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.
@@ -26,39 +33,40 @@ If none of those apply yet — start with the [Quickstart](#quickstart) and pick
 
 ## Quickstart
 
-Two minutes from `composer require` to a better-behaved agent.
+Two minutes from `npx` to a better-behaved agent — no install, no
+vendored package, no postinstall hook.
 
 ### For teams (recommended)
 
-Install once in the project — available to everyone who works on it:
+Run once in the project root — `npx` resolves the runtime against the
+npm registry on every invocation, and the version pin in
+`.agent-settings.yml` keeps it reproducible:
 
 ```bash
-# PHP
-composer require --dev event4u/agent-config
+# Bootstrap (writes .agent-settings.yml, .augment/, .claude/, …):
+npx @event4u/agent-config init
 
-# JavaScript/TypeScript
-npm install --save-dev @event4u/agent-config
+# Any subsequent command:
+npx @event4u/agent-config <command>
 ```
 
-After installing the package, run the installer to sync the payload and
-create `.agent-settings.yml`, `.vscode/settings.json`, `.augment/settings.json`,
-and the tool-specific glue:
+The init writes:
 
-```bash
-# PHP / Composer projects — explicit step (Composer does not auto-run it):
-php vendor/bin/install.php
-# or directly (any environment):
-bash vendor/event4u/agent-config/scripts/install
-
-# npm projects run the installer automatically via postinstall.
-# To re-run or override the default profile:
-bash node_modules/@event4u/agent-config/scripts/install --profile=balanced
-```
+- `.agent-settings.yml` (including the `agent_config_version` pin)
+- `.vscode/settings.json`, `.augment/settings.json`
+- per-tool glue: `.claude/`, `.cursor/`, `.clinerules/`,
+  `.windsurfrules`, `GEMINI.md`, `.github/copilot-instructions.md`
+
+→ Migrating from a pre-vX.0 install? See
+[`docs/migration/v1-to-v2.md`](docs/migration/v1-to-v2.md). The one-shot
+`npx @event4u/agent-config migrate` removes the legacy
+`composer.json` entry / `node_modules/@event4u/agent-config`,
+deletes the retired `~/.claude/{rules,skills}/event4u/` namespace if
+present, and writes the new `.agent-settings.yml` shape.
 
-**To install:** no Task / Make / build tools — `scripts/install` runs a
-bash payload sync plus a Python 3 bridge generator (stdlib only, default
-on macOS 12.3+ / major Linux distros). Python missing → orchestrator
-warns and continues payload-only. Task is needed only for *contributors*
+**To run:** Node ≥ 18 and Python 3 (stdlib only — default on macOS
+12.3+ / major Linux distros). Python missing → orchestrator warns and
+continues payload-only. Task is needed only for *contributors*
 rebuilding compressed content — see [CONTRIBUTING.md](CONTRIBUTING.md).
 
 **Verify hook coverage** after installing — every supported platform
@@ -71,13 +79,12 @@ dispatcher per bridge as a post-install smoke test (skip: `--no-smoke`).
 
 ### For individual use (optional)
 
-Install directly in your agent for global, cross-project use:
+Skills-only, global across projects — installs into the agent itself,
+no per-repo `init`:
 
-| Tool | Install |
-|---|---|
-| **Augment CLI** | `auggie plugin install agent-config@event4u-agent-config` |
-| **Claude Code** | `claude plugin install agent-config@event4u-agent-config` |
-| **Copilot CLI** | `copilot plugin install agent-config@event4u-agent-config` |
+```bash
+<auggie|claude|copilot> plugin install agent-config@event4u-agent-config
+```
 
 → [All install options & project bridge setup](docs/installation.md)
 
@@ -410,9 +417,10 @@ kernel set: [`docs/contracts/kernel-membership.md`](docs/contracts/kernel-member
 
 ## Supported Tools
 
-### Project-installed (Composer / npm)
+### Project-installed (`npx`)
 
-Every developer gets the same behavior. No per-user setup needed.
+Every developer gets the same behavior. No per-user setup needed —
+`npx @event4u/agent-config init` writes the per-tool glue listed below.
 
 | Tool | Rules | Skills | Commands | How it works |
 |---|---|---|---|---|

package/config/agent-settings.template.yml

@@ -5,6 +5,18 @@
 # values here directly or ask the agent (it follows the merge rules in
 # .augment/guidelines/agent-infra/layered-settings.md).
 
+# --- Agent config version pin ---
+#
+# Exact semver of the @event4u/agent-config release this project is
+# pinned to. Used by `npx @event4u/agent-config <cmd>` to re-exec at
+# the pinned version when the developer's local resolution differs.
+# Empty string = unpinned (resolver picks the latest release; only safe
+# for greenfield projects). Ranges (^, ~, >=) are NOT supported — the
+# pin replaces lockfile determinism, so it must be exact.
+# See docs/customization.md § "Agent config version pin" and
+# docs/architecture.md § "npx-only distribution + version-pin governance".
+agent_config_version: ""
+
 # --- Cost profile ---
 #
 # Master switch that controls which rule tiers load each session.
@@ -376,3 +388,16 @@ memory:
   # or paths outside the repo root that must not land in intake JSONL.
   # Example: ["api[_-]?key", "/Users/[a-z]+/Library"]
   redact_patterns: []
+
+# --- Update check ---
+#
+# Daily background check against the npm registry for a newer
+# @event4u/agent-config release. When enabled the dispatcher writes a
+# two-line banner to stderr **after** the subcommand finishes; CI,
+# non-TTY stdout, and `AGENT_CONFIG_NO_UPDATE_CHECK=1` always suppress
+# it regardless of this flag. State is persisted at
+# `~/.config/agent-config/update-check.json` (mode 0600) with a 24 h
+# cadence. See docs/customization.md § "Update check" for the suppression
+# matrix and the road-to-portable-runtime-and-update-check roadmap (P2).
+update_check:
+  enabled: true

package/docs/architecture.md

@@ -54,7 +54,7 @@ tree where:
   `.agent-src/<subdir>/`. Reading a context follows the symlink to
   the package payload.
 - `.augment/docs/guidelines/` — **symlink** into the package's
-  `docs/guidelines/` (consumer side: `vendor/event4u/agent-config/docs/guidelines/`;
+  `docs/guidelines/` (consumer side: `node_modules/@event4u/agent-config/docs/guidelines/`;
   package self-projection: `../docs/guidelines/`). This is the only
   `docs/` subdirectory exposed in `.augment/`; `docs/contracts/` and
   `docs/decisions/` are package-internal — rules that reference
@@ -70,6 +70,52 @@ them to the relative form when writing into `.agent-src/`. Hardcoding
 `.agent-src.uncompressed/` in source frontmatter or body links is
 forbidden and caught by `scripts/check_compressed_paths.py`.
 
+### Distribution model — npx-only + version-pin governance
+
+Starting with the road-to-portable-runtime cutover, the package ships
+exclusively as a **runtime resolved by `npx @event4u/agent-config`**.
+There is no Composer dependency, no `npm install` step, no `--global`
+symlink scheme. Consumers run:
+
+```bash
+npx @event4u/agent-config init      # bootstrap a project
+npx @event4u/agent-config <cmd>     # any subsequent command
+```
+
+**Why local installs are gone.** Vendoring the package into every
+consumer's `vendor/` or `node_modules/` created three problems: stale
+runtimes diverging from the published version, build-system coupling
+(Composer post-install hooks, npm postinstall scripts), and a parallel
+"global install" scheme that copied curated skills into `~/.claude/`,
+`~/.cursor/`, `~/.codeium/windsurf/` under an `event4u/` namespace.
+Maintenance cost was high, the abstractions leaked across surfaces, and
+debugging "which version is loaded" was non-trivial. `npx` resolves the
+runtime per invocation against a single npm registry source, which
+collapses all three failure modes.
+
+**How the pin replaces lockfile determinism.** A consumer-managed
+`composer.lock` / `package-lock.json` previously froze the runtime
+version per repo. Under npx-only, the equivalent role is played by the
+`agent_config_version` field in the consumer's `.agent-settings.yml`
+(see `config/agent-settings.template.yml`). The dispatcher reads the
+pin on every invocation and re-execs `npx @event4u/agent-config@<pin>`
+if the resolved version diverges (P3.2 pin-resolver). The pin lives in
+the consumer's repo, is reviewed in PRs, and survives `npx`'s own
+cache eviction.
+
+**Q1 council rejection + override + pin as substitute.** During Q1
+planning, the architecture council rejected the npx-only proposal on
+the grounds that `npx` resolution introduces a "09:00 vs 09:15
+release skew" window where two developers running the same command
+minutes apart could see different runtimes. The user overrode the
+rejection on the condition that an explicit version pin replaces
+lockfile determinism — the council's concern is real, but the pin
+collapses the skew window to whatever the project's PR cadence is.
+Pin drift across developers becomes a reviewable config change in
+`.agent-settings.yml` rather than an invisible registry-resolution
+race. ADR-pending entry will record the trade-off in full once P3 is
+green.
+
 ### Cloud-bundle pipeline
 
 `task build-cloud-bundles-all` produces one ZIP per skill at

package/docs/catalog.md

@@ -294,9 +294,9 @@ are excluded.
 | command | [`feature`](../.agent-src/commands/feature.md) | cluster: feature | Feature orchestrator — routes to explore, plan, refactor, roadmap, dev |
 | command | [`fix:ci`](../.agent-src/commands/fix/ci.md) | cluster: fix | Fetch CI errors from GitHub Actions and fix them |
 | command | [`fix:portability`](../.agent-src/commands/fix/portability.md) | cluster: fix | Find and fix project-specific references in shared .augment/ package files |
-| command | [`fix:pr-bots`](../.agent-src/commands/fix/pr-bots.md) | cluster: fix | Fix and reply to bot review comments (Copilot, Augment, Greptile, etc.) on a GitHub PR |
-| command | [`fix:pr-developers`](../.agent-src/commands/fix/pr-developers.md) | cluster: fix | Fix and reply to human reviewer comments on a GitHub PR |
-| command | [`fix:pr`](../.agent-src/commands/fix/pr.md) | cluster: fix | Fix and reply to all open review comments (bots + human reviewers) on a GitHub PR |
+| command | [`fix:pr-bot-comments`](../.agent-src/commands/fix/pr-bot-comments.md) | cluster: fix | Fix and reply to bot review comments (Copilot, Augment, Greptile, etc.) on a GitHub PR |
+| command | [`fix:pr-comments`](../.agent-src/commands/fix/pr-comments.md) | cluster: fix | Fix and reply to all open review comments (bots + human reviewers) on a GitHub PR |
+| command | [`fix:pr-developer-comments`](../.agent-src/commands/fix/pr-developer-comments.md) | cluster: fix | Fix and reply to human reviewer comments on a GitHub PR |
 | command | [`fix:refs`](../.agent-src/commands/fix/refs.md) | cluster: fix | Find and fix broken cross-references in .augment/ and agents/ files |
 | command | [`fix:seeder`](../.agent-src/commands/fix/seeder.md) | cluster: fix | Scan seeder data files for broken foreign key references — find constants used without getReference() and fix them |
 | command | [`fix`](../.agent-src/commands/fix.md) | cluster: fix | Fix orchestrator — routes to ci, references, portability, seeder, pr-comments, pr-bot-comments, pr-developer-comments |