@event4u/agent-config 2.0.0 → 2.2.0

package/docs/contracts/tier-3-contrib-plugin.md

@@ -0,0 +1,129 @@
+---
+stability: beta
+---
+
+# Tier-3 contrib plugin pattern
+
+**Purpose.** Document the deferred-implementation contract for
+**Tier-3 community AIs** — surfaces that have been named in scoping
+discussions or council rounds but have **not yet been requested by
+a real user**. Tier-3 ships when the first user request lands, not
+on speculation.
+
+**Scope.** Defines the candidate list, the manifest shape, the
+promotion path from Tier-3 → Tier-2, and the non-implementation
+guarantee. Does **not** ship code: `agents/manifests/contrib/` is
+unmanifested until a user asks for an entry by name.
+
+Last refreshed: 2026-05-12.
+
+## Tier definitions
+
+| Tier | Status | Trigger | Implementation |
+|---|---|---|---|
+| **Tier-1** | Shipped | First-class surfaces with daily users | Imperative bridge in `scripts/install.py` |
+| **Tier-2** | Shipped | Named in roadmaps + has plausible audience | Imperative bridge, same pattern as Tier-1 |
+| **Tier-3** | **Deferred** | Named in scoping/council but zero user demand | Manifest YAML in `agents/manifests/contrib/` (not yet implemented) |
+
+Phase 2.1 + 2.2 of
+[`road-to-global-first-install`](../../agents/roadmaps/road-to-global-first-install.md)
+closed Tier-1 and Tier-2 at **16 AIs**. Tier-3 is the explicit
+overflow bucket.
+
+## Candidate list (frozen at proposal time)
+
+The following surfaces are Tier-3 candidates as of 2026-05-12. They
+were surfaced during the
+[`2026-05-12-installer-expansion`](../../agents/council-sessions/2026-05-12-installer-expansion/synthesis.md)
+council round and have **no entries** in `_VALID_TOOLS`,
+`USER_SCOPE_PATHS`, `SCOPE_SUPPORT`, or the bash `VALID_TOOLS` set.
+
+- `qoder` — community fork, no public adoption signal
+- `trae` — ByteDance IDE, behind login wall
+- `opencode` — bundled into VS Code variants; coverage already via `vscode`
+- `codebuddy` — Tencent-internal, no public install path
+- `droid` — proposed CLI agent, alpha
+- `warp` — terminal-with-AI; integration shape unclear (PTY vs file marker)
+- `antigravity` — Google research project, no shipping surface
+
+Inclusion in this list is **not** a commitment to ship. Promotion
+requires a real user asking by name (issue, PR, council session, or
+recorded ask).
+
+## Manifest shape (when implemented)
+
+When the first user request lands, the responder MUST:
+
+1. Create `agents/manifests/contrib/<tool-id>.yml` matching the
+   schema below.
+2. Add the tool ID to `_VALID_TOOLS`, `USER_SCOPE_PATHS`,
+   `SCOPE_SUPPORT`, and the bash `VALID_TOOLS` set.
+3. Implement `ensure_<tool>_bridge` in `scripts/install.py` (≤60 LOC
+   — if larger, escalate via ADR per Phase 2.5 gate).
+4. Append a row to the `README.md` "Supported Tools" table.
+5. Re-run `task lint-skills` + `python3 -m pytest tests/test_install_py.py`.
+
+```yaml
+# agents/manifests/contrib/<tool-id>.yml
+tool_id: <slug>           # lowercase, hyphen-separated
+display_name: <Pretty>    # for README + CLI catalog
+scope: project | global | both
+discovery: marker | hook | config-merge
+marker_path: <relative>   # e.g. .tool-id/agent-config.md
+requested_by: <ref>       # GitHub issue, PR, council session, etc.
+requested_date: YYYY-MM-DD
+notes: |
+  Short rationale, integration shape, known limitations.
+```
+
+## Non-implementation guarantee
+
+`agents/manifests/contrib/` does **not** exist until needed. CI does
+not enforce its presence. The pattern is documented, not scaffolded.
+
+This prevents two failure modes:
+
+1. **Empty-shell drift** — a directory of YAML stubs with no
+   corresponding code, where the manifest claims support but the
+   installer silently no-ops.
+2. **Speculative breadth** — adding 7 IDs to `_VALID_TOOLS` "in
+   case" a user asks, then carrying maintenance cost on dead code.
+
+## Promotion path
+
+Tier-3 → Tier-2 promotion happens in a single PR:
+
+1. The first user request anchors the PR (link in commit body).
+2. Manifest YAML lands alongside the bridge.
+3. README + roadmap update in the same commit.
+4. After two reported successful installs (or one release cycle of
+   no bug reports), the tool moves out of `contrib/` and the manifest
+   YAML is deleted — the bridge stands on its own under the Tier-2
+   contract.
+
+There is no Tier-3 → Tier-3 churn: a candidate either gets
+requested and promoted, or stays unimplemented indefinitely. We do
+not "preemptively scaffold" Tier-3 entries.
+
+## Out of scope
+
+- **Capability matrices** — the manifest does not describe what the
+  tool _can_ do, only what the installer must emit. Capability docs
+  live in the consumer tool's own documentation.
+- **Auto-discovery** — there is no plugin loader. The installer is
+  imperative (see Phase 2.5 gate); manifests are a documentation
+  contract, not a runtime input.
+- **Third-party contribution channel** — this contract governs the
+  package maintainer's response to user requests, not a community
+  plugin marketplace. External plugins would require ADR-009+ to
+  introduce a stable extension surface.
+
+## Cross-references
+
+- [`ADR-007`](../decisions/ADR-007-agent-discovery-scopes.md) —
+  project / global / both scope taxonomy that Tier-3 entries inherit.
+- [`ADR-008`](../decisions/ADR-008-installed-tools-manifest.md) —
+  `agents/installed-tools.lock` for per-project state, distinct
+  from this maintainer-side contract.
+- [`road-to-global-first-install`](../../agents/roadmaps/road-to-global-first-install.md)
+  Phase 2.6 — completion trigger for this contract.

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

@@ -0,0 +1,278 @@
+---
+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
+
+## 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

@@ -1,33 +1,23 @@
 # Getting Started
 
 `agent-config` is a stack-agnostic orchestration contract for coding
-agents. The installer detects the project shape (Composer / npm / both /
-neither) and wires the matching glue. **Pick the entrypoint that
-matches the project**, not the language you happen to prefer.
+agents. Installation is npx-first; the package itself is npm-published
+and works in any project regardless of language.
 
 ## Installation
 
-The installer is the same orchestrator across stacks — it reads
-`composer.json` and/or `package.json`, syncs the payload, and generates
-the tool-specific glue. Pick one entrypoint:
+Pick one entrypoint:
 
 ```bash
-# Composer-based projects (PHP / Laravel / Symfony / Zend / Laminas)
-composer require --dev event4u/agent-config
-php vendor/bin/install.php
-# Equivalent: bash vendor/event4u/agent-config/scripts/install
-
-# npm-based projects (Next.js / React / Node / Vue / plain JS/TS)
-npm install --save-dev @event4u/agent-config
-# Postinstall runs the orchestrator. Re-run or pick a profile:
-# bash node_modules/@event4u/agent-config/scripts/install --profile=balanced
-
-# Mixed Composer + npm projects (Laravel + Inertia, Symfony + Vue, …)
-# Run both — the orchestrator merges results, no double-write.
-
-# Stack-less or polyglot repos (no Composer, no npm)
-git clone https://github.com/event4u-app/agent-config /tmp/agent-config
-bash /tmp/agent-config/scripts/install --target "$PWD"
+# Recommended — one-shot, no local dependency
+npx @event4u/create-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
+
+# Global CLI (one install per machine, all projects)
+npm install -g @event4u/agent-config
+agent-config --help
 ```
 
 That's it. Your agent now follows your team's standards. The orchestrator
@@ -49,9 +39,10 @@ so you can run a few package scripts without installing `go-task`,
 ./agent-config help                # full command list
 ```
 
-The wrapper is regenerated on every `npm install` / `composer install`
-and delegates to the copy under `node_modules/@event4u/agent-config/`
-or `vendor/event4u/agent-config/`.
+The wrapper is regenerated on every install and delegates to (in order):
+`$AGENT_CONFIG_MASTER`, `./node_modules/@event4u/agent-config/`,
+`agent-config` on `$PATH` (global npm install), or
+`npx @event4u/agent-config@latest`.
 
 ## First Run
 

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.