@event4u/agent-config 5.6.1 → 5.8.0

package/docs/decisions/ADR-010-profile-pack-preset-boundary.md

@@ -34,7 +34,7 @@ Step-15 introduces three new configuration concepts:
 
 A pre-existing fourth concept is in play:
 
-- **`cost_profile`** — current setting in `.agent-settings.yml`, values
+- **`rule_loading_tier`** — current setting in `.agent-settings.yml`, values
   `minimal` / `balanced` / `full` / `custom`. Owns **rule-tier loading**
   (kernel · kernel + tier-1 · kernel + tier-1 + tier-2). Contract:
   [`docs/contracts/cost-profile-defaults.md`](../contracts/cost-profile-defaults.md).
@@ -42,7 +42,7 @@ A pre-existing fourth concept is in play:
 Without a written boundary, three failure modes are predictable:
 
 1. The preset loader re-implements rule-tier gating (overlap with
-   `cost_profile`).
+   `rule_loading_tier`).
 2. Packs ship duplicate `profile` + `preset` defaults that drift from
    the canonical source.
 3. Three teams add knobs to three places, and a user picking
@@ -58,22 +58,22 @@ Four orthogonal axes, four owners, one resolution chain.
 | **Profile** | *Who is the user?* (audience taxonomy) | Default skill/command surface; README entry-paragraph; persona pre-selection | `profile.id` |
 | **Preset** | *How cautious is this run?* (risk + cost + autonomy budget) | The 12+ governance knobs (per-call $ ceiling, confidence band, block-on-risk, autonomy default, council escalation, …) | `preset.id` |
 | **Pack** | *What bundle of skills + commands?* (workflow recipe) | A frozen `(profile, preset, allow_skills, allow_commands)` 4-tuple; nothing more | `pack.id` |
-| **Cost Profile** | *How many rules load?* (token budget) | Rule-tier loading at session start (kernel · +tier-1 · +tier-2) | `cost_profile` |
+| **Cost Profile** | *How many rules load?* (token budget) | Rule-tier loading at session start (kernel · +tier-1 · +tier-2) | `rule_loading_tier` |
 
 ### Resolution chain (read order, last writer wins)
 
 ```
-pack  →  profile  →  preset  →  cost_profile  →  user/env/runtime overrides
+pack  →  profile  →  preset  →  rule_loading_tier  →  user/env/runtime overrides
 ```
 
 - A **pack** declares defaults for `profile`, `preset`, and the
-  skill / command allowlists. It cannot set `cost_profile` (that
+  skill / command allowlists. It cannot set `rule_loading_tier` (that
   axis belongs to the rule-tier loader and is governed separately).
 - A **profile** declares defaults for `preset`, audience-specific
   README pointer, persona pre-selection. It cannot set any preset
   knob directly — only `preset.id`.
 - A **preset** owns the 12+ knobs. No other axis writes them.
-- A **cost_profile** owns rule-tier loading. No other axis writes it.
+- A **rule_loading_tier** owns rule-tier loading. No other axis writes it.
 - The user's `.agent-settings.yml`, environment variables, and
   runtime CLI flags override every axis above them.
 
@@ -86,7 +86,7 @@ DUPLICATION ACROSS AXES IS A CONTRACT VIOLATION.
 
 - A pack **may not** override a preset knob; it overrides `preset.id`.
 - A profile **may not** override a preset knob; it overrides `preset.id`.
-- A preset **may not** override `cost_profile`; the user does that.
+- A preset **may not** override `rule_loading_tier`; the user does that.
 - The CI `task lint-config-schema` (added in Phase 1) hard-fails on a
   pack/profile YAML that names any preset-owned knob.
 
@@ -101,15 +101,15 @@ DUPLICATION ACROSS AXES IS A CONTRACT VIOLATION.
   has a single home.
 - Phase 2 item 7 (Workflow Packs) is a 4-tuple, not a re-implementation
   of profile + preset. Pack YAML stays under 30 lines.
-- `cost_profile` keeps its single-axis charter; this ADR explicitly
+- `rule_loading_tier` keeps its single-axis charter; this ADR explicitly
   refuses to fold it into the preset layer.
 
 ### Negative
 
 - One more concept on the install screen (`profile` + `preset` + `pack`
-  + `cost_profile` = four axes). Mitigated by: the wizard (Phase 1 item
+  + `rule_loading_tier` = four axes). Mitigated by: the wizard (Phase 1 item
   2) only asks for **profile** + **stack** + **risk appetite** and
-  derives the rest. Packs are opt-in; `cost_profile` keeps its
+  derives the rest. Packs are opt-in; `rule_loading_tier` keeps its
   `balanced` default.
 - A skill-allowlist conflict between a pack and a runtime CLI flag is
   resolved by "runtime wins". Users on a pack who shadow-disable a
@@ -125,8 +125,44 @@ DUPLICATION ACROSS AXES IS A CONTRACT VIOLATION.
   (Phase 1 item 4). Pack shape lives in `docs/contracts/workflow-packs.md`
   (Phase 2 item 7).
 
+## Addendum — runtime `active_packs` overlay is not a fifth axis (2026-06-02)
+
+The session-profile-activation work introduces an **ephemeral
+`runtime.active_packs` overlay**: a developer activates a profile for the
+current session and only the matching packs' commands/skills are the
+surfaced set. This addendum records that the overlay does **not** add a
+fifth axis and does **not** violate the no-duplication rule above.
+
+The resolution chain is
+`pack → profile → preset → rule_loading_tier → user/env/runtime overrides`.
+The `active_packs` overlay is an instance of the chain's **existing final
+link** (`… → user/env/runtime overrides`): a runtime override that
+**modulates the `pack` axis** for the duration of a session. It selects
+which already-installed packs are *surfaced*; it does not create a new
+knob, a new vocabulary, or a new ownership boundary.
+
+- **Axis ownership unchanged.** The `pack` axis still owns "which bundle".
+  The overlay narrows the *active subset* of installed packs at runtime —
+  the same way the documented "runtime wins" rule lets a CLI flag
+  shadow-disable a pack-supplied skill (see Consequences § Negative). It
+  is the read-time companion of that write-time precedent.
+- **No knob duplication.** The overlay stores only a list of pack ids
+  (`runtime.active_packs: [...]`), the closure of the activated
+  profile/pack. It never restates a `preset` knob or a `profile` default.
+- **Governance stays on its own axis.** Profile activation **does not**
+  touch `rule_loading_tier`. Rules load by tier + trigger, never by pack
+  (session-profile work Phase 0.4). Letting a profile move the tier would
+  be the very axis-collision this ADR forbids.
+- **Ephemeral + uncommitted.** The overlay lives in
+  `.agent-settings.local.yml` (gitignored, deepest-winning layer), never
+  the committed settings file — so it cannot drift into a persisted axis.
+
+Net: the overlay is a session-scoped *view* over the `pack` axis, not a
+new axis. ADR-010's orthogonality holds.
+
 ## See also
 
-- [`docs/contracts/cost-profile-defaults.md`](../contracts/cost-profile-defaults.md) — the existing `cost_profile` contract this ADR explicitly does **not** touch.
+- [`agents/settings/contexts/session-host-capability-audit.md`](../../agents/settings/contexts/session-host-capability-audit.md) — host-capability facts that bound the overlay's lifecycle (addendum input).
+- [`docs/contracts/cost-profile-defaults.md`](../contracts/cost-profile-defaults.md) — the existing `rule_loading_tier` contract this ADR explicitly does **not** touch.
 - [`agents/roadmaps/step-15-product-refinement.md`](../../agents/roadmaps/step-15-product-refinement.md) — Phase 1 items 1, 4 and Phase 2 item 7.
 - [`agents/runtime/council/responses/2026-05-16-step-15-product-refinement-v3.json`](../../agents/runtime/council/responses/2026-05-16-step-15-product-refinement-v3.json) — Council v3 action #2 (origin). <!-- council-ref-allowed: ADR decision-trace to originating council response -->

package/docs/decisions/ADR-013-discovery-frontmatter-contract.md

@@ -34,7 +34,7 @@ truth. The scan emits a single `dist/discovery/discovery-manifest.json`
 shipped inside the npm tarball; every downstream surface reads from that
 file and from nothing else. This ADR locks the **frontmatter shape**, the
 **closed vocabularies**, and the **non-overlap rule** that keeps the new
-keys from colliding with the existing `cost_profile` / `profile.id` axes
+keys from colliding with the existing `rule_loading_tier` / `profile.id` axes
 (ADR-010).
 
 ### Why a closed vocabulary
@@ -121,6 +121,7 @@ Amendments to the workspace list require an ADR-013 amendment.
 | `small-business` | SMB-shaped owner workflows. |
 | `construction` | Trade-business workflows. |
 | `ai-video` | AI video pipeline (per ADR-011, the only heavyweight domain). |
+| `fun` | Non-essential social/fun workflows (prediction-pool tips, etc.). Optional under the `small-business` workspace; `experimental` trust. |
 | `meta` | Artefacts that maintain *this* package (`agent-config` itself). |
 
 Amendments to the pack list require an ADR-013 amendment and the
@@ -128,7 +129,7 @@ matching `config/discovery/packs.yml` row in the same PR.
 
 ### Non-overlap rule (ADR-010 alignment)
 
-- `cost_profile` values (`minimal`, `balanced`, `full`, `custom`) are
+- `rule_loading_tier` values (`minimal`, `balanced`, `full`, `custom`) are
   **not** pack ids. The scanner hard-fails on overlap.
 - `profile.id` values (`founder`, `developer`, `content_creator`,
   `agency`, `finance`, `ops`) are **not** pack ids. The scanner
@@ -246,6 +247,19 @@ allowed by [`discovery-manifest.schema.json`](../contracts/discovery-manifest.sc
 Additive, no vocabulary rename. (Same change cleaned the `finance` label from
 "Finance / CFO" to "Finance".)
 
+### 2026-06-01 — New `fun` pack
+
+Added pack id `fun` to the closed vocabulary (Non-essential social/fun
+workflows — prediction-pool tip optimization, etc.). Mirrored in
+[`config/discovery/packs.yml`](../../config/discovery/packs.yml) and the
+`ADR_PACKS` frozenset in
+[`scripts/lint_discovery_vocabulary.py`](../../scripts/lint_discovery_vocabulary.py).
+Optional under the `small-business` workspace (alongside `ai-video`);
+`trust_level_default: experimental`, `install.default: false`. First
+artefacts: the `/prediction-pool` command + `prediction-pool-optimizer` skill in
+`packages/pack-fun/`. Additive, no rename; non-overlap with cost-profile
+and `profile.id` reservations holds.
+
 ## Cross-references
 
 - [ADR-007 — Agent Discovery Scopes](ADR-007-agent-discovery-scopes.md):

package/docs/decisions/ADR-034-per-skill-model-recommendation-transport.md

@@ -23,7 +23,7 @@ review_date: 2026-08-30
 
 ## Context
 
-`model-recommendation` (tier-2a, `core`) is a dead shell — it routes to `command:set-cost-profile`, which flips `cost_profile` but never selects a model. The task→model intelligence already exists in `contexts/model-recommendations.md` but has no mechanism to act. Claude Code now honours a native skill `model:` frontmatter key — verified against the official skills docs (`code.claude.com/docs/en/skills.md`): the override applies for the rest of the current turn, reverts to the session model on the next prompt, and accepts the `/model` values plus `inherit`. That makes per-skill model selection structural on Claude; Augment has no per-turn override, so a rule surfaces a one-question suggestion there.
+`model-recommendation` (tier-2a, `core`) is a dead shell — it routes to `command:set-cost-profile`, which flips `rule_loading_tier` but never selects a model. The task→model intelligence already exists in `contexts/model-recommendations.md` but has no mechanism to act. Claude Code now honours a native skill `model:` frontmatter key — verified against the official skills docs (`code.claude.com/docs/en/skills.md`): the override applies for the rest of the current turn, reverts to the session model on the next prompt, and accepts the `/model` values plus `inherit`. That makes per-skill model selection structural on Claude; Augment has no per-turn override, so a rule surfaces a one-question suggestion there.
 
 The projection constraint: source `SKILL.md` is shared across tools via `.agent-src/`. `.claude/skills/<name>` is a whole-**directory symlink** to `.agent-src/skills/<name>`; `.claude/skills/<slug>/SKILL.md` for commands is a **symlink** inside a real dir. Augment skills symlink the same target. A Claude-only native `model:` therefore cannot live in the shared symlink target without also appearing in Augment.
 

package/docs/decisions/ADR-036-global-install-browser-wizard-handoff.md

@@ -0,0 +1,106 @@
+---
+adr: 036
+status: accepted
+date: 2026-06-01
+decision: global-install-browser-wizard-handoff
+supersedes: —
+superseded_by: —
+phase: v5.x · install-UX consistency
+type: forward-looking
+---
+
+# ADR-036 — Global install hands off to the browser wizard (zero terminal prompts)
+
+## Status
+
+**Accepted** · 2026-06-01. Implements the install-UX half of
+[`road-to-self-update-and-global-hook-resolution`](../../agents/roadmaps/road-to-self-update-and-global-hook-resolution.md)
+(Phase 6). Builds on [`ADR-020`](ADR-020-global-only-consumer-scope.md)
+(global-only consumer scope) and reuses the wizard contract from
+[`gui-wizard`](../contracts/gui-wizard.md).
+
+## Context
+
+`npx @event4u/agent-config init` is the canonical first-time install
+(README Quickstart) and `agent-config upgrade` is the self-update path
+(ADR-020 update-lag fix). Both reach the global install through
+`scripts/install --global` → `install.py` `install_global()`. Field use
+surfaced four defects that made the global path drop into terminal
+interaction instead of the browser wizard the project path already used:
+
+1. **Terminal tool-picker.** `scripts/install`'s `prompt_tools()` fired
+   on every interactive run, pre-empting the wizard and — via
+   `TOOLS_EXPLICIT` — suppressing it (`_wizard_should_launch` treats an
+   explicit `--tools=` as "headless").
+2. **No wizard on `--global`.** `install_global()` returned before the
+   `_wizard_should_launch` / `_wizard_spawn` block; only the project
+   path launched the GUI.
+3. **Browser never opened.** `_wizard_await_ready` **printed** the
+   `WIZARD_READY` URL but never opened it (the child is spawned with
+   `--no-open` so the Python parent owns the open — it only printed).
+4. **Wrong identity + ADR-020 leak.** Spawning the wizard with
+   `--project-root <detect_root>` forced project write-root, so the
+   wizard read neither nor wrote the **global**
+   `~/.event4u/agent-config/settings/.agent-user.yml` (the saved
+   identity → name/language pre-fill defaulted to the OS account, e.g.
+   `mathiasberg`, instead of the saved `Matze`/`de`), and global content
+   would land in the project tree — an ADR-020 violation.
+
+## Decision
+
+On the interactive global-install path (`agent-config init` / `global` /
+`upgrade` / `refresh --global`), the install is **zero-terminal-interaction
+and hands off to the browser wizard**:
+
+- `scripts/install` skips `prompt_tools()` when the wizard will launch
+  (TTY · not `CI` · not `AGENT_CONFIG_NO_UI`) — the wizard is the single
+  tool-selection surface.
+- `install.py` launches the wizard after `install_global()` (parity with
+  the project path), gated by the single source of truth
+  `_wizard_should_launch`.
+- The wizard is spawned **without** `--project-root` so `resolveWriteRoot`
+  picks the **global** write root — the saved `.agent-user.yml` drives the
+  identity pre-fill, and no global content is written into the project
+  tree (reinforces ADR-020).
+- `_wizard_await_ready` opens the browser (`webbrowser.open`) after
+  printing the URL; the printed URL remains the headless fallback.
+- On the wizard-handoff path the run is non-interactive: foreign-file
+  conflicts auto-resolve to overwrite and the legacy migration runs
+  without the `[Y/n]` gate — no `--force`, no prompts. The wizard is the
+  settings + package surface that recreates fresh config.
+
+The terminal picker, conflict prompt, and migrate prompt remain the
+behaviour on **headless** paths (no TTY · `CI` · `--no-ui` ·
+explicit `--tools=`), where no wizard launches.
+
+## Consequences
+
+**Positive.**
+- "Run the command, it installs, then the wizard opens for packages +
+  settings" — the contract holds for `init` and `upgrade` alike.
+- A returning user's name/language pre-fill from the saved identity, not
+  the OS account.
+- Global content never leaks into the project tree on the wizard path.
+
+**Negative / trade-offs.**
+- Auto-overwrite + auto-migrate on the wizard path remove the per-file
+  confirmation. Scoped to the wizard-handoff path on paths agent-config
+  owns (ADR-020 global root); headless paths keep the prompts.
+- The browser-open + zero-prompt flow cannot be asserted in headless CI;
+  the welcome-step identity pre-fill (`Matze`/`de` from the global
+  write root) is covered by a Playwright drive.
+
+## Alternatives considered
+
+- **`npx` fallback inside the PostToolUse hook.** Rejected by the
+  2026-05-30 council (per-tool-call network + version drift) and again
+  2026-06-01; orthogonal to install UX. Hooks resolve the global binary.
+- **Keep the terminal prompts, document `--force`.** Rejected — the
+  maintainer's explicit contract is zero terminal interaction with a
+  browser handoff.
+
+## References
+
+- [`ADR-020`](ADR-020-global-only-consumer-scope.md) — global-only consumer scope.
+- [`gui-wizard`](../contracts/gui-wizard.md) — wizard apply contract.
+- [`road-to-self-update-and-global-hook-resolution`](../../agents/roadmaps/road-to-self-update-and-global-hook-resolution.md) — companion roadmap.

package/docs/decisions/ADR-037-cost-profile-untangle.md

@@ -0,0 +1,117 @@
+---
+adr: 037
+status: accepted
+date: 2026-06-01
+decision: cost-profile-untangle
+supersedes: —
+superseded_by: —
+phase: cost-profile-untangle
+type: structural
+review_date: 2026-09-01
+---
+
+# ADR-037 — Untangle `cost_profile` into single-purpose settings
+
+## Status
+
+**Accepted** · 2026-06-01. AI Council (anthropic/claude-sonnet-4-5 +
+openai/gpt-4o, analysis lens, 3 rounds, 2026-06-01) converged on the
+rename + keep-decoupled design below; findings were critically evaluated
+against the codebase before adoption.
+
+## Context
+
+The `cost_profile` setting had accreted multiple responsibilities plus a
+hard naming collision:
+
+1. **Canonical meaning** — rule-tier loading (`minimal | balanced | full |
+   custom`), a token-footprint lever resolved from `dist/router.json`.
+2. **Colliding second meaning** — a separate contract
+   (`memory-visibility-v1`) and the work-engine hook read the *same key*
+   `cost_profile` with an incompatible value set (`lean | standard |
+   verbose`) to gate the `🧠 Memory` visibility-line cadence. Because no
+   real install ever wrote `cost_profile: lean`, the suppress branch was
+   **unreachable dead code**.
+3. **Default drift** — the default was declared in four places with three
+   different answers (`balanced`, `minimal`, `standard`).
+4. **Migrated intent** — `cost_profile` was originally meant to gate
+   self-optimization; that capability had already moved to the independent
+   `pipelines.skill_improvement` setting + tier-2a rule loading.
+5. **Naming confusion** — four "cost"-sounding concepts (`cost_profile`,
+   the memory cadence, `/cost:report` + `cost.budgets`, and
+   `model_tier`/`model.auto_switch`) competed for one mental slot; only the
+   first two were literally named `cost_profile`, and the second was the
+   broken one.
+
+The root cause was the absence of a settings schema: nothing prevented one
+key from carrying two value vocabularies.
+
+## Decision
+
+1. **One key, one job.** Rename the canonical setting `cost_profile` →
+   `rule_loading_tier` (values unchanged: `minimal | balanced | full |
+   custom`). The name now describes the mechanism, not a side effect, which
+   makes the `/cost:report` mismatch obvious ("you can't lower your rule
+   loading tier to save money without losing guardrails").
+2. **Memory cadence owns its own key.** The visibility-line cadence moves
+   to `memory.cadence` (`auto | always | never`, default `always` —
+   behaviour-neutral; the previously-dead suppress path is now reachable as
+   `auto`). Named `memory.cadence`, not `memory_status`, to avoid a clash
+   with the existing `scripts/memory_status.py`.
+3. **Self-optimization stays decoupled.** `pipelines.skill_improvement`
+   remains the independent lever; `rule_loading_tier` is *not* re-coupled to
+   learning behaviour. The council was unanimous that coupling token
+   footprint to learning behaviour is the wrong axis.
+4. **Schema prevents recurrence.** A new
+   `scripts/schemas/agent-settings.schema.json` (+ CI validator) enum-
+   constrains the value-bearing keys so a value-vocabulary collision is a
+   hard CI failure, not silent dead code.
+5. **Migration, not break.** `install.py`'s `LEGACY_RENAME_MAP` rewrites
+   `cost_profile` → `rule_loading_tier`; loaders read the legacy key as a
+   fallback during a grace period. The default is consolidated to one
+   source of truth (`balanced`).
+
+### Deliberately *not* done (scope discipline)
+
+- **Command + file names kept** (`/set-cost-profile`,
+  `cost-profile-defaults.md`) — renaming them cascades through the
+  ownership-matrix, command-surface, discovery manifest, and marketplace
+  (all CI-enforced/generated); the cost/benefit did not clear the bar.
+  Their *content* now uses `rule_loading_tier`.
+- **`custom` left unchanged** — it is absent from `dist/router.json`
+  profiles (documented but not router-dispatched). Its implementation is a
+  pre-existing question, tracked as a follow-up, not part of this rename.
+- **`dist/router.json` `profiles` key kept** — it is the tier-list
+  structure, not the setting name; consumers may parse it.
+
+## Consequences
+
+- The silent dead-code bug is gone; the memory cadence is reachable and
+  tested.
+- A future settings-key collision fails CI immediately.
+- Existing installs migrate automatically; no manual action.
+- Internal naming is slightly inconsistent (command/file still say
+  "cost-profile" while the setting is `rule_loading_tier`) — an accepted
+  trade-off against a high-churn, low-value rename of generated surfaces.
+- Breaking change to a public settings key → next major (see
+  `BREAKING_CHANGES.md`).
+
+## Alternatives considered
+
+- **Re-couple `cost_profile` to self-optimization** (the original intent) —
+  rejected: couples two orthogonal axes (token footprint + learning
+  behaviour); the council and the existing decoupled architecture both
+  argue against it.
+- **Minimal fix — resolve only the collision, keep the `cost_profile`
+  name** — rejected: leaves the misleading "cost" name and so leaves part
+  of the four-concept confusion intact.
+- **Rename the command + doc files too** — deferred: disproportionate
+  cascade through CI-enforced manifests for marginal benefit.
+
+## References
+
+- `BREAKING_CHANGES.md` (next-major entry).
+- `docs/contracts/memory-visibility-v1.md` § Cadence interaction.
+- `docs/contracts/cost-profile-defaults.md` (rule-loading defaults).
+- `scripts/schemas/agent-settings.schema.json` + `scripts/validate_agent_settings.py`.
+- ADR-010 (profile / pack / preset boundary) — `cost_profile` axis renamed.

package/docs/decisions/ADR-038-canonical-settings-path.md

@@ -0,0 +1,66 @@
+# ADR-038: Canonical settings path is `agents/settings/.agent-settings.yml`
+
+- **Status:** Accepted
+- **Date:** 2026-06-01
+
+## Context
+
+The project's settings *layer* lives under `agents/settings/` — it already
+holds `contexts/`, `policies/`, and the per-machine override
+`.agent-settings.local.yml` (relocated there by `4f887ae8`). The main
+developer settings file, however, stayed at the repo root as
+`./.agent-settings.yml`: `agent_settings.py` (`DEFAULT_PROJECT_FILE`),
+`install.py` (`SETTINGS_FILE`), `sync_agent_settings.py` (`DEFAULT_SETTINGS`),
+and ~30 reader scripts all hardcode the root path. The split is inconsistent —
+the override sits in the settings layer while the file it overrides sits at the
+root — and surfaced as a real defect: roadmaps and contributors referenced
+`agents/settings/.agent-settings.yml` (the location they expected), which then
+failed `check-references` because no such canonical file existed.
+
+Both files are gitignored (`.gitignore` matches the `.agent-settings.yml`
+basename anywhere) and per-machine; neither is ever committed.
+
+## Decision
+
+The canonical project settings file is **`agents/settings/.agent-settings.yml`**,
+co-located with the rest of the settings layer. The repo-root
+`./.agent-settings.yml` becomes a **back-compat read-fallback only**.
+
+- **Read precedence (deepest wins):** legacy root `.agent-settings.yml`
+  < canonical `agents/settings/.agent-settings.yml` < per-machine
+  `agents/settings/.agent-settings.local.yml`.
+- **Write target:** always `agents/settings/.agent-settings.yml`
+  (`canonical_settings_write_path`). The legacy root file is migrated into
+  the canonical location, never written afresh.
+- **Resolution helper:** `project_settings_path()` returns the canonical file
+  when present, else the legacy root file when present (back-compat), else the
+  canonical path (fresh repo). All direct readers route through it.
+- **Migration:** `install` and the `migrate` command relocate an existing root
+  `./.agent-settings.yml` to `agents/settings/.agent-settings.yml` once; no
+  consumer install breaks because the fallback keeps the old location readable
+  until it is moved.
+
+## Consequences
+
+- Settings layout is internally consistent: the main file and its override live
+  together under `agents/settings/`.
+- Existing installs keep working unchanged until migrated (read-fallback).
+- One-time cost: ~36 Python reader sites + the TS settings server/CLI route
+  through the helper; install/sync/migrate gain the relocation step; docs and
+  the gitignore-managed block name the canonical path.
+- The `.gitignore` basename match already covers the canonical path — no new
+  ignore entry required.
+
+## Alternatives considered
+
+- **Keep root canonical (status quo).** Rejected: leaves the override/main-file
+  split inconsistent and keeps surfacing as wrong-path references.
+- **Hard cut, no fallback.** Rejected: breaks every existing install (and this
+  repo) until each re-runs setup; the fallback is cheap insurance.
+
+## References
+
+- `scripts/_lib/agent_settings.py` — resolver cascade + `project_settings_path` / `canonical_settings_write_path`.
+- `4f887ae8` — prior relocation of `.agent-settings.local.yml` into `agents/settings/`.
+- `docs/guidelines/agent-infra/layered-settings.md` — precedence model.
+- `docs/contracts/migrate-command.md` — migration surface.

package/docs/decisions/ADR-039-claude-skills-untracked.md

@@ -0,0 +1,139 @@
+---
+adr: 039
+status: accepted
+date: 2026-06-01
+decision: claude-skills-untracked
+supersedes: —
+superseded_by: —
+phase: road-to-claude-skills-untrack
+type: structural
+review_date: 2026-06-15
+---
+
+# ADR-039 — `.claude/skills/` is untracked; skills resolve from committed canonical sources
+
+## Status
+
+**Accepted** · 2026-06-01. Decision lands **without** soak — all binding
+conditions were verified empirically against a real Claude Code instance
+(v2.1.159) in the same session. Review date 2026-06-15 keeps the revert path
+open; reverting is one `git rm`-reversing commit plus a generator repoint.
+
+## Context
+
+`event4u/agent-config` distributes ~365 skills to Claude Code. Until
+commit `c0e2d897` the package committed `.claude/skills/<name>/SKILL.md`
+(symlinks) and the plugin marketplace (`.claude-plugin/marketplace.json`)
+referenced those committed paths. ADR-030 had established `.claude/skills/`
+as Claude Code's filesystem-channel convention, and the cleanup that
+untracked `.claude/{rules,personas,user-types}/` deliberately **kept**
+`.claude/skills/` tracked, flagging the question for a dedicated
+investigation (`road-to-claude-skills-untrack`).
+
+The question this ADR closes: can the package stop committing
+`.claude/skills/` — so `.claude/` in git reduces to `settings.json` only —
+without breaking skill resolution on any channel?
+
+Three resolution channels exist:
+
+1. **Marketplace plugin** — Claude Code reads `.claude-plugin/marketplace.json`
+   `skills[]` and loads skills from the referenced source paths.
+2. **Consumer filesystem** — `scripts/install.sh` builds `~/.claude/skills/`
+   symlinks at install time.
+3. **Local dev** — `task generate-tools` rebuilds a gitignored local
+   `.claude/skills/` for in-repo auto-discovery.
+
+Commit `c0e2d897` already repointed the marketplace generator (real skills →
+`./.agent-src/skills/<name>` (223), command-as-skill entries →
+`./.claude-plugin/skills/<slug>` (142), both committed), updated
+`lint_marketplace.py` and the pre-commit hook, and gitignored
+`/.claude/skills/`. This ADR is the decision-gate record that the
+investigation reached, backed by a real-instance registration test rather
+than reasoning alone.
+
+## Decision
+
+**`.claude/skills/` stays untracked.** Skills resolve from the committed
+canonical sources (`.agent-src/skills/` + `.claude-plugin/skills/`) for the
+marketplace channel, and from locally-built trees for the consumer and dev
+channels. `.claude/` in git is `settings.json` only.
+
+## Evidence (real Claude Code v2.1.159, this machine)
+
+- **Marketplace manifest validates.** `claude plugin validate
+  .claude-plugin/marketplace.json` → "Validation passed" (sole warning:
+  `metadata.keywords` is ignored at load — cosmetic, see Consequences).
+- **Marketplace registers + installs at runtime.** `claude plugin
+  marketplace add <repo>` → `claude plugin install
+  agent-config@event4u-agent-config` → **enabled**; `claude plugin details`
+  reports **Skills (365)** resolved from `./.agent-src/skills/` (223) +
+  `./.claude-plugin/skills/` (142), with **no committed `.claude/skills/`**.
+- **Runtime execution without a committed tree.** This very session is a live
+  Claude Code runtime in which `git ls-files .claude/skills/` returns `0`
+  yet skills load **and execute** (the `roadmap:process-full` skill was
+  loaded and run from its SKILL.md). Registration → runtime is therefore
+  demonstrated, not inferred, for the filesystem channel.
+- **Consumer filesystem channel.** `scripts/probe_skill_registration.py`
+  shows 365 skills register from user-scope `~/.claude/skills/`, built by
+  `install.sh`, independent of any committed project tree.
+- **Lint green.** `python3 scripts/lint_marketplace.py` → 365 skills, no
+  issues (reverse-completeness scans the two committed sources).
+- **Idempotent regen.** `task generate-tools` produces no tracked diff;
+  `.claude/skills/` stays gitignored (0 tracked files).
+
+## Council convergence
+
+Cross-checked with the AI council (analysis mode, members
+anthropic/claude-sonnet-4-5 + openai/gpt-4o, 2026-06-01). Both members
+converged on a single strongest blind spot: `claude plugin details` proves
+*registration metadata*, not *live runtime execution*, and asked for a live
+session test before closing. That test was then run and is recorded above
+(this session executes skills with zero committed `.claude/skills/`; the
+marketplace plugin was installed + enabled and resolved all 365 skills).
+The council's residual follow-ups are carried into Consequences.
+
+## Consequences
+
+**Positive**
+
+- `.claude/` in git is `settings.json` only — no per-skill-set PR churn from
+  the previously-committed 365 symlinks.
+- Marketplace source paths (`.agent-src/skills/`, `.claude-plugin/skills/`)
+  are **committed**, so marketplace consumers cloning at a tag or with
+  `--depth=1` still resolve every referenced skill — a strict improvement
+  over the old gitignore-adjacent layout.
+
+**Costs / residual risks (from council follow-ups)**
+
+- **Consumer channel depends on `install.sh`.** A consumer who clones the
+  repo but never runs `install.sh` (and never installs the marketplace
+  plugin) gets no `~/.claude/skills/`. This is unchanged from before the
+  untracking and is the documented consumer contract; a CI smoke test
+  (`npm install` → `probe_skill_registration.py` → assert 365) is a sensible
+  follow-up but is out of this ADR's scope.
+- **Channel precedence is undocumented.** When a dev has the repo open
+  (local `.claude/skills/`) *and* the marketplace plugin installed, the
+  precedence of local vs marketplace skills is not formally specified.
+  Day-to-day dev uses the local generate-tools tree; no conflict observed.
+  Follow-up only.
+- **`metadata.keywords` validator warning.** The field holds generic terms
+  (tool names, `php`, `laravel`), not skill names, so it is safe to drop;
+  left in place here to keep this diff minimal (out of scope per
+  `minimal-safe-diff`).
+
+## Alternatives
+
+- **Keep `.claude/skills/` tracked (ADR-030 convention).** Rejected: the
+  registration test shows the convention is satisfied by locally-built and
+  marketplace-resolved trees; committing 365 symlinks adds PR churn with no
+  resolution benefit.
+
+## References
+
+- ADR-030 — Claude Code command-projection strategy (established the
+  `.claude/skills/` filesystem-channel convention this ADR revisits).
+- `scripts/condense.py` — `generate_plugin_command_skills()` emits the
+  `.claude-plugin/skills/<slug>` projection.
+- `scripts/lint_marketplace.py` — reverse-completeness over the two
+  committed sources.
+- `scripts/probe_skill_registration.py` — live install-state probe.

package/docs/decisions/ADR-rule-kernel-and-router.md

@@ -74,7 +74,7 @@ size budgets.
 | `balanced` *(default)* | kernel + tier-1 | Day-to-day engineering work; matches pre-roadmap behaviour superset |
 | `full` | kernel + tier-1 + tier-2 | Architectural / cross-wing / governance sessions |
 
-Consumer projects opt in via `personal.cost_profile` in
+Consumer projects opt in via `personal.rule_loading_tier` in
 `.agent-settings.yml`. The install script keeps user-set values; only
 the template default is `balanced`.
 

package/docs/decisions/INDEX.md

@@ -39,6 +39,10 @@ _Auto-generated by `scripts/adr/regenerate_index.py`. Do not edit._
 | [ADR-033](ADR-033-distribution-identity-npm-primary.md) | Distribution Identity Npm Primary | accepted | 2026-05-29 | — |
 | [ADR-034](ADR-034-per-skill-model-recommendation-transport.md) | Per Skill Model Recommendation Transport | superseded | 2026-05-30 | — |
 | [ADR-035](ADR-035-model-capability-tiers.md) | Model Capability Tiers | accepted | 2026-05-30 | 034 |
+| [ADR-036](ADR-036-global-install-browser-wizard-handoff.md) | Global Install Browser Wizard Handoff | accepted | 2026-06-01 | — |
+| [ADR-037](ADR-037-cost-profile-untangle.md) | Cost Profile Untangle | accepted | 2026-06-01 | — |
+| [ADR-038](ADR-038-canonical-settings-path.md) | Canonical Settings Path | — | — | — |
+| [ADR-039](ADR-039-claude-skills-untracked.md) | Claude Skills Untracked | accepted | 2026-06-01 | — |
 
 ## Unnumbered (legacy)
 

package/docs/development.md

@@ -127,6 +127,18 @@ task dev:link                  # Symlink this repo as the global @event4u/agent-
 task dev:unlink                # Remove the global symlink
 ```
 
+**Switch the global install between dev and release** — one-shot toggles
+that flip BOTH the `agent-config` bin on PATH and the user-scope content:
+
+```bash
+task install:use-dev           # global = THIS working tree (npm link + dev-build content)
+task install:use-release       # global = latest npm release (npm i -g @latest + release content)
+```
+
+Run `install:use-dev` to test the working tree as the live global install,
+then `install:use-release` to switch back to the published version. They are
+symmetric — whichever you run last is the active global `agent-config`.
+
 **Typical flow:**
 
 1. In this repo: `task dev:link` — once. The `agent-config` bin on PATH