@event4u/agent-config 2.1.0 → 2.2.1

package/docs/installation.md

@@ -1,7 +1,32 @@
 # Installation
 
-**Principle:** Project-installed by default, plugin-enhanced when available.
-No Task, no Make, no build tools required for installation.
+**Principle:** Global-first install (cross-project, in `~/.claude/`,
+`~/.cursor/`, …), opt-in project export when a team wants the config
+committed to a repo. No Task, no Make, no build tools required.
+
+> **v2.1+** — the installer detects intent. Running `npx
+> @event4u/agent-config init` in `~/` or any directory without a
+> project manifest defaults to **global**. Running it inside a project
+> (`package.json` / `composer.json` / `pyproject.toml` / etc.) defaults
+> to **project**. Pass `--scope=global` or `--scope=project` to override
+> detection. See `--scope` in the CLI help for the full matrix.
+
+A global install records itself in `~/.config/agent-config/installed.lock`
+(schema_version, agent_config_version, installed_at, tools[]). `npx
+@event4u/agent-config update` keeps that manifest in lockstep
+with the project pin in `.agent-settings.yml`. A version-mismatched
+re-run of `init --scope=global` is refused with exit code 1 until you
+`update` or pass `--force`.
+
+To commit a specific tool's config into a project repo, use:
+
+```bash
+agent-config export --tool=<id> --output=<path>
+```
+
+(Idempotent; `--force` overrides drift. `--list` enumerates supported
+tool ids. See [`docs/contracts/command-clusters.md`](contracts/command-clusters.md)
+for the export contract.)
 
 ## Per-IDE setup — quick index
 
@@ -12,16 +37,16 @@ section below this index is reference material for advanced installs
 
 | Surface | One-liner | Per-IDE page |
 |---|---|---|
-| **Claude Code** | `npx @event4u/create-agent-config init --tools=claude-code` | [`per-ide/claude-code.md`](setup/per-ide/claude-code.md) |
+| **Claude Code** | `npx @event4u/agent-config init --tools=claude-code` | [`per-ide/claude-code.md`](setup/per-ide/claude-code.md) |
 | **Claude Desktop** | (uses `~/.claude/skills/` from Claude Code global install) | [`per-ide/claude-desktop.md`](setup/per-ide/claude-desktop.md) |
-| **Cursor** | `npx @event4u/create-agent-config init --tools=cursor` | [`per-ide/cursor.md`](setup/per-ide/cursor.md) |
-| **Windsurf** | `npx @event4u/create-agent-config init --tools=windsurf` | [`per-ide/windsurf.md`](setup/per-ide/windsurf.md) |
-| **Cline** | `npx @event4u/create-agent-config init --tools=cline` | [`per-ide/cline.md`](setup/per-ide/cline.md) |
-| **Aider** | `npx @event4u/create-agent-config init --tools=aider` | [`per-ide/aider.md`](setup/per-ide/aider.md) |
-| **Codex CLI** | `npx @event4u/create-agent-config init --tools=codex` | [`per-ide/codex.md`](setup/per-ide/codex.md) |
-| **Gemini CLI** | `npx @event4u/create-agent-config init --tools=gemini` | [`per-ide/gemini-cli.md`](setup/per-ide/gemini-cli.md) |
-| **GitHub Copilot** | `npx @event4u/create-agent-config init --tools=copilot` | [`per-ide/copilot.md`](setup/per-ide/copilot.md) |
-| **All surfaces** | `npx @event4u/create-agent-config init` (default) | (each page above applies) |
+| **Cursor** | `npx @event4u/agent-config init --tools=cursor` | [`per-ide/cursor.md`](setup/per-ide/cursor.md) |
+| **Windsurf** | `npx @event4u/agent-config init --tools=windsurf` | [`per-ide/windsurf.md`](setup/per-ide/windsurf.md) |
+| **Cline** | `npx @event4u/agent-config init --tools=cline` | [`per-ide/cline.md`](setup/per-ide/cline.md) |
+| **Aider** | `npx @event4u/agent-config init --tools=aider` | [`per-ide/aider.md`](setup/per-ide/aider.md) |
+| **Codex CLI** | `npx @event4u/agent-config init --tools=codex` | [`per-ide/codex.md`](setup/per-ide/codex.md) |
+| **Gemini CLI** | `npx @event4u/agent-config init --tools=gemini` | [`per-ide/gemini-cli.md`](setup/per-ide/gemini-cli.md) |
+| **GitHub Copilot** | `npx @event4u/agent-config init --tools=copilot` | [`per-ide/copilot.md`](setup/per-ide/copilot.md) |
+| **All surfaces** | `npx @event4u/agent-config init` (default) | (each page above applies) |
 
 Combine surfaces by comma-separating: `--tools=claude-code,cursor,windsurf`.
 
@@ -81,7 +106,7 @@ the per-IDE index above.
 > 2. `scripts/install.py` — bridge files (`.agent-settings.yml`, VSCode /
 >    Augment / Copilot JSON descriptors).
 >
-> `npx @event4u/create-agent-config init` and `setup.sh` (curl-based)
+> `npx @event4u/agent-config init` and `setup.sh` (curl-based)
 > are thin wrappers that delegate to `scripts/install`. Both underlying
 > stages remain callable directly for advanced use; see their `--help`.
 >
@@ -123,23 +148,23 @@ same flags, no extra state.
 
 ```bash
 # Pick tools interactively (TTY checkbox prompt)
-npx @event4u/create-agent-config init
+npx @event4u/agent-config init
 
 # Pick tools explicitly, non-interactive
-npx @event4u/create-agent-config init --tools=claude-code,cursor --yes
+npx @event4u/agent-config init --tools=claude-code,cursor --yes
 
 # Install everything (the default — backward-compatible)
-npx @event4u/create-agent-config init --tools=all --yes
+npx @event4u/agent-config init --tools=all --yes
 
 # Test a specific git ref (branch, tag, sha) instead of the latest npm tag
-npx @event4u/create-agent-config init --ref=main --yes
+npx @event4u/agent-config init --ref=main --yes
 ```
 
-The `@event4u/create-agent-config` package is a thin wrapper: it
-downloads the latest `@event4u/agent-config` tarball into a temp
-directory, runs `bash scripts/install --target <cwd> ...`, and cleans
-up after itself. The project-local payload package
-(`@event4u/agent-config`) is unchanged.
+`npx @event4u/agent-config init` fetches the latest tarball, runs
+`bash scripts/install --target <cwd> …`, and the install script handles
+its own cleanup. The same package exposes every other `agent-config`
+subcommand (`sync`, `validate`, `mcp:render`, `roadmap:progress`, …) —
+see `npx @event4u/agent-config help`.
 
 ### `curl | bash` (no Node required)
 
@@ -177,12 +202,12 @@ The package is versioned with the project. Settings are committed once.
 ### npx (recommended for any project)
 
 ```bash
-npx @event4u/create-agent-config init --tools=claude-code,cursor
+npx @event4u/agent-config init --tools=claude-code,cursor
 ```
 
-The wrapper downloads the latest `@event4u/agent-config` tarball into a
-temp dir, runs `scripts/install` with the selected tools, and cleans up
-afterwards. Nothing is added to `package.json`.
+`npx` fetches the latest `@event4u/agent-config` tarball and runs
+`scripts/install` with the selected tools. Nothing is added to
+`package.json`.
 
 ### Global CLI (one install per machine)
 
@@ -248,6 +273,7 @@ After initial setup, commit these files:
 
 ```
 .agent-settings.yml                ← shared profile (e.g., cost_profile: minimal)
+agents/installed-tools.lock        ← AI bill of materials (ADR-008, Phase 3)
 .augment/                          ← rules, skills, commands (symlinks)
 .cursor/rules/                     ← Cursor rules (symlinks)
 .claude/                           ← Claude rules, skills (symlinks)
@@ -255,7 +281,37 @@ AGENTS.md                          ← Copilot/Gemini instructions
 .github/copilot-instructions.md   ← GitHub Copilot instructions
 ```
 
-New team members: run `composer install` (or `npm install`) → open editor → done.
+`agents/installed-tools.lock` lists every AI tool the project expects,
+its scope (`global` or `project`), and its bridge marker path. Written
+by `init`, replayed by `sync`, checked by `validate`. Schema and
+workflow: [`docs/guidelines/agent-infra/installed-tools-manifest.md`](guidelines/agent-infra/installed-tools-manifest.md).
+
+### Team onboarding — clone → sync → done
+
+New team members get every AI bridge online with a single command:
+
+```bash
+git clone <repo>
+cd <repo>
+npx @event4u/agent-config sync
+```
+
+`sync` reads `agents/installed-tools.lock` and re-runs the installer
+for every tool whose bridge marker is missing locally. Idempotent —
+re-running after every clone is safe. Tools with markers already in
+place are skipped.
+
+Pair it with a CI gate to catch drift in PRs:
+
+```bash
+npx @event4u/agent-config validate
+```
+
+`validate` is read-only. Exit 1 on any of: marker missing, scope
+divergence (manifest says `project` but marker only exists at the
+global anchor, or vice versa), version drift (manifest's
+`agent_config_version` ≠ installed package). Full drift catalog and
+fix table: [`installed-tools-manifest.md § Drift detection`](guidelines/agent-infra/installed-tools-manifest.md#drift-detection-ci-gate).
 
 ---
 
@@ -559,7 +615,7 @@ When a new version of the package is published:
 
 ```bash
 # npx (one-shot, recommended) — always uses the latest tarball
-npx @event4u/create-agent-config init --tools=claude-code,cursor
+npx @event4u/agent-config init --tools=claude-code,cursor
 
 # Global CLI
 npm install -g @event4u/agent-config@latest

package/docs/setup/per-ide/aider.md

@@ -11,7 +11,7 @@ from the repo root for project conventions.
 ## Install
 
 ```bash
-npx @event4u/create-agent-config init --tools=aider
+npx @event4u/agent-config init --tools=aider
 ```
 
 Populates:

package/docs/setup/per-ide/claude-code.md

@@ -15,7 +15,7 @@ projects to those paths during install.
 
 ```bash
 # Inside an existing repo:
-npx @event4u/create-agent-config init --tools=claude-code
+npx @event4u/agent-config init --tools=claude-code
 
 # Or with the curl entrypoint:
 curl -sSL https://raw.githubusercontent.com/event4u-app/agent-config/main/setup.sh \

package/docs/setup/per-ide/claude-desktop.md

@@ -3,10 +3,14 @@
 The fastest path to running our skills, rules, and (optionally) the MCP
 server inside Claude Desktop. macOS / Windows / Linux. ~5 minutes.
 
-> **TL;DR** — run `npx @event4u/agent-config init --tools=claude-code`
-> inside each project that should expose the skills/rules to Claude
-> Desktop. The package now ships as an npx-resolved runtime; the
-> retired `--global` symlink scheme has been removed.
+> **TL;DR** — Claude Desktop reads from `~/.claude/` (global only, no
+> project-local discovery on macOS). Run `npx @event4u/agent-config
+> global --tools=claude-desktop` once per user, or
+> `npx @event4u/agent-config init --tools=claude-code` per project
+> (Claude Code's project install also covers Desktop on macOS via the
+> shared `~/.claude/` location seeded during `init`). The v1 npm /
+> composer install scheme is retired; the new global-first scheme is
+> ADR-007 and writes through `~/.config/agent-config/installed.lock`.
 
 ## Prerequisites
 

package/docs/setup/per-ide/cline.md

@@ -11,7 +11,7 @@ and `AGENTS.md`.
 ## Install
 
 ```bash
-npx @event4u/create-agent-config init --tools=cline
+npx @event4u/agent-config init --tools=cline
 ```
 
 Populates:
@@ -35,7 +35,7 @@ automatically. Run `/help` in the chat to verify rule loading.
 | Symptom | Fix |
 |---|---|
 | Rules not picked up | Reload VS Code window after `task generate-tools`. |
-| `.clinerules` missing | Re-run `npx @event4u/create-agent-config init --tools=cline`. |
+| `.clinerules` missing | Re-run `npx @event4u/agent-config init --tools=cline`. |
 
 ## Cross-references
 

package/docs/setup/per-ide/codex.md

@@ -11,7 +11,7 @@ repo root for project context.
 ## Install
 
 ```bash
-npx @event4u/create-agent-config init --tools=codex
+npx @event4u/agent-config init --tools=codex
 ```
 
 Populates:

package/docs/setup/per-ide/copilot.md

@@ -13,7 +13,7 @@ falls back to `AGENTS.md` where supported.
 ## Install
 
 ```bash
-npx @event4u/create-agent-config init --tools=copilot
+npx @event4u/agent-config init --tools=copilot
 ```
 
 Populates:
@@ -69,7 +69,7 @@ gh copilot --version             # if you want CLI plugin
 | Symptom | Fix |
 |---|---|
 | Copilot ignores the file | Reload the IDE window after install. |
-| File missing after install | Re-run `npx @event4u/create-agent-config init --tools=copilot`. |
+| File missing after install | Re-run `npx @event4u/agent-config init --tools=copilot`. |
 | Copilot PR review too noisy | See the `copilot-config` skill for suppression patterns. |
 
 ## Cross-references

package/docs/setup/per-ide/cursor.md

@@ -19,7 +19,7 @@ The package ships **both** so you don't have to pick.
 ## Project install
 
 ```bash
-npx @event4u/create-agent-config init --tools=cursor
+npx @event4u/agent-config init --tools=cursor
 ```
 
 This populates:
@@ -32,7 +32,7 @@ This populates:
 Combine surfaces if you use both Cursor and Claude Code:
 
 ```bash
-npx @event4u/create-agent-config init --tools=cursor,claude-code
+npx @event4u/agent-config init --tools=cursor,claude-code
 ```
 
 ## Global install

package/docs/setup/per-ide/gemini-cli.md

@@ -11,7 +11,7 @@ in the package's projection) for project context.
 ## Install
 
 ```bash
-npx @event4u/create-agent-config init --tools=gemini
+npx @event4u/agent-config init --tools=gemini
 ```
 
 Populates:

package/docs/setup/per-ide/windsurf.md

@@ -19,7 +19,7 @@ The package ships **both**.
 ## Project install
 
 ```bash
-npx @event4u/create-agent-config init --tools=windsurf
+npx @event4u/agent-config init --tools=windsurf
 ```
 
 Populates:
@@ -32,7 +32,7 @@ Populates:
 Combine with other surfaces:
 
 ```bash
-npx @event4u/create-agent-config init --tools=windsurf,claude-code,cursor
+npx @event4u/agent-config init --tools=windsurf,claude-code,cursor
 ```
 
 ## Wave-8 frontmatter

package/docs/troubleshooting.md

@@ -34,7 +34,7 @@ bash scripts/install --verbose
 # or, to regenerate everything (overwrites existing bridge files):
 bash scripts/install --force
 # or, for one-shot installs without a local node_modules tree:
-npx @event4u/create-agent-config init --tools=claude-code,cursor
+npx @event4u/agent-config init --tools=claude-code,cursor
 ```
 
 ### Check 2: Does your agent actually read these directories?
@@ -70,7 +70,7 @@ orchestrator explicitly inside the project root:
 
 ```bash
 # One-shot, no local checkout required (recommended)
-npx @event4u/create-agent-config init --tools=claude-code,cursor
+npx @event4u/agent-config init --tools=claude-code,cursor
 
 # When the global CLI is installed
 agent-config install --tools=claude-code,cursor
@@ -84,7 +84,7 @@ When the package version changes, symlinks that pointed to the old
 package path may break. Re-run the installer — it is idempotent:
 
 ```bash
-npx @event4u/create-agent-config init --tools=claude-code,cursor
+npx @event4u/agent-config init --tools=claude-code,cursor
 ```
 
 The installer replaces stale symlinks with fresh ones pointing at the
@@ -99,7 +99,7 @@ and Unix-style symlinks. Recommended setup:
 
 1. **WSL2** (preferred): install Ubuntu or a distribution of your choice,
    clone the project inside the WSL filesystem, and run
-   `npx @event4u/create-agent-config init` from WSL.
+   `npx @event4u/agent-config init` from WSL.
 2. **Git Bash**: works for the basic install, but symlinks require
    Developer Mode (Windows 10 1703+) or admin privileges. Without either,
    Git Bash falls back to copies, which means updates will not propagate

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "2.1.0",
+    "version": "2.2.1",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,

package/scripts/_cli/cmd_export.py

@@ -0,0 +1,157 @@
+"""``agent-config export`` — eject a tool's canonical content into the project.
+
+Phase 1.5 of road-to-global-first-install.md (ADR-007 D3). Replaces the
+rejected symlink-bridge subcommand: writes a real file with the resolved
+content for a named tool into a user-chosen path so it can be committed,
+shared with the team, or customized in place. Idempotent by default;
+``--force`` overrides content drift. No canonical-path defaults.
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import sys
+from pathlib import Path
+from typing import Callable, Optional
+
+from scripts.install import (
+    AIDER_MARKER,
+    CLAUDE_DESKTOP_MARKER,
+    CODEX_MARKER,
+    CONTINUE_MARKER,
+    JETBRAINS_MARKER,
+    KILOCODE_MARKER,
+    KIRO_MARKER,
+    ROOCODE_MARKER,
+    ZED_MARKER,
+)
+
+PACKAGE_ROOT = Path(__file__).resolve().parents[2]
+TEMPLATES_DIR = PACKAGE_ROOT / ".agent-src" / "templates"
+
+
+def _from_template(rel: str) -> Callable[[], str]:
+    def _read() -> str:
+        path = TEMPLATES_DIR / rel
+        if not path.is_file():
+            raise FileNotFoundError(
+                f"template missing from package: {path} "
+                f"(reinstall @event4u/agent-config or report a bug)"
+            )
+        return path.read_text(encoding="utf-8")
+    return _read
+
+
+def _from_constant(value: str) -> Callable[[], str]:
+    def _read() -> str:
+        return value
+    return _read
+
+
+# tool_id → (description, content_provider).
+EXPORT_REGISTRY: "dict[str, tuple[str, Callable[[], str]]]" = {
+    "roocode": ("Roo Code marker (.roo/rules/agent-config.md body)",
+                _from_constant(ROOCODE_MARKER)),
+    "claude-desktop": ("Claude Desktop marker (informational, global-scope tool)",
+                       _from_constant(CLAUDE_DESKTOP_MARKER)),
+    "aider": ("Aider marker (manual `read:` wiring documented inline)",
+              _from_constant(AIDER_MARKER)),
+    "codex": ("Codex CLI marker (informational — AGENTS.md is canonical)",
+              _from_constant(CODEX_MARKER)),
+    "continue": ("Continue.dev marker (.continue/rules/agent-config.md body)",
+                 _from_constant(CONTINUE_MARKER)),
+    "kilocode": ("Kilo Code marker (.kilocode/rules/agent-config.md body)",
+                 _from_constant(KILOCODE_MARKER)),
+    "zed": ("Zed marker (informational — .rules at repo root is canonical)",
+            _from_constant(ZED_MARKER)),
+    "jetbrains": ("JetBrains AI Assistant marker (.jetbrains/agent-config.md body)",
+                  _from_constant(JETBRAINS_MARKER)),
+    "kiro": ("Kiro marker (.kiro/steering/agent-config.md body)",
+             _from_constant(KIRO_MARKER)),
+    "agents-md": ("AGENTS.md template (Thin-Root entry point — consumer scaffold)",
+                  _from_template("AGENTS.md")),
+    "copilot-instructions": ("GitHub Copilot Code Review instructions template",
+                             _from_template("copilot-instructions.md")),
+}
+
+
+def _list_tools(out) -> int:
+    print("Available tools for `agent-config export --tool <id>`:", file=out)
+    width = max(len(t) for t in EXPORT_REGISTRY) + 2
+    for tool_id, (desc, _) in sorted(EXPORT_REGISTRY.items()):
+        print(f"  {tool_id:<{width}}{desc}", file=out)
+    return 0
+
+
+def _hash(content: str) -> str:
+    return hashlib.sha256(content.encode("utf-8")).hexdigest()
+
+
+def _rel(path: Path) -> Path:
+    try:
+        return path.relative_to(Path.cwd())
+    except ValueError:
+        return path
+
+
+def _write(output: Path, content: str, *, force: bool, out, err) -> int:
+    if output.exists():
+        existing = output.read_text(encoding="utf-8")
+        if _hash(existing) == _hash(content):
+            print(f"ℹ️  {_rel(output)} already exported (content matches).", file=out)
+            return 0
+        if not force:
+            print(
+                f"❌  refusing to overwrite {output} — content differs. "
+                f"Pass --force to replace.",
+                file=err,
+            )
+            return 1
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(content, encoding="utf-8")
+    print(f"✅  exported to {_rel(output)}", file=out)
+    return 0
+
+
+def main(argv: Optional[list[str]] = None, *, out=sys.stdout, err=sys.stderr) -> int:
+    parser = argparse.ArgumentParser(
+        prog="agent-config export",
+        description="Eject a tool's resolved content into a user-chosen path.",
+    )
+    parser.add_argument("--tool", metavar="ID",
+                        help="Tool to export (see --list for the catalog).")
+    parser.add_argument("--output", metavar="PATH",
+                        help="Destination path (relative to CWD).")
+    parser.add_argument("--force", action="store_true",
+                        help="Overwrite an existing file with non-matching content.")
+    parser.add_argument("--list", action="store_true",
+                        help="Print supported tool IDs with descriptions and exit.")
+    args = parser.parse_args(argv)
+
+    if args.list:
+        return _list_tools(out)
+    if not args.tool:
+        print("❌  --tool is required (see --list for the catalog).", file=err)
+        return 2
+    if not args.output:
+        print("❌  --output is required (no canonical-path defaults).", file=err)
+        return 2
+
+    entry = EXPORT_REGISTRY.get(args.tool)
+    if entry is None:
+        print(f"❌  unknown tool: {args.tool} (see --list)", file=err)
+        return 2
+
+    _, provider = entry
+    try:
+        content = provider()
+    except FileNotFoundError as exc:
+        print(f"❌  {exc}", file=err)
+        return 1
+
+    output = Path(args.output).expanduser().resolve()
+    return _write(output, content, force=args.force, out=out, err=err)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

package/scripts/_cli/cmd_sync.py

@@ -0,0 +1,162 @@
+"""``agent-config sync`` — replay the installed-tools manifest (ADR-008).
+
+Phase 3.3 of road-to-global-first-install.md. Reads
+``agents/installed-tools.lock``, then re-runs the bridge install for every
+tool whose ``bridge_marker`` is missing on disk. Tools whose marker already
+exists are skipped — the typical clone-and-sync flow is therefore idempotent
+on the second invocation.
+
+Sync never edits the manifest itself; ``init`` is the only writer. Sync only
+calls the installer with ``--scope`` / ``--tools`` derived from the manifest
+entries, so the manifest is the single source of truth.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+from typing import Iterable
+
+from scripts._lib import installed_tools
+from scripts.install import main as install_main
+
+
+def _marker_exists(project_root: Path, bridge_marker: str, scope: str) -> bool:
+    if not bridge_marker:
+        return True  # substrate-only entries (rare); treat as present
+    if scope == "global":
+        target = Path(bridge_marker).expanduser()
+    else:
+        # Project-scope: relative to the project root unless absolute.
+        candidate = Path(bridge_marker)
+        target = candidate if candidate.is_absolute() else (project_root / candidate)
+    return target.exists()
+
+
+def _group_by_scope(
+    entries: Iterable[dict],
+    project_root: Path,
+) -> tuple[dict[str, list[str]], list[tuple[str, str]]]:
+    """Return ({scope: [tool_names]}, [(name, marker_path)]) for missing tools.
+
+    The second list is the human-readable summary of what will be replayed.
+    """
+    missing: dict[str, list[str]] = {"project": [], "global": []}
+    surfaced: list[tuple[str, str]] = []
+    for entry in entries:
+        name = str(entry.get("name", "")).strip()
+        scope = str(entry.get("scope", "")).strip()
+        bridge_marker = str(entry.get("bridge_marker", "")).strip()
+        if not name or scope not in ("project", "global"):
+            continue
+        if _marker_exists(project_root, bridge_marker, scope):
+            continue
+        missing[scope].append(name)
+        surfaced.append((name, bridge_marker))
+    return missing, surfaced
+
+
+def _run_install(scope: str, tools: list[str], project_root: Path, *, force: bool, dry_run: bool) -> int:
+    if not tools:
+        return 0
+    argv = [f"--scope={scope}", f"--tools={','.join(sorted(set(tools)))}"]
+    if scope == "project":
+        argv += [f"--project={project_root}", "--no-smoke"]
+    if force:
+        argv.append("--force")
+    if dry_run:
+        argv.append("--skip-bridges")
+    return install_main(argv)
+
+
+def _parse(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="agent-config sync",
+        description=(
+            "Replay agents/installed-tools.lock — re-installs any tool whose "
+            "bridge marker is missing locally. Idempotent."
+        ),
+    )
+    parser.add_argument(
+        "--project",
+        default=None,
+        help="Override the project root (defaults to PROJECT_ROOT or cwd).",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print the planned replay set without touching bridges.",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Forwarded to the installer (overwrites existing bridge files).",
+    )
+    parser.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Suppress non-essential output.",
+    )
+    return parser.parse_args(argv)
+
+
+def _emit(quiet: bool, msg: str) -> None:
+    if not quiet:
+        print(msg)
+
+
+def main(argv: list[str]) -> int:
+    opts = _parse(argv)
+    project_root = Path(
+        opts.project or os.environ.get("PROJECT_ROOT") or os.getcwd()
+    ).resolve()
+    manifest = installed_tools.manifest_path(project_root)
+    data = installed_tools.read_manifest(manifest)
+
+    if data is None:
+        _emit(opts.quiet, f"❌  No manifest found at {manifest}")
+        _emit(opts.quiet, "    Run `./agent-config init --tools=<id>` to create one.")
+        return 1
+
+    entries = list(data.get("tools") or [])
+    if not entries:
+        _emit(opts.quiet, f"ℹ️  Manifest is empty: {manifest}")
+        return 0
+
+    missing, surfaced = _group_by_scope(entries, project_root)
+    total_missing = sum(len(v) for v in missing.values())
+    total_present = len(entries) - total_missing
+
+    _emit(opts.quiet, f"Manifest:  {manifest}")
+    _emit(opts.quiet, f"Tools:     {len(entries)} listed, {total_present} present, {total_missing} missing")
+    if total_missing == 0:
+        _emit(opts.quiet, "✅  All bridges already installed. Nothing to do.")
+        return 0
+
+    for name, marker in surfaced:
+        _emit(opts.quiet, f"  • {name:<15} → {marker} (missing)")
+
+    if opts.dry_run:
+        _emit(opts.quiet, "")
+        _emit(opts.quiet, "Dry-run: no bridges written.")
+        return 0
+
+    _emit(opts.quiet, "")
+    for scope in ("project", "global"):
+        tools = missing[scope]
+        if not tools:
+            continue
+        _emit(opts.quiet, f"Replaying scope={scope}: {', '.join(sorted(tools))}")
+        rc = _run_install(scope, tools, project_root, force=opts.force, dry_run=False)
+        if rc != 0:
+            _emit(opts.quiet, f"❌  Installer failed for scope={scope} (rc={rc}); aborting.")
+            return rc
+
+    _emit(opts.quiet, "")
+    _emit(opts.quiet, "✅  Sync complete.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))