@event4u/agent-config 1.39.0 → 1.41.0

package/scripts/compress.py

@@ -26,6 +26,8 @@ import shutil
 import sys
 from pathlib import Path
 
+import yaml
+
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 from _lib.script_output import info, success, flush_summary, resolve_level  # noqa: E402
 
@@ -44,28 +46,31 @@ def _read_augment_rules_use_symlinks() -> bool:
     """Read augment.rules_use_symlinks from .agent-settings.yml.
 
     Returns True only when the setting is present under the top-level
-    ``augment:`` block and resolves to a truthy YAML scalar
-    (true/yes/on/1, case-insensitive). Missing file, missing block, or
-    any other value → False (preserve copy default).
+    ``augment:`` block and resolves to a truthy value. Missing file,
+    missing block, or any other value → False (preserve copy default).
+
+    Centralized loader (road-to-portable-dev-preferences P3): tolerance
+    contract handles missing file / malformed YAML / no PyYAML uniformly.
     """
-    if not SETTINGS_FILE.exists():
-        return False
     try:
-        text = SETTINGS_FILE.read_text(encoding="utf-8")
-    except OSError:
+        from scripts._lib.agent_settings import load_agent_settings
+    except ImportError:  # pragma: no cover — script-style invocation
+        import sys as _sys
+        from pathlib import Path as _Path
+        _sys.path.insert(0, str(_Path(__file__).resolve().parent))
+        from _lib.agent_settings import load_agent_settings  # type: ignore[import-not-found]
+
+    data = load_agent_settings(project_path=SETTINGS_FILE)
+    augment = data.get("augment")
+    if not isinstance(augment, dict):
         return False
-    in_augment = False
-    for line in text.splitlines():
-        stripped = line.lstrip()
-        if not stripped or stripped.startswith("#"):
-            continue
-        if not line.startswith((" ", "\t")):
-            in_augment = stripped.startswith("augment:")
-            continue
-        if in_augment:
-            m = re.match(r"^\s+rules_use_symlinks\s*:\s*([^\s#]+)", line)
-            if m:
-                return m.group(1).strip().lower() in ("true", "yes", "on", "1")
+    value = augment.get("rules_use_symlinks")
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        return value.strip().lower() in ("true", "yes", "on", "1")
+    if isinstance(value, int):
+        return value == 1
     return False
 
 
@@ -503,6 +508,149 @@ def generate_windsurfrules() -> int:
     return len(rules)
 
 
+# ── Modern editor formats (road-to-simplicity-and-everywhere Phase 5) ─
+# Cursor `.cursor/rules/*.mdc` (frontmatter: description, globs,
+# alwaysApply) and Windsurf `.windsurf/rules/*.md` (frontmatter:
+# trigger, description, globs) are the formats current editors prefer.
+# Legacy `.windsurfrules` aggregate stays for users who prefer it.
+
+CURSOR_RULES_MDC_DIR = PROJECT_ROOT / ".cursor" / "rules"
+WINDSURF_RULES_DIR = PROJECT_ROOT / ".windsurf" / "rules"
+WINDSURF_WORKFLOWS_DIR = PROJECT_ROOT / ".windsurf" / "workflows"
+CURSOR_COMMANDS_DIR = PROJECT_ROOT / ".cursor" / "commands"
+
+
+def _parse_frontmatter(content: str) -> tuple[dict, str]:
+    """Split a `---`-delimited YAML frontmatter from the body."""
+    if not content.startswith("---"):
+        return {}, content
+    end = content.find("\n---", 3)
+    if end == -1:
+        return {}, content
+    raw = content[3:end].strip()
+    body = content[end + 4:].lstrip("\n")
+    try:
+        meta = yaml.safe_load(raw) or {}
+    except yaml.YAMLError:
+        meta = {}
+    return meta if isinstance(meta, dict) else {}, body
+
+
+def _emit_cursor_mdc(source: Path, target: Path) -> None:
+    """Write a Cursor `.mdc` file with Cursor-shaped frontmatter."""
+    meta, body = _parse_frontmatter(source.read_text())
+    description = (meta.get("description") or "").replace("\n", " ").strip()
+    always_apply = bool(meta.get("alwaysApply") or meta.get("type") == "always")
+    lines = [
+        "---",
+        f"description: {description}",
+        "globs: ",
+        f"alwaysApply: {'true' if always_apply else 'false'}",
+        "---",
+        "",
+        body.rstrip() + "\n",
+    ]
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text("\n".join(lines))
+
+
+def _emit_windsurf_rule(source: Path, target: Path) -> None:
+    """Write a Windsurf rule with Wave-8 frontmatter (trigger/description/globs)."""
+    meta, body = _parse_frontmatter(source.read_text())
+    description = (meta.get("description") or "").replace("\n", " ").strip()
+    always_apply = bool(meta.get("alwaysApply") or meta.get("type") == "always")
+    trigger = "always_on" if always_apply else "model_decision"
+    lines = [
+        "---",
+        f"trigger: {trigger}",
+        f"description: {description}",
+        "globs: ",
+        "---",
+        "",
+        body.rstrip() + "\n",
+    ]
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text("\n".join(lines))
+
+
+def _clean_modern_dir(target_dir: Path, valid_names: set[str]) -> None:
+    """Drop files in `target_dir` whose names are not in `valid_names`."""
+    if not target_dir.exists():
+        return
+    for item in target_dir.iterdir():
+        if item.name == "README.md":
+            continue
+        if item.name not in valid_names:
+            if item.is_dir() and not item.is_symlink():
+                shutil.rmtree(item)
+            else:
+                item.unlink()
+
+
+def generate_cursor_mdc_rules() -> int:
+    """Emit `.cursor/rules/*.mdc` per source rule (alongside legacy `.md` symlinks)."""
+    rules = sorted(RULES_SOURCE.glob("*.md"))
+    valid = {f"{r.stem}.mdc" for r in rules}
+    _clean_modern_dir(CURSOR_RULES_MDC_DIR, valid | {r.name for r in rules})
+    for rule in rules:
+        _emit_cursor_mdc(rule, CURSOR_RULES_MDC_DIR / f"{rule.stem}.mdc")
+    info(f"  ✅  Wrote {len(rules)} `.cursor/rules/*.mdc` files")
+    return len(rules)
+
+
+def generate_windsurf_modern_rules() -> int:
+    """Emit `.windsurf/rules/*.md` per source rule (Wave-8 frontmatter)."""
+    rules = sorted(RULES_SOURCE.glob("*.md"))
+    valid = {r.name for r in rules}
+    _clean_modern_dir(WINDSURF_RULES_DIR, valid)
+    for rule in rules:
+        _emit_windsurf_rule(rule, WINDSURF_RULES_DIR / rule.name)
+    info(f"  ✅  Wrote {len(rules)} `.windsurf/rules/*.md` files")
+    return len(rules)
+
+
+def generate_cursor_commands() -> int:
+    """Symlink `.cursor/commands/<slug>.md` per source command."""
+    if not COMMANDS_SOURCE.exists():
+        return 0
+    cmds = list(_iter_commands())
+    valid = {f"{slug}.md" for _, slug in cmds}
+    _clean_modern_dir(CURSOR_COMMANDS_DIR, valid)
+    CURSOR_COMMANDS_DIR.mkdir(parents=True, exist_ok=True)
+    count = 0
+    for source_file, slug in cmds:
+        link = CURSOR_COMMANDS_DIR / f"{slug}.md"
+        if link.exists() or link.is_symlink():
+            link.unlink()
+        rel = Path("../../.agent-src/commands") / source_file.relative_to(COMMANDS_SOURCE)
+        link.symlink_to(rel)
+        count += 1
+    info(f"  ✅  Linked {count} `.cursor/commands/*.md` files")
+    return count
+
+
+def generate_windsurf_workflows() -> int:
+    """Symlink `.windsurf/workflows/<slug>.md` per source command."""
+    if not COMMANDS_SOURCE.exists():
+        return 0
+    cmds = list(_iter_commands())
+    valid = {f"{slug}.md" for _, slug in cmds}
+    _clean_modern_dir(WINDSURF_WORKFLOWS_DIR, valid)
+    WINDSURF_WORKFLOWS_DIR.mkdir(parents=True, exist_ok=True)
+    count = 0
+    for source_file, slug in cmds:
+        link = WINDSURF_WORKFLOWS_DIR / f"{slug}.md"
+        if link.exists() or link.is_symlink():
+            link.unlink()
+        rel = Path("../../.agent-src/commands") / source_file.relative_to(COMMANDS_SOURCE)
+        link.symlink_to(rel)
+        count += 1
+    info(f"  ✅  Linked {count} `.windsurf/workflows/*.md` files")
+    return count
+
+
+
+
 def generate_gemini_md() -> None:
     """Create GEMINI.md symlink to AGENTS.md."""
     link = PROJECT_ROOT / "GEMINI.md"
@@ -695,9 +843,15 @@ def generate_tools() -> None:
     skills = generate_claude_skills()
     commands = generate_claude_commands()
     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()
     summary = (
         f"✅  generate-tools — rules={rules} skills={skills} "
-        f"commands={commands} personas={personas}"
+        f"commands={commands} personas={personas} "
+        f"cursor_mdc={cursor_mdc} windsurf_rules={windsurf_modern} "
+        f"cursor_commands={cursor_cmds} windsurf_workflows={windsurf_wf}"
     )
     if resolve_level() == "verbose":
         print(f"\n{summary}")
@@ -806,6 +960,7 @@ def clean_tools() -> None:
         PROJECT_ROOT / ".claude",
         PROJECT_ROOT / ".cursor",
         PROJECT_ROOT / ".clinerules",
+        PROJECT_ROOT / ".windsurf",
         PROJECT_ROOT / ".windsurfrules",
         PROJECT_ROOT / "GEMINI.md",
     ]

package/scripts/council_cli.py

@@ -53,9 +53,15 @@ class CouncilDisabledError(RuntimeError):
 
 
 def load_settings(path: Path = SETTINGS_FILE) -> dict[str, Any]:
-    if not path.exists():
-        return {}
-    return yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    """Load merged settings via the centralized loader.
+
+    road-to-portable-dev-preferences P3 migration: tolerance contract
+    (missing file / malformed YAML / no PyYAML) is handled uniformly by
+    ``load_agent_settings``. ``ai_council.*`` keys are not whitelisted,
+    so the project file remains authoritative for council config.
+    """
+    from scripts._lib.agent_settings import load_agent_settings
+    return load_agent_settings(project_path=path)
 
 
 def build_members(

package/scripts/extract_audit_patterns.py

@@ -0,0 +1,202 @@
+#!/usr/bin/env python3
+"""Mine repeated phase patterns from ``agents/state/audit/*.jsonl``.
+
+Consumer side of `audit-log-v1` (see
+`docs/contracts/audit-log-v1.md`). Reads append-only JSONL audit
+lines emitted by the `work_engine` phase hook and surfaces patterns
+that repeat across **independent** runs — i.e. distinct `work_id`
+values — so the human reviewer can promote them via the
+`learning-to-rule-or-skill` skill.
+
+Read-only: never mutates the JSONL, never writes outside `--output`.
+
+Pattern shape (one per row):
+
+  {
+    "summary":   "<phase>:<outcome>:<rules_hash>",
+    "phase":     "verify",
+    "outcome":   "success",
+    "rules_applied": ["verify-before-complete", "commit-policy"],
+    "count":     7,                # distinct work_ids
+    "line_ids":  ["01HXY...", ...],
+    "first_seen": "2026-05-01T...",
+    "last_seen":  "2026-05-11T..."
+  }
+
+Repetition gate: a pattern is emitted only when ``count >= 2`` and
+the two contributing lines come from **different** ``work_id`` values
+(independence floor — same gate as the skill's evidence rule).
+
+Usage::
+
+  python3 scripts/extract_audit_patterns.py                  # human table
+  python3 scripts/extract_audit_patterns.py --json           # machine
+  python3 scripts/extract_audit_patterns.py --min-count 3
+  python3 scripts/extract_audit_patterns.py --month 2026-05  # one file
+  python3 scripts/extract_audit_patterns.py --audit-dir <p>  # override
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections import defaultdict
+from dataclasses import dataclass, field, asdict
+from pathlib import Path
+from typing import Iterable
+
+ROOT = Path(__file__).resolve().parent.parent
+DEFAULT_AUDIT_DIR = ROOT / "agents" / "state" / "audit"
+SCHEMA_VERSION = 1
+
+
+@dataclass
+class Pattern:
+    summary: str
+    phase: str
+    outcome: str
+    rules_applied: list[str]
+    count: int = 0
+    line_ids: list[str] = field(default_factory=list)
+    work_ids: set[str] = field(default_factory=set)
+    first_seen: str = ""
+    last_seen: str = ""
+
+    def to_dict(self) -> dict:
+        d = asdict(self)
+        d["work_ids"] = sorted(self.work_ids)
+        return d
+
+
+def _iter_lines(audit_dir: Path, month: str | None) -> Iterable[dict]:
+    """Yield parsed JSONL records from the audit directory.
+
+    Silently skips malformed lines (forward-compat per contract § 86).
+    """
+    if not audit_dir.exists():
+        return
+    files = (
+        [audit_dir / f"{month}.jsonl"] if month
+        else sorted(audit_dir.glob("*.jsonl"))
+    )
+    for path in files:
+        if not path.exists():
+            continue
+        with path.open("r", encoding="utf-8") as fh:
+            for raw in fh:
+                raw = raw.strip()
+                if not raw:
+                    continue
+                try:
+                    rec = json.loads(raw)
+                except json.JSONDecodeError:
+                    continue
+                if rec.get("schema_version") != SCHEMA_VERSION:
+                    continue
+                yield rec
+
+
+def _pattern_key(rec: dict) -> tuple[str, str, tuple[str, ...]]:
+    rules = tuple(sorted(rec.get("rules_applied") or []))
+    return (rec.get("phase", ""), rec.get("outcome", ""), rules)
+
+
+def _resolve_supersedes(records: list[dict]) -> list[dict]:
+    """Apply supersede chains: drop records whose id is superseded."""
+    superseded: set[str] = set()
+    for rec in records:
+        if rec.get("type") == "supersede" and rec.get("supersedes"):
+            superseded.add(rec["supersedes"])
+    return [r for r in records if r.get("id") not in superseded]
+
+
+def mine(audit_dir: Path, month: str | None, min_count: int) -> list[dict]:
+    """Group records into patterns; enforce independence floor."""
+    records = _resolve_supersedes(list(_iter_lines(audit_dir, month)))
+    groups: dict[tuple, Pattern] = {}
+    for rec in records:
+        if rec.get("type") not in (None, "phase"):
+            continue
+        key = _pattern_key(rec)
+        if key not in groups:
+            phase, outcome, rules = key
+            rules_hash = "+".join(rules) or "<none>"
+            groups[key] = Pattern(
+                summary=f"{phase}:{outcome}:{rules_hash}",
+                phase=phase,
+                outcome=outcome,
+                rules_applied=list(rules),
+            )
+        pat = groups[key]
+        ts = rec.get("ts", "")
+        wid = rec.get("work_id", "")
+        if wid:
+            pat.work_ids.add(wid)
+        line_id = rec.get("id", "")
+        if line_id:
+            pat.line_ids.append(line_id)
+        pat.count = len(pat.work_ids)
+        if not pat.first_seen or ts < pat.first_seen:
+            pat.first_seen = ts
+        if not pat.last_seen or ts > pat.last_seen:
+            pat.last_seen = ts
+    out = [p.to_dict() for p in groups.values() if p.count >= min_count]
+    out.sort(key=lambda d: (-d["count"], d["summary"]))
+    return out
+
+
+def _render_table(patterns: list[dict]) -> str:
+    if not patterns:
+        return "(no patterns at or above the min-count threshold)"
+    lines = [
+        f"{'count':>5}  {'phase':<10} {'outcome':<8} {'rules':<40} summary",
+        f"{'-' * 5}  {'-' * 10} {'-' * 8} {'-' * 40} -------",
+    ]
+    for p in patterns:
+        rules = ",".join(p["rules_applied"]) or "<none>"
+        if len(rules) > 38:
+            rules = rules[:35] + "..."
+        lines.append(
+            f"{p['count']:>5}  {p['phase']:<10} {p['outcome']:<8} "
+            f"{rules:<40} {p['summary']}"
+        )
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument(
+        "--audit-dir", type=Path, default=DEFAULT_AUDIT_DIR,
+        help="Override audit-log directory (default: %(default)s).",
+    )
+    ap.add_argument(
+        "--month", help="Single YYYY-MM file instead of all months.",
+    )
+    ap.add_argument(
+        "--min-count", type=int, default=2,
+        help="Minimum distinct work_ids required (default: 2).",
+    )
+    ap.add_argument(
+        "--json", action="store_true", help="Emit machine-readable JSON.",
+    )
+    args = ap.parse_args(argv)
+
+    if args.min_count < 2:
+        print(
+            "❌  --min-count must be >= 2 (independence floor per "
+            "audit-log-v1 § Privacy floor).",
+            file=sys.stderr,
+        )
+        return 2
+
+    patterns = mine(args.audit_dir, args.month, args.min_count)
+    if args.json:
+        json.dump(patterns, sys.stdout, indent=2, sort_keys=True)
+        sys.stdout.write("\n")
+    else:
+        print(_render_table(patterns))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/install

@@ -15,13 +15,30 @@
 #   --source <dir>    Package source directory (default: auto-detect)
 #   --target <dir>    Target project root (default: cwd)
 #   --profile <name>  Cost profile for bridges (minimal|balanced|full)
+#   --tools <list>    Comma-separated tool IDs to install (default: all).
+#                     Valid: claude-code,claude-desktop,cursor,windsurf,
+#                            cline,gemini-cli,copilot,augment,aider,codex,all
+#   --list-tools      Print supported tool IDs with descriptions, then exit
+#   --yes, -y         Non-interactive mode: do not prompt (default for non-TTY)
 #   --force           Overwrite existing bridge files
 #   --dry-run         Show what payload sync would do (does not run bridges)
 #   --verbose         Detailed payload sync output
 #   --quiet           Suppress non-error output
 #   --skip-sync       Skip payload sync (install.sh)
 #   --skip-bridges    Skip bridge files (install.py)
+#   --global          Phase-3: ship kernel rules + curated skills to user-scope
+#                     dirs (~/.claude/, ~/.cursor/, ~/.codeium/windsurf/,
+#                     ~/.config/agent-config/) so the agent has them in every
+#                     project. Pair with --tools to scope surfaces; default = all.
+#   --uninstall       With --global: remove the event4u/ namespace dir from each
+#                     enabled surface (no effect on user-added files).
 #   --help, -h        Show this help
+#
+# Examples:
+#   bash scripts/install                                # everything (default)
+#   bash scripts/install --tools=claude-code,cursor     # only those two
+#   bash scripts/install --tools=cursor --yes           # CI-friendly
+#   bash scripts/install --list-tools                   # show catalog
 
 set -uo pipefail
 
@@ -32,19 +49,67 @@ INSTALL_PY="$SCRIPT_DIR/install.py"
 SOURCE_DIR=""
 TARGET_DIR=""
 PROFILE=""
+TOOLS=""
+TOOLS_EXPLICIT=false
+YES=false
 FORCE=false
 DRY_RUN=false
 VERBOSE=false
 QUIET=false
 SKIP_SYNC=false
 SKIP_BRIDGES=false
+LIST_TOOLS=false
+GLOBAL_INSTALL=false
+UNINSTALL=false
+
+# Single source of truth for valid tool IDs (also referenced by install.sh / install.py).
+VALID_TOOLS="claude-code claude-desktop cursor windsurf cline gemini-cli copilot augment aider codex all"
 
 show_help() {
-    sed -n '3,25p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+    sed -n '3,35p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+}
+
+list_tools() {
+    cat <<'EOF'
+Supported --tools IDs (default: all):
+
+  claude-code      .claude/rules, .claude/skills, .claude/commands, .claude/settings.json
+  claude-desktop   ~/Library/Application Support/Claude/ (global, see Phase 4 docs)
+  cursor           .cursor/rules, .cursor/commands (legacy .cursorrules also written)
+  windsurf         .windsurf/rules, .windsurf/workflows (legacy .windsurfrules also written)
+  cline            .clinerules/ symlinks
+  gemini-cli       GEMINI.md, .gemini/settings.json
+  copilot          .github/copilot-instructions.md, .vscode/settings.json
+  augment          .augment/ payload + settings (substrate — recommended for every install)
+  aider            AGENTS.md (Linux Foundation cross-tool contract; always written)
+  codex            AGENTS.md (same as aider — no extra action)
+  all              every ID above (the default; backward-compatible)
+
+Examples:
+  --tools=claude-code,cursor       project-local install for those two surfaces
+  --tools=all                      equivalent to omitting the flag
+EOF
 }
 
 err() { echo "  ❌  $*" >&2; }
 
+# Validate a comma-separated tool list against $VALID_TOOLS. Empty input is
+# rejected so a stray --tools= does not silently behave like --tools=all.
+validate_tools() {
+    local raw="$1"
+    [[ -z "$raw" ]] && { err "--tools requires a non-empty value (use --list-tools to see options)"; return 1; }
+    local IFS=','
+    local item
+    for item in $raw; do
+        [[ -z "$item" ]] && { err "--tools contains an empty entry"; return 1; }
+        if [[ " $VALID_TOOLS " != *" $item "* ]]; then
+            err "Unknown tool ID: $item (run --list-tools for the catalog)"
+            return 1
+        fi
+    done
+    return 0
+}
+
 while [[ $# -gt 0 ]]; do
     case "$1" in
         --source)        SOURCE_DIR="$2"; shift 2 ;;
@@ -53,17 +118,84 @@ while [[ $# -gt 0 ]]; do
         --target=*)      TARGET_DIR="${1#*=}"; shift ;;
         --profile)       PROFILE="$2"; shift 2 ;;
         --profile=*)     PROFILE="${1#*=}"; shift ;;
+        --tools)         TOOLS="$2"; TOOLS_EXPLICIT=true; shift 2 ;;
+        --tools=*)       TOOLS="${1#*=}"; TOOLS_EXPLICIT=true; shift ;;
+        --list-tools)    LIST_TOOLS=true; shift ;;
+        --yes|-y)        YES=true; shift ;;
         --force)         FORCE=true; shift ;;
         --dry-run)       DRY_RUN=true; shift ;;
         --verbose)       VERBOSE=true; shift ;;
         --quiet)         QUIET=true; shift ;;
         --skip-sync)     SKIP_SYNC=true; shift ;;
         --skip-bridges)  SKIP_BRIDGES=true; shift ;;
+        --global)        GLOBAL_INSTALL=true; shift ;;
+        --uninstall)     UNINSTALL=true; shift ;;
         --help|-h)       show_help; exit 0 ;;
         *)               err "Unknown argument: $1"; show_help >&2; exit 1 ;;
     esac
 done
 
+if $LIST_TOOLS; then
+    list_tools
+    exit 0
+fi
+
+# Interactive --tools picker (S9). Fires only when:
+#   - --tools was not explicitly passed
+#   - --yes / -y was not passed (CI / non-interactive opt-out)
+#   - stdin AND stdout are both TTYs (so we're not in a pipe / curl|bash flow)
+#   - --dry-run, --quiet, --skip-sync, --skip-bridges did not opt out of UX
+# Otherwise we fall through to the backward-compatible "all" default.
+prompt_tools() {
+    local choice picked tool i=0
+    local -a menu=(claude-code claude-desktop cursor windsurf cline gemini-cli copilot augment aider codex)
+    echo ""
+    echo "  📦 Pick the tools to install (comma-separated numbers, blank = all):"
+    for tool in "${menu[@]}"; do
+        i=$((i+1))
+        printf "    %2d) %s\n" "$i" "$tool"
+    done
+    echo "    a)  all (default)"
+    echo ""
+    printf "  Selection: "
+    IFS= read -r choice || choice=""
+    choice="${choice// /}"
+    if [[ -z "$choice" || "$choice" == "a" || "$choice" == "all" ]]; then
+        TOOLS="all"; return
+    fi
+    picked=""
+    local IFS=','
+    for n in $choice; do
+        if ! [[ "$n" =~ ^[0-9]+$ ]] || (( n < 1 || n > ${#menu[@]} )); then
+            err "Invalid selection: $n (expected 1-${#menu[@]} or 'a')"; exit 1
+        fi
+        picked+="${menu[$((n-1))]},"
+    done
+    TOOLS="${picked%,}"
+    echo "  ✅  Selected: $TOOLS"
+}
+
+if ! $TOOLS_EXPLICIT && ! $YES && ! $QUIET && ! $LIST_TOOLS && ! $GLOBAL_INSTALL && [[ -t 0 && -t 1 ]]; then
+    prompt_tools
+    TOOLS_EXPLICIT=true
+fi
+
+if $UNINSTALL && ! $GLOBAL_INSTALL; then
+    err "--uninstall is only valid combined with --global"
+    exit 1
+fi
+
+# Default = "all": backward compatible with pre-Phase-1 invocations. An
+# explicit --tools= (empty value) is rejected by validate_tools — only an
+# absent flag falls through to "all".
+if ! $TOOLS_EXPLICIT && [[ -z "$TOOLS" ]]; then
+    TOOLS="all"
+fi
+
+if ! validate_tools "$TOOLS"; then
+    exit 1
+fi
+
 # Auto-detect source: directory above this script
 if [[ -z "$SOURCE_DIR" ]]; then
     SOURCE_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
@@ -103,6 +235,7 @@ run_sync() {
     $DRY_RUN && args+=(--dry-run)
     $VERBOSE && args+=(--verbose)
     $QUIET   && args+=(--quiet)
+    args+=(--tools="$TOOLS")
     bash "$INSTALL_SH" "${args[@]}"
 }
 
@@ -123,10 +256,32 @@ run_bridges() {
     [[ -n "$PROFILE" ]] && args+=(--profile="$PROFILE")
     $FORCE && args+=(--force)
     $QUIET && args+=(--quiet)
+    args+=(--tools="$TOOLS")
     "$python_bin" "$INSTALL_PY" "${args[@]}"
 }
 
 RC=0
+
+# --global: dedicated user-scope path. Skips the project-bridge sync entirely
+# and forwards to install.py --global (Phase 3 / S13). --uninstall pairs with
+# --global to wipe the event4u/ namespace dir under each surface.
+if $GLOBAL_INSTALL; then
+    if ! python_bin="$(find_python)"; then
+        err "Python 3 not found — required for --global install"
+        exit 1
+    fi
+    if [[ ! -f "$INSTALL_PY" ]]; then
+        err "Missing $INSTALL_PY"
+        exit 1
+    fi
+    args=(--package "$SOURCE_DIR" --global --tools="$TOOLS")
+    $FORCE     && args+=(--force)
+    $QUIET     && args+=(--quiet)
+    $UNINSTALL && args+=(--uninstall)
+    "$python_bin" "$INSTALL_PY" "${args[@]}"
+    exit $?
+fi
+
 if ! $SKIP_SYNC; then
     if [[ ! -f "$INSTALL_SH" ]]; then
         err "Missing $INSTALL_SH"