@event4u/agent-config 2.1.0 → 2.2.1

package/docs/decisions/ADR-007-agent-discovery-scopes.md

@@ -0,0 +1,286 @@
+---
+adr: 007
+status: accepted
+date: 2026-05-12
+decision: global-default-install-with-export-subcommand
+supersedes: —
+superseded_by: —
+phase: post-v2.1.0 · simplicity-and-everywhere
+---
+
+# ADR-007 — Agent Discovery Scopes: Global-Default Install Model
+
+> **Note (post-acceptance):** the one-shot installer command was later
+> renamed from `npx @event4u/create-agent-config init` to
+> `npx @event4u/agent-config init` when the standalone wrapper package
+> was retired. References to the old command name below are preserved
+> for historical accuracy; the discovery-scope decision itself is
+> unchanged. See `CHANGELOG.md` → `[Unreleased]` → "Package
+> consolidation".
+
+## Status
+
+**Accepted** · 2026-05-12 · signed off by Matze after Council Round 3 convergence. Implementation tracked in `agents/roadmaps/road-to-global-first-install.md`.
+
+Originates from user ask: "Es macht keinen Sinn, das paket nicht
+global zu installieren." Validated through AI Council (2 + 1 rounds,
+2026-05-12 · members claude-sonnet-4-5 + gpt-4o). Council session:
+[`agents/council-sessions/2026-05-12-global-first-strategy/`](../../agents/council-sessions/2026-05-12-global-first-strategy/). <!-- council-ref-allowed: ADR decision trace -->
+
+## Context
+
+`event4u/agent-config` v2.1.0 ships strictly via
+`npx @event4u/create-agent-config init`, project-scoped. The package
+must serve **10 distinct AI agents**, each with its own discovery
+rules — both user-scope (global) and project-scope (workspace) paths.
+Today the CLI only installs project-locally; a `global` subcommand
+in `scripts/agent-config` returns "reserved for Phase 3 of
+road-to-simplicity-and-everywhere".
+
+The user wants global to be the **default** path, not a special case.
+Before flipping the default, we needed to answer four blocking
+questions: (1) is global-default sound across all 10 agents? (2) how
+do we detect user intent? (3) how do we handle tools that
+project-scope wins? (4) how do we preserve version reproducibility
+once `npx` resolves global state?
+
+### Relationship to the retired `--global` (commit `5388de25`)
+
+A previous `--global` flag existed in `scripts/install.py` and was
+**retired** on 2026-05-12 alongside the composer/npm drop
+(`road-to-portable-runtime-and-update-check` step P0.5,
+[archived roadmap](../../agents/roadmaps/archive/road-to-portable-runtime-and-update-check.md)).
+The retired design was an **in-project symlink scheme** driven by
+`templates/global-install-manifest.yml` — it wrote symlinks *into the
+project* pointing back at a curated set in the user's home. Pain that
+killed it: gitignore drift, link breakage on rebase / worktree, and a
+manifest separate from the main install set that drifted out of sync.
+
+ADR-007's `--global` is a **different mechanism with the same flag
+name**:
+
+| Dimension | Retired `--global` (pre `5388de25`) | ADR-007 `--global` (this decision) |
+|---|---|---|
+| Files live in | Project repo (`.claude/`, …) as symlinks | User home (`~/.claude/`, …) as **real files** |
+| Manifest | Separate curated `global-install-manifest.yml` | Same full set as project install (D4) |
+| Project-side artefacts | Symlinks, gitignored | None by default; opt-in via `export` (D3) |
+| Version-pin governance | None — drift via symlink target swap | `~/.config/agent-config/installed.lock` (D5) |
+| In-project gitignore footprint | Required and brittle | Zero |
+
+The retired pain is structurally absent from the new design: no
+in-project symlinks, no manifest split, an explicit version lockfile.
+The flag name is reused; the implementation is rebuilt.
+
+### Verified per-agent discovery matrix (May 2026)
+
+| Agent | User-scope (global) | Project-scope | Precedence |
+|---|---|---|---|
+| Claude Code | `~/.claude/{skills,commands,rules,settings.json}` + `~/.claude/CLAUDE.md` | `.claude/…` + `CLAUDE.md` | managed > user > project (skills) |
+| Claude Desktop | `~/.claude/` (shared) | — | user only |
+| Cursor | User Rules (app settings) + `~/.cursor/` (MCP) | `.cursor/rules/*.mdc` | team > user > project |
+| Windsurf | `~/.codeium/windsurf/global_rules.md` + `…/global_workflows/` | `.windsurfrules` + `.windsurf/{rules,workflows}/` | **workspace > global** |
+| Cline | `~/Documents/Cline/Rules/` | `.clinerules` (file or dir) | **workspace > global** |
+| Augment Code | `~/.augment/{rules,commands}/` | `.augment/{rules,commands}` + `.augment-guidelines` + `AGENTS.md` | workspace > user (cmds); user always-on (rules) |
+| GitHub Copilot | `~/.copilot/copilot-instructions.md` (CLI) + Personal Instructions (settings) | `.github/copilot-instructions.md` + `.github/instructions/*` | personal > repo > org |
+| Gemini CLI | `~/.gemini/GEMINI.md` + `~/.gemini/settings.json` | `GEMINI.md` (hierarchical) + `.gemini/settings.json` | **project > user > system** |
+| Aider | `~/.aider.conf.yml` + `~/.aider.conventions.md` | `.aider.conf.yml` (git root) + `CONVENTIONS.md` | last loaded wins |
+| OpenAI Codex | `~/.codex/AGENTS.md` (+ override) + `$HOME/.agents/skills` | `AGENTS.md` (repo + nested) + `.agents/skills` + `.codex/config.toml` | closer-to-cwd wins |
+
+**Finding:** every supported agent has a user-scope path. Global
+install is technically viable across the entire matrix.
+
+**Asymmetry that bit the original strategy:** Windsurf and Cline are
+`workspace > global` — a project-local override silently wins. Gemini
+is `project > user > system`. Claude Code is `user > project` for
+skills. A symlink-bridge approach (originally proposed) cannot give a
+consistent cross-tool experience because per-tool precedence rules
+differ.
+
+## Council Process
+
+| Round | Members | Cost (actual) | Verdict |
+|---|---|---|---|
+| 1 + 2 (interleaved) | claude-sonnet-4-5 + gpt-4o | $0.0443 | claude: **REJECT** · gpt-4o: **MODIFY** |
+| 3 (targeted resolution) | same | $0.0252 | **3/4 convergence** |
+
+Full responses:
+[`responses.json`](../../agents/council-sessions/2026-05-12-global-first-strategy/responses.json), <!-- council-ref-allowed: ADR decision trace -->
+[`responses-round3.json`](../../agents/council-sessions/2026-05-12-global-first-strategy/responses-round3.json). <!-- council-ref-allowed: ADR decision trace -->
+
+## Decision
+
+Adopt **Global-Default Install with Export-Subcommand** in five parts.
+
+### D1 — Install scope: global is the default
+
+`npx @event4u/create-agent-config init` defaults to **user-scope
+install** (`~/.claude/`, `~/.cursor/`, `~/.codeium/windsurf/`,
+`~/.augment/`, `~/Documents/Cline/Rules/`, `~/.copilot/`, `~/.gemini/`,
+`~/.aider.conventions.md`, `~/.codex/`). Project-scope install is
+**opt-in** via `--project[=<dir>]`. Global is no longer a flag — it
+is the brand promise.
+
+Rationale: one npx invocation = configured everywhere. Per-project
+overrides remain available via existing `.agent-settings.yml` merge
+chain (`~/.config/agent-config/agent-settings.yml` → project
+`.agent-settings.yml` → CLI flags).
+
+### D2 — Init UX: prompt only on ambiguity
+
+| Signal | Behaviour |
+|---|---|
+| CWD has existing `.agent-settings.yml` | Install **project** (current behaviour preserved) |
+| CWD has `package.json` / `composer.json` / `pyproject.toml` AND existing AI-tool config (`.claude/`, `.cursor/`, etc.) | Prompt: `Project (current dir) / User (~/) / Custom path` |
+| CWD has existing `~/.claude/CLAUDE.md` and command would overwrite | Prompt: `Merge / Backup-and-replace / Abort` — **Hard Floor** |
+| Anything else (incl. CWD = `~/`, empty dir, dotfile-git repos) | Install **global**, no prompt |
+
+`.git/` presence is **explicitly not a signal** (monorepos, dotfile
+managers, Hg/SVN workspaces all break it). Replaced by multi-signal
+detection + collision-triggered prompt.
+
+### D3 — Bridge → Export
+
+The originally proposed symlink-bridge subcommand is **rejected**.
+Replaced by:
+
+```
+agent-config export --tool=<x> --output=<path> [--force]
+```
+
+Behaviour:
+- Writes a **real file** (no symlink) with the resolved content for
+  the named tool, into the user-specified path.
+- Idempotent. `--force` overwrites; default refuses on existing file
+  with non-matching content (Hard Floor).
+- User decides path — no canonical defaults baked in (tool-specific
+  paths drift upstream).
+- Use cases: committing `.github/copilot-instructions.md` for team
+  sharing, versioning `AGENTS.md` or `CLAUDE.md` in repo, exporting
+  curated subsets to `docs/ai-context.md`.
+
+Rejected: symlink-bridge. Reasons (council-converged):
+- Tool-precedence asymmetry makes symlinks behave differently per
+  tool (Windsurf ignores global-bridged file; Claude Code honors it).
+- Symlinks under Git track the pointer path, not content — useless
+  on team-mate machines where `~/` differs.
+- Windows symlink privilege (`SeCreateSymbolicLinkPrivilege`) is
+  developer-mode / admin-only; corporate Group Policy frequently
+  blocks it.
+- EDR tools quarantine symlinks in user-profile config directories
+  as "unusual script activity".
+
+### D4 — Manifest: single full set, no curation split
+
+Global install ships **all** kernel + tier-1 + tier-2 + skills (same
+manifest as project install). No `templates/global-install-manifest.yml`.
+
+Council convergence is **3/4** here — anthropic strongly recommends
+**(a) full** with the argument "10 MB is negligible on any dev
+machine; curated subset creates drift + discovery problems + a second
+command to unblock the rest". OpenAI prefers **(b) curated** but with
+generic rationale.
+
+**Residual debate:** the (b) curated camp can still be honored
+post-implementation by adding an `agent-config install --minimal`
+flag without changing the default, if real-world feedback shows the
+full footprint hurts. The decision here is "ship full, narrow later
+if needed" rather than "ship curated, broaden later".
+
+### D5 — Version reproducibility: lockfile
+
+```
+~/.config/agent-config/installed.lock
+```
+
+Schema:
+```json
+{
+  "version": "2.2.0",
+  "installed_at": "2026-05-12T10:30:00Z",
+  "tools": ["claude-code", "cursor", "windsurf"]
+}
+```
+
+`init` on existing lock with matching version: **skip**.
+`init` on existing lock with differing version: **fail loud** with
+"Installed: v2.1.0. Current: v2.2.0. Run `agent-config update` or
+`init --force`."
+
+`update` is an explicit subcommand. Writes new lock atomically. No
+silent updates ever.
+
+### D6 — Source-repo guard stays
+
+`AGENT_CONFIG_ALLOW_SELF_INSTALL=1` requirement when run from inside
+the `agent-config` source repo applies to **both** global and
+project modes (a stray `npx … init` from inside the source tree
+would overwrite the maintainer's `~/.claude/` with package's own
+maintainer manifest).
+
+## Consequences
+
+### Positive
+
+- One command, every project: `npx @event4u/create-agent-config init` works
+  in `~/`, in a fresh project, in an existing project with no config.
+- Cross-tool consistency: every supported agent gets the same skill /
+  rule set from one source of truth in `~/`.
+- No symlink-related fragility (Windows, EDR, Git semantics).
+- Version reproducibility via lockfile is auditable, inspectable, and
+  explicit.
+
+### Negative
+
+- Behavioural change vs v2.1.0: existing project-installs continue to
+  work, but new installs default to a different location. Ships as a
+  v2.x release (v2.0.0 was the breaking npx-only cut; subsequent v2.x
+  work refines that line — no v3.0.0 planned). Documented migration
+  in the release notes is required.
+- Tools with `workspace > global` precedence (Windsurf, Cline,
+  Gemini) require user action to bridge: either `agent-config export`
+  into the project or `--project` flag at install. Pure global-only
+  users on those tools may not see the rules apply inside specific
+  repos.
+- A `~/.config/agent-config/installed.lock` introduces a new state
+  surface. Uninstall must remove it cleanly; corrupted-lock recovery
+  needs documenting.
+- Curation decision is provisional. If `~/.claude/skills/` footprint
+  causes complaints, post-launch we may need to add a `--minimal`
+  install profile (revisits D4).
+
+### Neutral
+
+- The latent `--global` flag in `scripts/install.py` becomes the new
+  default codepath — no longer hidden, fully exercised in CI.
+- The `bridge` subcommand reserved for "Phase 3 of
+  road-to-simplicity-and-everywhere" is **never built**. Roadmap
+  entry should be updated to point at `export` instead.
+
+## Implementation Plan (deferred to roadmap)
+
+Out of scope for this ADR. Sequencing target for a separate roadmap:
+
+1. Branch `feat/global-first-install` (requires user permission to
+   create — not auto-spawned by this ADR).
+2. Wire `scripts/install.py --global` through `create-agent-config`
+   npx entry + `scripts/agent-config global` subcommand.
+3. Implement multi-signal detection + collision prompt.
+4. Implement `agent-config export --tool=<x> --output=<path>`.
+5. Implement `~/.config/agent-config/installed.lock` + `update`
+   subcommand.
+6. Update `docs/installation.md`, per-IDE setup pages, `README.md`
+   tagline.
+7. Add CI matrix: global-install path on macOS, Linux, Windows
+   (lockfile, prompt suppression, Hard Floor enforcement).
+8. CHANGELOG entry + v2.x migration guide.
+
+## References
+
+- Council session:
+  [`agents/council-sessions/2026-05-12-global-first-strategy/`](../../agents/council-sessions/2026-05-12-global-first-strategy/) <!-- council-ref-allowed: ADR decision trace -->
+- User-scope discovery matrix sources: agent vendor official docs
+  (Claude, Cursor, Windsurf, Cline, Augment, Copilot, Gemini, Aider,
+  Codex) accessed 2026-05-12.
+- Prior latent global code: `scripts/install.py` (~280 LOC, never
+  reachable from npx entry).
+- Related rule: [`non-destructive-by-default`](../../.augment/rules/non-destructive-by-default.md) — Hard Floor on overwrite of user's existing `~/.claude/CLAUDE.md`.

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/getting-started.md

@@ -10,7 +10,7 @@ Pick one entrypoint:
 
 ```bash
 # Recommended — one-shot, no local dependency
-npx @event4u/create-agent-config init --tools=claude-code,cursor
+npx @event4u/agent-config init --tools=claude-code,cursor
 
 # No-Node fallback — curl | bash entrypoint (downloads a tarball)
 curl -sSL https://raw.githubusercontent.com/event4u-app/agent-config/main/setup.sh | bash

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).