@event4u/agent-config 2.2.2 → 2.4.0

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/rules/external-reference-deep-dive.md

@@ -0,0 +1,69 @@
+---
+type: "auto"
+tier: "2b"
+description: "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"
+alwaysApply: false
+source: package
+triggers:
+  - intent: "look at how X does it"
+  - intent: "compare with reference repo"
+  - intent: "use as template / vorlage"
+  - intent: "wie macht es X"
+  - intent: "vergleiche mit Y"
+  - intent: "schau dir Z an"
+  - intent: "study this competitor"
+  - keyword: "github.com/"
+  - keyword: "source of truth"
+  - phrase: "reference repo"
+---
+
+# external-reference-deep-dive
+
+## The Iron Law
+
+```
+EXTERNAL REFERENCE NAMED → DEEP-DIVE FIRST.
+NO README-ONLY SUMMARIES. NO METADATA GUESSES.
+INSPECT THE TREE, THE FRONTMATTER, THE CONFIGS, THE CODE.
+ABSENCE-OF-EVIDENCE IS NOT EVIDENCE — FETCH BEFORE CLAIMING.
+```
+
+Triggered when the user points to an external artifact (repo URL, `owner/repo`, file path, website, archive) **and** asks to analyze, compare, mirror, use as template, or "see how they do it". The user invested in naming the source — answer from the source, not from the cover.
+
+## Mandatory before drawing any conclusion
+
+1. **Use `/analyze-reference-repo`** (the canonical flow) when the artifact is a repo. Its Steps 2–5 are not optional shortcuts — they are the deep-dive contract: fetch listings (not just README), inspect key directories (`skills/`, `rules/`, `commands/`, `scripts/`, `.github/workflows/`, install configs, frontmatter samples), classify each axis adopt/adapt/reject/already.
+2. **For single files / websites** — fetch the actual content, not a summary. PDFs/DOCX/XLSX → `markitdown` first.
+3. **Cite verbatim** — every finding lands with a file path, line range, or URL fragment. "The README says X" is **not** a finding about implementation; it's a finding about marketing copy.
+4. **Surface what was inspected** — list the files / directories actually fetched, so the user can audit coverage.
+5. **"Not found" beats "probably not there"** — if a fetch budget was hit, say which subtrees are still un-inspected and ask before concluding absence.
+
+## Forbidden patterns
+
+- Reading only the README / homepage / package description and reporting capabilities.
+- Declaring "they don't support X" without listing the directories actually inspected.
+- Repeating a surface-level claim across turns without re-fetching when the user pushes back.
+- Treating `package.json` / `composer.json` keywords as evidence of behavior.
+- Summarizing a competitor's installer story from prose instead of reading `scripts/install*`, `bin/*`, or the npm `bin` field.
+
+## Failure mode catalog
+
+| Pattern | Why it fails | Fix |
+|---|---|---|
+| **README-summary-as-analysis** | Marketing prose ≠ implementation. Capabilities listed there may be aspirational, deprecated, or differently scoped. | Fetch the directory listing + 1–2 representative files per axis. |
+| **"Nothing matches" without enumeration** | Claims absence without proof. The user has to re-prompt to force the real lookup. | Before saying "no X", list the directories scanned. If the budget caps, ask which to expand. |
+| **Repeat-the-guess after pushback** | User says "really look" → agent re-paraphrases the same surface read. Burns trust. | On any pushback that names the source again, restart from a tree listing, not from prior notes. |
+| **Cross-tool path inference from a single example** | One config file ≠ a convention. | Inspect ≥2 unrelated tool integrations before claiming a pattern is the project's universal anchor strategy. |
+
+**Case-zero anchor.** May 2026 — `nextlevelbuilder/ui-ux-pro-max-skill` was named as the source of truth for 23 AI-tool anchors. Three rounds of "we have no content for these tools" were reported from README inference. The actual `tool-configs/*.json` files in the reference repo gave the exact directory layout per tool in one fetch. Cost: ~2 hours of user frustration. Lesson: when an external source is named, the first action is `GET /repos/{o}/{r}/contents/{interesting-subtree}` — not paraphrase.
+
+## Escape hatch
+
+User explicitly fences the scope (*"quick scan only"*, *"just glance at the README"*, *"don't fetch the whole thing"*) → quick-scan path is allowed. Say so up front: *"Quick-scan mode per your scope — README + top-level layout only, not a full analysis."*
+
+## See also
+
+- Command [`/analyze-reference-repo`](../commands/analyze-reference-repo.md) — canonical deep-dive flow.
+- Rule [`think-before-action`](think-before-action.md) — sibling Iron Law for code paths in **this** repo; this rule is its mirror for **external** artifacts.
+- Rule [`ask-when-uncertain`](ask-when-uncertain.md) — when a fetch budget caps, ask which subtree to expand instead of guessing.
+- Skill [`markitdown`](../skills/markitdown/SKILL.md) — convert binary office formats before analysis.

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/copilot-instructions.md

@@ -25,11 +25,18 @@ This repository contains {{project_description_oneline}}.
 > rules, guidelines) and `AGENTS.md`. The instructions below are
 > self-contained for Copilot Code Review.
 >
+> For multi-step workflows (refactors, new features, bug investigations),
+> switch Copilot Chat to **Agent mode** — it can read this file plus
+> `.augment/` and orchestrate tools. **Ask mode** and inline **Edit mode**
+> stay local to the current selection.
+>
 > For most tickets — feature, bug fix, or refactor — start with
 > `/implement-ticket` (see `.augment/commands/implement-ticket.md`). It drives
 > the linear flow `refine → memory → analyze → plan → implement → test →
 > verify → report`, blocks on ambiguity instead of guessing, and never
 > commits, pushes, or opens PRs on its own.
+>
+> See `docs/setup/per-ide/copilot.md` for the full activation guide.
 
 ## ✅ Scope Control
 

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,12 +6,38 @@
   },
   "metadata": {
     "description": "Shared agent configuration \u2014 skills for AI coding tools (Claude Code, Augment, Cursor, Cline, Windsurf, Gemini CLI).",
-    "version": "2.2.2"
+    "version": "2.4.0",
+    "keywords": [
+      "agent-config",
+      "skills",
+      "rules",
+      "claude-code",
+      "augment",
+      "cursor",
+      "cline",
+      "windsurf",
+      "gemini",
+      "copilot",
+      "laravel",
+      "php",
+      "ai-coding"
+    ]
   },
   "plugins": [
     {
       "name": "agent-config",
       "description": "Full skill catalog \u2014 writing, reviewing, managing, and analyzing agent content, plus stack-specific skills for Laravel, PHP, Docker, AWS, Playwright, and more.",
+      "keywords": [
+        "skills",
+        "rules",
+        "commands",
+        "laravel",
+        "php",
+        "review",
+        "testing",
+        "infrastructure",
+        "documentation"
+      ],
       "source": "./",
       "strict": false,
       "skills": [