@event4u/agent-config 2.1.0 → 2.2.0

package/.agent-src/rules/no-cheap-questions.md

@@ -20,9 +20,17 @@ NEVER OFFER NUMBERED CHOICES WITHOUT A REAL TRADE-OFF.
 
 ## What counts as cheap
 
-Nine classes — sequencing · format-only · commit asks (forbidden by [`commit-policy`](commit-policy.md)) · CI / test asks ([`verify-before-complete`](verify-before-complete.md) decides) · fenced-step re-asks ([`scope-control § fenced step`](scope-control.md#fenced-step--user-set-review-gates)) · Iron-Law option (breaches `commit-policy`, `scope-control § git-ops`, or `non-destructive-by-default`) · context-derived · dominant option · re-ask after decline ([`scope-control § decline = silence`](scope-control.md#decline--silence--no-re-asking-on-the-same-task)).
+Ten classes — sequencing · format-only · commit asks · CI / test asks · fenced-step re-asks · Iron-Law option · context-derived · dominant option · re-ask after decline · **paternalistic state-assuming option** (Iron Law 3 below). Per-class detail + governing rule: [`asking-and-brevity-examples § cheap-question-catalog`](../docs/guidelines/agent-infra/asking-and-brevity-examples.md#cheap-question-class-catalog--extended-examples).
 
-Per-class patterns and examples: [`asking-and-brevity-examples § cheap-question-catalog`](../docs/guidelines/agent-infra/asking-and-brevity-examples.md#cheap-question-class-catalog--extended-examples).
+## Iron Law 3 — No Paternalistic State-Assuming Options
+
+```
+NEVER FABRICATE USER STATE TO JUSTIFY AN OPTION.
+"TAKE A BREAK", "SLEEP ON IT", "COME BACK FRESH" — FORBIDDEN.
+THE USER DECIDES WHEN TO STOP. THE AGENT DECIDES WHAT TO BUILD NEXT.
+```
+
+Every numbered option = technical / scope / sequencing choice with real trade-off, not mood-management nudge. Forbidden patterns + carve-outs: [`asking-and-brevity-examples § iron-law-3`](../docs/guidelines/agent-infra/asking-and-brevity-examples.md#no-cheap-questions--iron-law-3-detail-paternalistic-state-options).
 
 ## Pre-Send Self-Check — MANDATORY before every question
 
@@ -34,6 +42,7 @@ Run silently before any numbered-options block:
 4. One option obviously dominant?
 5. User fenced next step (*"plan only"*, *"review first"*) → deliver + handback per `scope-control § fenced step`.
 6. User already declined? Re-ask forbidden per `scope-control § decline = silence`.
+7. Any option assumes user fatigue / frustration / "had enough" without in-message citation? Iron Law 3 — drop it.
 
 Any "yes" → **do not ask**. Pick the dominant path, state assumption inline (*"assuming X — adjust if wrong"*), hand back. One-question-per-turn from [`ask-when-uncertain`](ask-when-uncertain.md) still applies when the question is genuine.
 

package/.agent-src/skills/readme-writing-package/SKILL.md

@@ -146,6 +146,30 @@ install, first example, or requirements.
 deep-link-table pattern, collapsibles, and anti-patterns (premature
 splitting, duplication between README and `/docs/`).
 
+#### Per-AI catalog pattern (multi-platform AI / CLI packages)
+
+For packages targeting many AI assistants or platforms (CLI installers,
+agent-config tools, language SDKs with 10+ targets), prefer flat per-AI
+catalog over giant matrix. One line per target, install command on left,
+aligned trailing comment naming platform:
+
+```bash
+npx <package> init --tools=claude-code      # Claude Code
+npx <package> init --tools=cursor           # Cursor
+npx <package> init --tools=windsurf         # Windsurf
+# ... one line per supported target
+```
+
+Pair catalog with separate "Global install" subsection (same flags plus
+`--global`) and "Other commands" subsection. Reference example:
+[`README.md § Pick specific AIs`](../../../README.md#pick-specific-ais) in
+this repo. Inspiration:
+[`ui-ux-pro-max-skill § Installation`](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill#installation).
+
+Use catalog when package's primary install action varies by platform; use
+matrix table (Tool / Rules / Skills / Commands) for capability comparison.
+Different jobs — install vs. coverage.
+
 README = enough to adopt. Docs = enough to master.
 
 ### 8. Validate

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Shared agent configuration \u2014 skills for AI coding tools (Claude Code, Augment, Cursor, Cline, Windsurf, Gemini CLI).",
-    "version": "2.1.0"
+    "version": "2.2.0"
   },
   "plugins": [
     {

package/CHANGELOG.md

@@ -9,6 +9,23 @@ versioning policy is documented in [CONTRIBUTING.md](CONTRIBUTING.md#versioning-
 
 ## [Unreleased]
 
+Four roadmaps land in this release.
+
+**Global-First Install (R4)** — `npx @event4u/create-agent-config init`
+now defaults to a **global** install (`~/.claude/`, `~/.cursor/`, …)
+when run outside a project, and a **project** install when run inside
+one. A new global lockfile at `~/.config/agent-config/installed.lock`
+records `agent_config_version` + `tools[]` and refuses mismatched
+re-installs (exit 1) until `update` or `--force` realigns it. New
+`agent-config export --tool=<id> --output=<path>` subcommand ejects a
+named tool's resolved content into the project tree (idempotent;
+`--force` overrides drift). 12 supported tool ids (claude-code,
+cursor, windsurf, cline, aider, codex, gemini, copilot,
+claude-desktop, continue, kilocode, zed, jetbrains, kiro). Windows
+CI matrix added for the lockfile + export paths. See
+[`docs/decisions/ADR-007-agent-discovery-scopes.md`](docs/decisions/ADR-007-agent-discovery-scopes.md)
+and [`docs/decisions/ADR-008-installed-tools-manifest.md`](docs/decisions/ADR-008-installed-tools-manifest.md).
+
 Three roadmaps land in this release.
 
 **Universal Execution Engine (R1)** — the `/implement-ticket` runtime is
@@ -318,6 +335,37 @@ our recommendation order, not its support status.
   users" tension without removing any path that an existing user
   might rely on.
 
+## [2.2.0](https://github.com/event4u-app/agent-config/compare/2.1.0...2.2.0) (2026-05-12)
+
+### Features
+
+* **npx:** expand --tools validator to 13 supported AI ids ([7af69a7](https://github.com/event4u-app/agent-config/commit/7af69a766f575c30d8f29ea04052647b6a1b8a19))
+* **cli:** add sync and validate subcommands for installed-tools manifest ([62a5c66](https://github.com/event4u-app/agent-config/commit/62a5c66a131bcf8866be2a8c0e76ba6e054017af))
+* **cli:** add export subcommand and update version-drift handling ([6110f3b](https://github.com/event4u-app/agent-config/commit/6110f3b0ee454ca215c569d8f42ca38ffce577e8))
+* **install:** global-first install with lockfile + installed-tools manifest engine ([6200d42](https://github.com/event4u-app/agent-config/commit/6200d42225d5712a10d5458dc608da3f5cd0164c))
+
+### Bug Fixes
+
+* **rules:** trim no-cheap-questions to satisfy 12% concentration cap ([4abf946](https://github.com/event4u-app/agent-config/commit/4abf94628838c027da13d190e5e7b27738070db2))
+
+### Documentation
+
+* **rules:** add no-cheap-questions Iron Law 3 against paternalistic state options ([b98687b](https://github.com/event4u-app/agent-config/commit/b98687bd397d39eae6811e54eb743a095fa33b8b))
+* README + installation + manifest guideline for global-first install ([cdc52ff](https://github.com/event4u-app/agent-config/commit/cdc52ffc5abb9cff6fda9133dd0b8dc524794d18))
+* **contracts:** add tier-3 contrib plugin contract ([2dbf9cd](https://github.com/event4u-app/agent-config/commit/2dbf9cd2ec772dc2248de2b8f17248e97a67a60b))
+* **adr:** add ADR-007 global-first install + ADR-008 installed-tools manifest ([e214de2](https://github.com/event4u-app/agent-config/commit/e214de27bd8d19858fdc16cecc4ebfeaaebce136))
+
+### CI
+
+* **windows:** add lockfile + export tests on Windows runner ([e5802a5](https://github.com/event4u-app/agent-config/commit/e5802a56f45bcfd5eb845c7af816bb12a0b4492b))
+
+### Chores
+
+* **taskfile:** add test-install-local for offline one-liner smoke test ([594ac69](https://github.com/event4u-app/agent-config/commit/594ac69c8682f106dee9ebc9ce3e55bb0083e254))
+* **roadmap:** archive road-to-global-first-install (24/24 complete) ([71d8cf2](https://github.com/event4u-app/agent-config/commit/71d8cf2966976c286ffecc1646cb7990255cccd1))
+
+Tests: 3350 (+97 since 2.1.0)
+
 ## [2.1.0](https://github.com/event4u-app/agent-config/compare/2.0.0...2.1.0) (2026-05-12)
 
 ### Features

package/README.md

@@ -14,7 +14,7 @@ Give your AI agents an audit-disciplined orchestration contract — testing, Git
 > Your agent picks up the project's stack, runs tests, prepares PRs, fixes CI — and follows your team's coding standards while doing it. Stack-aware skill sets ship for PHP (Laravel · Symfony · Zend/Laminas), JavaScript (Next.js · React · Node), and cross-stack concerns (API · testing · security · observability).
 
 <p align="center">
-  <strong>174 Skills</strong> · <strong>60 Rules</strong> · <strong>106 Commands</strong> · <strong>69 Guidelines</strong> · <strong>8 AI Tools</strong>
+  <strong>174 Skills</strong> · <strong>60 Rules</strong> · <strong>106 Commands</strong> · <strong>70 Guidelines</strong> · <strong>8 AI Tools</strong>
 </p>
 
 ---
@@ -36,6 +36,14 @@ If none of those apply yet — start with the [Quickstart](#quickstart) and pick
 Two minutes from `npx` to a better-behaved agent — no install, no
 vendored package, no postinstall hook.
 
+**v2.1+ — global-first by default.** Running `init` outside a project
+defaults to a user-scope install (`~/.claude/`, `~/.cursor/`, …) and
+records itself in `~/.config/agent-config/installed.lock`. Running it
+inside a project (a `package.json` / `composer.json` / `pyproject.toml`
+manifest is present) defaults to a project-scope install. Override with
+`--scope=global` or `--scope=project`. See
+[`docs/installation.md`](docs/installation.md) for the full matrix.
+
 ### For teams (recommended)
 
 Run once in the project root — `npx` resolves the runtime against the
@@ -77,6 +85,48 @@ Copilot fallback) is wired through one universal dispatcher per
 `--format json` for tooling). The installer also dry-fires the
 dispatcher per bridge as a post-install smoke test (skip: `--no-smoke`).
 
+### Pick specific AIs
+
+Default `init` wires every supported AI. To install just one, pass
+`--tools=<name>`:
+
+```bash
+npx @event4u/agent-config init --tools=claude-code      # Claude Code
+npx @event4u/agent-config init --tools=cursor           # Cursor
+npx @event4u/agent-config init --tools=windsurf         # Windsurf
+npx @event4u/agent-config init --tools=cline            # Cline
+npx @event4u/agent-config init --tools=gemini-cli       # Gemini CLI
+npx @event4u/agent-config init --tools=copilot          # GitHub Copilot
+npx @event4u/agent-config init --tools=augment          # Augment Code
+npx @event4u/agent-config init --tools=roocode          # Roo Code
+npx @event4u/agent-config init --tools=aider            # Aider
+npx @event4u/agent-config init --tools=codex            # Codex CLI
+npx @event4u/agent-config init --tools=claude-desktop   # Claude Desktop
+npx @event4u/agent-config init --tools=continue         # Continue
+```
+
+Multiple AIs in one shot: `--tools=claude-code,cursor,augment`.
+
+#### Global install (user-scope, available across projects)
+
+Add `--global` to write to the user-scope paths from
+[`ADR-007`](docs/decisions/ADR-007-agent-discovery-scopes.md) (`~/.claude/`,
+`~/.cursor/`, …) instead of the current project:
+
+```bash
+npx @event4u/agent-config init --global                       # all tools, user-scope
+npx @event4u/agent-config init --tools=claude-code --global   # → ~/.claude/
+npx @event4u/agent-config init --tools=cursor --global        # → ~/.cursor/
+```
+
+Per-AI scope support varies — Claude Desktop, for example, is
+global-only (no project-local discovery on macOS), while Roo Code and
+Continue.dev are project-local. The Supported Tools table below
+documents per-AI scope. Incompatible combinations (e.g.
+`--tools=roocode --global` or `--tools=claude-desktop` without
+`--global`) are rejected with a directive error; `--tools=all`
+silently filters to the scope's compatible subset.
+
 ### For individual use (optional)
 
 Skills-only, global across projects — installs into the agent itself,
@@ -431,16 +481,31 @@ Every developer gets the same behavior. No per-user setup needed —
 | **Windsurf** | ✅ | — | ☑️ | Reads `.windsurfrules` + commands via AGENTS.md |
 | **Gemini CLI** | ✅ | — | ☑️ | Reads `GEMINI.md` (includes commands reference) |
 | **GitHub Copilot** | ✅ | — | ☑️ | Reads `.github/copilot-instructions.md` (includes commands) |
+| **Roo Code** | ✅ | — | ☑️ | Auto-discovers `.roo/rules/*.md` + AGENTS.md |
+| **Codex CLI** | ✅ | — | ☑️ | Auto-discovers `AGENTS.md` at project root |
+| **Continue.dev** | ✅ | — | ☑️ | Auto-discovers `.continue/rules/*.md` + AGENTS.md |
+| **Aider** | 📌 | — | — | Marker + manual `read:` in `.aider.conf.yml` |
+| **Claude Desktop** | 📌 | — | — | Global-only — install with `--global` (see ADR-007) |
 
 ✅ = native support &nbsp; — = not available &nbsp; ☑️ = text reference only
-(commands are listed in `AGENTS.md`, but the tool cannot invoke them as
-native slash-commands)
+(commands listed in `AGENTS.md`, tool cannot invoke them as native
+slash-commands) &nbsp; 📌 = informational marker only (no auto-discovery
+or manual wiring required)
 
 > **What this means in practice:** Augment Code and Claude Code get the full
 > package (rules + 174 skills + 106 native commands). Cursor, Cline, Windsurf,
-> Gemini CLI, and GitHub Copilot only get the **rules** natively; skills and
-> commands are available to them as documentation the agent can read, not as
-> first-class features.
+> Gemini CLI, GitHub Copilot, Roo Code, Codex CLI, and Continue.dev only get
+> the **rules** natively; skills and commands are available as documentation
+> the agent can read, not as first-class features. Aider and Claude Desktop
+> ship marker-only bridges — Aider needs a one-line `read:` entry in
+> `.aider.conf.yml`; Claude Desktop is global-scope and pairs with `--global`.
+
+> **Team reproducibility (ADR-008):** every tool you `init` is also recorded in
+> `agents/installed-tools.lock` — committed, machine-managed. New team members
+> run `npx @event4u/agent-config sync` after cloning and every bridge in the
+> table above is replayed locally. CI can gate drift with `agent-config validate`.
+> Schema, workflow, and drift catalog:
+> [`docs/guidelines/agent-infra/installed-tools-manifest.md`](docs/guidelines/agent-infra/installed-tools-manifest.md).
 
 ### Plugin-installed (optional, for global use)
 

package/docs/architecture.md

@@ -145,7 +145,7 @@ fails on any source-side violation, without producing artifacts.
 | **Skills** | 174 | On-demand expertise — stack analysis (Laravel · Symfony · Zend / Laminas · Next.js · React · Node), testing, Docker, API design, security, observability, … |
 | **Rules** | 60 | Always-active constraints — coding standards, scope control, verification, language-and-tone, agent-authority |
 | **Commands** | 106 | Slash-command workflows — `/commit`, `/create-pr`, `/fix ci`, `/optimize skills`, `/feature plan`, `/work`, `/implement-ticket`, `/compress`, … |
-| **Guidelines** | 69 | Reference material cited by skills — PHP patterns, Eloquent, Playwright, agent-infra, … |
+| **Guidelines** | 70 | Reference material cited by skills — PHP patterns, Eloquent, Playwright, agent-infra, … |
 | **Templates** | 7 | Scaffolds for features, roadmaps, contexts, skills, overrides |
 | **Contexts** | 5 | Shared knowledge about the system itself |
 

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