@event4u/agent-config 5.7.0 → 5.8.0

package/dist/discovery/discovery-manifest.json.sha256

@@ -1 +1 @@
-feb5aee058e611d4b90fc31f384f5f10b8df31306acadd27f9fd863941d01def  discovery-manifest.json
+a943cc6a13b848ee35ec40fcc64ca9cf0823fffdf944d3d15afa54535ca72d74  discovery-manifest.json

package/dist/discovery/discovery-manifest.summary.md

@@ -1,8 +1,8 @@
 # Discovery Manifest — Summary
 
-- Generated: `2026-06-01T14:03:17Z`
+- Generated: `2026-06-02T02:48:57Z`
 - Scanner: `ca7acd2ec7af`
-- Artefacts: **449**
+- Artefacts: **453**
 - Unassigned: **0**
 
 ## `engineering` — Engineering
@@ -90,5 +90,5 @@
 
 | Pack | Artefacts |
 |---|---|
-| `meta` — Meta | 263 |
+| `meta` — Meta | 267 |
 

package/dist/discovery/orphan-report.md

@@ -1,6 +1,6 @@
 # Discovery — Orphan Report
 
-- Generated: `2026-06-01T14:03:17Z`
+- Generated: `2026-06-02T02:48:57Z`
 - Orphan artefacts: **0**
 
 > An orphan is an artefact whose declared pack has no other members.

package/dist/discovery/packs.json

@@ -1,6 +1,6 @@
 {
-  "checksum": "sha256:8efbf1568f8ccc06e87bdefcb41d2478cbfe08f576e9037e8f629d2697f4a267",
-  "generated_at": "2026-06-01T14:03:17Z",
+  "checksum": "sha256:b55ddc4224e45ec7627ece7c2fd6f043df8c7030efbe50df87573f0da4de4173",
+  "generated_at": "2026-06-02T02:48:57Z",
   "packs": [
     {
       "artefact_count": 85,
@@ -784,7 +784,7 @@
       ]
     },
     {
-      "artefact_count": 263,
+      "artefact_count": 267,
       "artefacts": [
         "packages/core/.agent-src.uncondensed/commands/agent-handoff.md",
         "packages/core/.agent-src.uncondensed/commands/agent-status.md",
@@ -894,6 +894,10 @@
         "packages/core/.agent-src.uncondensed/commands/post-as/ghostwriter.md",
         "packages/core/.agent-src.uncondensed/commands/post-as/me.md",
         "packages/core/.agent-src.uncondensed/commands/prepare-for-review.md",
+        "packages/core/.agent-src.uncondensed/commands/profile.md",
+        "packages/core/.agent-src.uncondensed/commands/profile/activate.md",
+        "packages/core/.agent-src.uncondensed/commands/profile/deactivate.md",
+        "packages/core/.agent-src.uncondensed/commands/profile/show.md",
         "packages/core/.agent-src.uncondensed/commands/project-analyze.md",
         "packages/core/.agent-src.uncondensed/commands/project-health.md",
         "packages/core/.agent-src.uncondensed/commands/quality-fix.md",
@@ -1051,14 +1055,14 @@
         "packages/core/.agent-src.uncondensed/templates/agents/proposal.example.md"
       ],
       "by_lifecycle": {
-        "active": 262,
+        "active": 266,
         "archived": 0,
         "deprecated": 0,
         "experimental": 1
       },
       "by_trust_level": {
         "advisory": 0,
-        "core": 262,
+        "core": 266,
         "experimental": 1,
         "professional": 0,
         "restricted": 0

package/dist/discovery/trust-report.md

@@ -1,6 +1,6 @@
 # Discovery — Trust Report
 
-- Generated: `2026-06-01T14:03:17Z`
+- Generated: `2026-06-02T02:48:57Z`
 - Workspaces tracked: **8**
 - Human-review-required artefacts: **2**
 
@@ -8,7 +8,7 @@
 
 | Workspace | core | professional | experimental | advisory | restricted |
 |---|---|---|---|---|---|
-| `agent-config-maintainer` | 262 | 0 | 2 | 0 | 0 |
+| `agent-config-maintainer` | 266 | 0 | 2 | 0 | 0 |
 | `engineering` | 86 | 41 | 1 | 0 | 0 |
 | `finance` | 2 | 3 | 0 | 1 | 0 |
 | `founder` | 7 | 0 | 0 | 1 | 0 |

package/dist/discovery/workspaces.json

@@ -1,6 +1,6 @@
 {
-  "checksum": "sha256:8efbf1568f8ccc06e87bdefcb41d2478cbfe08f576e9037e8f629d2697f4a267",
-  "generated_at": "2026-06-01T14:03:17Z",
+  "checksum": "sha256:b55ddc4224e45ec7627ece7c2fd6f043df8c7030efbe50df87573f0da4de4173",
+  "generated_at": "2026-06-02T02:48:57Z",
   "scanner_version": "ca7acd2ec7af",
   "workspaces": [
     {
@@ -454,7 +454,7 @@
       ]
     },
     {
-      "artefact_count": 263,
+      "artefact_count": 267,
       "default_packs": [
         "meta"
       ],
@@ -464,7 +464,7 @@
       "optional_packs": [],
       "packs": [
         {
-          "artefact_count": 263,
+          "artefact_count": 267,
           "artefacts": [
             "packages/core/.agent-src.uncondensed/commands/agent-handoff.md",
             "packages/core/.agent-src.uncondensed/commands/agent-status.md",
@@ -574,6 +574,10 @@
             "packages/core/.agent-src.uncondensed/commands/post-as/ghostwriter.md",
             "packages/core/.agent-src.uncondensed/commands/post-as/me.md",
             "packages/core/.agent-src.uncondensed/commands/prepare-for-review.md",
+            "packages/core/.agent-src.uncondensed/commands/profile.md",
+            "packages/core/.agent-src.uncondensed/commands/profile/activate.md",
+            "packages/core/.agent-src.uncondensed/commands/profile/deactivate.md",
+            "packages/core/.agent-src.uncondensed/commands/profile/show.md",
             "packages/core/.agent-src.uncondensed/commands/project-analyze.md",
             "packages/core/.agent-src.uncondensed/commands/project-health.md",
             "packages/core/.agent-src.uncondensed/commands/quality-fix.md",

package/dist/mcp/registry-manifest.json

@@ -1,15 +1,15 @@
 {
   "discovery": {
-    "artefact_count": 449,
+    "artefact_count": 453,
     "scanner_version": "ca7acd2ec7af"
   },
-  "generated_at": "2026-06-01",
+  "generated_at": "2026-06-02",
   "package": {
     "description": "Universal AI Agent OS \u2014 audited skills, governance rules, commands, and templates for AI coding tools (Claude Code, Cursor, Windsurf, Copilot).",
     "homepage": "https://github.com/event4u-app/agent-config#readme",
     "name": "@event4u/agent-config",
     "repository": "https://github.com/event4u-app/agent-config",
-    "version": "5.7.0"
+    "version": "5.8.0"
   },
   "registries": [
     {

package/docs/architecture.md

@@ -148,7 +148,7 @@ note, package-internal path-swap, description budget, and the
 |---|---|---|
 | **Skills** | 223 | On-demand expertise — stack analysis (Laravel · Symfony · Zend / Laminas · Next.js · React · Node), testing, Docker, API design, security, observability, … |
 | **Rules** | 79 | Always-active constraints — coding standards, scope control, verification, language-and-tone, agent-authority |
-| **Commands** | 146 | Slash-command workflows — `/commit`, `/create-pr`, `/fix ci`, `/optimize skills`, `/feature plan`, `/work`, `/implement-ticket`, `/condense`, … |
+| **Commands** | 150 | Slash-command workflows — `/commit`, `/create-pr`, `/fix ci`, `/optimize skills`, `/feature plan`, `/work`, `/implement-ticket`, `/condense`, … |
 | **Guidelines** | 73 | 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/catalog.md

@@ -1,6 +1,6 @@
 # agent-config — Public Catalog
 
-Consumer-facing catalog of all **520 public artefacts** shipped by
+Consumer-facing catalog of all **524 public artefacts** shipped by
 this package. Internal package-maintenance rules and deprecation shims
 are excluded.
 
@@ -157,7 +157,7 @@ are excluded.
 | skill | [`playwright-testing`](../.agent-src/skills/playwright-testing/SKILL.md) |  | Use when writing Playwright E2E tests — browser automation, visual regression testing, Page Objects, fixtures, and reliable test patterns. |
 | skill | [`po-discovery`](../.agent-src/skills/po-discovery/SKILL.md) |  | Use when shaping a fuzzy product ask into a refined backlog item — problem framing, user-story rewrite, AC tightening — even if the user just says 'help me write this ticket'. |
 | skill | [`positioning-strategy`](../.agent-src/skills/positioning-strategy/SKILL.md) |  | Use when locking the market frame — category, segment, alternative, point-of-view — before messaging, launch, or pricing rides on it. Triggers on 'who are we for', 'opposable audit'. |
-| skill | [`prediction-pool-optimizer`](../.agent-src/skills/prediction-pool-optimizer/SKILL.md) |  | Optimize prediction-pool tips (kicktipp etc.): pool rules + market odds → the expected-points-maximizing tip per match. Triggers 'optimize my pool tips', 'best kicktipp picks', 'predict'. |
+| skill | [`prediction-pool-optimizer`](../.agent-src/skills/prediction-pool-optimizer/SKILL.md) |  | Optimize prediction-pool tips (kicktipp etc.): rules + multi-book consensus odds → expected-points-max answer for every question, scores AND bonus. Triggers 'optimize my pool tips', 'predict'. |
 | skill | [`privacy-review`](../.agent-src/skills/privacy-review/SKILL.md) |  | Use when reviewing data flows, support macros, refund templates for GDPR/CCPA/HIPAA fit — regime, consent, PII redaction (email, order-id), breach triage. Triggers 'is this GDPR-safe', 'PII redact'. |
 | skill | [`project-analysis-core`](../.agent-src/skills/project-analysis-core/SKILL.md) |  | Raw discovery primitives — project discovery, version resolution, docs loading, architecture mapping, execution flow. Called by `universal-project-analysis`. Single-pass scan → `project-analyzer`. |
 | skill | [`project-analysis-hypothesis-driven`](../.agent-src/skills/project-analysis-hypothesis-driven/SKILL.md) |  | Use when a bug has multiple plausible causes across layers — competing hypotheses, validation loops, evidence-based conclusions — even when the user just says 'why is this happening?'. |
@@ -318,7 +318,7 @@ are excluded.
 | rule | [`user-interrupt-priority`](../.agent-src/rules/user-interrupt-priority.md) | always | User interrupts override the current task — STOP, complete new task in full, then ASK before resuming; never silently return to prior work |
 | rule | [`verify-before-complete`](../.agent-src/rules/verify-before-complete.md) | always | Verify before completion — run tests and quality tools before claiming done |
 
-## Commands (146)
+## Commands (150)
 
 | kind | name | cluster | description |
 |---|---|---|---|
@@ -431,6 +431,10 @@ are excluded.
 | command | [`post-as:me`](../.agent-src/commands/post-as/me.md) | cluster: post-as | Draft a copyable markdown post in the maintainer's own voice (style source = .agent-user.md.voice_sample). No disclosure footer — the user is the author. |
 | command | [`prediction-pool`](../.agent-src/commands/prediction-pool.md) |  | Fill a prediction pool (kicktipp, football/basketball WM): optimize expected points under the rules, enter tips via Playwright. Triggers 'Tippspiel', 'kicktipp', 'predict the pool'. |
 | command | [`prepare-for-review`](../.agent-src/commands/prepare-for-review.md) |  | Prepare a PR branch for local review — updates main and merges the full branch chain so the branch is up to date |
+| command | [`profile`](../.agent-src/commands/profile.md) | cluster: profile | Session-profile orchestrator — activate / deactivate / show the active packs for this session (recommendation-bias surface filter, no persistence) |
+| command | [`profile:activate`](../.agent-src/commands/profile/activate.md) | cluster: profile | Activate a session profile — surface only the named profile/pack closure plus core artefacts, no persistence |
+| command | [`profile:deactivate`](../.agent-src/commands/profile/deactivate.md) | cluster: profile | Deactivate the session profile — clear the overlay (or drop named packs) so the full surface returns |
+| command | [`profile:show`](../.agent-src/commands/profile/show.md) | cluster: profile | Show the active session profile — active packs and surfaced/hidden command+skill counts (observability surface) |
 | command | [`project-analyze`](../.agent-src/commands/project-analyze.md) |  | Full project analysis — detect stack, inventory modules, audit docs, create missing contexts |
 | command | [`project-health`](../.agent-src/commands/project-health.md) |  | Quick project health check — show status of docs, modules, contexts, and roadmaps without creating anything |
 | command | [`quality-fix`](../.agent-src/commands/quality-fix.md) |  | Run quality pipeline (PHP and/or JS/TS) and fix all errors — auto-detects language from changed files |

package/docs/contracts/command-clusters.md

@@ -55,6 +55,8 @@ column 1 of this table.
 | `skill` | — | `preview` | new cluster 2026-05-30 (`road-to-leaner-core-and-discovery` Phase 5) — non-destructive skill/command preview: surfaces the declared steps + files/commands a skill would touch before it runs, per [`skill-dry-run`](skill-dry-run.md). Singular `skill` (one target) vs plural `skills` (the catalog) by design. |
 | `image` | — | `analyse` · `create` · `verify` | new cluster 2026-05-31 (`road-to-character-image-fidelity` Phase 4) — character-image fidelity surface mirroring `/video:*`. `:analyse` extracts a per-feature spec from an image and diffs it against a Canon Spec down to the smallest mole (OCR for lettered tattoos, per-section severity scores, canon-breaking hard gate); `:create` assembles a max-fidelity anchors-first generation prompt from the Canon Spec, governance- + provider-gated, `AIV_DRYRUN=true` default; `:verify` runs the analyser in loop mode against a candidate and reports the gate verdict + remaining diff with plateau/oscillation/budget stop conditions. Skills: [`image-analyser`](../../skills/image-analyser/SKILL.md) + [`image-creator`](../../skills/image-creator/SKILL.md); schema/rubric/loop in [`canon-spec.md`](../../skills/image-analyser/canon-spec.md). |
 
+| `profile` | — | `activate` · `deactivate` · `show` | new cluster 2026-06-02 (`road-to-session-profile-activation`) — session-profile activation: an ephemeral `runtime.active_packs` overlay that biases the surfaced command/skill set to the active pack closure, with no persistence and no execution-gating (recommendation-bias MVP). `:activate <name…>` resolves an alias (`config/discovery/session-profiles.yml`) or a raw pack id, fails fast on a not-installed pack, expands the `requires_hint` closure, and writes the overlay atomically to `agents/settings/.agent-settings.local.yml`; `:deactivate [name…]` clears it (or drops named packs, keeping deps a still-active pack needs); `:show` is the observability surface (active packs + surfaced/hidden counts). Overlay = runtime modulation of the existing `pack` axis, not a fifth axis (ADR-010 addendum). Library: `scripts/config/session_profiles.py`; schema in [`session-profile-overlay`](session-profile-overlay.md). |
+
 **Net change:** Phase 1 collapsed 15 atomics → 3 clusters; Phase 2
 collapses 26 atomics → 11 sub-command clusters. Sub-commands use
 colon syntax (`/cluster:sub`) so Claude Code's command palette can

package/docs/contracts/session-profile-overlay.md

@@ -0,0 +1,120 @@
+---
+stability: beta
+keep-beta-until: 2026-09-02
+---
+
+# Session-profile overlay — contract
+
+> **Status:** beta · **Owner:** package maintainer · **Last reviewed:** 2026-06-02
+>
+> Schema and semantics for the `runtime.active_packs` overlay shipped by the
+> `/profile` command cluster. The overlay lets a developer activate a
+> profile for the **current session** so only the matching packs'
+> commands/skills are the surfaced set, then switch freely without
+> persisting the choice. Locked decisions: the session-profile-activation
+> roadmap Phase 0. Axis boundary: the
+> [ADR-010 addendum](../decisions/ADR-010-profile-pack-preset-boundary.md).
+
+## Decision
+
+The overlay is an **ephemeral, runtime modulation of the `pack` axis** — an
+instance of the resolution chain's existing
+`… → user/env/runtime overrides` link. It is **not** a fifth axis.
+
+It selects which already-installed packs are *surfaced* this session; it
+never installs, never persists, never gates execution.
+
+## On-disk shape
+
+Written to `agents/settings/.agent-settings.local.yml` (gitignored,
+deepest-winning cascade layer) — **never** the committed `.agent-settings.yml`.
+
+```yaml
+runtime:
+  active_packs: [engineering-base, laravel, php]   # expanded closure, sorted
+```
+
+- `runtime.active_packs` — a list of installed pack ids: the transitive
+  `requires_hint` closure of the activated profile/pack seed set.
+- Absent / empty / wrong-type → **no overlay** (full surface).
+
+## Activatable tokens
+
+`/profile activate <name…>` accepts, for each name:
+
+1. a **session-profile alias** from `config/discovery/session-profiles.yml`
+   (`developer`, `po`, `finance`, `gtm`, `content`) → its seed pack list, or
+2. a **raw pack id** from `config/discovery/packs.yml` (`laravel`, `php`, …).
+
+Multiple names union their closures. The seed set's transitive
+`requires_hint` closure is expanded before writing. **Only installed packs
+are activatable** — a not-installed seed pack fails fast (exit 2). Installed
+set = the top-level `packs:` block in settings, or the full vocabulary when
+no block is present (maintainer repo / base-only install).
+
+## Surface filter (recommendation-bias)
+
+For each `command` / `skill` artefact in `dist/discovery/discovery-manifest.json`:
+
+- **always surfaced** when it is **core-trust** (`trust.level == "core"`) or
+  unscoped (no `packs`);
+- otherwise **surfaced iff** `packs ∩ active_packs ≠ ∅`;
+- **no overlay → everything surfaced.**
+
+Execution is **never gated**: an inactive-pack artefact still runs, with a
+one-line "from inactive pack X" notice. Hard execution-gating is deferred
+(host-dependent — see
+[`session-host-capability-audit`](../../agents/settings/contexts/session-host-capability-audit.md)).
+
+## Lifecycle (locked: option a)
+
+- **Activate / switch / deactivate** are explicit `/profile` sub-commands.
+- The overlay **survives an IDE restart** (task-scoped). A new session emits
+  a **staleness notice** via the `profile-staleness` `session_start` hook —
+  it never silently resets (the registry-refresh Catch-22).
+- **Kill-switch:** delete `runtime.active_packs` (or the local file).
+
+## Robustness invariants
+
+- **Fail-open read** — a corrupt / unparseable / schema-invalid overlay is
+  ignored; the full surface returns. A misconfigured overlay never hides
+  artefacts.
+- **Atomic write** — the helper writes via a temp file + `os.replace`, so a
+  concurrent reader never sees a half-written overlay.
+- **Closure self-heal** — a closure dependency that is not installed is
+  dropped from the written set with a note, never blocking activation.
+
+## Reconciliation with the existing `--profile=<id>` install flag
+
+The install/CLI flag `--profile=<minimal|balanced|full>`
+(`scripts/install.py`) is a **legacy alias for `rule_loading_tier`** — it
+sets the rule-loading cost tier, not an audience profile. The word
+"profile" is overloaded across three distinct, orthogonal things; this
+command does **not** add a fourth meaning:
+
+| Surface | What it sets | Axis | Persists? |
+|---|---|---|---|
+| `install --profile=<minimal\|balanced\|full>` | `rule_loading_tier` (cost tier) | rule_loading_tier | yes |
+| `profile.id` in settings (`founder`/`developer`/…) | audience identity → default surface + personas ([`profile-system`](profile-system.md)) | profile | yes |
+| **`/profile activate <name>`** (this command) | `runtime.active_packs` — which installed packs are *surfaced* this session | pack (runtime overlay) | **no** |
+
+The session overlay answers *which installed packs are surfaced right now?*.
+It does **not** change `rule_loading_tier`, does **not** change
+`profile.id`, and writes only the gitignored local file. The naming
+collision is pre-existing; the overlay deliberately keeps to the `pack`
+axis (ADR-010 addendum) so it adds no new axis despite sharing the word.
+
+## Implementation
+
+- Library + CLI: `scripts/config/session_profiles.py`
+  (`activate` · `deactivate` · `show` · `surface` · `stale-notice`).
+- Aliases: `config/discovery/session-profiles.yml`.
+- Hook: `scripts/profile_staleness_hook.py` (session_start staleness notice).
+- Tests: `tests/test_session_profiles.py`.
+
+## See also
+
+- [`ADR-010 addendum`](../decisions/ADR-010-profile-pack-preset-boundary.md) — overlay ≠ fifth axis.
+- [`profile-system`](profile-system.md) — the profile (audience) axis the overlay is reconciled against.
+- [`command-clusters`](command-clusters.md) — the `/profile` cluster registration.
+- [`session-host-capability-audit`](../../agents/settings/contexts/session-host-capability-audit.md) — why hard-gating + true session-reset are deferred.

package/docs/customization.md

@@ -429,6 +429,32 @@ packs at install time via `npx @event4u/agent-config install` and the
 resulting `.agent-settings.yml` records which packs the project opted
 into.
 
+### Session profiles — surface one audience for the current session
+
+Install every pack once, then **activate a profile per session** so only
+the matching packs' commands/skills are the surfaced set:
+
+- `/profile activate laravel` — surface the Laravel closure
+  (`laravel` + `php` + `engineering-base`) + core artefacts; everything
+  else is hidden from `/help` and the skill surface.
+- `/profile activate po` — switch to the product-owner surface.
+- `/profile show` — active packs + surfaced/hidden counts.
+- `/profile deactivate` — full surface returns.
+
+The activatable name is a session-profile alias
+(`config/discovery/session-profiles.yml`: `developer`, `po`, `finance`,
+`gtm`, `content`) or a raw pack id. It is **recommendation-bias only** —
+an inactive-pack command still runs (with a one-line notice); execution is
+never blocked. The choice is **ephemeral**: it writes
+`runtime.active_packs` to the gitignored `agents/settings/.agent-settings.local.yml`,
+never the committed config, and is cleared with `/profile deactivate`.
+A new session emits a staleness reminder if a profile is still active.
+
+This is a runtime view over the existing **pack** axis, not a new axis,
+and is unrelated to the install `--profile=<minimal|balanced|full>` flag
+(which sets `rule_loading_tier`). Full contract:
+[`session-profile-overlay`](contracts/session-profile-overlay.md).
+
 ---
 
 ## Update check

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

@@ -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
 
+- [`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-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/INDEX.md

@@ -41,6 +41,8 @@ _Auto-generated by `scripts/adr/regenerate_index.py`. Do not edit._
 | [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)