@event4u/agent-config 2.2.2 → 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/agent-config

@@ -114,6 +114,24 @@ Commands:
   validate                   Read-only drift detection on the manifest
                              (marker missing, scope divergence, version drift).
                              Exits 1 on drift. Flags: --quiet | --skip-version-check
+  uninstall                  Remove bridge markers (project) or lockfile
+                             entries (global). Idempotent. User-deployed
+                             content under ~/.<tool>/ is preserved unless
+                             --purge is passed (destructive).
+                             Flags: --global | --tools=<list> | --dry-run
+                                    | --purge | --force | --project=<path>
+  prune                      Remove project bridge markers not declared in
+                             agents/installed-tools.lock (npm-prune style).
+                             Hard-floors when lockfile is absent.
+                             Flags: --dry-run | --json | --project=<path>
+                                    | --all-missing-lock
+  doctor                     Read-only drift report: manifest ↔ filesystem.
+                             Lists missing, modified, and foreign files.
+                             Exits 1 on drift, 2 on missing lockfile.
+                             Flags: --json | --project=<path>
+  versions                   List available @event4u/agent-config versions
+                             on npm. Marks the current pin and latest.
+                             Flags: --offline | --limit=N | --json
   help                       Show this help
   --version, -V              Print package version
 
@@ -151,6 +169,17 @@ Examples:
   ./agent-config sync --dry-run
   ./agent-config sync
   ./agent-config validate
+  ./agent-config uninstall --tools=cursor --dry-run
+  ./agent-config uninstall --global --tools=windsurf --purge
+  ./agent-config prune --dry-run
+  ./agent-config prune --json
+  ./agent-config doctor
+  ./agent-config doctor --json
+  ./agent-config versions
+  ./agent-config versions --limit=10
+  ./agent-config versions --json
+  ./agent-config init --offline --tools=claude-code,cursor --yes
+  ./agent-config update --offline --to=2.2.0
 
 All commands operate on the CURRENT DIRECTORY (your project root).
 The CLI is strictly consumer-facing. Maintainer tasks live in Taskfile.yml.
@@ -596,6 +625,42 @@ cmd_validate() {
   exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_validate "$@"
 }
 
+# `agent-config uninstall` — remove bridge markers (project) or lockfile
+# entries (global). Idempotent. Pass `--purge` to also delete deployed
+# content directories under user-scope anchors (destructive). See
+# scripts/_cli/cmd_uninstall.py.
+cmd_uninstall() {
+  require_python3
+  exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_uninstall "$@"
+}
+
+# `agent-config prune` — remove orphaned project bridge markers.
+# Drift-cleanup sibling to `uninstall`: compares on-disk markers
+# against agents/installed-tools.lock and unlinks anything not
+# declared. Hard-floors when lockfile is absent. See
+# scripts/_cli/cmd_prune.py.
+cmd_prune() {
+  require_python3
+  exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_prune "$@"
+}
+
+# `agent-config doctor` — read-only drift report against the manifest.
+# Surfaces missing / modified / foreign files. Exit 0 clean, 1 drift,
+# 2 manifest-absent. See scripts/_cli/cmd_doctor.py.
+cmd_doctor() {
+  require_python3
+  exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_doctor "$@"
+}
+
+# `agent-config versions` — list available @event4u/agent-config versions
+# on the npm registry. Marks the current pin (from .agent-settings.yml)
+# and the latest published version. Offline-tolerant. See
+# scripts/_cli/cmd_versions.py.
+cmd_versions() {
+  require_python3
+  exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_versions "$@"
+}
+
 main() {
   local cmd="${1-}"
   [[ $# -gt 0 ]] && shift || true
@@ -641,6 +706,10 @@ main() {
     export)                  cmd_export "$@" ;;
     sync)                    cmd_sync "$@" ;;
     validate)                cmd_validate "$@" ;;
+    uninstall)               cmd_uninstall "$@" ;;
+    prune)                   cmd_prune "$@" ;;
+    doctor)                  cmd_doctor "$@" ;;
+    versions)                cmd_versions "$@" ;;
     help|--help|-h|"")        usage ;;
     --version|-V)            print_version ;;
     *)

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/compress.py

@@ -19,6 +19,8 @@ Usage:
     python scripts/compress.py --project-augment            # rebuild .augment/ projection
 """
 
+from __future__ import annotations
+
 import hashlib
 import json
 import re
@@ -38,6 +40,40 @@ AUGMENT_DIR = PROJECT_ROOT / ".augment"
 HASH_FILE = PROJECT_ROOT / ".compression-hashes.json"
 SETTINGS_FILE = PROJECT_ROOT / ".agent-settings.yml"
 
+# Self-projection tool toggle — see .agent-tools.yml. When the file is
+# absent (e.g. tests run in tmp dirs, consumer projects), `_active_tools`
+# returns ``None`` which is treated as "emit every tool".
+_ALL_TOOLS = frozenset({
+    "claude-code", "claude-desktop", "augment", "copilot",
+    "cursor", "windsurf", "cline", "gemini",
+})
+
+
+def _active_tools() -> frozenset[str] | None:
+    """Return the set of active self-projection tools, or None for "all".
+
+    Reads `.agent-tools.yml` relative to the current `PROJECT_ROOT` so
+    test fixtures that monkey-patch `compress.PROJECT_ROOT` see their own
+    (empty) project root and get the default "all tools" behaviour.
+    """
+    tools_file = PROJECT_ROOT / ".agent-tools.yml"
+    if not tools_file.exists():
+        return None
+    try:
+        data = yaml.safe_load(tools_file.read_text()) or {}
+    except yaml.YAMLError:
+        return None
+    tools = data.get("tools") if isinstance(data, dict) else None
+    if not isinstance(tools, list):
+        return None
+    return frozenset(str(t) for t in tools if isinstance(t, str))
+
+
+def _tool_active(tool_id: str) -> bool:
+    """True when ``tool_id`` should be emitted by self-projection."""
+    active = _active_tools()
+    return True if active is None else tool_id in active
+
 # Files to copy as-is even if .md (not compressed by agent)
 COPY_AS_IS = {"README.md"}
 
@@ -306,6 +342,24 @@ PERSONA_TOOL_DIRS = {
     ".cursor/personas": "../../.agent-src/personas",
 }
 
+# Map tool-projection directories to the canonical tool ID used by
+# `.agent-tools.yml`. Directories not in this map are always emitted.
+_DIR_TOOL_ID = {
+    ".claude/rules": "claude-code",
+    ".cursor/rules": "cursor",
+    ".clinerules": "cline",
+    ".claude/personas": "claude-code",
+    ".cursor/personas": "cursor",
+}
+
+
+def _filter_tool_dirs(mapping: dict[str, str]) -> dict[str, str]:
+    """Drop entries whose tool ID is not active in `.agent-tools.yml`."""
+    return {
+        d: p for d, p in mapping.items()
+        if _tool_active(_DIR_TOOL_ID.get(d, "claude-code"))
+    }
+
 
 def strip_frontmatter(content: str) -> str:
     """Remove YAML frontmatter (between --- markers) from content."""
@@ -461,8 +515,9 @@ def generate_rule_symlinks() -> int:
     """
     # All .md files in .agent-src/rules/ — not just universal ones
     rules = sorted([f.name for f in RULES_SOURCE.glob("*.md")])
+    tool_dirs = _filter_tool_dirs(TOOL_DIRS)
     total = 0
-    for tool_dir, rel_prefix in TOOL_DIRS.items():
+    for tool_dir, rel_prefix in tool_dirs.items():
         target_dir = PROJECT_ROOT / tool_dir
         target_dir.mkdir(parents=True, exist_ok=True)
 
@@ -481,13 +536,13 @@ def generate_rule_symlinks() -> int:
 
     # Verify counts match across all tool directories
     source_count = len(rules)
-    for tool_dir in TOOL_DIRS:
+    for tool_dir in tool_dirs:
         target_dir = PROJECT_ROOT / tool_dir
         tool_count = len([f for f in target_dir.iterdir() if f.is_symlink() and f.suffix == ".md"])
         if tool_count != source_count:
             print(f"  ⚠️  {tool_dir}: {tool_count} rules (expected {source_count})")
 
-    info(f"  ✅  Created {total} rule symlinks across {len(TOOL_DIRS)} tool directories ({source_count} rules each)")
+    info(f"  ✅  Created {total} rule symlinks across {len(tool_dirs)} tool directories ({source_count} rules each)")
     return total
 
 
@@ -812,8 +867,9 @@ def generate_persona_symlinks() -> int:
     personas = sorted([
         f.name for f in PERSONAS_SOURCE.glob("*.md") if f.stem != "README"
     ])
+    tool_dirs = _filter_tool_dirs(PERSONA_TOOL_DIRS)
     total = 0
-    for tool_dir, rel_prefix in PERSONA_TOOL_DIRS.items():
+    for tool_dir, rel_prefix in tool_dirs.items():
         target_dir = PROJECT_ROOT / tool_dir
         target_dir.mkdir(parents=True, exist_ok=True)
 
@@ -830,28 +886,35 @@ def generate_persona_symlinks() -> int:
             link.symlink_to(target)
             total += 1
 
-    info(f"  ✅  Created {total} persona symlinks across {len(PERSONA_TOOL_DIRS)} tool directories ({len(personas)} personas each)")
+    info(f"  ✅  Created {total} persona symlinks across {len(tool_dirs)} tool directories ({len(personas)} personas each)")
     return total
 
 
 def generate_tools() -> None:
-    """Generate all tool-specific directories and files."""
+    """Generate all tool-specific directories and files.
+
+    `.agent-tools.yml` (top-level) gates per-tool emission. When the file
+    is missing, every tool is emitted (preserves test fixtures and
+    pre-gating behaviour). See `_active_tools()` and `_tool_active()`.
+    """
     info("🔧  Generating multi-agent tool directories...\n")
     rules = generate_rule_symlinks()
-    generate_windsurfrules()
-    generate_gemini_md()
-    skills = generate_claude_skills()
-    commands = generate_claude_commands()
+    windsurfrules = generate_windsurfrules() if _tool_active("windsurf") else 0
+    if _tool_active("gemini"):
+        generate_gemini_md()
+    skills = generate_claude_skills() if _tool_active("claude-code") else 0
+    commands = generate_claude_commands() if _tool_active("claude-code") else 0
     personas = generate_persona_symlinks()
-    cursor_mdc = generate_cursor_mdc_rules()
-    windsurf_modern = generate_windsurf_modern_rules()
-    cursor_cmds = generate_cursor_commands()
-    windsurf_wf = generate_windsurf_workflows()
+    cursor_mdc = generate_cursor_mdc_rules() if _tool_active("cursor") else 0
+    windsurf_modern = generate_windsurf_modern_rules() if _tool_active("windsurf") else 0
+    cursor_cmds = generate_cursor_commands() if _tool_active("cursor") else 0
+    windsurf_wf = generate_windsurf_workflows() if _tool_active("windsurf") else 0
     summary = (
         f"✅  generate-tools — rules={rules} skills={skills} "
         f"commands={commands} personas={personas} "
         f"cursor_mdc={cursor_mdc} windsurf_rules={windsurf_modern} "
-        f"cursor_commands={cursor_cmds} windsurf_workflows={windsurf_wf}"
+        f"cursor_commands={cursor_cmds} windsurf_workflows={windsurf_wf} "
+        f"windsurfrules={windsurfrules}"
     )
     if resolve_level() == "verbose":
         print(f"\n{summary}")