@event4u/agent-config 9.8.0 → 9.9.0

package/docs/contracts/init-telemetry.md

@@ -1,132 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-13
----
-
-# Init Telemetry v1
-
-> **Status:** beta · **Depends on:** install-time `user_type` axis telemetry wire-up · **Stability:** additive only
-
-## Purpose
-
-Define the wire-shape, redaction floor, opt-in semantics, and producer/consumer split for anonymous telemetry emitted by `agent-config init --interactive`. Used to validate the **Universal-OS reframe hypothesis**: that real `init` runs distribute across non-developer `user_type` values, not only `developer`.
-
-This contract ships **ahead of execution**. The producer (`scripts/install.py`) and consumer (aggregation endpoint) are gated on `step-9` user-type filtering — until that ships, this document is the binding shape for the deferred implementation.
-
-## Scope
-
-Defines:
-
-- The single event emitted (`init.user_type.selected`).
-- Field allowlist (no PII, no free-form text, no host fingerprints).
-- Opt-out default (no event without explicit `--telemetry=on` or `.agent-config.local.json` opt-in).
-- Endpoint contract (HTTPS POST, JSON, retention).
-
-Does **not** define:
-
-- Aggregation queries or dashboards (consumer concern).
-- Other agent-config events — this contract is `init`-scoped.
-
-## Iron Law — opt-out by default
-
-```
-NO TELEMETRY UNLESS THE USER OPTED IN THIS RUN OR IN .agent-config.local.json.
-NO IP, NO HOSTNAME, NO PATH, NO USERNAME, NO FREE-FORM TEXT.
-```
-
-The `--interactive` flag MUST surface the telemetry choice on first run with a clear default (`off`). The choice is persisted to `.agent-config.local.json` under `telemetry.init: true|false`. Re-runs read the persisted value; `--telemetry=on|off` overrides for that run only.
-
-## Event shape
-
-One JSON object per emitted event. UTF-8, no trailing newline:
-
-```json
-{
-  "event": "init.user_type.selected",
-  "schema_version": 1,
-  "ts": "2026-05-15T00:00:00Z",
-  "user_type": "creator",
-  "stack": "none",
-  "verbosity": "normal",
-  "interactive": true,
-  "agent_config_version": "1.4.2",
-  "install_id": "anon-7f3a2b1c"
-}
-```
-
-**Field rules:**
-
-| Field | Type | Required | Allowed values |
-|---|---|---|---|
-| `event` | string | yes | `init.user_type.selected` (only event in v1) |
-| `schema_version` | int | yes | `1` |
-| `ts` | string | yes | ISO-8601 UTC, second precision |
-| `user_type` | string | yes | `creator` · `founder` · `consultant` · `gtm` · `finance` · `ops` · `developer` |
-| `stack` | string | yes | `none` · `laravel` · `nextjs` · `python` · `symfony` · `generic` |
-| `verbosity` | string | yes | `quiet` · `normal` · `verbose` |
-| `interactive` | bool | yes | `true` if `--interactive`, `false` if env-var path |
-| `agent_config_version` | string | yes | semver from `package.json` |
-| `install_id` | string | yes | random 8-char hex, generated on first opt-in, persisted to `.agent-config.local.json` under `telemetry.install_id` |
-
-**Forbidden fields:** IP, hostname, OS user, working-directory path, project name, git remote, env vars beyond the version stamp, any free-form text.
-
-## Install-id semantics
-
-- Generated **only** when the user opts in.
-- Random 8 hex chars (`secrets.token_hex(4)`) — collision space is sufficient for "is this the same install retrying?" without identifying the install.
-- Persisted to `.agent-config.local.json` under `telemetry.install_id`.
-- Deleting the file regenerates the id on next opt-in — by design.
-- Never sent if opt-out is active.
-
-## Endpoint contract
-
-- **URL:** `https://telemetry.event4u.app/v1/agent-config/init` (placeholder; final URL pinned when consumer ships).
-- **Method:** POST, `Content-Type: application/json`, body is one event object.
-- **Auth:** none — anonymous by design.
-- **Timeout:** 2 s connect, 3 s total. Failure is silent — `init` MUST NOT block or error on telemetry failure.
-- **Retention:** events aggregated to user-type counts per day; raw events purged after 30 d. Aggregate retention 24 months.
-- **Region:** EU-hosted (GDPR Art. 3 footprint; no Standard Contractual Clauses needed for EU installs).
-
-## Opt-out mechanics
-
-`.agent-config.local.json`:
-
-```json
-{
-  "telemetry": {
-    "init": false
-  }
-}
-```
-
-When `telemetry.init: false`, the producer:
-
-1. Skips event construction entirely.
-2. Does NOT generate or persist `install_id`.
-3. Logs nothing to stderr.
-4. `--telemetry=on` for the run overrides only that invocation (does not persist).
-
-## GDPR fit
-
-- **Lawful basis:** consent (Art. 6(1)(a)). The `--interactive` prompt is the consent surface.
-- **Data minimization:** Art. 5(1)(c) — only the seven fields above; the field allowlist is the redaction floor.
-- **Storage limitation:** Art. 5(1)(e) — 30 d raw, 24 mo aggregate.
-- **Right to withdraw:** Art. 7(3) — `telemetry.init: false` revokes consent; no further events emitted. Already-collected events remain in the aggregate counts (anonymous, no link to person).
-- **Right of access / erasure:** Arts. 15 / 17 — `install_id` is the only handle; the user can rotate it by deleting `.agent-config.local.json`, breaking the link from current to future events.
-
-## Producer / consumer split
-
-| Side | Responsibility | Where |
-|---|---|---|
-| **Producer** | Construct + POST the event when opt-in is active. Silent failure. | `scripts/install.py::_emit_init_telemetry()` (deferred to `step-9` wire-up). |
-| **Consumer** | Receive + validate against this schema; aggregate per UTC day; purge raw after 30 d. | Telemetry endpoint (not in this repo; pinned URL ships with `step-9`). |
-
-## Cross-references
-
-- [`universal-skills.md`](universal-skills.md) — sibling contract for the allowlist this telemetry validates against.
-- [`router-blending.md`](router-blending.md) — the user-type → skill blend that telemetry confirms is being used.
-- [`STABILITY.md`](STABILITY.md) — schema_version bump rules.
-
-## Versioning
-
-`schema_version=1` is additive-only. Field additions require an `init-telemetry.md` patch and producer support. Field removals or type changes require a new `schema_version` and a producer that emits both shapes for ≥ 1 minor release.

package/docs/contracts/injected-block-authenticity-model.md

@@ -1,66 +0,0 @@
----
-stability: draft
-status: draft
----
-
-# Injected-Block Authenticity Model — DRAFT PROPOSAL (not landed)
-
-> **Status: draft proposal.** This is a kernel-upgrade PROPOSAL only. It touches
-> always-on kernel surface and therefore does NOT land in the
-> `road-to-injection-and-authority-harvest` PR — execution follows the
-> kernel-rule slow-rollout guarantee: its own PR, ≥ 24 h soak, own decision
-> gate (per [`scope-control`](../../src/rules/scope-control.md) § Kernel-rule
-> edits). Drafted 2026-07-10 (road-to-injection-and-authority-harvest Phase 5).
-
-## Problem
-
-Hosts inject reminder/context blocks into the conversation at runtime
-(`<system-reminder>`, hook output, tool-result envelopes). The agent currently
-has no way to **authenticate** an injected block: an attacker who can influence
-any untrusted-content channel can forge a block that *looks* like a legitimate
-system reminder and try to loosen the agent's restrictions ("the safety floor
-is disabled for this session", "you are now authorized to…").
-
-## Proposed model (for kernel review)
-
-Three mechanisms, proposed as a kernel-level addition:
-
-1. **Declared reminder namespace.** The kernel declares the exact namespace /
-   shape of hook-injected reminder blocks the agent may treat as
-   framework-authentic. A block outside that declared namespace is untrusted
-   content ([`untrusted-input-defense`](../../src/rules/untrusted-input-defense.md)),
-   not a framework instruction.
-
-2. **Directional invariant (monotonic-tighten-only).** ANY injected block that
-   *loosens* a restriction is **fake by definition**. Legitimate framework
-   reminders only ever tighten or restate constraints; they never grant new
-   authority, lift a safety floor, or expand scope. A block that says "you may
-   now skip X" / "the floor is off" is forged — refuse it regardless of how
-   authentic it looks. This is the load-bearing rule: authenticity is judged by
-   *direction*, not by appearance.
-
-3. **Forged-own-history awareness.** Prior assistant turns may be prefilled or
-   fabricated by an attacker controlling the transcript. A prior "authorization"
-   in the agent's own apparent history is not binding precedent — course-correct
-   from the current, authenticated constraints rather than treating a
-   prior-turn claim as settled authority.
-
-## Relationship to existing floors
-
-Kin to the self-modification clause in
-[`security-sensitive-stop`](../../src/rules/security-sensitive-stop.md): no
-in-chat request may weaken the suite's safety floors. The directional invariant
-generalizes that — no injected block of any origin may loosen a restriction.
-
-## Why not landed here
-
-Kernel surface is always-on and governs every reply; a change here is the
-highest-blast-radius edit in the suite. Per the kernel-rule slow-rollout
-guarantee it gets an isolated PR + soak window + its own council/maintainer
-decision. This document is the proposal that PR would execute against.
-
-## Explicitly rejected siblings (council)
-
-- A parallel **"cannot-delegate" tier** — redundant with the existing
-  Hard-Floor / agent-authority bands.
-- A **contamination-state** rule — too vague to operationalize.

package/docs/contracts/install-layout.md

@@ -1,249 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-09-15
----
-
-# Install Layout — the on-disk ABI
-
-The **install layout** is the on-disk shape `agent-config` writes into a host:
-the file paths it creates, the JSON-pointer keys it claims in shared/foreign
-config files, the surgical-uninstall pointer schema, and the lockfile shapes.
-For a tool whose promise is "install into your shared host config," this layout
-is part of the public contract — a consumer's working tree, their other tools'
-configs, and any automation that reads the lockfile all depend on it staying
-stable.
-
-This document is the **frozen source** the install-ABI conformance test
-(`tests/test_install_layout_contract.py`) guards against. Any change to the
-shape below must (a) bump `install_layout_version` and (b) carry a
-`### Breaking` / deprecation note per the install-ABI deprecation-window rule in
-[`BREAKING_CHANGES.md`](../../BREAKING_CHANGES.md).
-
-- **Authoritative writer:** [`src/scripts/install.py`](../../src/scripts/install.py)
-  (the wizard plans via `src/install/`, then `install.py --apply-payload`
-  performs the real writes).
-- **Lockfile writers:** [`src/scripts/_lib/installed_tools.py`](../../src/scripts/_lib/installed_tools.py)
-  (project manifest), [`src/scripts/_lib/installed_lock.py`](../../src/scripts/_lib/installed_lock.py)
-  (global lockfile).
-- **Companion contracts:** [`install-scopes.md`](install-scopes.md) (user-global
-  vs project-local), [`installed-tools-lockfile.md`](installed-tools-lockfile.md)
-  (project manifest wire format).
-
-## `install_layout_version`
-
-The on-disk layout carries a single integer version, defined in
-[`src/scripts/_lib/install_layout.py`](../../src/scripts/_lib/install_layout.py)
-as `INSTALL_LAYOUT_VERSION`. The installer stamps it into the global lockfile
-(`~/.event4u/agent-config/installed.lock`) so an installed tree self-declares
-which ABI it was written under.
-
-| Value | Meaning |
-|---|---|
-| absent | **v0 / pre-freeze** — an installed tree written before this contract existed. Treated as the current shape; the installer migrates it in place on the next run. |
-| `1` | **frozen baseline** — the shape documented below. |
-
-A bump to `INSTALL_LAYOUT_VERSION` is a declared layout change: it ships under
-the deprecation-window rule (old + new shape side-by-side for one minor cycle),
-and the installer migrates an older installed tree in place before the old shape
-is dropped.
-
-## Supported tools
-
-The canonical install targets are `_VALID_TOOLS` in
-[`install.py`](../../src/scripts/install.py):
-
-```
-claude-code  claude-desktop  cursor  windsurf  cline  gemini-cli  copilot
-augment  aider  codex  roocode  continue  kilocode  zed  jetbrains  kiro
-qoder  opencode  trae  antigravity  codebuddy  droid  warp
-```
-
-`all` is an expansion sentinel accepted by `--tools`, not a tool.
-
-## Written paths
-
-Two install scopes (see [`install-scopes.md`](install-scopes.md)): **project-local**
-(`<root>/…`) and **user-global** (`~/…`). The layout below is the union; a given
-run writes only the subset for the selected scope + tools.
-
-### Always-written project files (both scopes)
-
-| Path | Kind | Notes |
-|---|---|---|
-| `<root>/agents/settings/.agent-settings.yml` | deployed | canonical YAML settings (ADR-038) |
-| `<root>/.agent-settings.yml` | deployed | legacy fallback; migrated then removed on first run |
-| `<root>/agents/.event4u-bridge.yml` | retired | Retired (ADR-020 amendment 2026-07-13); no longer written. Global root resolves from `~/.event4u/agent-config`; installer / `refresh --project` delete any legacy leftover. |
-| `<root>/agents/.agent-state/install-mode.txt` | marker | `minimal\n` or `full\n` |
-
-Minimal-install scaffold (override layer): `agents/overrides/{rules,skills,commands}/.gitkeep`,
-`agents/overrides/README.md`.
-
-VSCode substrate bridge: `<root>/.vscode/settings.json` key
-`/chat/pluginLocations/<plugin_path>` is written unconditionally and is
-**intentionally not tracked** in the manifest (see § Untracked surfaces).
-
-### Per-tool project-scope bridge markers
-
-`PROJECT_BRIDGE_MARKERS` in [`install.py`](../../src/scripts/install.py). The
-manifest records the marker path as the tool's `bridge_marker`.
-
-| Tool | Path (project-relative) | Kind |
-|---|---|---|
-| claude-code | `.claude/settings.json` | bridge (JSON merge) |
-| claude-desktop | `.claude-desktop/agent-config.md` | marker |
-| cursor | `.cursor/hooks.json` | bridge (JSON merge) |
-| windsurf | `.windsurf/hooks.json` | bridge (JSON merge) |
-| cline | `.clinerules/hooks/<HookName>` (6 hook scripts) | bridge (executable) |
-| gemini-cli | `.gemini/settings.json` | bridge (JSON merge) |
-| copilot | `.github/plugin/marketplace.json` | bridge (whole-file write) |
-| augment | `.augment/settings.json` | bridge (JSON merge) |
-| aider | `.aider/agent-config.md` | marker |
-| codex | `.codex/agent-config.md` | marker |
-| roocode | `.roo/rules/agent-config.md` | marker |
-| continue | `.continue/rules/agent-config.md` | marker |
-| kilocode | `.kilocode/rules/agent-config.md` | marker |
-| zed | `.zed/agent-config.md` | marker |
-| jetbrains | `.jetbrains/agent-config.md` | marker |
-| kiro | `.kiro/steering/agent-config.md` | marker |
-
-Anchor-pointer bridges (subset, project scope): `.windsurf/agent-config.bridge.yml`,
-`.clinerules/agent-config.bridge.yml`, `.gemini/agent-config.bridge.yml`.
-
-> **Known gap (frozen as-is):** `qoder`, `opencode`, `trae`, `antigravity`,
-> `codebuddy`, `droid`, `warp` are valid tools with global deploy sources but no
-> project-scope bridge marker — a project-scope install of these writes no marker
-> and records no `bridge_marker`. The contract freezes the current behaviour; a
-> future addition of markers for these tools is an additive (non-breaking) change.
-
-### User-global content deployment (`--global` / `--scope=global`)
-
-User-scope anchor roots are `USER_SCOPE_PATHS`; deployed subtrees are
-`GLOBAL_DEPLOY_SOURCES` (both in [`install.py`](../../src/scripts/install.py)).
-
-| Tool | User-scope anchor | Deployed subtrees |
-|---|---|---|
-| claude-code | `~/.claude/` | `rules/`, `skills/`, `commands/`, `personas/` |
-| augment | `~/.augment/` | `rules/`, `skills/`, `commands/`, `contexts/`, `personas/`, `templates/` |
-| cursor | `~/.cursor/` | `rules/`, `commands/`, `personas/` |
-| windsurf | `~/.codeium/windsurf/` | `rules/` |
-| cline | `~/Documents/Cline/Rules/` | flat `rules/` (no sub-prefix) |
-| gemini-cli | `~/.gemini/` | `rules/`, `skills/`, `commands/`, `personas/` |
-| codex | `~/.codex/` | `rules/`, `skills/`, `commands/`, `personas/` |
-| continue / roocode / kilocode / qoder / opencode / trae / codebuddy | `~/.continue/`, `~/.roo/`, `~/.kilocode/`, `~/.qoder/`, `~/.opencode/`, `~/.trae/`, `~/.codebuddy/` | claude-code bundle |
-| antigravity | `~/.agents/` | claude-code bundle |
-| droid | `~/.factory/` | claude-code bundle |
-| warp | `~/.warp/` | claude-code bundle |
-| kiro | `~/.kiro/` | `rules/`, `steering/`, `personas/` |
-| claude-desktop | `~/Library/Application Support/Claude/agent-config.md` (marker) | `~/.event4u/agent-config/claude-desktop/bundles/*.zip` |
-
-Tools `copilot`, `aider`, `zed`, `jetbrains` write no global content (hint
-printed only).
-
-### Global runtime root (`~/.event4u/agent-config/`)
-
-| Path | Writer | Notes |
-|---|---|---|
-| `installed.lock` | `installed_lock.py` | global lockfile (carries `install_layout_version`) |
-| `.agent-settings.yml` | `install.py` | global layer of the three-layer settings merge |
-| `.agent-user.yml` | `install.py` | user personal settings |
-| `install-log.jsonl` | `src/install/` (TS) | transaction log (TS engine only) |
-
-### User-scope hook trampolines (explicit-flag only)
-
-Written only with `--{augment,cursor,cline,windsurf,gemini}-user-hooks`:
-a per-tool `*-dispatcher.sh` under the tool's hook dir, plus a JSON merge into
-that tool's user-scope settings/hooks file (cline also writes 6 hook wrappers).
-
-## Claimed JSON-pointer keys
-
-All JSON merges use `deep_merge()` — recurse into nested dicts, replace at
-leaves; sibling keys owned by other tools survive. The exceptions are noted.
-
-| File | Pointer(s) | Merge / overwrite |
-|---|---|---|
-| `.augment/settings.json` | `/enabledPlugins/agent-config@event4u` | deep_merge |
-| `~/.augment/settings.json` | `/hooks/{SessionStart,SessionEnd,Stop,PreToolUse,PostToolUse}/0` | deep_merge (array-replace) |
-| `.claude/settings.json` | `/enabledPlugins/agent-config@event4u-agent-config` | deep_merge |
-| `.cursor/hooks.json`, `~/.cursor/hooks.json` | `/hooks/{sessionStart,sessionEnd,stop,beforeSubmitPrompt,postToolUse}` | deep_merge |
-| `.windsurf/hooks.json`, `~/.codeium/windsurf/hooks.json` | `/hooks/{post_setup_worktree,pre_user_prompt,post_cascade_response}` | deep_merge |
-| `.gemini/settings.json`, `~/.gemini/settings.json` | `/hooks/{SessionStart,SessionEnd,AfterAgent,BeforeAgent,AfterTool}` | deep_merge |
-| `.github/plugin/marketplace.json` | `/marketplace/name`, `/marketplace/plugins/0` | **whole-file write** |
-| `.vscode/settings.json` | `/chat/pluginLocations/<path>` | deep_merge (**untracked**) |
-
-Per the manifest contract, RFC-6901 pointers target object keys, never array
-indices — except the documented hook-array replacements above, which the
-installer owns wholesale.
-
-## Surgical-uninstall pointer schema
-
-An uninstall/prune flow removes exactly what the installer wrote, leaving
-foreign keys and files intact. The pointers it follows:
-
-1. **`bridge_marker`** (per tool) — single canonical path proving the tool is
-   installed. Existence-tracked; removal signals complete uninstall for that tool.
-2. **`files[]`** (per tool) — objects with `path`, `kind` ∈ `{deployed, bridge, marker}`,
-   and `sha256` (or `null` for markers). `deployed` = owned content (delete);
-   `bridge` = shared config (remove only our keys); `marker` = sentinel (delete).
-3. **`merged_keys[]`** (per tool) — objects with `file` + `json_pointer` (+ optional
-   `value_hash`). Uninstall removes only these keys.
-4. **`status`** — `installed` (default) or `uninstalling`; the two-phase uninstall
-   resume target (`agent-config prune --resume-uninstall` sweeps only `uninstalling`
-   entries' `files[]`).
-
-Full wire format: [`installed-tools-lockfile.md`](installed-tools-lockfile.md).
-
-## Lockfile shapes
-
-### Project manifest — `agents/installed-tools.lock`
-
-`schema_version: 2`, reader tolerates v1 + v2. Wire format is the canonical
-contract in [`installed-tools-lockfile.md`](installed-tools-lockfile.md); this
-layout contract freezes that the file exists at that path and carries that shape.
-
-### Global lockfile — `~/.event4u/agent-config/installed.lock`
-
-Written by `installed_lock.py`. Frozen shape:
-
-```yaml
-schema_version: 1
-install_layout_version: 1
-agent_config_version: "<semver>"
-installed_at: "<ISO-8601 UTC>"
-tools:
-  - claude-code
-  - cursor
-```
-
-`install_layout_version` is the field this contract adds (§ `install_layout_version`).
-Absent on a pre-freeze tree → treated as v0, migrated in place. The legacy
-`~/.config/agent-config/installed.lock` is read as a fallback, never written.
-
-## Untracked surfaces (frozen as known gaps)
-
-These are written but **not** recorded in any lockfile; uninstall cannot
-currently undo them. They are frozen as documented behaviour, not contract
-promises — fixing them is an additive change (recording a previously-untracked
-write), never a breaking one.
-
-- `.vscode/settings.json` `chat.pluginLocations` (substrate bridge, written
-  unconditionally).
-- User-scope `merged_keys` (the global install path passes `files_by_tool` but
-  not `merged_keys_by_tool`, so JSON merges into `~/.augment/settings.json`,
-  `~/.cursor/hooks.json`, etc. are unrecorded).
-- Best-effort legacy-trampoline removal (`OSError` swallowed; failed removals
-  leave stale files with no manifest entry).
-
-## `--apply-payload` entry point
-
-The real-apply path consumes a JSON payload (`wizard-v2` or legacy `installer-v1`
-schema) and writes the layout above, emitting NDJSON progress frames
-(`{"type":"file",…}`, `{"type":"done"}`, `{"type":"error",…}`). `dry_run: true`
-previews without writing. The payload schema is a separate wire contract from the
-on-disk layout this document freezes.
-
-## See also
-
-- [`STABILITY.md`](STABILITY.md) — beta/stable contract policy.
-- [`BREAKING_CHANGES.md`](../../BREAKING_CHANGES.md) — install-ABI deprecation-window rule.
-- [`install-scopes.md`](install-scopes.md) · [`installed-tools-lockfile.md`](installed-tools-lockfile.md).
-- [`tests/test_install_layout_contract.py`](../../tests/test_install_layout_contract.py) — the conformance test that locks this shape.

package/docs/contracts/install-scopes.md

@@ -1,82 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-09-04
----
-
-# Install Scopes — user-global vs project-local
-
-**Status:** Active (locked 2026-05-25 via Phase B of `road-to-clean-skill-distribution-channels.md`)
-**Owner:** maintainer-team
-**Inputs:** [`docs/contracts/skill-distribution-channels.md`](skill-distribution-channels.md), [`agents/evidence/audits/2026-05-distribution-channels/03-installer-scope-flow.md`](../../agents/evidence/audits/2026-05-distribution-channels/03-installer-scope-flow.md)
-
-## Rule
-
-`event4u/agent-config` may be installed at **one** of two scopes per developer machine:
-
-| Scope | Lives at | Default for | Rationale |
-|---|---|---|---|
-| **project-local** | `<project-root>/.augment/`, `<project-root>/.claude/skills/`, … | Application repos | The skills, rules, and personas are pinned alongside the code they serve. The install is reproducible from the repo. |
-| **user-global** | `~/.augment/`, `~/.claude/skills/`, … | Tooling repos / dotfiles | The same skills follow the developer across every project they touch. Useful when no specific repo "owns" the install. |
-
-Installing at **both** scopes simultaneously is the failure mode the canonical-channel contract prevents — the host harness loads both registrations, and any version drift surfaces as duplicate skills with stale frontmatter (the 2026-05-25 bug).
-
-## The installer enforces this
-
-`scripts/install.sh` runs `scripts/_lib/scope_guard.sh` before any file write:
-
-1. **`OK`** — no install at the other scope. Proceed.
-2. **`WARN`** — install at the other scope, same version. Same content; duplicate registration but no drift. Surface a warning, proceed.
-3. **`DRIFT`** — install at the other scope, different version. Block with a numbered-options prompt:
-
-```
-  1. Abort install — fix drift first (recommended)
-  2. Upgrade the OTHER scope first
-  3. Force install at this scope — accept drift (set SCOPE_GUARD_BYPASS=1)
-  4. Clean the other scope (bash scripts/cleanup_other_scope.sh --confirm)
-```
-
-Non-interactive shells default to **abort**. CI runs and the orchestrator set `SCOPE_GUARD_BYPASS=1` to skip the gate.
-
-The `agent-config setup` wizard exposes the same check at `GET /api/v1/wizard/scope-guard` (extended-mode endpoint). The first wizard step renders the verdict before the user picks an install scope.
-
-## How to clean a stale other-scope install
-
-Use the companion script:
-
-```bash
-# Dry-run (default) — list what would be removed
-bash scripts/cleanup_other_scope.sh --user
-
-# Confirm and delete
-bash scripts/cleanup_other_scope.sh --user --confirm
-
-# Narrow to a single tool
-bash scripts/cleanup_other_scope.sh --user --confirm --tools=claude-code
-
-# Remove from a specific project root
-bash scripts/cleanup_other_scope.sh --project /path/to/proj --confirm
-```
-
-The script refuses to delete anything without `--confirm` per `non-destructive-by-default`. It only touches the tool-scoped paths the contract names (`.claude/skills/`, `.augment/`, `.cursor/rules/`, `.clinerules/`, `.windsurf/rules/`, `.github/copilot-instructions.md`); the rest of the scope root is never modified.
-
-## When to pick which scope
-
-- **App repo** (Laravel, Next.js, monorepo) → project-local. The skills/rules ship with the code; CI installs them deterministically.
-- **Tooling repo** (dotfiles, personal sandbox) → user-global. The install follows the developer.
-- **Both apply** (a tooling repo that also has project-specific overrides) → project-local for the overrides, no user-global install. The override mechanism at `agents/overrides/` covers the divergence.
-
-The scope guard does **not** make the picking decision; it enforces "one scope per machine at one version".
-
-## Failure modes the guard catches
-
-- A user installed `event4u/agent-config` globally a year ago, then `npx`d a recent project that pulled v3.x into `./.claude/skills/`. Same skill ID, different frontmatter on disk. Without the guard, the Claude session sees both registrations and the agent reasons against the wrong description.
-- A maintainer ran `scripts/install.sh --target=$HOME` for a quick test and forgot to clean up. The next project install at the same scope spawns a drift the user has no easy way to debug.
-- A CI run on a worker that previously cached `~/.claude/skills/` from a stale prior job. `CI=true` skips the gate, but the probe (Phase C) catches it post-install.
-
-## See also
-
-- [`docs/contracts/skill-distribution-channels.md`](skill-distribution-channels.md) — per-tool canonical channel.
-- [`scripts/_lib/scope_guard.sh`](../../src/scripts/_lib/scope_guard.sh) — guard implementation.
-- [`scripts/cleanup_other_scope.sh`](../../src/scripts/cleanup_other_scope.sh) — companion cleanup.
-- [`tests/test_cleanup_other_scope.py`](../../tests/test_cleanup_other_scope.py) — safety regression.
-- [`README.md` § Installation](../../README.md) — consumer-facing install path.