@event4u/agent-config 2.26.0 → 3.1.0

package/scripts/install.py

@@ -34,6 +34,9 @@ import shlex
 import shutil
 import subprocess
 import sys
+import threading
+import time
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Optional
 
@@ -1009,7 +1012,7 @@ def ensure_augment_user_hooks(package_root: Path, force: bool) -> list[dict[str,
 # scripts/hook_manifest.yaml to resolve which concerns fire on each
 # (platform, event) tuple. Mirrors AUGMENT_DISPATCHER_BINDINGS so each
 # concern fires on the same logical surface across platforms — the
-# contract from agents/contexts/hardening-pattern.md § Cross-platform
+# contract from agents/settings/contexts/hardening-pattern.md § Cross-platform
 # parity.
 CLAUDE_DISPATCHER_BINDINGS = (
     ("session_start",      "SessionStart"),
@@ -1074,7 +1077,7 @@ def ensure_claude_bridge(project_root: Path, force: bool) -> list[dict[str, Any]
 # Native event names per https://cursor.com/docs/reference/third-party-hooks
 # (camelCase). UserPromptSubmit lives at `beforeSubmitPrompt`. Stop is
 # IDE-only — CLI-only Cursor users get the rule-only checkpoint
-# fallback per agents/contexts/chat-history-platform-hooks.md.
+# fallback per agents/settings/contexts/chat-history-platform-hooks.md.
 CURSOR_DISPATCHER_BINDINGS = (
     ("session_start",       "sessionStart"),
     ("session_end",         "sessionEnd"),
@@ -1335,7 +1338,7 @@ def ensure_windsurf_bridge(project_root: Path, force: bool) -> list[dict[str, An
     scope. Idempotent via deep_merge — rerunning replaces hook arrays
     rather than appending duplicates. `show_output: false` keeps post
     hooks silent (per Windsurf docs); concerns stream their own output
-    via agents/state/.dispatcher/.
+    via agents/runtime/state/.dispatcher/.
     """
     hooks: dict[str, list] = {}
     for ac_event, native in WINDSURF_DISPATCHER_BINDINGS:
@@ -1602,7 +1605,8 @@ def ensure_roocode_bridge(project_root: Path, force: bool) -> None:
 # `~/Library/Application Support/Claude/` on macOS — no project-local
 # discovery. The project bridge is informational only: a marker file that
 # documents the link and tells humans where the canonical rules live.
-# Phase 2.3 will formalize this as scope=global-only via SCOPE_SUPPORT.
+# Formalized as scope=global-only via SCOPE_SUPPORT (Phase 3.1 of
+# road-to-global-only-install — consumer installs are global-only).
 CLAUDE_DESKTOP_MARKER = """# Agent Config bridge — Claude Desktop
 
 This file marks the project as an `event4u/agent-config` consumer.
@@ -2052,26 +2056,36 @@ USER_SCOPE_PATHS = {
 }
 
 
-# Per-tool scope support per ADR-007 matrix + Tier-1/2 verification.
-# Values: "both" · "project" · "global". Used by _validate_scope() to
-# reject explicit `--tools=X` selections that conflict with the chosen
-# scope (project default or `--global`). `--tools=all` silently filters
-# incompatible IDs so the default install path stays backward-compatible.
+# Per-tool scope support per ADR-007 matrix + ADR-020 consumer global-only
+# amendment. Values: "both" · "project" · "global". Used by _validate_scope()
+# to reject explicit `--tools=X` selections that conflict with the chosen
+# scope. `--tools=all` silently filters incompatible IDs so the default
+# install path stays backward-compatible.
 #
-# Rationale:
-#   - claude-desktop has no project discovery (informational marker only
-#     in project trees); --project rejects it explicitly.
-#   - jetbrains avoids mutating team-shared .idea/; --project marker is
-#     informational only; canonical scope is global.
-#   - roocode / kilocode auto-discover `.roo/rules/` and `.kilocode/rules/`
-#     per project; no user-scope discovery convention; --global rejects.
+# road-to-global-only-install § Phase 3.1 — consumer installs are
+# global-only. Every AI ID with a user-scope convention is pinned to
+# "global". Maintainers can still drive project-scope installs by
+# setting AGENT_CONFIG_DEV_MODE=1 — `_enforce_consumer_global_only`
+# gates the scope before validation, so the SCOPE_SUPPORT matrix is the
+# canonical declaration of "where this tool is allowed to write."
+#
+# Exception:
+#   - copilot is "both" because GitHub Copilot has no user-scope
+#     convention for instructions — `copilot-instructions.md` lives
+#     in-repo by design. Project scope still requires
+#     AGENT_CONFIG_DEV_MODE=1 (consumer-floor gate); the "both" value
+#     keeps the gate at the env-flag layer rather than the matrix layer.
 SCOPE_SUPPORT = {
-    "claude-code":    "both",
+    "claude-code":    "global",
     "claude-desktop": "global",
-    "cursor":         "both",
-    "windsurf":       "both",
-    "cline":          "both",
-    "gemini-cli":     "both",
+    "cursor":         "global",
+    "windsurf":       "global",
+    "cline":          "global",
+    "gemini-cli":     "global",
+    # GitHub Copilot ships `copilot-instructions.md` in-repo by design
+    # — no user-scope convention exists. Project scope stays available
+    # but is gated by AGENT_CONFIG_DEV_MODE=1 via the consumer-floor
+    # check, not by the matrix.
     "copilot":        "both",
     # `augment` is global-only by design: a single user-scope deploy to
     # `~/.augment/` is the canonical surface. The package owner accepts
@@ -2081,17 +2095,14 @@ SCOPE_SUPPORT = {
     # installs are rejected so the per-repo `.augment/` surface stays
     # out of the install matrix entirely.
     "augment":        "global",
-    "aider":          "both",
-    "codex":          "both",
-    # Phase 2.4: roocode / kilocode lifted to "both" — global deploys
-    # write to `~/.roo/skills/` and `~/.kilocode/skills/` matching the
-    # nextlevelbuilder/ui-ux-pro-max-skill anchors.
-    "roocode":        "both",
-    "continue":       "both",
-    "kilocode":       "both",
-    "zed":            "both",
+    "aider":          "global",
+    "codex":          "global",
+    "roocode":        "global",
+    "continue":       "global",
+    "kilocode":       "global",
+    "zed":            "global",
     "jetbrains":      "global",
-    "kiro":           "both",
+    "kiro":           "global",
     # Phase 2.4 expansion — global-only for new anchors; project bridges
     # are not yet implemented for these IDs.
     "qoder":          "global",
@@ -2248,6 +2259,15 @@ To remove this marker, delete this file.
 #: package-owned, not Claude-owned, content.
 _CLAUDE_DESKTOP_BUNDLES_SUBPATH = "claude-desktop/bundles"
 
+#: road-to-global-only-install § Phase 2.1 — canonical global path
+#: constants. Single source of truth for the user-scope settings file
+#: locations. Used by the settings reader (Python + TypeScript via
+#: docs/contracts/settings-api.md) to merge ``defaults < global <
+#: project-overrides``.
+GLOBAL_ROOT = Path.home() / ".event4u" / "agent-config"
+GLOBAL_USER_SETTINGS_PATH = GLOBAL_ROOT / ".agent-user.yml"
+GLOBAL_AGENT_SETTINGS_PATH = GLOBAL_ROOT / ".agent-settings.yml"
+
 
 def _bridge_marker(tool_id: str, scope: str) -> str:
     """Return the canonical bridge-marker path for ``(tool_id, scope)``.
@@ -2269,9 +2289,22 @@ def _validate_scope(tools: set[str], scope: str, was_all: bool) -> set[str]:
     `--tools=all` or omitted the flag), incompatible tools are silently
     filtered so the default install stays backward-compatible. Explicit
     tool lists hard-reject with a directive error per Phase 2.3.
+
+    Maintainer dev mode (``AGENT_CONFIG_DEV_MODE=1``) bypasses the matrix
+    filter entirely. Per ``docs/maintainers/dev-mode.md`` the flag
+    "allows project-scope writes back into the repo tree" — that
+    contract requires the full bridge surface (cursor / cline / windsurf
+    / gemini-cli / …) to remain reachable under ``--project`` so
+    ``task dev:install-global`` can dogfood every projection. The
+    consumer-facing gate already runs upstream via
+    ``_enforce_consumer_global_only``; reaching this function with
+    ``scope == "project"`` means the dev gate already approved the
+    write, so the matrix filter would be double-gating maintainer flows.
     """
     if scope not in ("project", "global"):
         fail(f"_validate_scope: unknown scope '{scope}'")
+    if os.environ.get("AGENT_CONFIG_DEV_MODE") == "1":
+        return tools
     incompatible = sorted(
         t for t in tools
         if SCOPE_SUPPORT.get(t, "both") not in ("both", scope)
@@ -2291,6 +2324,125 @@ def _validate_scope(tools: set[str], scope: str, was_all: bool) -> set[str]:
     return tools  # unreachable; fail() exits
 
 
+def _enforce_consumer_global_only(scope: str) -> None:
+    """road-to-global-only-install § Phase 3.2 — gate the project scope.
+
+    Consumer installs ship global-only (ADR-020). The legacy project
+    scope stays available for maintainers via ``AGENT_CONFIG_DEV_MODE=1``
+    so the dogfood-on-this-repo loop keeps working. Anything else
+    routing through the orchestrator with ``scope == "project"`` aborts
+    with a directive error pointing at the maintainer doc.
+
+    Pure side-effect gate — separate from ``_resolve_scope`` so the
+    unit-tested resolver stays a pure function of its inputs.
+    """
+    if scope != "project":
+        return
+    if os.environ.get("AGENT_CONFIG_DEV_MODE") == "1":
+        return
+    fail(
+        "--scope=project is reserved for maintainers (ADR-020 — consumer "
+        "installs are global-only). Set AGENT_CONFIG_DEV_MODE=1 to opt in. "
+        "See docs/maintainers/dev-mode.md."
+    )
+
+
+# --- road-to-global-only-install § Phase 2.2 — three-layer settings reader ---
+#
+# Merge order (per ADR-020 / D9):
+#
+#     defaults  <  global  <  project-overrides
+#
+# The defaults layer is the rendered template body in
+# ``config/agent-settings.template.yml``. The global layer is
+# ``~/.event4u/agent-config/.agent-settings.yml``. The project layer is
+# ``<project_root>/.agent-settings.yml`` — tolerated but no longer
+# required to exist. Any layer that is missing or unparseable falls back
+# to an empty dict so the merge stays total.
+#
+# The TypeScript wizard route ``GET /api/v1/wizard/settings`` mirrors the
+# same precedence (see :mod:`src.server.routes.wizard`) so the Python
+# installer and the Fastify server agree on what *the user's effective
+# settings* look like at any given moment.
+
+def _load_yaml_doc(path: Path) -> dict:
+    """Load a YAML file as a dict; return ``{}`` on every recoverable error.
+
+    Used by the three-layer settings reader. Mirrors the defensive shape
+    of :func:`scripts.config.profiles._load_yaml`: missing PyYAML, missing
+    file, parse error, or non-dict root all collapse to an empty dict so
+    callers can blindly :func:`deep_merge` the result without guards.
+    """
+    try:
+        import yaml  # type: ignore[import-not-found]
+    except ImportError:
+        return {}
+    if not path.exists() or not path.is_file():
+        return {}
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return {}
+    try:
+        data = yaml.safe_load(text)
+    except yaml.YAMLError:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _load_default_settings(package_root: Path) -> dict:
+    """Parse the rendered settings template into a defaults dict.
+
+    The template carries ``__COST_PROFILE__`` / ``__USER_TYPE__``
+    placeholders that PyYAML cannot parse as scalars. We substitute the
+    most permissive defaults (``balanced`` + empty user_type) before
+    parsing — the resulting tree is the *defaults* layer of the merge,
+    and downstream layers overwrite cost_profile / user_type as needed.
+    """
+    template_source = package_root / "config" / "agent-settings.template.yml"
+    if not template_source.exists():
+        return {}
+    try:
+        text = template_source.read_text(encoding="utf-8")
+    except OSError:
+        return {}
+    rendered = text.replace(COST_PROFILE_PLACEHOLDER, DEFAULT_PROFILE).replace(
+        USER_TYPE_PLACEHOLDER, ""
+    )
+    try:
+        import yaml  # type: ignore[import-not-found]
+    except ImportError:
+        return {}
+    try:
+        data = yaml.safe_load(rendered)
+    except yaml.YAMLError:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def read_layered_settings(
+    package_root: Path,
+    project_root: "Path | None" = None,
+) -> dict:
+    """Three-layer settings merge — ``defaults < global < project``.
+
+    ``project_root`` is optional: when ``None`` (or the project file is
+    absent), the merge collapses to ``defaults < global`` so a consumer
+    who installs global-only sees the same effective settings the
+    Fastify server would surface. Always returns a dict — never raises.
+
+    Used by :func:`main` to compute the effective configuration before
+    rendering per-tool bridges, and by the Phase 2.4 ``settings migrate``
+    subcommand to detect which keys are local-only overrides.
+    """
+    merged = _load_default_settings(package_root)
+    merged = deep_merge(merged, _load_yaml_doc(GLOBAL_AGENT_SETTINGS_PATH))
+    if project_root is not None:
+        project_file = project_root / SETTINGS_FILE
+        merged = deep_merge(merged, _load_yaml_doc(project_file))
+    return merged
+
+
 def _resolve_scope(
     opts: "argparse.Namespace",
     detected: str,
@@ -2745,6 +2897,284 @@ def _resolve_package_root_for_global() -> Path:
     return candidate
 
 
+#: Consumer bridge marker filename, relative to the project root.
+#: Spec: docs/contracts/consumer-bridge.md (event4u-bridge/v1).
+CONSUMER_BRIDGE_MARKER_RELPATH = Path("agents") / ".event4u-bridge.yml"
+
+
+# ---------------------------------------------------------------------------
+# Phase 5.2 — migrate-to-global first-run hook
+# ---------------------------------------------------------------------------
+#
+# Legacy artefacts that signal a pre-ADR-020 install in the project root.
+# Same surface the ``migrate-to-global`` command detects (see
+# ``scripts/_cli/cmd_migrate_to_global.py``). Kept in sync intentionally so
+# the prompt and the migration tool agree on what counts as "legacy".
+MIGRATE_LEGACY_YAML_FILES = (".agent-settings.yml", ".agent-user.yml")
+MIGRATE_LEGACY_TOOL_DIRS = (".augment", ".claude", ".cursor")
+
+
+def _detect_legacy_for_migration(project_root: Path) -> list[str]:
+    """Return a sorted list of legacy artefact relpaths present in ``project_root``.
+
+    Skipped (returns ``[]``) when:
+
+    - ``AGENT_CONFIG_DEV_MODE=1`` is set (maintainer dogfood loop),
+    - the project root IS the agent-config source repo
+      (``.agent-src.uncompressed/`` present),
+    - the bridge marker already exists (project is already global-only).
+    """
+    if os.environ.get("AGENT_CONFIG_DEV_MODE") == "1":
+        return []
+    if (project_root / ".agent-src.uncompressed").is_dir():
+        return []
+    if (project_root / CONSUMER_BRIDGE_MARKER_RELPATH).is_file():
+        return []
+
+    found: list[str] = []
+    for name in MIGRATE_LEGACY_YAML_FILES:
+        if (project_root / name).is_file():
+            found.append(name)
+        elif (project_root / "settings" / name).is_file():
+            found.append(f"settings/{name}")
+    for name in MIGRATE_LEGACY_TOOL_DIRS:
+        p = project_root / name
+        if p.is_dir() and not p.is_symlink():
+            found.append(f"{name}/")
+    return sorted(found)
+
+
+def _prompt_migrate_to_global(project_root: Path, artefacts: list[str]) -> bool:
+    """Ask the user whether to run ``migrate-to-global`` now.
+
+    Interactive TTY → ``[Y/n]`` prompt (Enter = yes). Non-interactive (CI
+    or no TTY) → auto-yes per roadmap Phase 5.2 contract. Three invalid
+    replies short-circuit to "no" (defensive, never blocks the install).
+    """
+    if not QUIET:
+        print()
+        warn("Legacy project-local artefacts detected — pre-ADR-020 layout:")
+        for rel in artefacts:
+            info(f"  {project_root / rel}")
+        info("ADR-020 ships consumer installs as global-only.")
+        info("`agent-config migrate-to-global` copies → verifies → moves them safely.")
+
+    if not _is_interactive():
+        if not QUIET:
+            info("Non-interactive mode → defaulting to YES (run migration).")
+        return True
+
+    attempts = 0
+    while attempts < 3:
+        try:
+            reply = _read_line("Run `agent-config migrate-to-global` now? [Y/n]: ")
+        except EOFError:
+            return False
+        if reply == "" or reply.lower() in ("y", "yes"):
+            return True
+        if reply.lower() in ("n", "no"):
+            return False
+        attempts += 1
+        warn(f"Invalid choice '{reply}'. Enter Y or n.")
+    return False
+
+
+def _run_migrate_to_global(project_root: Path) -> int:
+    """Invoke ``cmd_migrate_to_global._do_migrate`` against ``project_root``.
+
+    Returns the migrator's exit code so the caller can abort the install
+    on failure. The perms gate is skipped because the install path runs
+    its own checks; surfacing two perm errors back-to-back would be
+    confusing for first-run users.
+    """
+    import importlib  # noqa: PLC0415 — local to keep startup lean.
+
+    try:
+        cmd_mod = importlib.import_module("scripts._cli.cmd_migrate_to_global")
+    except ImportError as exc:
+        warn(f"migrate-to-global unavailable: {exc}")
+        return 1
+
+    install_mod = sys.modules[__name__]
+    return cmd_mod._do_migrate(project_root, force=False, install_mod=install_mod, out=sys.stdout)
+
+
+def _format_global_root_for_marker(global_root: Path) -> str:
+    """Render ``global_root`` for the bridge marker.
+
+    Per ``docs/contracts/consumer-bridge.md``, readers MUST expand ``~``
+    against the **current process's** ``$HOME``. To keep the marker
+    portable across maintainer home dirs, render the path with a
+    leading ``~/`` when it lives under ``Path.home()``; fall back to
+    the absolute path otherwise (e.g. ``EVENT4U_CONFIG_HOME`` override
+    pointing outside ``$HOME``).
+    """
+    try:
+        rel = global_root.resolve().relative_to(Path.home().resolve())
+    except ValueError:
+        return str(global_root)
+    return f"~/{rel.as_posix()}"
+
+
+def _write_consumer_bridge_marker(
+    project_root: Path,
+    installer_version: str,
+    *,
+    env: Optional[dict] = None,
+    now: Optional[datetime] = None,
+) -> Optional[Path]:
+    """Write ``agents/.event4u-bridge.yml`` at the consumer project root.
+
+    Returns the written path, or ``None`` when the write was skipped per
+    ``docs/contracts/consumer-bridge.md`` § Writer contract:
+
+    - ``AGENT_CONFIG_DEV_MODE=1`` (maintainer dev installs never lay the
+      bridge into the source repo).
+    - The project root is the agent-config source repo itself
+      (``.agent-src.uncompressed/`` present) — same rationale.
+
+    Atomic write: ``tempfile`` in the same dir + ``os.replace``. Same
+    pattern the lockfile uses (see ``scripts/_lib/installed_lock.py``).
+    Mode ``0o644`` per contract — no secrets, world-readable.
+    """
+    import tempfile
+
+    env_map = env if env is not None else os.environ
+    if env_map.get("AGENT_CONFIG_DEV_MODE") == "1":
+        return None
+    if (project_root / ".agent-src.uncompressed").is_dir():
+        return None
+
+    paths_mod = _load_user_global_paths_module()
+    global_root_str = _format_global_root_for_marker(paths_mod.event4u_root(env=env_map))
+    stamp = (now or datetime.now(timezone.utc)).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    body = (
+        "# event4u/agent-config — consumer bridge marker (auto-written).\n"
+        "# Spec: docs/contracts/consumer-bridge.md (event4u-bridge/v1).\n"
+        "# Reader contract: expand ~ against the current $HOME; fail closed\n"
+        "# when global_root is missing on disk; never write back through it.\n"
+        "schema: event4u-bridge/v1\n"
+        f"global_root: {global_root_str}\n"
+        f"installed_at: {stamp}\n"
+        f"installer_version: {installer_version}\n"
+    )
+
+    target = project_root / CONSUMER_BRIDGE_MARKER_RELPATH
+    target.parent.mkdir(parents=True, exist_ok=True)
+
+    fd, tmp_name = tempfile.mkstemp(
+        prefix=".event4u-bridge.", suffix=".yml.tmp",
+        dir=str(target.parent), text=False,
+    )
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            fh.write(body)
+        os.chmod(tmp_name, 0o644)
+        os.replace(tmp_name, target)
+    except Exception:
+        try:
+            os.unlink(tmp_name)
+        except OSError:
+            pass
+        raise
+    return target
+
+
+#: Per-tool project anchors (Phase 4.3). Some AI tools only load rules
+#: when an anchor file is **inside** the workspace. For those IDs we
+#: plant a thin pointer file under the tool's per-project directory
+#: whose body references the bridge marker (``agents/.event4u-bridge.yml``).
+#: Tools that load purely from user-scope (Claude Code, Cursor, Augment)
+#: read the marker once and need no per-tool file — they are absent
+#: from this map by design (see ``docs/contracts/consumer-bridge.md``
+#: § Per-tool anchor strategy).
+PROJECT_ANCHOR_TOOLS: dict[str, str] = {
+    "windsurf":   ".windsurf/agent-config.bridge.yml",
+    "cline":      ".clinerules/agent-config.bridge.yml",
+    "gemini-cli": ".gemini/agent-config.bridge.yml",
+}
+
+
+def _write_per_tool_project_anchors(
+    project_root: Path,
+    tools: set[str],
+    *,
+    env: Optional[dict] = None,
+    now: Optional[datetime] = None,
+) -> list[Path]:
+    """Plant thin pointer files for tools in :data:`PROJECT_ANCHOR_TOOLS`.
+
+    Each pointer is a tiny YAML body that references the bridge marker
+    at ``agents/.event4u-bridge.yml`` (relative from the pointer's
+    location) plus the resolved ``global_root`` for convenience. Same
+    gate semantics as :func:`_write_consumer_bridge_marker`:
+
+    - Skipped under ``AGENT_CONFIG_DEV_MODE=1``.
+    - Skipped inside the agent-config source repo
+      (``.agent-src.uncompressed/`` present).
+    - Skipped when the tool is not in ``tools``.
+
+    Atomic write per file (temp file + ``os.replace``); ``0o644``
+    permissions per ``docs/contracts/consumer-bridge.md`` (the pointers
+    contain no secrets, only paths).
+    """
+    import tempfile
+
+    env_map = env if env is not None else os.environ
+    if env_map.get("AGENT_CONFIG_DEV_MODE") == "1":
+        return []
+    if (project_root / ".agent-src.uncompressed").is_dir():
+        return []
+
+    paths_mod = _load_user_global_paths_module()
+    global_root_str = _format_global_root_for_marker(paths_mod.event4u_root(env=env_map))
+    stamp = (now or datetime.now(timezone.utc)).strftime("%Y-%m-%dT%H:%M:%SZ")
+    written: list[Path] = []
+
+    for tool_id, rel_path in sorted(PROJECT_ANCHOR_TOOLS.items()):
+        if tool_id not in tools:
+            continue
+        target = project_root / rel_path
+        target.parent.mkdir(parents=True, exist_ok=True)
+
+        # Relative path from the pointer file back to the bridge marker.
+        # Both live inside ``project_root``; ``os.path.relpath`` keeps the
+        # result portable across machines (no absolute path leakage).
+        bridge_abs = project_root / CONSUMER_BRIDGE_MARKER_RELPATH
+        bridge_rel = os.path.relpath(bridge_abs, target.parent)
+
+        body = (
+            "# event4u/agent-config — per-tool project anchor (auto-written).\n"
+            "# Spec: docs/contracts/consumer-bridge.md § Per-tool anchor strategy.\n"
+            f"# Tool: {tool_id}. Bridge marker: agents/.event4u-bridge.yml.\n"
+            "schema: event4u-bridge/v1\n"
+            f"tool: {tool_id}\n"
+            f"bridge: {bridge_rel}\n"
+            f"global_root: {global_root_str}\n"
+            f"installed_at: {stamp}\n"
+        )
+
+        fd, tmp_name = tempfile.mkstemp(
+            prefix=".agent-config.bridge.", suffix=".yml.tmp",
+            dir=str(target.parent), text=False,
+        )
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as fh:
+                fh.write(body)
+            os.chmod(tmp_name, 0o644)
+            os.replace(tmp_name, target)
+        except Exception:
+            try:
+                os.unlink(tmp_name)
+            except OSError:
+                pass
+            raise
+        written.append(target)
+
+    return written
+
+
 #: Inline package identifier injected into deployed Markdown
 #: frontmatter (P5.1). Human-readable provenance only; the manifest
 #: remains the authoritative ownership source (see P5.3).
@@ -3137,6 +3567,38 @@ def install_global(
         if rc != 0:
             return rc
 
+        # Consumer bridge marker (Phase 4.2). One declarative pointer at
+        # ``agents/.event4u-bridge.yml`` lets per-tool adapters locate
+        # the global root from inside the repo. Skipped in maintainer
+        # dev mode and in the source repo (see contract § Writer
+        # contract; the surrounding ``.agent-src.uncompressed`` guard
+        # already covers the source-repo case, the dev-mode skip is
+        # enforced inside the writer).
+        marker_path = _write_consumer_bridge_marker(project_root, installed_version)
+        if marker_path is not None and not QUIET:
+            rel = (
+                marker_path.relative_to(project_root)
+                if marker_path.is_relative_to(project_root)
+                else marker_path
+            )
+            info(f"Bridge marker written: {rel}")
+
+        # Per-tool project anchors (Phase 4.3). Plant thin pointer files
+        # for tools that only load rules when an anchor exists inside
+        # the workspace (Windsurf, Cline, Gemini-CLI). Same dev-mode +
+        # source-repo gate as the bridge marker (enforced inside the
+        # writer). Filter to the tools the caller actually selected so
+        # we never plant anchors for tools the user excluded.
+        anchor_paths = _write_per_tool_project_anchors(project_root, tools)
+        if anchor_paths and not QUIET:
+            for p in anchor_paths:
+                rel = (
+                    p.relative_to(project_root)
+                    if p.is_relative_to(project_root)
+                    else p
+                )
+                info(f"Project anchor written: {rel}")
+
     if not QUIET:
         print()
         success("Global install completed.")
@@ -3304,6 +3766,43 @@ def parse_options(argv: list[str]) -> argparse.Namespace:
             "docs/contracts/universal-skills.md for the always-loaded set."
         ),
     )
+    parser.add_argument(
+        "--no-ui",
+        dest="no_ui",
+        action="store_true",
+        help=(
+            "suppress the post-install browser-wizard auto-launch. Also "
+            "honored via AGENT_CONFIG_NO_UI=1 env. CI runners (CI=1) and "
+            "non-TTY stdouts auto-suppress regardless of this flag. See "
+            "agents/roadmaps/wizard-install-py-wiring.md."
+        ),
+    )
+    parser.add_argument(
+        "--dry-run",
+        dest="dry_run",
+        action="store_true",
+        help=(
+            "print a plan summary of what would be installed (profile, "
+            "scope, tools, wizard auto-launch decision) and exit 0 "
+            "without writing any files or spawning subprocesses. "
+            "Distinct from the internal alias-resolution --dry-run "
+            "passed to bridge sub-invocations."
+        ),
+    )
+    parser.add_argument(
+        "--apply-payload",
+        dest="apply_payload",
+        default=None,
+        help=(
+            "path to a WizardApplyPayload JSON file (schemas/"
+            "wizard-apply-payload.schema.json). When supplied, install.py "
+            "reads the payload, validates schema_version, translates "
+            "tools/packs/settings into CLI equivalents, and dispatches "
+            "as if those flags were passed directly. Combine with "
+            "--dry-run for the Phase 1.5 preview path "
+            "(road-to-global-only-install § D12 / Phase 1.5)."
+        ),
+    )
     opts = parser.parse_args(argv)
     opts.tools = _merge_tools_aliases(opts.tools, opts.ai)
     if opts.scope == "global" and opts.custom_path:
@@ -3411,19 +3910,26 @@ def _write_install_mode_marker(project_root: Path, mode: str) -> None:
 
 
 def install_minimal(target_root: Path, force: bool, user_type: str = "") -> int:
-    """Bootstrap the project-local override layer only (D2-compliant).
+    """Bootstrap the project-local override layer only (ADR-020-compliant).
 
-    Writes:
+    Writes the global-only consumer scaffold:
 
-    * ``agents/.gitkeep`` so the folder is committable.
-    * ``.agent-settings.yml`` stub (cost_profile=balanced, version pin
-      commented out per D4).
+    * ``agents/overrides/{rules,skills,commands}/.gitkeep`` so the
+      override subdirs are committable in a fresh repo.
+    * ``agents/overrides/README.md`` explaining the override layer and
+      its resolution model.
+    * ``agents/.event4u-bridge.yml`` (Phase 4.2) anchoring the project
+      to the user-global ``~/.event4u/agent-config/`` install.
+    * ``.agent-settings.yml`` — only when ``user_type`` is supplied
+      (back-compat with the step-9 interactive flow); otherwise the
+      project-local settings file is **not** written (global config
+      is the source of truth per ADR-020 § D2).
 
     Refuses (exit 1) when ``target_root`` is **inside** an existing
     agent-config project (Phase-1 anchor walk above the target). The
     in-target case is allowed and treated as idempotent — re-running
-    ``--minimal`` in a folder that already has ``.agent-settings.yml``
-    does nothing unless ``--force`` is passed.
+    ``--minimal`` in a folder that already has the bridge marker does
+    nothing unless ``--force`` is passed.
 
     Does **not** touch ``.gitignore`` (D2 — user owns the ignore file).
     The ``./agent-config`` wrapper is installed by ``scripts/install.sh``
@@ -3455,40 +3961,71 @@ def install_minimal(target_root: Path, force: bool, user_type: str = "") -> int:
 
     templates = _minimal_templates_root()
     settings_src = templates / SETTINGS_FILE
-    gitkeep_src = templates / "agents-gitkeep"
+    overrides_gitkeep_src = templates / "overrides-gitkeep"
+    overrides_readme_src = templates / "agents-overrides-readme.md"
 
-    if not settings_src.is_file() or not gitkeep_src.is_file():
-        fail(f"Bundled minimal templates missing under {templates}")
+    if not settings_src.is_file():
+        fail(f"Bundled minimal settings template missing under {templates}")
+    if not overrides_gitkeep_src.is_file() or not overrides_readme_src.is_file():
+        fail(f"Bundled overrides scaffold templates missing under {templates}")
 
     info(f"Minimal init → {target_root}")
 
-    # 1. agents/.gitkeep
-    agents_dir = target_root / "agents"
-    agents_dir.mkdir(exist_ok=True)
-    gitkeep_dst = agents_dir / ".gitkeep"
-    if gitkeep_dst.exists() and not force:
-        skip(f"agents/.gitkeep already exists (use --force to overwrite)")
-    else:
-        gitkeep_dst.write_text(gitkeep_src.read_text(encoding="utf-8"), encoding="utf-8")
-        success("Wrote agents/.gitkeep")
+    # 1. agents/overrides/{rules,skills,commands}/.gitkeep — committable
+    # scaffold for the project-local override layer (ADR-020 § Phase 4.5).
+    overrides_root = target_root / "agents" / "overrides"
+    overrides_root.mkdir(parents=True, exist_ok=True)
+    gitkeep_body = overrides_gitkeep_src.read_text(encoding="utf-8")
+    for sub in ("rules", "skills", "commands"):
+        sub_dir = overrides_root / sub
+        sub_dir.mkdir(exist_ok=True)
+        gitkeep_dst = sub_dir / ".gitkeep"
+        if gitkeep_dst.exists() and not force:
+            skip(f"agents/overrides/{sub}/.gitkeep already exists (use --force to overwrite)")
+        else:
+            gitkeep_dst.write_text(gitkeep_body, encoding="utf-8")
+            success(f"Wrote agents/overrides/{sub}/.gitkeep")
 
-    # 2. .agent-settings.yml stub
-    settings_dst = target_root / SETTINGS_FILE
-    if settings_dst.exists() and not force:
-        skip(f"{SETTINGS_FILE} already exists (use --force to overwrite)")
+    # 2. agents/overrides/README.md — explains the override layer.
+    readme_dst = overrides_root / "README.md"
+    if readme_dst.exists() and not force:
+        skip("agents/overrides/README.md already exists (use --force to overwrite)")
     else:
-        body = settings_src.read_text(encoding="utf-8")
-        if user_type:
-            body = body.rstrip() + (
+        readme_dst.write_text(overrides_readme_src.read_text(encoding="utf-8"), encoding="utf-8")
+        success("Wrote agents/overrides/README.md")
+
+    # 3. .agent-settings.yml stub — only when user_type is supplied
+    # (back-compat with the step-9 interactive flow). Global config is
+    # the source of truth per ADR-020 § D2; a fresh `--minimal` run
+    # without user_type does not write a project-local settings file.
+    if user_type:
+        settings_dst = target_root / SETTINGS_FILE
+        if settings_dst.exists() and not force:
+            skip(f"{SETTINGS_FILE} already exists (use --force to overwrite)")
+        else:
+            body = settings_src.read_text(encoding="utf-8").rstrip() + (
                 "\n\n# --- Personal (step-9 user-type axis) ---\n"
                 "personal:\n"
                 f"  user_type: {user_type}\n"
             )
-        settings_dst.write_text(body, encoding="utf-8")
-        suffix = f" (user_type={user_type})" if user_type else ""
-        success(f"Wrote {SETTINGS_FILE}{suffix}")
+            settings_dst.write_text(body, encoding="utf-8")
+            success(f"Wrote {SETTINGS_FILE} (user_type={user_type})")
 
-    # 3. install-mode marker (Step 8 A5) — authoritative state for
+    # 4. Consumer bridge marker (Phase 4.2). Anchors the project to
+    # the user-global ``~/.event4u/agent-config/`` install. The writer
+    # itself enforces the dev-mode + source-repo skip contract.
+    lock_mod = _load_installed_lock_module()
+    installed_version = lock_mod.current_package_version()
+    marker_path = _write_consumer_bridge_marker(target_root, installed_version)
+    if marker_path is not None:
+        rel = (
+            marker_path.relative_to(target_root)
+            if marker_path.is_relative_to(target_root)
+            else marker_path
+        )
+        success(f"Wrote {rel}")
+
+    # 5. install-mode marker (Step 8 A5) — authoritative state for
     # doctor --context and future install-aware tooling. Written even
     # on idempotent re-runs so the marker is repaired if removed.
     _write_install_mode_marker(target_root, "minimal")
@@ -3508,7 +4045,7 @@ def install_minimal(target_root: Path, force: bool, user_type: str = "") -> int:
         print()
         info("Next steps:")
         info("  • Ensure `agent-config` is on $PATH: npm install -g @event4u/agent-config")
-        info("  • Add `.agent-settings.yml` and `agents/` to git (or to .gitignore — your call).")
+        info("  • Drop project-scoped overrides under `agents/overrides/{rules,skills,commands}/`.")
         info("  • Run `agent-config doctor` to verify the layer is picked up.")
     return 0
 
@@ -3627,14 +4164,316 @@ def run_interactive_init(project_root: Path, force: bool) -> int:
     return 0
 
 
+# --- Wizard auto-launch (Phase 6 follow-up) ---
+#
+# Auto-launches the browser configuration wizard at the tail of a
+# successful install. The TS side ships a `gui` subcommand on the
+# installer CLI; this Python parent acts as a supervisor that:
+#
+#   1. evaluates gate conditions (TTY, CI, --no-ui, env override),
+#   2. validates the dist exists,
+#   3. spawns `node <cli> gui --project-root <root>` via subprocess.Popen,
+#   4. captures stderr on a background thread (for failure surfacing),
+#   5. reads stdout line-by-line with a progressive timeout
+#      (10s → 20s → 40s → 80s) and matches the strict readiness regex
+#      `^WIZARD_READY url=(http://(?:127.0.0.1|localhost):\d+/)\r?$`,
+#   6. on success: prints the URL banner and waits for the child to
+#      exit (Ctrl-C in the parent terminal propagates to the child),
+#   7. on timeout: kills the child, prints captured stderr tail, falls
+#      through to a fallback message; install itself is unaffected.
+#
+# Council synthesis: agents/runtime/council/responses/wizard-wiring-2026-05-22.synthesis.md
+# Roadmap: agents/roadmaps/wizard-install-py-wiring.md Step 3.
+
+_WIZARD_READY_RE = re.compile(
+    r"^WIZARD_READY url=(http://(?:127\.0\.0\.1|localhost):\d+/)\r?$"
+)
+_WIZARD_TIMEOUTS = (10.0, 20.0, 40.0, 80.0)  # cumulative budget 150s.
+
+
+def _wizard_should_launch(opts: argparse.Namespace) -> tuple[bool, str]:
+    """Evaluate gate conditions for the post-install wizard auto-launch.
+
+    Returns (decision, reason). When decision is False the reason
+    string explains why (CI / no-tty / --no-ui / env override) and is
+    suitable for the pre-install banner Council Tier 2 § 8.
+    """
+    if getattr(opts, "no_ui", False):
+        return (False, "--no-ui flag set")
+    env_no_ui = os.environ.get("AGENT_CONFIG_NO_UI", "").strip()
+    if env_no_ui and env_no_ui != "0":
+        return (False, "AGENT_CONFIG_NO_UI env set")
+    if os.environ.get("CI", "").strip():
+        return (False, "CI environment detected")
+    if not sys.stdout.isatty():
+        return (False, "stdout is not a TTY")
+    return (True, "")
+
+
+def _wizard_cli_dist(project_root: Path) -> Path | None:
+    """Resolve the installer dist path. Returns None if not built.
+
+    Walks up from this file (scripts/install.py is at <pkg>/scripts/)
+    to <pkg>/packages/core/installer/dist/cli.js. That's the layout
+    the monorepo ships; consumer installs run `node <pkg>/.../cli.js`.
+    """
+    package_root = Path(__file__).resolve().parent.parent
+    cli = package_root / "packages" / "core" / "installer" / "dist" / "cli.js"
+    return cli if cli.exists() else None
+
+
+def _wizard_spawn(project_root: Path) -> int:
+    """Spawn the wizard, await readiness, hand off to the child.
+
+    Returns the child's exit code on clean shutdown, 0 on
+    readiness-timeout (install itself succeeded; wizard is best-effort).
+    Never raises into the parent — every error surfaces as a printed
+    fallback line and a 0 return.
+    """
+    cli = _wizard_cli_dist(project_root)
+    if cli is None:
+        print(
+            "(Wizard not available — installer package not built. "
+            "Run 'npm run build' inside packages/core/installer/.)"
+        )
+        return 0
+
+    cmd = ["node", str(cli), "gui", "--project-root", str(project_root)]
+    env = os.environ.copy()
+    # The Node child writes its own readiness banner; suppress the
+    # browser-open inside the child so the Python parent stays in
+    # charge of the user-facing URL print (Tier 2 § 8 ordering).
+    env.setdefault("AGENT_CONFIG_GUI_NO_OPEN", "1")
+
+    try:
+        child = subprocess.Popen(  # noqa: S603 - cmd is locally-built, not user input
+            cmd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            env=env,
+            bufsize=1,  # line-buffered
+        )
+    except OSError as exc:
+        print(f"(Wizard failed to start: {exc}; run 'node {cli} gui' manually.)")
+        return 0
+
+    # Drain stderr on a background thread so a chatty child can't
+    # block the readline loop below. Cap at 80 lines to bound memory.
+    stderr_tail: list[str] = []
+
+    def _drain_stderr() -> None:
+        if child.stderr is None:
+            return
+        for line in child.stderr:
+            stderr_tail.append(line.rstrip("\r\n"))
+            if len(stderr_tail) > 80:
+                del stderr_tail[: len(stderr_tail) - 80]
+
+    stderr_thread = threading.Thread(target=_drain_stderr, daemon=True)
+    stderr_thread.start()
+
+    return _wizard_await_ready(child, stderr_tail, cli)
+
+
+def _wizard_await_ready(
+    child: subprocess.Popen[str],
+    stderr_tail: list[str],
+    cli: Path,
+) -> int:
+    """Read child stdout until the WIZARD_READY regex matches.
+
+    Progressive backoff per Council Tier 1 § 2. On match, prints the
+    URL banner and blocks on child.wait() (parent Ctrl-C is forwarded
+    to the child by the OS via the shared process group).
+    """
+    assert child.stdout is not None
+    elapsed_total = 0.0
+    matched_url: str | None = None
+
+    for interim in _WIZARD_TIMEOUTS:
+        deadline = time.monotonic() + interim
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                break
+            # readline blocks until \n or EOF; we cap total wait per
+            # phase via deadline. Use poll() to detect child exit.
+            if child.poll() is not None:
+                break
+            line = child.stdout.readline()
+            if not line:
+                # EOF — child closed stdout without WIZARD_READY.
+                break
+            m = _WIZARD_READY_RE.match(line)
+            if m is not None:
+                matched_url = m.group(1)
+                break
+        if matched_url is not None or child.poll() is not None:
+            break
+        elapsed_total += interim
+        if elapsed_total < sum(_WIZARD_TIMEOUTS):
+            print(f"(Wizard still booting after {int(elapsed_total)}s — waiting…)")
+
+    if matched_url is None:
+        try:
+            child.terminate()
+            child.wait(timeout=2)
+        except (subprocess.TimeoutExpired, OSError):
+            try:
+                child.kill()
+            except OSError:
+                pass
+        tail = "\n  ".join(stderr_tail[-20:]) if stderr_tail else "(no stderr captured)"
+        print(
+            f"(Wizard server boot timed out after {int(sum(_WIZARD_TIMEOUTS))}s; "
+            f"run 'node {cli} gui' manually.)\n"
+            f"  Last stderr:\n  {tail}"
+        )
+        return 0
+
+    print()
+    print(f"Setup wizard ready: {matched_url}")
+    print("(Wizard runs in the background; close the tab or press Ctrl-C to stop.)")
+    try:
+        return child.wait()
+    except KeyboardInterrupt:
+        try:
+            child.terminate()
+            return child.wait(timeout=5)
+        except (subprocess.TimeoutExpired, OSError):
+            try:
+                child.kill()
+            except OSError:
+                pass
+            return 130
+
+
+def _dry_run_summary(opts: argparse.Namespace) -> int:
+    """Print a one-block plan summary for --dry-run and exit 0.
+
+    Lists profile, scope, tools, target root, and the wizard
+    auto-launch decision. Writes nothing, spawns nothing. The wizard
+    line is shown per Council Tier 3 § 10 user-requirement carve-out.
+    """
+    target = Path(
+        opts.custom_path or opts.project or os.environ.get("PROJECT_ROOT") or os.getcwd()
+    ).resolve()
+    will_launch, why_not = _wizard_should_launch(opts)
+    print()
+    print("[dry-run] Plan summary — no files written, no subprocesses spawned:")
+    print(f"  profile:     {opts.profile}")
+    print(f"  user-type:   {opts.user_type or '(none)'}")
+    print(f"  scope:       {opts.scope or ('global' if opts.global_install else 'auto')}")
+    print(f"  tools:       {opts.tools or 'all'}")
+    print(f"  target:      {target}")
+    print(f"  minimal:     {opts.minimal}")
+    print(f"  force:       {opts.force}")
+    print(f"  offline:     {opts.offline}")
+    if will_launch:
+        print("  wizard:      Would auto-launch (pass --no-ui to suppress).")
+    else:
+        print(f"  wizard:      Suppressed ({why_not}).")
+    print()
+    return 0
+
+
 # --- Main ---
 
+def _apply_payload_preview(payload: dict[str, Any], opts: argparse.Namespace) -> int:
+    """Render a Phase 1.5 dry-run preview for a WizardApplyPayload.
+
+    Reads schema_version, lists tools / packs / settings keys, and
+    exits 0 without spawning. Used by the wizard `/api/v1/wizard/apply`
+    bridge to surface the apply diff before the maintainer commits.
+    """
+    schema_version = payload.get("schema_version", "<missing>")
+    target = Path(
+        opts.custom_path or opts.project or os.environ.get("PROJECT_ROOT") or os.getcwd()
+    ).resolve()
+    print()
+    print("[apply-payload] Plan summary — no files written, no subprocesses spawned:")
+    print(f"  schema:      {schema_version}")
+    if schema_version == "wizard-v2":
+        tools = payload.get("tools") or []
+        packs = payload.get("packs") or []
+        settings = payload.get("settings") or {}
+        scope_to_project = bool(payload.get("scope_to_project_only", False))
+        print(f"  tools:       {','.join(tools) if tools else '(none)'}")
+        print(f"  packs:       {','.join(packs) if packs else '(base)'}")
+        print(f"  settings:    {len(settings)} top-level key(s)")
+        print(f"  scope:       {'project' if scope_to_project else 'global'}")
+    elif schema_version == "installer-v1":
+        ai_tools = payload.get("ai_tools") or []
+        configs = payload.get("configs") or {}
+        print(f"  ai_tools:    {','.join(ai_tools) if ai_tools else '(none)'}")
+        print(f"  configs:     {len(configs)} tool config(s)")
+    else:
+        print(f"  error:       unsupported schema_version: {schema_version!r}")
+        print()
+        return 2
+    print(f"  target:      {target}")
+    print(f"  dry_run:     {bool(payload.get('dry_run', opts.dry_run))}")
+    print()
+    return 0
+
+
 def main(argv: list[str]) -> int:
     global QUIET
 
     opts = parse_options(argv)
     QUIET = opts.quiet
 
+    # road-to-global-only-install § Phase 1.5 — Wizard Apply bridge.
+    # When --apply-payload <path> is supplied, read the WizardApplyPayload
+    # JSON, validate schema_version, and (for dry-run) print a preview
+    # block. The bridge calls install.py with `--dry-run` set, so the
+    # short-circuit below this block keeps the run side-effect-free.
+    if getattr(opts, "apply_payload", None):
+        payload_path = Path(opts.apply_payload).resolve()
+        if not payload_path.is_file():
+            fail(f"--apply-payload path not found: {payload_path}")
+        try:
+            payload = json.loads(payload_path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError as exc:
+            fail(f"--apply-payload JSON parse error: {exc}")
+        if not isinstance(payload, dict):
+            fail("--apply-payload root must be a JSON object")
+        schema_version = payload.get("schema_version")
+        if schema_version not in ("wizard-v2", "installer-v1"):
+            fail(
+                f"--apply-payload schema_version must be 'wizard-v2' or "
+                f"'installer-v1', got {schema_version!r}"
+            )
+        # Translate payload → opts so the dry-run / real-install path
+        # downstream sees the same shape it would from CLI flags. Only
+        # dry-run preview is wired in Phase 1.5; real apply lands in a
+        # follow-up minor (kill-switch via package version per D7).
+        if schema_version == "wizard-v2":
+            tools = payload.get("tools") or []
+            if isinstance(tools, list) and tools:
+                opts.tools = ",".join(t for t in tools if isinstance(t, str))
+            if bool(payload.get("scope_to_project_only", False)):
+                opts.scope = "project"
+            else:
+                opts.scope = "global"
+        elif schema_version == "installer-v1":
+            ai_tools = payload.get("ai_tools") or []
+            if isinstance(ai_tools, list) and ai_tools:
+                opts.tools = ",".join(t for t in ai_tools if isinstance(t, str))
+        # Payload dry_run wins over CLI when explicitly set true.
+        if bool(payload.get("dry_run", False)):
+            opts.dry_run = True
+        if opts.dry_run:
+            return _apply_payload_preview(payload, opts)
+        # Real-apply path through the payload bridge is gated by the
+        # follow-up minor (Phase 1.9). Until then, fail loudly so the
+        # caller knows they need --dry-run.
+        fail(
+            "--apply-payload without --dry-run is not yet wired "
+            "(road-to-global-only-install § Phase 1.5 ships dry-run only)."
+        )
+
     # --offline: propagate via env so child subprocesses (versions /
     # update / check_update_banner) honor the air-gap guarantee
     # without each one needing its own flag. AGENT_CONFIG_NO_UPDATE_CHECK
@@ -3647,6 +4486,24 @@ def main(argv: list[str]) -> int:
     if opts.profile not in SUPPORTED_PROFILES:
         fail(f"Unsupported profile: {opts.profile}. Supported: {', '.join(SUPPORTED_PROFILES)}")
 
+    # Dry-run short-circuit (Council Tier 2 § 9): print a plan summary
+    # and exit 0 before any filesystem write or subprocess spawn.
+    # Distinct from the internal `--dry-run` strings passed to
+    # alias-resolution sub-invocations elsewhere in this file.
+    if getattr(opts, "dry_run", False):
+        return _dry_run_summary(opts)
+
+    # Wizard auto-launch decision banner (Council Tier 2 § 8): print
+    # the gate verdict BEFORE the install runs so the user knows what
+    # will happen at the tail without having to wait through every
+    # bridge write to find out.
+    will_launch, why_not = _wizard_should_launch(opts)
+    if will_launch:
+        if not QUIET:
+            info("Setup wizard will launch automatically after install.")
+    elif not QUIET:
+        info(f"Setup wizard auto-launch disabled ({why_not}).")
+
     # Minimal-init short-circuit (Step 7 Phase 2): bypass scope
     # detection, conflict policy, and the full bridge install. Writes
     # only the project-local override layer (agents/.gitkeep +
@@ -3674,6 +4531,7 @@ def main(argv: list[str]) -> int:
     detected, detect_reason = detect_scope(detect_root)
     custom_path: Path | None = Path(opts.custom_path).resolve() if opts.custom_path else None
     scope = _resolve_scope(opts, detected, detect_reason, custom_path)
+    _enforce_consumer_global_only(scope)
 
     # Scope validation runs before filesystem / package detection so
     # --tools=X / --scope conflicts fail fast with a directive error
@@ -3693,6 +4551,14 @@ def main(argv: list[str]) -> int:
 
     try:
         if scope == "global":
+            # Phase 5.2 — first-run hook: when legacy artefacts live in the
+            # project tree, prompt before laying down the global surface so
+            # the user is not left with a dual-stack install.
+            artefacts = _detect_legacy_for_migration(detect_root)
+            if artefacts and _prompt_migrate_to_global(detect_root, artefacts):
+                rc = _run_migrate_to_global(detect_root)
+                if rc != 0:
+                    return rc
             # Pass detect_root so the manifest refresh runs when --global is
             # invoked from within a project tree (ADR-008 Phase 3.2).
             return install_global(parsed_tools, opts.force, project_root=detect_root)
@@ -3861,6 +4727,15 @@ def _main_project_install(
         else:
             print("  Re-run complete. Walkthrough: https://github.com/event4u-app/agent-config/blob/main/docs/getting-started.md")
             print()
+
+    # Wizard auto-launch (Phase 6 follow-up). Runs after the success
+    # banner so the user sees install completion even if the wizard
+    # boot times out. Gate was already evaluated at the top of main()
+    # for the pre-install banner; re-check here so the supervisor
+    # logic stays the single source of truth.
+    will_launch, _ = _wizard_should_launch(opts)
+    if will_launch:
+        return _wizard_spawn(project_root)
     return 0