@event4u/agent-config 1.41.1 → 2.0.0

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.1"
+    "version": "2.0.0"
   },
   "plugins": [
     {

package/CHANGELOG.md

@@ -318,6 +318,37 @@ our recommendation order, not its support status.
   users" tension without removing any path that an existing user
   might rely on.
 
+## [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
+
+* **roadmap:** invert portable-runtime to npx-only distribution ([f8f6594](https://github.com/event4u-app/agent-config/commit/f8f65944490f69528616d21f4aa008c7c3d0bfa9))
+
+Tests: 3173 (+0 since 1.41.1)
+
 ## [1.41.1](https://github.com/event4u-app/agent-config/compare/1.41.0...1.41.1) (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
@@ -410,9 +418,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

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

@@ -518,8 +518,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 +526,16 @@ The underlying stages keep their own CLI surfaces:
 
 ---
 
-## Global user-level install (`--global`)
+## Global user-level install — retired
 
-`--global` ships a curated subset of kernel rules + top-N skills into
-**per-tool user-scope directories**, so the agent has them in every
-project on the machine without a per-project install.
-
-```bash
-# Default: every supported surface, namespaced under event4u/.
-bash scripts/install --global
-
-# Scope to specific surfaces (mirrors the project install --tools flag).
-bash scripts/install --global --tools=claude-code,cursor
-
-# Remove only what we put there — never touches user files.
-bash scripts/install --global --uninstall
-```
-
-| Surface       | Target directory                                                |
-| ------------- | --------------------------------------------------------------- |
-| Claude Code   | `~/.claude/rules/event4u/`, `~/.claude/skills/event4u/`         |
-| Cursor        | `~/.cursor/rules/imported/event4u/{rules,skills}/`              |
-| Windsurf      | `~/.codeium/windsurf/global_workflows/event4u/{rules,skills}/`  |
-| Fallback      | `~/.config/agent-config/{rules,skills}/event4u/`                |
-
-The fallback path is always written so an editor we don't yet know
-about can still pick the files up.
-
-**Curation source:** `templates/global-install-manifest.yml`. Edit
-post-install to grow or shrink the global set; re-run `--global` to
-re-project. `--uninstall` only removes the `event4u/` namespace —
-user-added rules / skills under sibling paths stay untouched.
-
-**When to use:** running multiple unrelated projects where a per-project
-install is overkill, or wiring up a new editor (Claude Desktop, Cursor)
-that benefits from a baseline set of skills out of the box.
+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.
 
 ---