@event4u/agent-config 2.3.0 → 2.4.1

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

@@ -40,9 +40,11 @@ One line: one-time setup, six questions, one at a time (iron law from
 
 ### 2. Offer user-global cross-project defaults
 
-Detect whether `~/.config/agent-config/agent-settings.yml` exists. Path is
-XDG-style, matches existing `~/.config/agent-config/` dir used for
-`anthropic.key`, `openai.key`, `council-spend.jsonl`.
+Detect whether `~/.event4u/agent-config/agent-settings.yml` exists (or
+legacy `~/.config/agent-config/agent-settings.yml`, read as fallback by
+every loader). New path namespaces every package-owned user-global
+artefact under one root — same place `anthropic.key`, `openai.key`,
+`council-spend.jsonl` now live.
 
 - **File exists** → skip step entirely. Re-onboarding never overwrites
   user-global file silently.
@@ -54,7 +56,7 @@ XDG-style, matches existing `~/.config/agent-config/` dir used for
   → empty → first-time setup, ask:
 
 ```
-> A user-global config at ~/.config/agent-config/agent-settings.yml lets
+> A user-global config at ~/.event4u/agent-config/agent-settings.yml lets
 > you carry your DX-comfort defaults (name, IDE, autonomy, cost profile,
 > communication style) across every project that uses event4u/agent-config.
 >
@@ -177,7 +179,7 @@ Skip unless step 2 captured explicit "yes". Re-confirm intent in one line —
 never silent-write a file outside project tree:
 
 ```
-> Writing ~/.config/agent-config/agent-settings.yml with the six
+> Writing ~/.event4u/agent-config/agent-settings.yml with the six
 > mergeable keys mirrored from this project's choices:
 >
 >   name: {personal.user_name or ""}
@@ -191,10 +193,12 @@ never silent-write a file outside project tree:
 > 2. Cancel — keep settings project-local only
 ```
 
-`1` → ensure `~/.config/agent-config/` exists (`mkdir -p`, mode `0700`),
+`1` → ensure `~/.event4u/agent-config/` exists (`mkdir -p`, mode `0700`;
+migration shim in `scripts/install.py` moves any legacy
+`~/.config/agent-config/` files into new namespace on first run),
 then write file with mode `0600`. Schema is **flat-or-nested YAML keyed on
 dotted paths** in whitelist documented in
-[`scripts/_lib/agent_settings.py`](../scripts/_lib/agent_settings.py).
+[`scripts/_lib/agent_settings.py`](../../scripts/_lib/agent_settings.py).
 Use same section-aware merge rules from
 [`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules)
 **only if file unexpectedly already exists** between step 2 and this step
@@ -263,7 +267,8 @@ Skip this block in cloud surfaces (no settings file, no log path).
   `ide`).
 - **User-global file is opt-in, one-shot, never silent.** Step 2 captures
   intent, step 9 re-confirms before actual write. If
-  `~/.config/agent-config/agent-settings.yml` already exists when
+  `~/.event4u/agent-config/agent-settings.yml` (or legacy
+  `~/.config/agent-config/agent-settings.yml`) already exists when
   `/onboard` starts, step 2 is skipped entirely — re-onboarding never
   silently rewrites developer's cross-project defaults. Use
   `/sync-agent-settings` (project-scoped only) or edit file manually for
@@ -282,4 +287,4 @@ cloud agent should proceed without invoking it.
 - [`set-cost-profile`](set-cost-profile.md) — isolated profile change
 - [`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md) — merge rules for mid-life edits
 - [`agent-settings` template](../templates/agent-settings.md) — settings reference
-- [`scripts/_lib/agent_settings.py`](../scripts/_lib/agent_settings.py) — centralized loader + whitelist that consumes the user-global file
+- [`scripts/_lib/agent_settings.py`](../../scripts/_lib/agent_settings.py) — centralized loader + whitelist that consumes the user-global file

package/.agent-src/skills/ai-council/SKILL.md

@@ -89,7 +89,7 @@ travel changes.
 
 | Mode | Client | Billable | Transport | Status |
 |---|---|---|---|---|
-| `api` | `AnthropicClient` / `OpenAIClient` | yes | provider SDK + key from `~/.config/agent-config/<provider>.key` | shipped |
+| `api` | `AnthropicClient` / `OpenAIClient` | yes | provider SDK + key from `~/.event4u/agent-config/<provider>.key` (legacy `~/.config/agent-config/<provider>.key` read as fallback) | shipped |
 | `manual` | `ManualClient` | no | `stdout` (prompt block) + `stdin` (user pastes the web-UI reply, terminated by a line containing only `END`) | shipped (Phase 2b) |
 
 Resolution lives in `scripts/ai_council/modes.py`:
@@ -338,7 +338,8 @@ Real failure modes seen in the wild:
 
 The bundler's redaction pass strips:
 
-- Paths matching `~/.config/agent-config/*.key`.
+- Paths matching `~/.event4u/agent-config/*.key` and the legacy
+  `~/.config/agent-config/*.key`.
 - Lines starting with `Authorization:`.
 - `key = …`, `secret = …`, `token = …`, `password = …` assignments.
 - `sk-ant-…` and `sk-…` token-like strings.
@@ -358,7 +359,8 @@ per-invocation caps from `ai_council.cost_budget`:
 - `max_calls` — maximum number of council members per invocation.
 - `daily_limit_usd` — rolling 24h spend cap across all `/council`
   invocations. `0` disables. Persists in
-  `~/.config/agent-config/council-spend.jsonl` (mode 0600). Breach
+  `~/.event4u/agent-config/council-spend.jsonl` (mode 0600; legacy
+  `~/.config/agent-config/council-spend.jsonl` read as fallback). Breach
   fires `on_overrun(event)` with `event.breach_kind == "daily"` and,
   if the callback returns False or is absent, tags the member
   `daily_budget_exceeded` instead of `cost_budget_exceeded`.

package/.agent-src/skills/using-git-worktrees/SKILL.md

@@ -97,7 +97,7 @@ Ask format:
 
 > 1. `.worktrees/` — project-local, hidden
 > 2. `worktrees/` — project-local, visible
-> 3. `~/.config/agent-config/worktrees/<project>/` — global
+> 3. `~/.event4u/agent-config/worktrees/<project>/` — global
 
 **Recommendation: 1 — `.worktrees/`** — project-local keeps the worktree next to the repo (easy cleanup), and the leading dot keeps it out of `ls`. Caveat: pick 3 if multiple repos must share a single worktree root.
 

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

@@ -6,10 +6,11 @@
 #
 # Precedence (lowest → highest):
 #   1. Package defaults (shipped by event4u/agent-config)
-#   2. ~/.config/agent-config/agent-settings.yml — user-global DX-comfort
+#   2. ~/.event4u/agent-config/agent-settings.yml — user-global DX-comfort
 #      defaults (whitelist: name, ide, cost_profile, personal.bot_icon,
 #      personal.autonomy, caveman.speak_scope). Created on opt-in via
-#      /onboard; project-local files always win.
+#      /onboard; project-local files always win. Legacy
+#      ~/.config/agent-config/agent-settings.yml is read as a fallback.
 #   3. This file (.agent-project-settings.yml) — team defaults
 #   4. .agent-settings.yml — developer overrides (gitignored)
 #
@@ -38,7 +39,7 @@ schema_version: 1
 # 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"
+agent_config_version: "2.3.0"
 
 # --- Project identity ---
 project:

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

@@ -5,11 +5,18 @@ how scripts read agent settings — replaces ~15 ad-hoc loaders in P3.
 
 Resolution order (deepest wins; user-global is whitelist-filtered only):
 
-  N. ``~/.config/agent-config/agent-settings.yml``  (user-global; whitelist only)
+  N. ``~/.event4u/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)
 
+The user-global path is resolved via the sibling
+:mod:`work_engine._lib.user_global_paths` module (vendored from
+``scripts/_lib/user_global_paths.py`` so the engine stays self-contained
+when shipped into consumer projects) with a read-fallback to the legacy
+``~/.config/agent-config/agent-settings.yml`` so pre-2.4 installs keep
+working during the namespace migration.
+
 ``<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
@@ -37,12 +44,26 @@ import logging
 from pathlib import Path
 from typing import Any, Iterator
 
+from . import user_global_paths
+
 logger = logging.getLogger(__name__)
 
 DEFAULT_PROJECT_FILE = ".agent-settings.yml"
-DEFAULT_USER_GLOBAL_FILE = (
-    Path.home() / ".config" / "agent-config" / "agent-settings.yml"
-)
+USER_GLOBAL_FILENAME = "agent-settings.yml"
+
+#: Canonical write target under the new ``~/.event4u/agent-config/``
+#: namespace. Reads route through :func:`_resolve_user_global_file` so
+#: pre-2.4 installs are still picked up from ``~/.config/agent-config/``
+#: until the migration shim copies them across.
+DEFAULT_USER_GLOBAL_FILE = user_global_paths.write_target(USER_GLOBAL_FILENAME)
+
+
+def _resolve_user_global_file() -> Path:
+    """Return the active user-global settings path with legacy fallback."""
+    found = user_global_paths.resolve_with_fallback(USER_GLOBAL_FILENAME)
+    if found is not None:
+        return found
+    return DEFAULT_USER_GLOBAL_FILE
 
 #: Exact dotted paths allowed to cascade from user-global into the merged
 #: settings. Anything not listed here is silently ignored when present in
@@ -129,7 +150,8 @@ def load_agent_settings(
 
     ``project_path`` defaults to ``./.agent-settings.yml`` (CWD-relative).
     ``user_global_path`` defaults to
-    ``~/.config/agent-config/agent-settings.yml``. Both arguments accept
+    ``~/.event4u/agent-config/agent-settings.yml`` (with a read fallback
+    to the legacy ``~/.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.
 
@@ -143,7 +165,7 @@ def load_agent_settings(
     with pre-cascade callers.
     """
     user_global_raw = _read_yaml(
-        Path(user_global_path) if user_global_path else DEFAULT_USER_GLOBAL_FILE,
+        Path(user_global_path) if user_global_path else _resolve_user_global_file(),
     ) or {}
 
     user_global_filtered, ignored = _filter_whitelist(
@@ -181,7 +203,7 @@ def iter_setting_overrides(
     Never blocks, never raises on missing files.
     """
     user_global_path_resolved = (
-        Path(user_global_path) if user_global_path else DEFAULT_USER_GLOBAL_FILE
+        Path(user_global_path) if user_global_path else _resolve_user_global_file()
     )
     user_global_raw = _read_yaml(user_global_path_resolved) or {}
     user_global_filtered, _ = _filter_whitelist(user_global_raw, MERGEABLE_KEYS)

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

@@ -0,0 +1,249 @@
+"""Vendor-namespaced user-global path resolution.
+
+Phase 1 of road-to-event4u-namespace-and-claude-desktop.md. Single source
+of truth for "where does this package keep user-global state on disk?".
+Replaces hard-coded ``~/.config/agent-config/`` literals scattered across
+``scripts/_lib`` and ``scripts/ai_council``.
+
+Resolution order:
+
+  1. ``$EVENT4U_CONFIG_HOME``  — full path override (testing + power users).
+  2. ``~/.event4u/agent-config/``  — vendor-namespaced source-of-truth.
+
+For backward compatibility during the transition, ``legacy_xdg_root()``
+exposes the old ``~/.config/agent-config/`` path so loaders can read
+state written by pre-2.4 installs. Writers should never target the
+legacy path; the auto-migration shim (Phase 3) copies state once into
+the new namespace.
+
+Contract — pure, read-only, never auto-creates directories.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+from pathlib import Path
+from typing import Optional
+
+#: Marker suffix for in-progress entry copies during migration. A copy
+#: that crashes mid-flight leaves ``<name><suffix><pid>`` behind so the
+#: next run can clean it up before retrying — instead of treating a
+#: partial subdir as a completed copy.
+_PARTIAL_SUFFIX = ".event4u-partial-"
+
+#: Environment variable that overrides ``event4u_root()`` outright.
+#: Accepts a full path (``~`` expanded). Primarily used by tests; power
+#: users may also point this at a custom location.
+EVENT4U_HOME_ENV = "EVENT4U_CONFIG_HOME"
+
+#: Vendor-namespaced default. Relative to the user's home directory.
+DEFAULT_EVENT4U_ROOT_RELATIVE = Path(".event4u") / "agent-config"
+
+#: Legacy XDG-shaped default written by pre-2.4 installs. Read-only
+#: fallback during the transition; never the target of a write.
+LEGACY_XDG_ROOT_RELATIVE = Path(".config") / "agent-config"
+
+
+def event4u_root(env: Optional[dict] = None) -> Path:
+    """Return the active user-global root directory.
+
+    Honours ``EVENT4U_CONFIG_HOME`` first, falls back to
+    ``~/.event4u/agent-config/``. Never creates the directory.
+    """
+    env_map = env if env is not None else os.environ
+    override = env_map.get(EVENT4U_HOME_ENV)
+    if override:
+        return Path(override).expanduser()
+    return Path.home() / DEFAULT_EVENT4U_ROOT_RELATIVE
+
+
+def legacy_xdg_root() -> Path:
+    """Return the pre-2.4 user-global root at ``~/.config/agent-config/``.
+
+    Used by loaders during the transition to read settings, lockfiles,
+    and keys written before the namespace migration ran. Writers MUST
+    NOT target this path — only ``event4u_root()`` is a valid write
+    target. Never creates the directory.
+    """
+    return Path.home() / LEGACY_XDG_ROOT_RELATIVE
+
+
+def resolve_with_fallback(
+    relative_name: str,
+    *,
+    env: Optional[dict] = None,
+) -> Optional[Path]:
+    """Resolve a named file/dir under the user-global root, with legacy fallback.
+
+    Returns the new-namespace path if it exists on disk, otherwise the
+    legacy XDG path if it exists, otherwise ``None``. Callers that need
+    the *write target* (regardless of existence) should use
+    ``event4u_root() / relative_name`` directly.
+
+    ``relative_name`` is a forward-slash separated string (e.g.
+    ``"installed.lock"`` or ``"agents/global"``). It is treated as a
+    path fragment relative to the chosen root; absolute paths are
+    rejected with ``ValueError``.
+    """
+    fragment = Path(relative_name)
+    if fragment.is_absolute():
+        raise ValueError(
+            f"resolve_with_fallback expects a relative path, got {relative_name!r}"
+        )
+    new_path = event4u_root(env=env) / fragment
+    if new_path.exists():
+        return new_path
+    legacy_path = legacy_xdg_root() / fragment
+    if legacy_path.exists():
+        return legacy_path
+    return None
+
+
+def write_target(relative_name: str, *, env: Optional[dict] = None) -> Path:
+    """Return the canonical write target for a named user-global file/dir.
+
+    Always rooted at ``event4u_root()`` — writers never target the
+    legacy XDG path. Caller is responsible for ``mkdir(parents=True)``
+    on the parent before writing. Never creates the directory itself.
+    """
+    fragment = Path(relative_name)
+    if fragment.is_absolute():
+        raise ValueError(
+            f"write_target expects a relative path, got {relative_name!r}"
+        )
+    return event4u_root(env=env) / fragment
+
+
+#: Breadcrumb dropped into the legacy root after a successful migration.
+#: Tells the user where their state now lives and how to clean up. The
+#: legacy tree itself is never auto-deleted — only the user does that.
+MIGRATION_BREADCRUMB_NAME = "MIGRATED.md"
+
+_BREADCRUMB_TEMPLATE = """# Migrated to `~/.event4u/agent-config/`
+
+This directory (`~/.config/agent-config/`) is the **legacy** location
+for `event4u/agent-config` user-global state. As of v2.4 the canonical
+location is `~/.event4u/agent-config/`.
+
+The migration shim has already copied your settings, keys, lockfiles,
+and overrides into the new namespace. File modes (0600 on keys) were
+preserved. Loaders prefer the new path but still read from this tree
+as a fallback, so removing it is safe **once you've confirmed** the
+new location is working.
+
+## To clean up
+
+```bash
+rm -rf ~/.config/agent-config
+```
+
+## Why the move
+
+`~/.config/` is a generic XDG-shaped directory shared by many tools.
+`~/.event4u/agent-config/` is vendor-namespaced and avoids collisions
+with unrelated CLIs. See
+`agents/roadmaps/road-to-event4u-namespace-and-claude-desktop.md` for
+the full rationale.
+"""
+
+
+def migrate_legacy_namespace(
+    *,
+    env: Optional[dict] = None,
+    legacy_root_override: Optional[Path] = None,
+) -> bool:
+    """Copy pre-2.4 user-global state from legacy XDG root into the new namespace.
+
+    Idempotent and safe to call on every install / init. Returns ``True``
+    if a copy ran during this invocation, ``False`` when the migration
+    was already complete or there was nothing to migrate.
+
+    Contract:
+
+    - Never auto-deletes the legacy tree — that's the user's call (the
+      breadcrumb at ``~/.config/agent-config/MIGRATED.md`` documents it).
+    - Preserves file modes via ``shutil.copytree(..., copy_function=copy2)``
+      so 0600 key files stay 0600 after the copy.
+    - If the new root already exists with any content, the migration
+      treats it as already-done and only writes the breadcrumb (if
+      missing) — never overwrites new-namespace state.
+    - If the legacy root is missing or empty, the function is a no-op.
+    - Per-entry atomic write: each entry is copied to a sibling
+      ``<name>.event4u-partial-<pid>`` and then ``os.replace``'d into
+      the final name. If a previous run crashed mid-``copytree``, the
+      leftover ``*.event4u-partial-*`` siblings are cleaned up at the
+      top of the next run before retrying — a partial directory is
+      never mistaken for a completed copy.
+
+    ``legacy_root_override`` is for tests; production callers leave it ``None``.
+    """
+    legacy_root = (
+        legacy_root_override if legacy_root_override is not None else legacy_xdg_root()
+    )
+    new_root = event4u_root(env=env)
+
+    if not legacy_root.exists() or not legacy_root.is_dir():
+        return False
+
+    # Skip the migrated-breadcrumb itself when checking for content so a
+    # second invocation does not loop on its own marker.
+    legacy_entries = [
+        p for p in legacy_root.iterdir() if p.name != MIGRATION_BREADCRUMB_NAME
+    ]
+    if not legacy_entries:
+        return False
+
+    # Real content check ignores partial-copy debris from a prior
+    # interrupted run; otherwise the breadcrumb would be written for
+    # a half-finished migration and retry would never run.
+    new_has_content = new_root.exists() and any(
+        not _is_partial_entry(p) for p in new_root.iterdir()
+    )
+    if new_has_content:
+        _ensure_breadcrumb(legacy_root)
+        return False
+
+    new_root.mkdir(parents=True, exist_ok=True)
+    _purge_partial_entries(new_root)
+
+    for entry in legacy_entries:
+        target = new_root / entry.name
+        if target.exists():
+            continue
+        staging = new_root / f"{entry.name}{_PARTIAL_SUFFIX}{os.getpid()}"
+        if staging.exists():
+            _remove_path(staging)
+        if entry.is_dir():
+            shutil.copytree(entry, staging, copy_function=shutil.copy2)
+        else:
+            shutil.copy2(entry, staging)
+        os.replace(staging, target)
+
+    _ensure_breadcrumb(legacy_root)
+    return True
+
+
+def _is_partial_entry(path: Path) -> bool:
+    return _PARTIAL_SUFFIX in path.name
+
+
+def _purge_partial_entries(new_root: Path) -> None:
+    """Remove ``*.event4u-partial-*`` leftovers from a previous interrupted run."""
+    for entry in new_root.iterdir():
+        if _is_partial_entry(entry):
+            _remove_path(entry)
+
+
+def _remove_path(path: Path) -> None:
+    if path.is_dir() and not path.is_symlink():
+        shutil.rmtree(path)
+    else:
+        path.unlink(missing_ok=True)
+
+
+def _ensure_breadcrumb(legacy_root: Path) -> None:
+    """Write the ``MIGRATED.md`` breadcrumb into ``legacy_root`` if absent."""
+    breadcrumb = legacy_root / MIGRATION_BREADCRUMB_NAME
+    if breadcrumb.exists():
+        return
+    breadcrumb.write_text(_BREADCRUMB_TEMPLATE, encoding="utf-8")

package/.agent-src/templates/scripts/work_engine/hooks/settings.py

@@ -17,8 +17,9 @@ settings.py``):
 Per road-to-portable-dev-preferences P3, the YAML read goes through
 :func:`work_engine._lib.agent_settings.load_agent_settings`, which
 cascades the whitelisted ``cost_profile`` (and other DX-comfort keys)
-from ``~/.config/agent-config/agent-settings.yml`` when the project
-file omits them. Project values always win.
+from ``~/.event4u/agent-config/agent-settings.yml`` (legacy
+``~/.config/agent-config/agent-settings.yml`` read as fallback) when
+the project file omits them. Project values always win.
 """
 from __future__ import annotations
 
@@ -67,9 +68,11 @@ def load_hook_settings(
     ``settings_path`` defaults to ``./.agent-settings.yml`` relative to
     the current working directory — same convention as chat-history.
     ``user_global_path`` defaults to
-    ``~/.config/agent-config/agent-settings.yml`` and only cascades the
-    whitelisted DX-comfort keys (currently ``cost_profile``) when the
-    project file omits them. See road-to-portable-dev-preferences P3.
+    ``~/.event4u/agent-config/agent-settings.yml`` (with a read fallback
+    to the legacy ``~/.config/agent-config/agent-settings.yml``) and
+    only cascades the whitelisted DX-comfort keys (currently
+    ``cost_profile``) when the project file omits them. See
+    road-to-portable-dev-preferences P3.
     """
     path = Path(settings_path) if settings_path else Path(DEFAULT_SETTINGS_FILE)
     raw = load_agent_settings(

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": "2.3.0",
+    "version": "2.4.1",
     "keywords": [
       "agent-config",
       "skills",

package/CHANGELOG.md

@@ -343,6 +343,45 @@ our recommendation order, not its support status.
   users" tension without removing any path that an existing user
   might rely on.
 
+## [2.4.1](https://github.com/event4u-app/agent-config/compare/2.4.0...2.4.1) (2026-05-13)
+
+### Bug Fixes
+
+* **install:** write lockfile to canonical event4u namespace ([ca57607](https://github.com/event4u-app/agent-config/commit/ca5760785f150903bcad74e278b59e534f83634d))
+* **install:** source global deploy from .agent-src/ subdirectories ([f151caf](https://github.com/event4u-app/agent-config/commit/f151caf854d9ce8519bc244d441a7c8bf73e7fde))
+
+Tests: 3521 (+0 since 2.4.0)
+
+## [2.4.0](https://github.com/event4u-app/agent-config/compare/2.3.0...2.4.0) (2026-05-13)
+
+### Features
+
+* **install:** Claude Desktop ZIP bundle deployment ([9f2a00c](https://github.com/event4u-app/agent-config/commit/9f2a00cfd752232abdcf16c6e3440c46f5c9d596))
+* **install:** event4u namespace and auto-migration shim ([a58570e](https://github.com/event4u-app/agent-config/commit/a58570ecff885a7d50350c4281e675d7ff34f912))
+
+### Bug Fixes
+
+* **agent_settings:** align source with template via relative import ([a85b6c8](https://github.com/event4u-app/agent-config/commit/a85b6c82284310876d075a924918052fc7dbabdb))
+* **work_engine:** vendor user_global_paths into template for self-contained import ([f111c4e](https://github.com/event4u-app/agent-config/commit/f111c4e60de6cd60fbe81635029f9f34437a5ead))
+* **migrate:** atomic per-entry write with partial-debris purge ([5bd5aad](https://github.com/event4u-app/agent-config/commit/5bd5aadf0085657ec98eee049dda440d05b06801))
+
+### Documentation
+
+* **roadmap:** mark Steps 5-6 done (commit + PR opened) ([8492b7f](https://github.com/event4u-app/agent-config/commit/8492b7fd3cfd76075a64d5de770db2c5013e02dd))
+* **adr:** ADR-009 rollback section + AI Council convergence ([cc78adc](https://github.com/event4u-app/agent-config/commit/cc78adc0a9d0fbc51b2a65f35d8e0f13c1456a2f))
+* **contracts:** mark installed-tools-lockfile as beta ([90991da](https://github.com/event4u-app/agent-config/commit/90991da2f840ebae978fc4df9996c01324816404))
+* **adr:** ADR-009 event4u namespace + Claude Desktop ZIP bundles ([c707bd3](https://github.com/event4u-app/agent-config/commit/c707bd31211f94ace858738b7aee8d3898f0da88))
+* **roadmap:** add road-to-event4u-namespace-and-claude-desktop ([d92706b](https://github.com/event4u-app/agent-config/commit/d92706bd53621ff3a225db6eb9ee490f17f613d2))
+
+### Chores
+
+* **onboard:** rephrase 'event4u-owned' as 'package-owned' ([4bdd43b](https://github.com/event4u-app/agent-config/commit/4bdd43b7a6637a36cfa377045b6cd0f3f51b0fd1))
+* **template:** bump agent_config_version pin to 2.3.0 ([1180bf2](https://github.com/event4u-app/agent-config/commit/1180bf263f2f33fb5b41b13439c92cfbdc3a70d8))
+* **index:** regenerate index + catalog for accurate counts ([655a5eb](https://github.com/event4u-app/agent-config/commit/655a5eb81ce6744548a6f50451f66576a7c2b5ac))
+* **sync:** regenerate derived outputs for event4u namespace ([c277a94](https://github.com/event4u-app/agent-config/commit/c277a94f881ad4702ed2e97cebf6c5a7c8471a35))
+
+Tests: 3521 (+31 since 2.3.0)
+
 ## [2.3.0](https://github.com/event4u-app/agent-config/compare/2.2.2...2.3.0) (2026-05-13)
 
 ### Features

package/config/agent-settings.template.yml

@@ -237,8 +237,9 @@ worktrees:
 # roadmap, diff, prompt, or file set. Council members never see the
 # host agent's reasoning — only the artefact + a neutral system prompt.
 #
-# Tokens are NEVER stored here. They live in ~/.config/agent-config/
-# <provider>.key (mode 0600), installed via:
+# Tokens are NEVER stored here. They live in ~/.event4u/agent-config/
+# <provider>.key (mode 0600; legacy ~/.config/agent-config/<provider>.key
+# is read as a fallback), installed via:
 #   bash scripts/install_anthropic_key.sh
 #   bash scripts/install_openai_key.sh
 #
@@ -396,7 +397,8 @@ memory:
 # 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
+# `~/.event4u/agent-config/update-check.json` (mode 0600; legacy
+# `~/.config/agent-config/update-check.json` read as fallback) 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:

package/docs/catalog.md

@@ -1,6 +1,6 @@
 # agent-config — Public Catalog
 
-Consumer-facing catalog of all **406 public artefacts** shipped by
+Consumer-facing catalog of all **408 public artefacts** shipped by
 this package. Internal package-maintenance rules and deprecation shims
 are excluded.
 
@@ -186,7 +186,7 @@ are excluded.
 | skill | [`voc-extract`](../.agent-src/skills/voc-extract/SKILL.md) |  | Use when extracting Voice-of-Customer themes from existing artefacts — GH issues, PR threads, Sentry patterns. Triggers on 'what are users saying', 'recurring complaints', 'top themes'. |
 | skill | [`websocket`](../.agent-src/skills/websocket/SKILL.md) |  | Use when building real-time features — WebSocket broadcasting, live updates, presence channels, connection state — even when the user just says 'push this to the client live'. |
 
-## Rules (57)
+## Rules (58)
 
 | kind | name | type | description |
 |---|---|---|---|
@@ -210,6 +210,7 @@ are excluded.
 | rule | [`domain-adoption-policy`](../.agent-src/rules/domain-adoption-policy.md) | auto | Adopting a new domain track (mobile, ML, blockchain, IoT, gaming) — gates import on demand, ownership, CI fit, Sunset compatibility BEFORE harvest |
 | rule | [`downstream-changes`](../.agent-src/rules/downstream-changes.md) | auto | After EVERY code edit, find ALL downstream changes needed to existing files, including callers, tests, imports, types, and documentation |
 | rule | [`e2e-testing`](../.agent-src/rules/e2e-testing.md) | auto | Playwright E2E tests — locators, assertions, Page Objects, fixtures, CI, and flaky test prevention |
+| rule | [`external-reference-deep-dive`](../.agent-src/rules/external-reference-deep-dive.md) | auto | 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 |
 | rule | [`guidelines`](../.agent-src/rules/guidelines.md) | manual | Writing or reviewing code — check relevant guideline before writing or reviewing code |
 | rule | [`improve-before-implement`](../.agent-src/rules/improve-before-implement.md) | auto | Before implementing features or architectural changes — validate the request against existing code, challenge weak requirements, suggest improvements |
 | rule | [`invite-challenge`](../.agent-src/rules/invite-challenge.md) | auto | Before executing a complex plan or non-trivial design — ask 'am I solving the right problem?' and pause for user confirmation, even when no ambiguity |
@@ -359,7 +360,7 @@ are excluded.
 | command | [`upstream-contribute`](../.agent-src/commands/upstream-contribute.md) |  | Contribute a learning, skill, rule, or fix from a consumer project back to the shared agent-config package |
 | command | [`work`](../.agent-src/commands/work.md) |  | Drive a free-form prompt end-to-end through refine → score → plan → implement → test → verify → report — Option-A loop over the `work_engine` Python engine, confidence-band gated, no auto-git. |
 
-## Guidelines (69)
+## Guidelines (70)
 
 | kind | name | category | description |
 |---|---|---|---|
@@ -374,6 +375,7 @@ are excluded.
 | guideline | [`direct-answers-demos`](../docs/guidelines/agent-infra/direct-answers-demos.md) | agent-infra |  |
 | guideline | [`engineering-memory-data-format`](../docs/guidelines/agent-infra/engineering-memory-data-format.md) | agent-infra |  |
 | guideline | [`first-principles`](../docs/guidelines/agent-infra/first-principles.md) | agent-infra |  |
+| guideline | [`installed-tools-manifest`](../docs/guidelines/agent-infra/installed-tools-manifest.md) | agent-infra |  |
 | guideline | [`inversion-thinking`](../docs/guidelines/agent-infra/inversion-thinking.md) | agent-infra |  |
 | guideline | [`ios-simulator-guide`](../docs/guidelines/agent-infra/ios-simulator-guide.md) | agent-infra |  |
 | guideline | [`language-and-tone-examples`](../docs/guidelines/agent-infra/language-and-tone-examples.md) | agent-infra |  |

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

@@ -1,3 +1,7 @@
+---
+stability: beta
+---
+
 # Installed-Tools Lockfile — Wire Contract
 
 Canonical wire-format spec for `agents/installed-tools.lock` — the