@event4u/agent-config 2.1.0 → 2.2.0

package/docs/decisions/ADR-008-installed-tools-manifest.md

@@ -0,0 +1,160 @@
+---
+adr: 008
+status: proposed
+date: 2026-05-12
+decision: committed-installed-tools-manifest-separate-from-settings
+supersedes: —
+superseded_by: —
+phase: v2.x · post-global-first-install
+---
+
+# ADR-008 — Installed-Tools Manifest
+
+## Status
+
+**Proposed** · 2026-05-12 · pending implementation in Phase 3 of
+[`road-to-global-first-install`](../../agents/roadmaps/road-to-global-first-install.md).
+
+Originates from user ask (Matze, 2026-05-12): "Sollten wir auf
+Projektebene festhalten, welche Agents wir initialisiert haben, damit
+bei jedem Sync das Verzeichnis aktualisiert werden kann?" Validated
+through AI Council Round 1 (claude-sonnet-4-5 + gpt-4o, $0.0298 actual,
+both converged on "yes, separate file"). Council session:
+[`agents/council-sessions/2026-05-12-project-settings-and-v1-v2/`](../../agents/council-sessions/2026-05-12-project-settings-and-v1-v2/). <!-- council-ref-allowed: ADR decision trace -->
+
+## Context
+
+After ADR-007 (global-first install), each developer's AI tooling
+lives in user-scope paths (`~/.claude/`, `~/.augment/`, …). A project
+no longer carries the AI config in its tree — except for tools with
+`workspace > global` precedence (Windsurf, Cline, Gemini-when-project-
+wins) that **must** keep a project-local bridge.
+
+**Resulting gap:** a project has no committed record of which AI
+tools it expects. A new team member cloning the repo cannot tell
+whether the codebase was built with Claude Code, Windsurf, both, or
+five others. Onboarding is "ask the team lead, hope they remember".
+
+**Two related but orthogonal problems:**
+
+1. **Bill of materials** — "Which AIs does this project use?"
+2. **Settings hierarchy** — "How do agents behave in this project?"
+
+Today, `.agent-project-settings.yml` (committed) answers #2 (personas,
+quality tools, locked keys). #1 is unanswered.
+
+### What we considered
+
+| Option | Verdict |
+|---|---|
+| **A.** Add `installed_tools` block to `.agent-project-settings.yml` | **Rejected** — mixes behaviour with bill-of-materials, creates a "god file" that every sync command must parse and partially ignore. Settings ≠ manifest. |
+| **B.** Put manifest at root: `.agent-installed-tools.lock` | Rejected — root is already crowded with 10+ AI dotfiles; adding another worsens it. |
+| **C.** Separate manifest at `agents/installed-tools.lock` | **Accepted** — co-located with project-shared agent docs; clear name; clear job. |
+| **D.** Skip — let team docs / README describe the tool set | Rejected — README drifts, no machine-readable contract, no drift detection. |
+
+Council (Sonnet): _"Settings (user prefs, locked keys, override paths)
+≠ Manifest (which tools exist). Mixing them creates a god file."_ Both
+members converged on a separate file; the location split (Sonnet
+favoured `installed-tools.lock`, GPT-4o favoured
+`.project-settings.yml`) resolved in favour of Sonnet on the
+separation-of-concerns argument.
+
+## Decision
+
+**Adopt option C.** Ship `agents/installed-tools.lock` as the
+committed, schema-versioned bill-of-materials for AI tooling.
+
+### Schema (v1)
+
+```yaml
+schema_version: 1
+agent_config_version: "2.x.y"   # version that wrote the file last
+tools:
+  - name: claude-code            # matches scripts/install.py _VALID_TOOLS
+    scope: global                # one of: global, project
+    bridge_marker: ~/.claude/PROJECT_MANAGED_BY_AGENT_CONFIG
+    installed_at: "2026-05-12"
+  - name: windsurf
+    scope: project               # workspace > global → must live in repo
+    bridge_marker: .windsurf/PROJECT_MANAGED_BY_AGENT_CONFIG
+    installed_at: "2026-05-12"
+```
+
+**Fields:**
+
+- `schema_version` — integer; bump on breaking schema changes.
+- `agent_config_version` — last package version that wrote the file.
+- `tools[]` — append-on-init order; not alphabetised (preserves
+  installation history for forensics).
+- `tools[].name` — must match `_VALID_TOOLS` in `scripts/install.py`.
+- `tools[].scope` — `global` (user-home install) or `project`
+  (workspace-wins tools that need a local bridge).
+- `tools[].bridge_marker` — path to the marker file the installer
+  drops to claim ownership. `validate` checks this file exists.
+- `tools[].installed_at` — ISO date; informational only.
+
+### Lifecycle
+
+1. `init --ai <name>` — adds an entry (idempotent). Existing entry
+   for same tool with **same scope** is a no-op. Existing entry with
+   **different scope** refuses without `--force` (loud warning:
+   "tool X is committed as scope=global; you are about to change it
+   to project").
+2. `sync` — reads the lock file, replays every listed tool's install
+   (skip if marker present, install if missing). Used by new team
+   members.
+3. `validate` — read-only drift check. Exit 1 if any listed marker
+   is missing or scope mismatches the file system. **No auto-fix.**
+4. Manual edit — discouraged. Lock file is machine-managed; humans
+   edit via CLI subcommands.
+
+### Relationship to `.agent-project-settings.yml`
+
+| File | Owner | Scope | Example keys |
+|---|---|---|---|
+| `agents/installed-tools.lock` | this ADR | bill of materials | `tools[]`, `scope`, `bridge_marker` |
+| `.agent-project-settings.yml` | layered-settings system | behaviour | `personas.default`, `quality.php.tools`, `locked_keys` |
+
+Both committed, both have a single job, never overlap.
+
+## Consequences
+
+### Positive
+
+- Onboarding: `git clone` + `npx @event4u/agent-config sync` brings
+  every team member's AI tooling to parity.
+- Drift detection: `validate` catches "team lead added Windsurf but
+  forgot to commit the lock-file update".
+- Forensics: install order preserved in `tools[]` order; `installed_at`
+  pins approximate timestamps.
+- Separation of concerns: behaviour settings stay clean; manifest
+  stays focused.
+
+### Negative
+
+- New committed file = one more thing to keep in sync with reality.
+  Mitigated by **machine-written-only** rule and `validate` CI hook.
+- Scope migration (tool moves between `global` and `project`) needs
+  documented playbook in `installed-tools-manifest.md` (Phase 3.5).
+- Single-developer projects gain little — the manifest is overhead
+  until a second developer joins. Mitigation: file is optional;
+  commands work without it (empty manifest = empty install).
+
+### Neutral
+
+- File lives under `agents/`, not at repo root — consistent with
+  Matze's preference and council Sonnet's argument that root is
+  already crowded.
+
+## Implementation Plan
+
+Tracked as Phase 3 of `road-to-global-first-install` (steps 3.1–3.5).
+Ships in a v2.x minor release **after** Phase 2 lands. Out of scope
+for this ADR.
+
+## References
+
+- [`ADR-007`](ADR-007-agent-discovery-scopes.md) — global-first install (this ADR depends on it).
+- [`agents/roadmaps/road-to-global-first-install.md`](../../agents/roadmaps/road-to-global-first-install.md) Phase 3.
+- [`agents/council-sessions/2026-05-12-project-settings-and-v1-v2/`](../../agents/council-sessions/2026-05-12-project-settings-and-v1-v2/) — full council transcripts. <!-- council-ref-allowed: ADR decision trace -->
+- [`docs/guidelines/agent-infra/layered-settings.md`](../guidelines/agent-infra/layered-settings.md) — the existing 4-layer settings precedence; this ADR adds a parallel file outside that hierarchy.

package/docs/decisions/INDEX.md

@@ -10,6 +10,8 @@ _Auto-generated by `scripts/adr/regenerate_index.py`. Do not edit._
 | [ADR-004](ADR-004-rule-governance-pruning.md) | Rule Governance Pruning | accepted | 2026-05-08 | — |
 | [ADR-005](ADR-005-subagent-worktrees.md) | Subagent Worktrees No Auto Merge | accepted | 2026-05-09 | — |
 | [ADR-006](ADR-006-skill-tools-python-pilot.md) | Skill Tools Python Pilot Pass | accepted | 2026-05-09 | — |
+| [ADR-007](ADR-007-agent-discovery-scopes.md) | Global Default Install With Export Subcommand | accepted | 2026-05-12 | — |
+| [ADR-008](ADR-008-installed-tools-manifest.md) | Committed Installed Tools Manifest Separate From Settings | proposed | 2026-05-12 | — |
 
 ## Unnumbered (legacy)
 

package/docs/guidelines/agent-infra/asking-and-brevity-examples.md

@@ -106,3 +106,35 @@ correction pattern.
 
 Acknowledge once, in the user's language, switch behavior, no
 excuses (mirrors `language-and-tone` § slip handling).
+
+
+## No Cheap Questions — Iron Law 3 detail (paternalistic state options)
+
+Companion to `no-cheap-questions` § Iron Law 3. The rule states the
+prohibition; this file lists the patterns and the carve-outs.
+
+**Forbidden patterns** (non-exhaustive):
+
+- "Stop hier — du hast genug für heute"
+- "Take a break and come back fresh"
+- "Weitermachen wenn frisch"
+- "Du wirkst genervt, sollen wir pausieren?"
+- "Sleep on it"
+- "That's a good stopping point" as a numbered option
+- Any option whose recommendation rests on inferred fatigue,
+  frustration, or end-of-day mood.
+
+**Carve-outs** — allowed because they cite **observable, in-message**
+evidence, not inferred state:
+
+- User said "ich bin müde / done for today / let's stop" **this turn**
+  → ack and stop (instruction, not option).
+- Hard Floor confirmation per `non-destructive-by-default` → "confirm
+  or abort" is the option, not "rest".
+- Context-window / freshness threshold tripped per `context-hygiene` →
+  cite the threshold ("fresh chat at 75%"), do not infer mood.
+
+**The rule of thumb**: every numbered option must be a technical /
+scope / sequencing choice with a real trade-off, not a mood-management
+nudge. If the only remaining differentiator is "you might be tired" →
+drop the option, recommend a concrete next step instead.

package/docs/guidelines/agent-infra/installed-tools-manifest.md

@@ -0,0 +1,135 @@
+# Installed-Tools Manifest
+
+Project-committed bill of materials for AI tooling. Answers the
+question "which AIs does this project use, where do their bridges live,
+and is everyone on the team on the same set?". Canonical schema is
+ADR-008 ([`docs/decisions/ADR-008-installed-tools-manifest.md`](../../decisions/ADR-008-installed-tools-manifest.md)).
+Phase 3 of [`road-to-global-first-install`](../../../agents/roadmaps/road-to-global-first-install.md).
+
+This file lives at **`agents/installed-tools.lock`** — committed,
+machine-managed, and orthogonal to `.agent-project-settings.yml`
+(which owns *behaviour*, not *bill of materials*).
+
+## Schema (v1)
+
+```yaml
+schema_version: 1
+agent_config_version: "2.x.y"          # last package version that wrote the file
+tools:
+  - name: claude-code                  # must match _VALID_TOOLS in scripts/install.py
+    scope: global                      # one of: global, project
+    bridge_marker: ~/.claude/          # validate checks this path exists
+    installed_at: "2026-05-12"
+  - name: roocode
+    scope: project                     # workspace-wins → must live in repo
+    bridge_marker: .roo/rules/agent-config.md
+    installed_at: "2026-05-12"
+```
+
+| Field | Owner | Notes |
+|---|---|---|
+| `schema_version` | machine | bumps on breaking schema changes |
+| `agent_config_version` | machine | last writer's package version; `validate` flags drift |
+| `tools[]` | machine | append-on-init order preserved (not alphabetised) |
+| `tools[].name` | machine | one of the 17 valid IDs in `scripts/install.py` |
+| `tools[].scope` | machine | `global` (user-home) or `project` (workspace bridge) |
+| `tools[].bridge_marker` | machine | absolute / `~`-prefixed for global, repo-relative for project |
+| `tools[].installed_at` | machine | ISO date; informational only |
+
+The file is **machine-managed**. Hand-editing is discouraged — every
+mutation goes through `init`, `sync`, or `init --force`.
+
+## Workflow
+
+### Team onboarding (clone → sync → done)
+
+```bash
+git clone <repo>
+cd <repo>
+npx @event4u/agent-config sync
+```
+
+`sync` reads `agents/installed-tools.lock`, checks every listed tool's
+bridge marker, and replays `install.py --tools=<id>` for each missing
+one. Tools whose marker is already present are skipped — `sync` is
+idempotent and safe to re-run.
+
+### Adding a tool
+
+```bash
+npx @event4u/agent-config init --tools=<id>
+# or --tools=<id1>,<id2>
+```
+
+`init` writes an entry per tool. Existing entry with the same
+`(name, scope)` → no-op. Entry with **different scope** → loud warning
+and refusal until you pass `--force` (see scope migration below).
+
+### Drift detection (CI gate)
+
+```bash
+npx @event4u/agent-config validate
+```
+
+Read-only. Exit code 1 if any drift is found. Surfaces three drift
+kinds; no auto-fix.
+
+| Kind | Trigger | Fix |
+|---|---|---|
+| `marker_missing` | recorded `bridge_marker` does not exist | `agent-config sync` |
+| `scope_divergence` | marker only exists at the *other* scope | `agent-config init --tools=<id> --force` |
+| `version_drift` | manifest's `agent_config_version` ≠ installed package | `agent-config update` then `agent-config init --force` |
+
+`--skip-version-check` suppresses the third kind for repositories that
+intentionally pin an older version of the manifest.
+
+## Scope migration
+
+Moving a tool between `project` and `global` is supported but loud:
+
+1. Run `init --tools=<id> --scope=<new> --force`. The installer detects
+   the conflict, warns, and rewrites the entry only when `--force` is
+   present.
+2. The old bridge is **not** removed automatically — clean up the
+   leftover marker yourself (`rm .windsurf/agent-config.md` etc.).
+3. `validate` afterwards confirms the new state.
+
+Reasoning: scope is a project-wide decision; flipping it silently
+would surprise other team members who never asked for the change. The
+loud refusal forces an explicit `--force` so the diff is reviewable in
+the next commit.
+
+## Relationship to other files
+
+| File | What it answers | Layer |
+|---|---|---|
+| `agents/installed-tools.lock` | **which AIs?** (this guideline) | bill of materials |
+| `.agent-project-settings.yml` | **how do agents behave?** | layered-settings (team file) |
+| `~/.config/agent-config/installed.lock` | **which package version did I install globally?** | per-developer global lockfile (Phase 1) |
+| `.agent-settings.yml` | **what are my personal preferences in this project?** | layered-settings (developer file) |
+
+Each file has one job. They never overlap. The two `.lock` files look
+similar by name but answer different questions: `installed.lock` is
+per-developer / cross-project (the package itself), while
+`installed-tools.lock` is per-project / team-shared (which tools are
+expected in *this* repo).
+
+## CI integration
+
+Recommended gate (GitHub Actions / GitLab CI):
+
+```yaml
+- name: Validate installed-tools manifest
+  run: npx @event4u/agent-config validate
+```
+
+Pair it with `agent-config sync` in your dev-setup script so new
+contributors get a working environment without reading the manifest by
+hand.
+
+## References
+
+- [`ADR-008`](../../decisions/ADR-008-installed-tools-manifest.md) — manifest decision and schema.
+- [`ADR-007`](../../decisions/ADR-007-agent-discovery-scopes.md) — global-first install (prerequisite).
+- [`docs/installation.md`](../../installation.md) — team-onboarding flow.
+- [`layered-settings.md`](layered-settings.md) — parallel settings hierarchy (orthogonal to this manifest).

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/create-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/create-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
 
@@ -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).
 
 ---
 

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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "2.1.0",
+    "version": "2.2.0",
     "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())