@event4u/agent-config 2.26.0 → 3.1.0

package/docs/installation.md

@@ -1,23 +1,27 @@
 # Installation
 
-**Principle:** Global-first install (cross-project, in `~/.claude/`,
-`~/.cursor/`, …), opt-in project export when a team wants the config
-committed to a repo. No Task, no Make, no build tools required.
-
-> **v2.1+** — the installer detects intent. Running `npx
-> @event4u/agent-config init` in `~/` or any directory without a
-> project manifest defaults to **global**. Running it inside a project
-> (`package.json` / `composer.json` / `pyproject.toml` / etc.) defaults
-> to **project**. Pass `--scope=global` or `--scope=project` to override
-> detection. See `--scope` in the CLI help for the full matrix.
-
-A global install records itself in `~/.event4u/agent-config/installed.lock`
+**Principle:** Global is the only consumer scope. `init` writes to
+user-scope paths (`~/.event4u/agent-config/`, `~/.claude/`,
+`~/.cursor/`, …); the project tree only gets `agents/overrides/`
+and `agents/.event4u-bridge.yml`. Opt-in `export` if a team wants
+a tool's config committed to a repo. No Task, no Make, no build
+tools required.
+
+> **v2.5+** — `npx @event4u/agent-config init` always installs
+> globally. The `--project` / `--scope=project` flag is no longer
+> exposed to consumers; project-scope survives only behind the
+> maintainer-only `AGENT_CONFIG_DEV_MODE=1` flag (see
+> [`docs/maintainers/dev-mode.md`](maintainers/dev-mode.md)). The
+> legacy `--global` flag is accepted as a no-op for back-compat.
+> Rationale: [ADR-020](decisions/ADR-020-global-only-consumer-scope.md).
+
+The install records itself in `~/.event4u/agent-config/installed.lock`
 (schema_version, agent_config_version, installed_at, tools[]; the legacy
 `~/.config/agent-config/installed.lock` is read as a fallback). `npx
 @event4u/agent-config update` keeps that manifest in lockstep
 with the project pin in `.agent-settings.yml`. A version-mismatched
-re-run of `init --scope=global` is refused with exit code 1 until you
-`update` or pass `--force`.
+re-run of `init` is refused with exit code 1 until you `update` or
+pass `--force`.
 
 To commit a specific tool's config into a project repo, use:
 
@@ -127,6 +131,14 @@ the per-IDE index above.
 >
 > Python 3.10+ is required for bridges. If it is missing, the orchestrator
 > prints a warning and continues with the payload sync only.
+>
+> **Node.js 20.11+** is required for the `agent-config` binary itself.
+> Starting with the TypeScript CLI shell (ADR-012, road
+> `typescript-cli-and-local-gui-foundation`), the published `bin/`
+> entry is the compiled `dist/cli/agent-config.js`; `npx` resolves it
+> through the registry, so consumers do not need to install Node
+> dependencies into their own project. The package's `engines.node`
+> pin is the source of truth.
 
 | Mode | Best for | Scope |
 |---|---|---|
@@ -303,6 +315,15 @@ Under the hood:
 
 - `scripts/install.sh` — payload sync (callable directly for sync-only runs).
 - `scripts/install.py` — bridge files (callable directly for bridge-only runs).
+  Two install.py-specific flags worth knowing:
+  - `--dry-run` prints a plan summary (profile · scope · tools · target ·
+    wizard auto-launch decision) and exits 0 without writing files or
+    spawning subprocesses. Distinct from the bash wrapper's `--dry-run`,
+    which only skips bridges.
+  - `--no-ui` suppresses the post-install browser-wizard auto-launch.
+    Also honored via `AGENT_CONFIG_NO_UI=1`. CI runners (`CI=1`) and
+    non-TTY stdouts auto-suppress regardless. See
+    [`docs/wizard.md § Auto-launch`](wizard.md#auto-launch-from-npx--init).
 
 A full run creates:
 
@@ -706,7 +727,7 @@ writes two local-only files outside the repo contract:
   `mode: cli` members. Daily UTC reset. Inspect with
   `agent-config council quota`; clear today's counter for one provider
   with `agent-config council quota --reset <provider> --confirm`.
-- `agents/council-events.log` — JSONL audit trail. One line per
+- `agents/runtime/council/events.log` — JSONL audit trail. One line per
   necessity-gate decision and per quota block. Gitignored by the
   installer (managed `.gitignore` block); never committed.
   `original_ask` is hashed `sha256[:12]` before write — the raw prompt
@@ -722,7 +743,7 @@ Per-feature environment overrides for ephemeral worktrees, CI runners,
 or sandbox testing:
 
 - `AGENT_CONFIG_NO_EVENTS_LOG=1` — disables every write to
-  `agents/council-events.log` in-process. Quota counter and council
+  `agents/runtime/council/events.log` in-process. Quota counter and council
   output stay untouched.
 - `AGENT_CONFIG_LEGACY_ANCHOR=1` — reverts project-root discovery to
   the pre-step-7 `.git`-only walk. See [Migration — Step 7 anchor
@@ -750,13 +771,13 @@ anchor** wins:
 
 1. `.git` (file or directory).
 2. `agents/` directory containing **any** of `roadmaps/`,
-   `.ai-council.yml`, or `roadmaps-progress.md` — bare `agents/`
+   `settings/.ai-council.yml`, or `roadmaps-progress.md` — bare `agents/`
    does **not** anchor (D1).
 
 If no boundary anchor exists in any ancestor, the **outermost**
 (closest-to-fs-root) `.agent-settings.yml` becomes the root. This
 preserves the layered-settings cascade — see
-[`agents/council-sessions/step-7-d3-cascade-conflict-decision.md`](../agents/council-sessions/step-7-d3-cascade-conflict-decision.md)
+[`agents/runtime/council/sessions/step-7-d3-cascade-conflict-decision.md`](../agents/runtime/council/sessions/step-7-d3-cascade-conflict-decision.md)
 for the rationale.
 
 When a single ancestor carries multiple anchors, the **diagnostic

package/docs/maintainers/dev-mode.md

@@ -0,0 +1,105 @@
+# Maintainer Dev Mode (`AGENT_CONFIG_DEV_MODE=1`)
+
+**Audience.** Maintainers of `@event4u/agent-config` working **inside**
+the package repo. Consumers never see this flag; consumer installs
+land in `~/.event4u/agent-config/` per [ADR-020](../decisions/ADR-020-global-only-consumer-scope.md).
+
+**Status.** Forward-looking — the gate ships in Phase 3 of the
+`road-to-global-only-install` roadmap. This document is the
+canonical reference once Phase 3 lands.
+
+## Why the flag exists
+
+Phase 3 of `road-to-global-only-install` flips `SCOPE_SUPPORT` so that
+**every** consumer scope on `scripts/install.py` is global. The
+package repo itself is structurally identical to a consumer repo
+(same `.augment/`, `.claude/`, `.cursor/` projection layout) which
+means maintainer dev-installs would otherwise be blocked by the same
+gate.
+
+`AGENT_CONFIG_DEV_MODE=1` is the explicit, audit-visible opt-out.
+With the flag set, the installer:
+
+1. Allows project-scope writes back into the repo tree (so a
+   maintainer can run `task dev:install-global` and iterate on the
+   working copy).
+2. **Skips** writing `agents/.event4u-bridge.yml` into the package
+   repo (per `consumer-bridge § Writer contract`). The repo is the
+   source, not a consumer of itself.
+3. Treats `~/.event4u/agent-config/` as a peer install — touches are
+   limited to the working-copy projection.
+
+Without the flag, `scripts/install.py` refuses to write anywhere
+under the repo tree and points at this document.
+
+## When to set it
+
+Set the flag for these workflows, and **only** these:
+
+- `task dev:install-global` — refresh the user-scope projection from the working tree.
+- `task dev:install:gui` — iterate the unified Setup-Wizard / Installer-GUI before merge.
+- `task dev:setup` / `task dev:setup:dry-run` — exercise the onboarding wizard.
+- `task release` rehearsal — verify the published shape matches the dev shape.
+
+Do **not** set it for:
+
+- Consumer project work (the flag is undefined behaviour outside this repo).
+- CI runs on the package itself (CI uses the flag transparently via the dev tasks above; bare runs MUST NOT export it).
+- Production maintainer machines that also consume the package as a user (set per-shell, not in `~/.zshrc`).
+
+## How to set it
+
+Per-command (preferred):
+
+```bash
+AGENT_CONFIG_DEV_MODE=1 task dev:install-global
+```
+
+Per-shell session:
+
+```bash
+export AGENT_CONFIG_DEV_MODE=1
+task dev:install:gui
+unset AGENT_CONFIG_DEV_MODE
+```
+
+The `unset` discipline matters: a stale `=1` in your shell environment
+is the most common way a project-scope write sneaks into a consumer
+repo. Future work (`agent-config doctor`, Phase 5.4) will warn when
+the flag is set outside the package repo.
+
+## Safety properties
+
+- **Audit-visible.** Every install run logs whether the flag was set
+  at the top of the transaction log.
+- **No silent fallback.** If `scripts/install.py` detects the
+  package repo signature (presence of `.agent-src.uncompressed/` plus
+  `dist/router.json`) and the flag is **not** set, the install
+  refuses with a one-line error pointing here.
+- **Not for consumers.** Setting the flag in a consumer project is
+  defined as undefined behaviour. The installer will not actively
+  refuse (because it cannot distinguish a misconfigured shell from a
+  legitimate vendored maintainer install), but it will print a single
+  warning line on every run.
+
+## Interaction with the bridge marker
+
+Per [`consumer-bridge`](../contracts/consumer-bridge.md), the bridge
+marker is the in-repo pointer to the global root. Under
+`AGENT_CONFIG_DEV_MODE=1`:
+
+- The marker is **not** written into the package repo — the repo's
+  `agents/` directory is the project surface, not a consumer surface.
+- A pre-existing marker in the package repo is treated as stale and
+  removed on the next dev install (with an audit log line).
+- Consumer adapters reading the marker from inside the package repo
+  during local development should expand `global_root` against the
+  current user's `$HOME` per the reader contract — same as in a
+  consumer repo.
+
+## References
+
+- [ADR-020](../decisions/ADR-020-global-only-consumer-scope.md) — the global-only decision.
+- [`consumer-bridge`](../contracts/consumer-bridge.md) — bridge marker schema.
+- [`road-to-global-only-install`](../../agents/roadmaps/road-to-global-only-install.md) — Phase 3 SCOPE_SUPPORT flip + Phase 5 migration order.
+- [`taskfiles/dev.yml`](../../taskfiles/dev.yml) — `dev:install-global`, `dev:install:gui`, `dev:setup` task entries.

package/docs/migrations/commands-1.15.0.md

@@ -58,7 +58,7 @@ rg -n '/(fix|optimize|feature)-[a-z-]+' \
 Common spots:
 
 - `agents/roadmaps/*.md` — roadmap steps that name commands
-- `agents/contexts/*.md` — context docs cross-linking commands
+- `agents/settings/contexts/*.md` — context docs cross-linking commands
 - Custom skills/rules under `.augment/` overrides
 - Internal team docs / runbooks / onboarding pages
 
@@ -88,12 +88,12 @@ the deprecation cycle for Phase 1 closes. Tracked in
 ## Related rule split — `chat-history` (post-1.15.0, superseded)
 
 > **Superseded · 2026-05-04** by
-> [`agents/contexts/chat-history-platform-hooks.md`](../../agents/contexts/chat-history-platform-hooks.md).
+> [`agents/settings/contexts/chat-history-platform-hooks.md`](../../agents/settings/contexts/chat-history-platform-hooks.md).
 > The three sibling rules (`chat-history-ownership`,
 > `chat-history-cadence`, `chat-history-visibility`) and the heartbeat
 > marker no longer exist. Persistence is now a pure platform-hook
 > contract — `session_start` auto-adopts foreign sessions silently;
-> the agent never reads or writes `agents/.agent-chat-history` cooperatively.
+> the agent never reads or writes `agents/runtime/.agent-chat-history` cooperatively.
 > Manual recovery lever: `./agent-config chat-history:adopt`.
 
 For historical context: the monolithic `rules/chat-history.md` was

package/docs/parity/bench-ruflo.json

@@ -5,7 +5,7 @@
   "parity_doc": "docs/parity/ruflo.md",
   "parent_bench": "docs/parity/bench.json",
   "claim_under_test": {
-    "source": "agents/audit-2026-05-14-north-star/external-findings.md § 2",
+    "source": "agents/evidence/audits/2026-05-14-north-star/external-findings.md § 2",
     "headline": "Average dollar cost per 25-prompt corpus run, separated by model tier (Haiku / Sonnet / Opus) and by token class (input / output / cache-read / cache-write).",
     "comparison_target": "ruflo cost-tracker README (claimed upstream, not yet pulled into this repo)",
     "type": "claimed_upstream_not_verified_in_repo"

package/docs/parity/ruflo.md

@@ -2,7 +2,7 @@
 
 > Per-row verdict against the eight Ruflo measurement-governance patterns
 > catalogued in
-> [`external-findings.md § 2`](../../agents/council-sessions/audit-2026-05-14-north-star/external-findings.md).
+> [`external-findings.md § 2`](../../agents/evidence/audits/2026-05-14-north-star/external-findings.md).
 > Owner roadmap: [`step-11-ruflo-parity.md`](../../agents/roadmaps/step-11-ruflo-parity.md)
 > (Phase 6 Step 1). Cross-index lives at
 > [`step-99-north-star-restructure.md`](../../agents/roadmaps/step-99-north-star-restructure.md)
@@ -10,7 +10,7 @@
 >
 > **Verdict legend:** `[x] covered by <file:line>` · `[~] superseded by <approach>` · `[!] gap`.
 > **Acceptance:** zero `[!]` rows. Closure flips the corresponding cell in the
-> [composite scorecard](../../agents/council-sessions/audit-2026-05-14-north-star/external-findings.md#5-composite-scorecard--agent-config-vs-the-field)
+> [composite scorecard](../../agents/evidence/audits/2026-05-14-north-star/external-findings.md#5-composite-scorecard--agent-config-vs-the-field)
 > `vs Ruflo` column from `–` to `=` or `+`.
 
 **Measured-vs-claimed disclaimer:** Each row cites the **mechanism** that
@@ -41,6 +41,6 @@ mechanisms remain claimed until [`bench.json`](bench.json) soak completes
 
 ## Cross-references
 
-- Composite scorecard refresh: owned by [`step-99-north-star-restructure.md`](../../agents/roadmaps/step-99-north-star-restructure.md) Phase 5 Step 4 (replaces [`external-findings.md § 5`](../../agents/council-sessions/audit-2026-05-14-north-star/external-findings.md)).
+- Composite scorecard refresh: owned by [`step-99-north-star-restructure.md`](../../agents/roadmaps/step-99-north-star-restructure.md) Phase 5 Step 4 (replaces [`external-findings.md § 5`](../../agents/evidence/audits/2026-05-14-north-star/external-findings.md)).
 - Bench-ruflo redundancy verdict: [`bench-ruflo.json`](bench-ruflo.json) (step-11 Phase 6 Step 2).
 - G5 redundancy gate cite: step-99 Acceptance Criteria row "G5 — external redundancy (Domination Mandate)".

package/docs/profiles.md

@@ -1,7 +1,7 @@
 # Six entry paths — by `profile.id`
 
 Each block below is the first-screen for one shipped profile. The
-`profile.id` written by `/onboard` selects the anchor; the block names
+`profile.id` written by `agent-config setup` selects the anchor; the block names
 the audience, the first three things the agent does for that role,
 and the exact commands and skills wired into the profile YAML at
 [`.agent-src.uncompressed/profiles/<id>.yml`](../.agent-src.uncompressed/profiles/).

package/docs/quality.md

@@ -27,7 +27,7 @@ This runs, in order:
 The linter (`scripts/skill_linter.py`) validates:
 
 - **Required structure** — YAML frontmatter, description, triggers
-- **Frontmatter schema** — Each artefact type has a JSON-Schema in `scripts/schemas/`; violations surface as `schema_<rule>` errors (see [frontmatter contract](../agents/docs/frontmatter-contract.md))
+- **Frontmatter schema** — Each artefact type has a JSON-Schema in `scripts/schemas/`; violations surface as `schema_<rule>` errors (see [frontmatter contract](../agents/reference/docs/frontmatter-contract.md))
 - **Anti-patterns** — Procedural rules in behavior rules, overlong skills, scope creep
 - **Compression quality** — Key sections preserved after compression
 
@@ -86,7 +86,7 @@ task consistency-fix     # Regenerate ALL derived outputs
 Skills dispatched via `scripts/runtime_dispatcher.py run --skill NAME --output FILE`
 write a typed `ExecutionResult` JSON (exit code, stdout, stderr, duration,
 artifacts) to the given path. In CI, the two pilot skills `lint-skills`
-and `check-refs` write to `agents/reports/runs/` and
+and `check-refs` write to `agents/runtime/reports/runs/` and
 `scripts/ci_summary.py` renders them into the GitHub Step Summary so
 failures are visible on the PR page.
 

package/docs/recruits/_template.md

@@ -23,7 +23,7 @@
 - **Consent record:** `<link-to-dm-or-email-thread-or-signed-form>`
 
 > Consent gate per step-13 Phase 1 row 3 — a recruit without an explicit
-> consent record cannot anchor `agents/eval-findings/`. Anonymised
+> consent record cannot anchor `agents/evidence/eval-findings/`. Anonymised
 > finding is acceptable; missing consent record is not.
 
 ## Pre-session readiness
@@ -61,11 +61,11 @@ Empty list = the session wasn't real.
 - **MCP setup time:** `__ minutes __ seconds` (gate: `< 10 min`)
 - **First useful invocation reached without terminal?:** (yes | no | partial)
 - **Recruit would recommend to a peer?:** (yes | maybe | no | declined-to-answer)
-- **Eligible to anchor `agents/eval-findings/`?:** (yes | no — reason)
+- **Eligible to anchor `agents/evidence/eval-findings/`?:** (yes | no — reason)
 
 ## Cross-links
 
-- **Eval-finding file (if logged):** `agents/eval-findings/YYYY-MM-DD-<slug>.md`
+- **Eval-finding file (if logged):** `agents/evidence/eval-findings/YYYY-MM-DD-<slug>.md`
 - **Case-study file (if subject opted in):** `docs/case-studies/YYYY-MM-DD-<type>-<slug>.md`
 - **Roadmap rows closed by this session:**
   - step-13 P1 row 1 (recruit) — yes / no

package/docs/setup/enterprise-and-offline.md

@@ -10,7 +10,7 @@
 
 Re-introducing a Composer-published distribution was evaluated in the
 Phase 0 council session
-(`agents/council-questions/composer-fallback-feasibility.md`) and
+(`agents/runtime/council/questions/composer-fallback-feasibility.md`) and
 **rejected** on three grounds:
 
 1. **Lock-shape mismatch.** `installed.lock` is npm-shaped (flat dep
@@ -193,9 +193,9 @@ A developer arrives on Monday with no network and finds a broken
 
 - `agents/roadmaps/road-to-distribution-maturity.md` § Phase 2 — the
   roadmap entry that produced this document.
-- `agents/council-questions/composer-fallback-feasibility.md` — the
+- `agents/runtime/council/questions/composer-fallback-feasibility.md` — the
   question that rejected the Composer path.
-- `agents/council-questions/hermetic-install-scaffolding.md` — the
+- `agents/runtime/council/questions/hermetic-install-scaffolding.md` — the
   question that shaped Path D.
 - `docs/decisions/ADR-007-agent-discovery-scopes.md` — the lock
   manifest contract that Phase 2 extends additively.

package/docs/setup/mcp-server-docker.md

@@ -61,12 +61,14 @@ for semantics.
 ## Volume mounts (`chat_history_append`)
 
 The `chat_history_append` tool writes to
-`agents/.agent-chat-history` **inside the container**. For writes to
-survive container lifecycle, mount the host directory:
+`agents/runtime/.agent-chat-history` **inside the container**
+(`agents/.agent-chat-history` and `.agent-chat-history` are accepted
+for back-compat). For writes to survive container lifecycle, mount
+the host directory:
 
 ```bash
 docker run --rm -i \
-  -v "$(pwd)/agents/.agent-chat-history:/app/agents/.agent-chat-history" \
+  -v "$(pwd)/agents/runtime/.agent-chat-history:/app/agents/runtime/.agent-chat-history" \
   agent-config-mcp:local
 ```
 

package/docs/setup/per-ide/claude-desktop.md

@@ -9,8 +9,9 @@ server inside Claude Desktop. macOS / Windows / Linux. ~10 minutes.
 > ZIP per skill under
 > `~/.event4u/agent-config/claude-desktop/bundles/` so you can drag /
 > drop them into the Customize panel. The v1 npm / composer install
-> scheme is retired; the new global-first scheme is ADR-007 and writes
-> through `~/.event4u/agent-config/installed.lock` (legacy
+> scheme is retired; the current global-only scheme follows ADR-007 +
+> [ADR-020](../../decisions/ADR-020-global-only-consumer-scope.md) and
+> writes through `~/.event4u/agent-config/installed.lock` (legacy
 > `~/.config/agent-config/installed.lock` read as fallback).
 
 ## Prerequisites