@event4u/agent-config 2.3.0 → 2.4.0

package/scripts/_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/scripts/ai_council/__init__.py

@@ -13,9 +13,10 @@ Architecture:
     prompts.py      — Neutrality system-prompt templates per input mode.
 
 Trust boundary: this module makes networked, paid calls. Tokens come
-exclusively from ~/.config/agent-config/<provider>.key (mode 0600). The
-module never edits files, never opens PRs, never merges — output is
-text only, advisory.
+exclusively from ``~/.event4u/agent-config/<provider>.key`` (mode 0600;
+legacy ``~/.config/agent-config/<provider>.key`` is read as a fallback
+for pre-2.4 installs). The module never edits files, never opens PRs,
+never merges — output is text only, advisory.
 """
 
 from scripts.ai_council.clients import (

package/scripts/ai_council/budget_guard.py

@@ -2,8 +2,12 @@
 
 Adds a 24h-rolling-window USD limit on top of the per-session caps in
 `orchestrator.CostBudget`. Persists a small JSONL ledger in
-``~/.config/agent-config/council-spend.jsonl`` (mode 0600, same
-permission discipline as the API keys).
+``~/.event4u/agent-config/council-spend.jsonl`` (mode 0600, same
+permission discipline as the API keys). The legacy
+``~/.config/agent-config/council-spend.jsonl`` is read as a fallback so
+spend history accumulated under a pre-2.4 install is preserved across
+the namespace migration; new entries are always appended to the new
+path.
 
 Contract
 - The ledger is **append-only**. Each line is ``{"ts": ISO-8601 UTC,
@@ -31,10 +35,34 @@ import sys
 from dataclasses import dataclass
 from pathlib import Path
 
-LEDGER_PATH = Path.home() / ".config" / "agent-config" / "council-spend.jsonl"
+from scripts._lib import user_global_paths
+
+LEDGER_FILENAME = "council-spend.jsonl"
+
+#: Canonical write target under the new namespace. Reads route via
+#: :func:`_resolve_ledger_path` so a ledger still sitting in the legacy
+#: ``~/.config/agent-config/`` tree keeps contributing to the rolling
+#: window until the user migrates.
+LEDGER_PATH = user_global_paths.write_target(LEDGER_FILENAME)
 ROLLING_WINDOW_HOURS = 24
 
 
+def _resolve_ledger_path(path: Path | None) -> Path:
+    """Return the active ledger path, preferring the new namespace.
+
+    A caller-supplied ``path`` always wins (tests pin a tmp file). When
+    no override is given we prefer the new namespace, then fall back to
+    the legacy location if a ledger file already exists there. New
+    writes always target the new namespace via :data:`LEDGER_PATH`.
+    """
+    if path is not None:
+        return path
+    found = user_global_paths.resolve_with_fallback(LEDGER_FILENAME)
+    if found is not None:
+        return found
+    return LEDGER_PATH
+
+
 @dataclass
 class SpendEntry:
     ts: _dt.datetime  # UTC, tz-aware
@@ -87,8 +115,10 @@ def read_entries(path: Path | None = None) -> list[SpendEntry]:
     """Read every well-formed entry from the ledger.
 
     Malformed lines are skipped silently. Empty/missing ledger → [].
+    Reads route through :func:`_resolve_ledger_path` so a legacy ledger
+    keeps contributing to the rolling window until the user migrates.
     """
-    p = path or LEDGER_PATH
+    p = _resolve_ledger_path(path)
     if not p.exists():
         return []
     out: list[SpendEntry] = []

package/scripts/ai_council/bundler.py

@@ -38,6 +38,8 @@ class CouncilContext:
 # placeholder. Order matters — the most specific pattern goes first.
 
 _REDACTION_LINE_PATTERNS: list[tuple[re.Pattern[str], str]] = [
+    (re.compile(r"~?/?\.event4u/agent-config/[^/\s]+\.key"),
+     "[redacted: agent-config key path]"),
     (re.compile(r"~?/?\.config/agent-config/[^/\s]+\.key"),
      "[redacted: agent-config key path]"),
     (re.compile(r"^\s*Authorization:\s", re.IGNORECASE),

package/scripts/ai_council/clients.py

@@ -1,7 +1,10 @@
 """External-AI clients for the council.
 
 Mirrors the contract from `scripts/skill_trigger_eval.py`:
-- Tokens come exclusively from ~/.config/agent-config/<provider>.key.
+- Tokens come exclusively from ``~/.event4u/agent-config/<provider>.key``
+  (legacy ``~/.config/agent-config/<provider>.key`` is read as a
+  fallback so pre-2.4 installs keep working until the user moves the
+  files into the new namespace).
 - File mode must be exactly 0o600. Drift is a hard abort.
 - No environment-variable fallback. No keychain fallback.
 - Real SDKs (`anthropic`, `openai`) are *soft* dependencies — the
@@ -28,8 +31,24 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import TextIO
 
-ANTHROPIC_KEY_PATH = Path.home() / ".config" / "agent-config" / "anthropic.key"
-OPENAI_KEY_PATH = Path.home() / ".config" / "agent-config" / "openai.key"
+from scripts._lib import user_global_paths
+
+ANTHROPIC_KEY_FILENAME = "anthropic.key"
+OPENAI_KEY_FILENAME = "openai.key"
+
+#: Canonical write target under the new namespace. Reads route via
+#: :func:`_resolve_key_path` so a key still sitting in the legacy
+#: ``~/.config/agent-config/`` tree keeps working.
+ANTHROPIC_KEY_PATH = user_global_paths.write_target(ANTHROPIC_KEY_FILENAME)
+OPENAI_KEY_PATH = user_global_paths.write_target(OPENAI_KEY_FILENAME)
+
+
+def _resolve_key_path(filename: str) -> Path:
+    """Return the active key path, preferring the new namespace."""
+    found = user_global_paths.resolve_with_fallback(filename)
+    if found is not None:
+        return found
+    return user_global_paths.write_target(filename)
 
 DEFAULT_ANTHROPIC_MODEL = "claude-sonnet-4-5"
 DEFAULT_OPENAI_MODEL = "gpt-4o"
@@ -87,12 +106,14 @@ def _load_key(path: Path, prefix: str, install_script: str) -> str:
     return key
 
 
-def load_anthropic_key(path: Path = ANTHROPIC_KEY_PATH) -> str:
-    return _load_key(path, "sk-ant-", "scripts/install_anthropic_key.sh")
+def load_anthropic_key(path: Path | None = None) -> str:
+    resolved = path if path is not None else _resolve_key_path(ANTHROPIC_KEY_FILENAME)
+    return _load_key(resolved, "sk-ant-", "scripts/install_anthropic_key.sh")
 
 
-def load_openai_key(path: Path = OPENAI_KEY_PATH) -> str:
-    return _load_key(path, "sk-", "scripts/install_openai_key.sh")
+def load_openai_key(path: Path | None = None) -> str:
+    resolved = path if path is not None else _resolve_key_path(OPENAI_KEY_FILENAME)
+    return _load_key(resolved, "sk-", "scripts/install_openai_key.sh")
 
 
 class ExternalAIClient(ABC):

package/scripts/install.py

@@ -2158,17 +2158,34 @@ _CLAUDE_DESKTOP_MARKER_TEMPLATE = """\
 
 Installed by `@event4u/agent-config` (user scope, ADR-007).
 
-- Lockfile: `{lockfile}`
-- Anchor:   `{anchor}`
+- Lockfile:    `{lockfile}`
+- Anchor:      `{anchor}`
+- Skill bundles: `{bundles_dir}` ({bundle_count} ZIPs)
 
-Claude Desktop has no native rules / skills filesystem convention; this
-file is informational. Rules and skills for AI coding tools are deployed
-to their respective user-scope directories (`~/.claude/`, `~/.augment/`,
-`~/.cursor/`, `~/.codeium/windsurf/`, `~/Documents/Cline/Rules/`).
+## Import skills into Claude Desktop
+
+Claude Desktop has no filesystem skill-discovery convention — skills are
+imported manually via the Customize → Skills UI.
+
+1. Open Claude Desktop → **Settings → Customize → Skills**.
+2. Click the **Upload skill** button.
+3. Browse to `{bundles_dir}` and pick the `<skill-name>.zip` files you
+   want to install. One ZIP = one skill.
+4. Repeat per skill. Claude Desktop keeps each upload until you remove it.
+
+The bundle directory is regenerated on every
+`npx @event4u/agent-config init --tools=claude-desktop` run (only
+changed skills are rewritten — content-hash idempotency).
 
 To remove this marker, delete this file.
 """
 
+#: Subpath under ``~/.event4u/agent-config/`` where Claude Desktop ZIP
+#: bundles are written. Kept separate from the per-tool USER_SCOPE_PATHS
+#: anchor (which is the Claude Desktop config dir) because bundles are
+#: package-owned, not Claude-owned, content.
+_CLAUDE_DESKTOP_BUNDLES_SUBPATH = "claude-desktop/bundles"
+
 
 def _bridge_marker(tool_id: str, scope: str) -> str:
     """Return the canonical bridge-marker path for ``(tool_id, scope)``.
@@ -2477,6 +2494,24 @@ def _load_installed_tools_module():
     return installed_tools
 
 
+def _load_user_global_paths_module():
+    """Lazy-import ``scripts._lib.user_global_paths`` (Phase 3 migration shim)."""
+    pkg_root = str(Path(__file__).resolve().parents[1])
+    if pkg_root not in sys.path:
+        sys.path.insert(0, pkg_root)
+    from scripts._lib import user_global_paths  # noqa: WPS433 — lazy by design
+    return user_global_paths
+
+
+def _load_claude_desktop_bundler_module():
+    """Lazy-import ``scripts._lib.claude_desktop_bundler`` (Phase 4 ZIP bundler)."""
+    pkg_root = str(Path(__file__).resolve().parents[1])
+    if pkg_root not in sys.path:
+        sys.path.insert(0, pkg_root)
+    from scripts._lib import claude_desktop_bundler  # noqa: WPS433 — lazy by design
+    return claude_desktop_bundler
+
+
 def _sha256_of_file(path: Path) -> Optional[str]:
     """Return the hex SHA-256 of ``path`` content, or ``None`` if unreadable.
 
@@ -2794,29 +2829,68 @@ def _copy_dir_dereferencing_symlinks(
     return (written, skipped, written_paths)
 
 
+def _claude_desktop_bundles_dir() -> Path:
+    """Return the canonical bundle output dir under the event4u namespace.
+
+    Located via :func:`user_global_paths.write_target` so the path
+    honours the ``EVENT4U_HOME`` env override used by tests.
+    """
+    paths_mod = _load_user_global_paths_module()
+    return paths_mod.write_target(_CLAUDE_DESKTOP_BUNDLES_SUBPATH)
+
+
 def _write_claude_desktop_marker(
-    force: bool, lockfile_path: Path,
+    force: bool,
+    lockfile_path: Path,
+    *,
+    bundles_dir: Path,
+    bundle_count: int,
 ) -> tuple[int, int, list[Path]]:
     """Write the Claude Desktop user-scope marker file.
 
     Returns ``(written, skipped, written_paths)`` for symmetry with the
-    tree copier (P1.4). The marker is a single Markdown file; existing
-    files are preserved unless ``force=True``.
+    tree copier (P1.4). The marker points users at ``bundles_dir`` for
+    the Customize → Skills import flow (Phase 4). Existing markers are
+    overwritten unconditionally because the bundle count is part of the
+    body and we want it to stay current.
     """
     anchor = Path(USER_SCOPE_PATHS["claude-desktop"]).expanduser()
     target = anchor / "agent-config.md"
-    decision = _resolve_file_conflict(target, force_hint=force)
-    if decision == "skip":
-        return (0, 1, [])
     anchor.mkdir(parents=True, exist_ok=True)
     body = _CLAUDE_DESKTOP_MARKER_TEMPLATE.format(
         lockfile=str(lockfile_path),
         anchor=str(anchor),
+        bundles_dir=str(bundles_dir),
+        bundle_count=bundle_count,
     )
     target.write_text(body, encoding="utf-8")
     return (1, 0, [target])
 
 
+def _deploy_claude_desktop(
+    force: bool, package_root: Path, lockfile_path: Path,
+) -> tuple[int, int, str, list[Path]]:
+    """Build skill ZIP bundles + write the marker for ``claude-desktop``.
+
+    Phase 4 of road-to-event4u-namespace-and-claude-desktop. Bundles
+    land in ``~/.event4u/agent-config/claude-desktop/bundles/``; the
+    marker file in the Claude Desktop config dir points at them with
+    Customize → Skills import instructions.
+
+    Returns ``(bundle_count, 0, "deployed", [bundles_dir, marker])``.
+    The ``deployed`` status replaces the v2.3 ``marker``-only status.
+    """
+    bundler = _load_claude_desktop_bundler_module()
+    bundles_dir = _claude_desktop_bundles_dir()
+    bundler.build_skill_bundles(package_root, bundles_dir, force=force)
+    # Count total existing ZIPs (idempotent runs may not rewrite any).
+    bundle_count = sum(1 for _ in bundles_dir.glob("*.zip")) if bundles_dir.is_dir() else 0
+    _, _, marker_paths = _write_claude_desktop_marker(
+        force, lockfile_path, bundles_dir=bundles_dir, bundle_count=bundle_count,
+    )
+    return (bundle_count, 0, "deployed", [bundles_dir, *marker_paths])
+
+
 def _deploy_global_content(
     tools: set[str],
     force: bool,
@@ -2827,20 +2901,21 @@ def _deploy_global_content(
 
     For each tool in ``tools`` that has a ``GLOBAL_DEPLOY_SOURCES`` entry,
     copies the listed package subtrees into ``USER_SCOPE_PATHS[tool_id]``
-    (expanded). For ``claude-desktop`` writes the marker file. For tools
-    without a deployment plan (e.g. ``copilot``), records a ``hint`` status
-    so the caller can print an actionable next step.
+    (expanded). For ``claude-desktop`` builds per-skill ZIP bundles under
+    ``~/.event4u/agent-config/claude-desktop/bundles/`` and writes the
+    marker file pointing at them (Phase 4). For tools without a deployment
+    plan (e.g. ``copilot``), records a ``hint`` status so the caller can
+    print an actionable next step.
 
     Returns ``{tool_id: (written, skipped, status, written_paths)}``
-    where ``status`` is one of ``deployed``, ``marker``, ``hint``,
-    ``unsupported`` and ``written_paths`` is the absolute path list of
-    every file the deploy actually wrote (P1.4).
+    where ``status`` is one of ``deployed``, ``hint``, ``unsupported``
+    and ``written_paths`` is the absolute path list of every file the
+    deploy actually wrote (P1.4).
     """
     results: dict[str, tuple[int, int, str, list[Path]]] = {}
     for tool_id in sorted(tools):
         if tool_id == "claude-desktop":
-            w, s, paths = _write_claude_desktop_marker(force, lockfile_path)
-            results[tool_id] = (w, s, "marker", paths)
+            results[tool_id] = _deploy_claude_desktop(force, package_root, lockfile_path)
             continue
         plan = GLOBAL_DEPLOY_SOURCES.get(tool_id)
         if plan is None:
@@ -2879,8 +2954,9 @@ def install_global(
 ) -> int:
     """User-scope install path (ADR-007 + Phase 1.6 lockfile lifecycle).
 
-    Reads ``~/.config/agent-config/installed.lock`` first. A recorded
-    version that does not match the running package version refuses the
+    Reads ``~/.event4u/agent-config/installed.lock`` first (with a read
+    fallback to the legacy ``~/.config/agent-config/installed.lock``). A
+    recorded version that does not match the running package version refuses the
     install with a remediation hint unless ``--force`` is passed. On
     success the lockfile is rewritten atomically with the current
     package version + the union of previously-recorded and now-installed
@@ -2894,7 +2970,22 @@ def install_global(
     presence of ``.agent-settings.yml``), the project-scope manifest at
     ``agents/installed-tools.lock`` is also refreshed with ``scope=global``
     entries per ADR-008 Phase 3.2.
+
+    Phase 3 namespace migration: before any lockfile read, the legacy
+    ``~/.config/agent-config/`` tree (pre-2.4 installs) is migrated into
+    ``~/.event4u/agent-config/`` so subsequent reads land on the canonical
+    path. The migration is idempotent and leaves a ``MIGRATED.md``
+    breadcrumb behind; the legacy tree is never auto-deleted.
     """
+    paths_mod = _load_user_global_paths_module()
+    migrated = paths_mod.migrate_legacy_namespace()
+    if migrated and not QUIET:
+        info(
+            "🔁 Migrated user-global config to "
+            f"{paths_mod.event4u_root()} (legacy "
+            f"{paths_mod.legacy_xdg_root()} preserved as fallback)"
+        )
+
     lock_mod = _load_installed_lock_module()
     installed_version = lock_mod.current_package_version()
     lock_path = lock_mod.lockfile_path()
@@ -2945,7 +3036,10 @@ def install_global(
         for tool_id in sorted(deploy_results):
             w, s, status, _ = deploy_results[tool_id]
             anchor = USER_SCOPE_PATHS.get(tool_id, "")
-            if status == "deployed":
+            if status == "deployed" and tool_id == "claude-desktop":
+                bundles_dir = _claude_desktop_bundles_dir()
+                print(f"      {tool_id:<15} → {bundles_dir} ({w} bundles)")
+            elif status == "deployed":
                 print(f"      {tool_id:<15} → {anchor} ({w} files, {s} skipped)")
             elif status == "marker":
                 print(f"      {tool_id:<15} → {anchor}agent-config.md ({'written' if w else 'skipped'})")

package/scripts/install_anthropic_key.sh

@@ -3,10 +3,12 @@
 #
 # Reads the key with `read -s` so it never echoes to the terminal and
 # never lands in shell history or scrollback. Writes atomically to
-# ~/.config/agent-config/anthropic.key with mode 0600.
+# ~/.event4u/agent-config/anthropic.key with mode 0600. The legacy
+# ~/.config/agent-config/anthropic.key is read as a fallback by the
+# loaders so pre-2.4 installs keep working until the namespace shim runs.
 #
 # Contract — companion to scripts/skill_trigger_eval.py:
-#   - File path:  $HOME/.config/agent-config/anthropic.key
+#   - File path:  $HOME/.event4u/agent-config/anthropic.key
 #   - File mode:  0600 (owner read/write only)
 #   - Key format: must start with `sk-ant-`
 #   - No --force, no --yes, no env-var bypass. Piped stdin is rejected.
@@ -16,7 +18,7 @@
 
 set -euo pipefail
 
-TARGET_DIR="${HOME}/.config/agent-config"
+TARGET_DIR="${HOME}/.event4u/agent-config"
 TARGET_FILE="${TARGET_DIR}/anthropic.key"
 
 # ── controlling-terminal requirement ─────────────────────────────────────

package/scripts/install_openai_key.sh

@@ -3,10 +3,12 @@
 #
 # Reads the key with `read -s` so it never echoes to the terminal and
 # never lands in shell history or scrollback. Writes atomically to
-# ~/.config/agent-config/openai.key with mode 0600.
+# ~/.event4u/agent-config/openai.key with mode 0600. The legacy
+# ~/.config/agent-config/openai.key is read as a fallback by the loaders
+# so pre-2.4 installs keep working until the namespace shim runs.
 #
 # Contract — companion to scripts/ai_council/clients.py:
-#   - File path:  $HOME/.config/agent-config/openai.key
+#   - File path:  $HOME/.event4u/agent-config/openai.key
 #   - File mode:  0600 (owner read/write only)
 #   - Key format: must start with `sk-`
 #   - No --force, no --yes, no env-var bypass. Piped stdin is rejected.
@@ -16,7 +18,7 @@
 
 set -euo pipefail
 
-TARGET_DIR="${HOME}/.config/agent-config"
+TARGET_DIR="${HOME}/.event4u/agent-config"
 TARGET_FILE="${TARGET_DIR}/openai.key"
 
 # ── controlling-terminal requirement ─────────────────────────────────────