@event4u/agent-config 1.38.0 → 1.39.0

package/.agent-src/commands/onboard.md

@@ -12,35 +12,68 @@ suggestion:
 
 # /onboard
 
-Centralized first-run flow. Bundles what used to be scattered "ask once"
-prompts (user_name, IDE, rtk install, cost profile, learning loop) into a
-single interactive setup. Ends by setting `onboarding.onboarded: true` in
-`.agent-settings.yml`.
+Centralized first-run flow. Bundles scattered "ask once" prompts (user_name,
+IDE, rtk install, cost profile, learning loop) into one interactive setup.
+Ends by setting `onboarding.onboarded: true` in `.agent-settings.yml`.
 
-Triggered by the [`onboarding-gate`](../rules/onboarding-gate.md) rule when
-`onboarding.onboarded` is `false` or by the user explicitly re-running it.
+Triggered by [`onboarding-gate`](../rules/onboarding-gate.md) when
+`onboarding.onboarded` is `false`, or by explicit re-run.
 
 ## When NOT to use
 
 - Change cost profile only → [`/set-cost-profile`](set-cost-profile.md).
-- Single-value edit → ask the agent to change it, or edit
-  `.agent-settings.yml` directly. The agent follows the merge rules in
-  [`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md).
+- Single-value edit → ask agent to change it, or edit `.agent-settings.yml`
+  directly per [`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md).
 
 ## Preconditions
 
-`.agent-settings.yml` exists. If missing, tell the user to run
-`scripts/install` (or `python3 scripts/install.py`) first and stop — this
-command assumes the file and its template-derived defaults are in place.
+`.agent-settings.yml` exists. If missing, tell user to run `scripts/install`
+(or `python3 scripts/install.py`) first and stop — command assumes file +
+template defaults are in place.
 
 ## Steps
 
 ### 1. Greet and set expectations
 
-Keep it short. One line explaining this is the one-time setup, six
-questions, one at a time, following the iron law (`user-interaction`).
+One line: one-time setup, six questions, one at a time (iron law from
+`user-interaction`).
 
-### 2. Capture `personal.user_name`
+### 2. Offer user-global cross-project defaults
+
+Detect whether `~/.config/agent-config/agent-settings.yml` exists. Path is
+XDG-style, matches existing `~/.config/agent-config/` dir used for
+`anthropic.key`, `openai.key`, `council-spend.jsonl`.
+
+- **File exists** → skip step entirely. Re-onboarding never overwrites
+  user-global file silently.
+- **File missing AND first-time setup heuristic** — heuristic for "first
+  machine setup": no other `.agent-settings.yml` in any sibling project on
+  disk. Conservative shell probe:
+  `find $(dirname "$PWD") -maxdepth 3 -name .agent-settings.yml 2>/dev/null | grep -v "^$PWD/" | head -1`
+  → non-empty → developer done this before, **skip**.
+  → empty → first-time setup, ask:
+
+```
+> A user-global config at ~/.config/agent-config/agent-settings.yml lets
+> you carry your DX-comfort defaults (name, IDE, autonomy, cost profile,
+> communication style) across every project that uses event4u/agent-config.
+>
+> Project-local .agent-settings.yml always wins. Only six keys are
+> mergeable from the user-global file:
+>   name · ide · cost_profile · personal.bot_icon · personal.autonomy · caveman.speak_scope
+>
+> 1. Yes — create it after this onboarding finishes
+> 2. No — keep settings project-local only
+```
+
+If user picks `1`, **defer write** to tail step (see step 9). Capture choice
+in working memory only; do **not** create file here. File gets written
+**after** project-local values are confirmed, so initial values mirror
+what developer just chose for this project.
+
+If user picks `2`, set working-memory flag to skip step 9.
+
+### 3. Capture `personal.user_name`
 
 Skip if already set (non-empty). Otherwise:
 
@@ -51,11 +84,11 @@ Skip if already set (non-empty). Otherwise:
 > 2. Skip — stay anonymous
 ```
 
-Free-text answer → write to `personal.user_name`. `2` → leave empty.
+Free-text → write to `personal.user_name`. `2` → leave empty.
 
-### 3. Capture `personal.ide` (with auto-detect)
+### 4. Capture `personal.ide` (with auto-detect)
 
-Skip if already set. Otherwise auto-detect first:
+Skip if set. Otherwise auto-detect first:
 
 ```bash
 ps aux | grep -iE '(Visual Studio Code|Code Helper|phpstorm|cursor)' | grep -v grep
@@ -73,13 +106,13 @@ ps aux | grep -iE '(Visual Studio Code|Code Helper|phpstorm|cursor)' | grep -v g
 > 4. Skip — I'll configure it later
 ```
 
-If IDE is set, also ask about `personal.open_edited_files` (`true`/`false`).
+If IDE set, also ask `personal.open_edited_files` (`true`/`false`).
 
-### 4. Capture `personal.pr_comment_bot_icon`
+### 5. Capture `personal.pr_comment_bot_icon`
 
-Personal preference — each developer decides how their own PR replies
-should look. Skip only if the user has already set a non-default value
-deliberately (agent can't tell, so always ask on first run):
+Personal preference — each developer decides how own PR replies look. Skip
+only if user already set non-default deliberately (agent can't tell, so
+always ask on first run):
 
 ```
 > When I reply to PR review comments on your behalf, should I prefix each
@@ -91,7 +124,7 @@ deliberately (agent can't tell, so always ask on first run):
 
 `1` → write `personal.pr_comment_bot_icon: true`. `2` → leave `false`.
 
-### 5. Detect `personal.rtk_installed`
+### 6. Detect `personal.rtk_installed`
 
 Silent `which rtk`.
 
@@ -108,16 +141,17 @@ Silent `which rtk`.
 ```
 
 `1` or `2` → run install, on success set `rtk_installed: true` and apply
-rtk post-install steps (telemetry off, init --global) per the
-[`rtk-output-filtering`](../skills/rtk-output-filtering/SKILL.md) skill.
-`3` → leave `rtk_installed: false` and move on. No "ask again tomorrow"
-logic — `/onboard` is one-shot.
+rtk post-install steps (telemetry off, init --global) per
+[`rtk-output-filtering`](../skills/rtk-output-filtering/SKILL.md).
+`3` → leave `rtk_installed: false`, move on. No "ask again tomorrow" —
+`/onboard` is one-shot.
+
 
-### 6. Confirm `cost_profile` and learning loop
+### 7. Confirm `cost_profile` and learning loop
 
 Read current `cost_profile` and `pipelines.skill_improvement` values.
-Present them plainly (they already have sensible defaults from the
-template — `minimal` + `skill_improvement: true`):
+Present plainly (sensible defaults from template — `minimal` +
+`skill_improvement: true`):
 
 ```
 > Cost profile: {current} (minimal by default — includes the learning loop)
@@ -128,16 +162,54 @@ template — `minimal` + `skill_improvement: true`):
 > 3. Disable learning loop — sets pipelines.skill_improvement=false
 ```
 
-`2` → defer to `/set-cost-profile` and return here. `3` → flip the toggle.
+`2` → defer to `/set-cost-profile` and return here. `3` → flip toggle.
 
-### 7. Mark onboarded
+### 8. Mark onboarded
 
-Write `onboarding.onboarded: true` to `.agent-settings.yml` using the
+Write `onboarding.onboarded: true` to `.agent-settings.yml` using
 section-aware merge rules from
 [`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules)
-(preserve comments, key order, touch only the changed fields).
+(preserve comments, key order, touch only changed fields).
+
+### 9. Write user-global file (only if opted in at step 2)
+
+Skip unless step 2 captured explicit "yes". Re-confirm intent in one line —
+never silent-write a file outside project tree:
+
+```
+> Writing ~/.config/agent-config/agent-settings.yml with the six
+> mergeable keys mirrored from this project's choices:
+>
+>   name: {personal.user_name or ""}
+>   ide: {personal.ide or ""}
+>   cost_profile: {cost_profile}
+>   personal.bot_icon: {personal.pr_comment_bot_icon}
+>   personal.autonomy: {personal.autonomy or "ask"}
+>   caveman.speak_scope: {caveman.speak_scope or "prose_only"}
+>
+> 1. Yes, write it
+> 2. Cancel — keep settings project-local only
+```
+
+`1` → ensure `~/.config/agent-config/` exists (`mkdir -p`, mode `0700`),
+then write file with mode `0600`. Schema is **flat-or-nested YAML keyed on
+dotted paths** in whitelist documented in
+[`scripts/_lib/agent_settings.py`](../scripts/_lib/agent_settings.py).
+Use same section-aware merge rules from
+[`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules)
+**only if file unexpectedly already exists** between step 2 and this step
+(race condition); otherwise create from scratch with exact six keys above
+and a one-line file header comment:
+
+```yaml
+# event4u/agent-config — user-global DX-comfort defaults
+# Whitelist: name · ide · cost_profile · personal.bot_icon · personal.autonomy · caveman.speak_scope
+# Project-local .agent-settings.yml always wins. See docs/customization.md.
+```
+
+`2` → no write, no error, no second ask. Move on.
 
-### 8. Summary
+### 10. Summary
 
 Echo what was captured, in one block:
 
@@ -152,18 +224,19 @@ Echo what was captured, in one block:
   cost_profile: {value}
   pipelines.skill_improvement: {value}
   onboarding.onboarded: true
+  user-global: {"written" if step 9 wrote · "—" otherwise}
 
 You can re-run this with /onboard anytime, or edit .agent-settings.yml
 directly — the agent follows the merge rules in `layered-settings` when
 you ask it to change a value.
 ```
 
-### 9. Maintainer-only feature pointer
+### 11. Maintainer-only feature pointer
 
-Print a one-screen hint after the summary — no question, no prompt, just a
-pointer for maintainers who want to opt into the artefact-engagement
-telemetry layer. Consumers can ignore it; the feature is **default-off**
-and stays off unless explicitly enabled.
+Print one-screen hint after summary — no question, no prompt, just pointer
+for maintainers who want to opt into artefact-engagement telemetry layer.
+Consumers can ignore; feature is **default-off** and stays off unless
+explicitly enabled.
 
 ```
 ℹ️  Maintainer telemetry (opt-in)
@@ -181,20 +254,27 @@ Skip this block in cloud surfaces (no settings file, no log path).
 
 ## Gotchas
 
-- `.agent-settings.yml` is git-ignored. This command never commits.
-- One question per turn. The iron law from `ask-when-uncertain` applies;
-  do not stack questions 2–6 into a single prompt.
+- `.agent-settings.yml` is git-ignored. Command never commits.
+- One question per turn. Iron law from `ask-when-uncertain` applies; do
+  not stack questions 2–9 into single prompt.
 - Re-running `/onboard` when `onboarded: true` is allowed — walk through
-  all steps again and rewrite the values the user confirms.
-- Never overwrite a non-empty value without asking (applies to `user_name`
-  and `ide`).
+  all steps again and rewrite values user confirms.
+- Never overwrite non-empty value without asking (applies to `user_name`,
+  `ide`).
+- **User-global file is opt-in, one-shot, never silent.** Step 2 captures
+  intent, step 9 re-confirms before actual write. If
+  `~/.config/agent-config/agent-settings.yml` already exists when
+  `/onboard` starts, step 2 is skipped entirely — re-onboarding never
+  silently rewrites developer's cross-project defaults. Use
+  `/sync-agent-settings` (project-scoped only) or edit file manually for
+  mid-life changes.
 
 ## Cloud Behavior
 
 On cloud surfaces (Claude.ai Web, Skills API) this command is **fully inert** —
-there is no `.agent-settings.yml` to write, no `onboarding.onboarded` key to
-flip, and no local IDE/rtk environment to capture. First-run setup is a
-local-agent concern; the cloud agent should proceed without invoking it.
+no `.agent-settings.yml` to write, no `onboarding.onboarded` key to flip,
+no local IDE/rtk env to capture. First-run setup is local-agent concern;
+cloud agent should proceed without invoking it.
 
 ## See also
 
@@ -202,3 +282,4 @@ local-agent concern; the cloud agent should proceed without invoking it.
 - [`set-cost-profile`](set-cost-profile.md) — isolated profile change
 - [`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md) — merge rules for mid-life edits
 - [`agent-settings` template](../templates/agent-settings.md) — settings reference
+- [`scripts/_lib/agent_settings.py`](../scripts/_lib/agent_settings.py) — centralized loader + whitelist that consumes the user-global file

package/.agent-src/templates/agents/agent-project-settings.example.yml

@@ -6,14 +6,21 @@
 #
 # Precedence (lowest → highest):
 #   1. Package defaults (shipped by event4u/agent-config)
-#   2. This file (.agent-project-settings.yml) — team defaults
-#   3. .agent-settings.yml — developer overrides (gitignored)
+#   2. ~/.config/agent-config/agent-settings.yml — user-global DX-comfort
+#      defaults (whitelist: name, ide, cost_profile, personal.bot_icon,
+#      personal.autonomy, caveman.speak_scope). Created on opt-in via
+#      /onboard; project-local files always win.
+#   3. This file (.agent-project-settings.yml) — team defaults
+#   4. .agent-settings.yml — developer overrides (gitignored)
 #
 # Any key marked `locked: true` in this file CANNOT be overridden by
 # .agent-settings.yml. Use sparingly — locked keys reduce developer
 # autonomy. Reserve for compliance or correctness concerns (e.g.
 # forcing a test framework, pinning a coding style).
 #
+# Full precedence model + user-global whitelist contract:
+#   docs/guidelines/agent-infra/layered-settings.md
+#
 # Copy this file to `.agent-project-settings.yml` (drop the `.example`)
 # and commit it.
 

package/.agent-src/templates/scripts/work_engine/_lib/__init__.py

@@ -0,0 +1,7 @@
+"""Internal helpers shared across work_engine submodules.
+
+Currently houses :mod:`agent_settings` — the byte-identical mirror of
+``scripts/_lib/agent_settings.py`` from the agent-config package. The
+parity test in ``tests/test_template_agent_settings_parity.py`` guards
+the two files against drift.
+"""

package/.agent-src/templates/scripts/work_engine/_lib/agent_settings.py

@@ -0,0 +1,168 @@
+"""Centralized loader for ``.agent-settings.yml`` with user-global fallback.
+
+Phase 1 of road-to-portable-dev-preferences. Single source of truth for
+how scripts read agent settings — replaces ~15 ad-hoc loaders in P3.
+
+Resolution order (project wins, user-global fills gaps for whitelisted
+keys only):
+
+  1. Project ``./.agent-settings.yml``                  (full file, all keys)
+  2. ``~/.config/agent-config/agent-settings.yml``      (whitelist only)
+  3. Built-in defaults                                  (currently empty)
+
+Whitelisted keys (``MERGEABLE_KEYS``) are exact dotted paths. A
+non-whitelisted key in the user-global file is silently ignored — the
+``verbose=True`` flag surfaces ignored paths via ``logging.info`` for
+debugging.
+
+Contract — pure, read-only, tolerant:
+
+* Lazy PyYAML import; no yaml installed → defaults returned.
+* Missing project file → user-global + defaults.
+* Missing user-global file → project + defaults.
+* Both missing → defaults.
+* Malformed YAML / unreadable file → defaults, logged at WARNING.
+* No file is ever created or written by this module.
+"""
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_PROJECT_FILE = ".agent-settings.yml"
+DEFAULT_USER_GLOBAL_FILE = (
+    Path.home() / ".config" / "agent-config" / "agent-settings.yml"
+)
+
+#: Exact dotted paths allowed to cascade from user-global into the merged
+#: settings. Anything not listed here is silently ignored when present in
+#: the user-global file. Adding a key requires an ADR — see
+#: ``agents/roadmaps/road-to-portable-dev-preferences.md``.
+MERGEABLE_KEYS: tuple[str, ...] = (
+    "name",
+    "ide",
+    "cost_profile",
+    "personal.bot_icon",
+    "personal.autonomy",
+    "caveman.speak_scope",
+)
+
+_DEFAULTS: dict[str, Any] = {}
+
+
+def load_agent_settings(
+    project_path: Path | str | None = None,
+    user_global_path: Path | str | None = None,
+    verbose: bool = False,
+) -> dict[str, Any]:
+    """Return the merged settings dict.
+
+    ``project_path`` defaults to ``./.agent-settings.yml`` (CWD-relative).
+    ``user_global_path`` defaults to
+    ``~/.config/agent-config/agent-settings.yml``. Both arguments accept
+    ``Path`` or ``str``. Pass ``verbose=True`` to log keys present in
+    user-global that are not on the whitelist.
+    """
+    project = _read_yaml(
+        Path(project_path) if project_path else Path(DEFAULT_PROJECT_FILE),
+    ) or {}
+    user_global_raw = _read_yaml(
+        Path(user_global_path) if user_global_path else DEFAULT_USER_GLOBAL_FILE,
+    ) or {}
+
+    user_global_filtered, ignored = _filter_whitelist(
+        user_global_raw, MERGEABLE_KEYS,
+    )
+    if verbose and ignored:
+        logger.info(
+            "agent_settings: ignored non-whitelisted user-global keys: %s",
+            sorted(ignored),
+        )
+
+    merged: dict[str, Any] = _deep_copy_defaults(_DEFAULTS)
+    _deep_merge(merged, user_global_filtered)
+    _deep_merge(merged, project)
+    return merged
+
+
+def _read_yaml(path: Path) -> dict[str, Any] | None:
+    """Best-effort YAML read; never raises. Returns ``None`` on any failure."""
+    if not path.is_file():
+        return None
+    try:
+        import yaml  # type: ignore[import-untyped]
+    except ImportError:
+        return None
+    try:
+        with path.open(encoding="utf-8") as fh:
+            data = yaml.safe_load(fh) or {}
+    except (OSError, yaml.YAMLError):
+        logger.warning("agent_settings: unreadable or malformed YAML at %s", path)
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def _filter_whitelist(
+    raw: dict[str, Any], allowed: tuple[str, ...],
+) -> tuple[dict[str, Any], list[str]]:
+    """Return ``(filtered_dict, ignored_paths)`` from a user-global blob."""
+    filtered: dict[str, Any] = {}
+    for dotted in allowed:
+        value = _get_dotted(raw, dotted)
+        if value is not None:
+            _set_dotted(filtered, dotted, value)
+    ignored = [p for p in _leaf_paths(raw) if p not in allowed]
+    return filtered, ignored
+
+
+def _get_dotted(data: dict[str, Any], dotted: str) -> Any:
+    cursor: Any = data
+    for part in dotted.split("."):
+        if not isinstance(cursor, dict) or part not in cursor:
+            return None
+        cursor = cursor[part]
+    return cursor
+
+
+def _set_dotted(target: dict[str, Any], dotted: str, value: Any) -> None:
+    parts = dotted.split(".")
+    cursor = target
+    for part in parts[:-1]:
+        nxt = cursor.setdefault(part, {})
+        if not isinstance(nxt, dict):
+            nxt = {}
+            cursor[part] = nxt
+        cursor = nxt
+    cursor[parts[-1]] = value
+
+
+def _leaf_paths(data: dict[str, Any], prefix: str = "") -> list[str]:
+    paths: list[str] = []
+    for key, value in data.items():
+        path = f"{prefix}.{key}" if prefix else key
+        if isinstance(value, dict) and value:
+            paths.extend(_leaf_paths(value, path))
+        else:
+            paths.append(path)
+    return paths
+
+
+def _deep_merge(dst: dict[str, Any], src: dict[str, Any]) -> None:
+    """Merge ``src`` into ``dst`` in-place; nested dicts are merged recursively."""
+    for key, value in src.items():
+        if (
+            isinstance(value, dict)
+            and isinstance(dst.get(key), dict)
+        ):
+            _deep_merge(dst[key], value)
+        else:
+            dst[key] = value
+
+
+def _deep_copy_defaults(src: dict[str, Any]) -> dict[str, Any]:
+    out: dict[str, Any] = {}
+    _deep_merge(out, src)
+    return out

package/.agent-src/templates/scripts/work_engine/hooks/settings.py

@@ -13,6 +13,12 @@ settings.py``):
 * Chat-history hooks gate on **two** switches: ``hooks.chat_history.
   enabled`` AND the global ``chat_history.enabled``. Either off → no
   chat-history hook registers.
+
+Per road-to-portable-dev-preferences P3, the YAML read goes through
+:func:`work_engine._lib.agent_settings.load_agent_settings`, which
+cascades the whitelisted ``cost_profile`` (and other DX-comfort keys)
+from ``~/.config/agent-config/agent-settings.yml`` when the project
+file omits them. Project values always win.
 """
 from __future__ import annotations
 
@@ -20,6 +26,8 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
+from work_engine._lib.agent_settings import load_agent_settings
+
 DEFAULT_SETTINGS_FILE = ".agent-settings.yml"
 DEFAULT_CHAT_HISTORY_SCRIPT = "scripts/chat_history.py"
 
@@ -52,36 +60,27 @@ _DEFAULT = HookSettings()
 
 def load_hook_settings(
     settings_path: Path | str | None = None,
+    user_global_path: Path | str | None = None,
 ) -> HookSettings:
     """Return :class:`HookSettings` hydrated from ``.agent-settings.yml``.
 
     ``settings_path`` defaults to ``./.agent-settings.yml`` relative to
     the current working directory — same convention as chat-history.
+    ``user_global_path`` defaults to
+    ``~/.config/agent-config/agent-settings.yml`` and only cascades the
+    whitelisted DX-comfort keys (currently ``cost_profile``) when the
+    project file omits them. See road-to-portable-dev-preferences P3.
     """
     path = Path(settings_path) if settings_path else Path(DEFAULT_SETTINGS_FILE)
-    raw = _read_yaml(path)
-    if raw is None:
+    raw = load_agent_settings(
+        project_path=path,
+        user_global_path=user_global_path,
+    )
+    if not raw:
         return _DEFAULT
     return _settings_from_raw(raw)
 
 
-def _read_yaml(path: Path) -> dict[str, Any] | None:
-    if not path.is_file():
-        return None
-    try:
-        import yaml  # type: ignore[import-untyped]
-    except ImportError:
-        return None
-    try:
-        with path.open(encoding="utf-8") as fh:
-            data = yaml.safe_load(fh) or {}
-    except (OSError, yaml.YAMLError):
-        return None
-    if not isinstance(data, dict):
-        return None
-    return data
-
-
 def _settings_from_raw(data: dict[str, Any]) -> HookSettings:
     hooks = data.get("hooks")
     if not isinstance(hooks, dict):

package/.claude-plugin/marketplace.json

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

package/AGENTS.md

@@ -16,12 +16,12 @@ task ci                # full pipeline — green before PR
 
 ## Pointers
 
-- **Package self-orientation** — identity, four-wing cognition map, repo layout, tech stack, key-rules table, telemetry, command-suggester: [`docs/contracts/package-self-orientation.md`](docs/contracts/package-self-orientation.md).
-- **Kernel + Router** — 9 always-loaded Iron-Law rules, tier-1 / tier-2 routing, cost profiles, per-rule char caps enforced by `task lint-rule-budget`: [`kernel-membership`](docs/contracts/kernel-membership.md) + [`rule-router`](docs/contracts/rule-router.md).
+- **Package self-orientation** (beta) — identity, four-wing cognition map, repo layout, tech stack, key-rules table, telemetry, command-suggester: [`docs/contracts/package-self-orientation.md`](docs/contracts/package-self-orientation.md).
+- **Kernel + Router** (beta) — 9 always-loaded Iron-Law rules, tier-1 / tier-2 routing, cost profiles, per-rule char caps enforced by `task lint-rule-budget`: [`kernel-membership`](docs/contracts/kernel-membership.md) + [`rule-router`](docs/contracts/rule-router.md).
 - **Multi-tool projection** — Augment, Claude Code, Cursor, Cline, Windsurf, Gemini CLI, Claude.ai bundle pipeline that ships from `.agent-src/` to consumer surfaces: [`docs/architecture.md`](docs/architecture.md#cloud-bundle-pipeline).
 - **Editing this repo** — Iron-Law rules (portability, source-of-truth, skill-quality) and the Thin-Root contract (caps · pointer-ratio · triage block) governing AGENTS.md: [`augment-portability`](.agent-src/rules/augment-portability.md), [`augment-source-of-truth`](.agent-src/rules/augment-source-of-truth.md), [`skill-quality`](.agent-src/rules/skill-quality.md), [`agents-md-thin-root`](.agent-src/skills/agents-md-thin-root/SKILL.md).
-- **Consumer story + architecture deep-dive** — what the package does for installers and how it ships: [`README.md`](README.md), [`docs/architecture.md`](docs/architecture.md).
-- **Personas** — 11 review-lens cast (6 core · 5 specialist), `personas:` vs `/mode` axes, citation map, override pattern: [`docs/personas.md`](docs/personas.md), schema [`docs/contracts/persona-schema.md`](docs/contracts/persona-schema.md).
+- **Consumer story + architecture deep-dive** — install story + ship pipeline: [`README.md`](README.md), [`docs/architecture.md`](docs/architecture.md).
+- **Personas** — 11 review-lens cast (6 core · 5 specialist), `personas:` vs `/mode` axes, citation map, override pattern: [`docs/personas.md`](docs/personas.md), schema [`docs/contracts/persona-schema.md`](docs/contracts/persona-schema.md) (beta).
 
 ## Emergency triage — read this when nothing else is reachable
 

package/CHANGELOG.md

@@ -318,6 +318,40 @@ our recommendation order, not its support status.
   users" tension without removing any path that an existing user
   might rely on.
 
+## [1.39.0](https://github.com/event4u-app/agent-config/compare/1.38.0...1.39.0) (2026-05-11)
+
+### Features
+
+* **onboard,docs:** wire user-global DX defaults into onboarding + docs ([761a969](https://github.com/event4u-app/agent-config/commit/761a96979c42b880d83f72ccd2ac2d752ae47f0b))
+* **settings:** add centralized agent-settings loader ([d5699be](https://github.com/event4u-app/agent-config/commit/d5699bee9ebb47dd2f1d78716e1ff84a7139b5da))
+
+### Bug Fixes
+
+* **ci:** grant contents:write to deploy-mcp-worker for release comment ([fb5c895](https://github.com/event4u-app/agent-config/commit/fb5c89537daef55e5dde12bfe85cc703bfa181ed))
+
+### Documentation
+
+* **roadmap:** add road-to-simplicity-and-everywhere (highest prio) ([417a8fa](https://github.com/event4u-app/agent-config/commit/417a8fa9b7059dac783d3bc9423c64a994a9421a))
+* **roadmap:** add road-to-mcp-full-coverage (Discovery-First) ([fabf897](https://github.com/event4u-app/agent-config/commit/fabf89761322a437b39178366e45f68efbdd7924))
+* **mcp-cloud:** clarify Lite-vs-Full scope at endpoint surface ([97c4684](https://github.com/event4u-app/agent-config/commit/97c4684d07be4fe49c248a1ee0a60cd36b82e071))
+* **stability:** align public surface with stability markers ([d9afe4a](https://github.com/event4u-app/agent-config/commit/d9afe4ad67aad80e2bb12b1c707189f3ee8f47c2))
+* **mcp:** clarify .agent-settings.yml vs. MCP client config ([27a77b2](https://github.com/event4u-app/agent-config/commit/27a77b2459cad1faff12cd8a237e59091ec687de))
+* **mcp:** add per-client setup guide for hosted Remote MCP ([179da38](https://github.com/event4u-app/agent-config/commit/179da38631ea9693a94f259fb1edd2746b89425d))
+
+### Refactoring
+
+* **work-engine:** centralize agent-settings loading in shared _lib ([3c548bb](https://github.com/event4u-app/agent-config/commit/3c548bb72d3c2022362050a4c88ebe412bf7a897))
+
+### Chores
+
+* **compress:** regenerate commands/onboard.md after onboard,docs source edit ([e676915](https://github.com/event4u-app/agent-config/commit/e67691564405f05fba033f29b0df696e25788dd0))
+
+### Other
+
+* add portable-dev-preferences (3 phases, refined via AI council) ([7468a4c](https://github.com/event4u-app/agent-config/commit/7468a4cd2d352d6bfcd7797a8dd8b6ed8ec8f27a))
+
+Tests: 2699 (+20 since 1.38.0)
+
 ## [1.38.0](https://github.com/event4u-app/agent-config/compare/1.37.0...1.38.0) (2026-05-11)
 
 ### Features

package/README.md

@@ -108,11 +108,22 @@ curl https://agent-config-mcp.event4u.workers.dev
 # → { "ok": true, "name": "agent-config-mcp", "release_key": "v…", … }
 ```
 
-Read-only, identity-stable per release. Client config snippets and URL
-shapes (latest vs. pinned `/v<X.Y.Z>`) live in
+Read-only, identity-stable per release. Per-client setup snippets
+(Claude Desktop, Claude Code, Cursor, Zed, Continue) —
+[`docs/setup/mcp-client-config.md`](docs/setup/mcp-client-config.md).
+URL shapes (latest vs. pinned `/v<X.Y.Z>`) —
 [`docs/setup/mcp-cloud-endpoints.md`](docs/setup/mcp-cloud-endpoints.md).
 Operator setup (account, R2, secrets) — [`docs/setup/mcp-cloud-setup.md`](docs/setup/mcp-cloud-setup.md).
-Experimental — A0-cloud contract in [`docs/contracts/mcp-cloud-scope.md`](docs/contracts/mcp-cloud-scope.md).
+Experimental — A0-cloud contract lives at `docs/contracts/mcp-cloud-scope.md` (internal reference only per `STABILITY.md`).
+
+> **Scope — Lite, not Full.** The hosted MCP endpoint serves the
+> read-only governance surface (skills · commands · rules · guidelines
+> · contexts) as MCP prompts and resources. It does **not** execute any
+> of the ~112 Python scripts that ship with the package (linters,
+> audits, `task ci`, work-engine hooks, …). Those require the full
+> local install per [Quickstart](#quickstart). See
+> [`docs/contracts/mcp-cloud-scope.md`](docs/contracts/mcp-cloud-scope.md)
+> for the execution-safety boundary.
 
 ### Optional: persistent agent memory
 

package/docs/customization.md

@@ -42,6 +42,51 @@ The `.agent-settings.yml` file in the consumer project configures agent behavior
 It is written as YAML with section-level grouping; dotted keys below reference
 those sections.
 
+### User-global DX-comfort defaults (cross-project)
+
+Six **DX-comfort** keys can be carried across every project that uses
+`event4u/agent-config` by storing them once in a user-global file at:
+
+```
+~/.config/agent-config/agent-settings.yml
+```
+
+The path is XDG-style and matches the existing
+`~/.config/agent-config/` directory used for `anthropic.key`,
+`openai.key`, and `council-spend.jsonl`.
+
+**Whitelist (locked, exact dotted paths)** — only these six keys are
+mergeable from the user-global file; every other key is silently ignored:
+
+```
+name
+ide
+cost_profile
+personal.bot_icon
+personal.autonomy
+caveman.speak_scope
+```
+
+**Merge order** (lowest → highest precedence):
+
+```
+1. Package defaults                                   (shipped by event4u/agent-config)
+2. ~/.config/agent-config/agent-settings.yml          (user-global · whitelist-filtered)
+3. <project>/.agent-settings.yml                      (project-local · always wins)
+```
+
+Project-local values **always win**. The user-global file is a
+fallback, never a lock. Non-whitelisted keys in the user-global file
+are dropped without error — adding `personal.theme` there has no
+effect.
+
+The file is created **only on explicit opt-in via `/onboard`**. The
+loader at [`scripts/_lib/agent_settings.py`](../scripts/_lib/agent_settings.py)
+is **read-only** — no script can create or mutate it without an
+explicit `/onboard` confirmation. Edit the file by hand for mid-life
+changes; `/sync-agent-settings` stays project-scoped and never touches
+user-global state.
+
 ### Available settings
 
 | Setting | Default | Description |

package/docs/guidelines/agent-infra/layered-settings.md

@@ -1,37 +1,74 @@
 # Layered Settings
 
-Two-file settings model: **team defaults** (committed) and
-**developer overrides** (git-ignored). Lets a project pin decisions
-without forcing every developer to work the same way.
+Three-file settings model: **team defaults** (committed),
+**user-global DX-comfort defaults** (per-developer, cross-project), and
+**developer overrides** (per-project, git-ignored). Lets a project pin
+decisions, a developer carry DX preferences across every project, and
+project-local choices always win.
 
-Referenced by `road-to-project-memory.md` Phase 0. Consumed by the
-settings loader, the `/onboard` command, and any agent that edits
-`.agent-settings.yml` on user request.
+Referenced by `road-to-project-memory.md` Phase 0 and
+`road-to-portable-dev-preferences.md`. Consumed by the centralized
+settings loader at
+[`scripts/_lib/agent_settings.py`](../../../scripts/_lib/agent_settings.py),
+the `/onboard` command, and any agent that edits `.agent-settings.yml`
+on user request.
 
-## The two files
+## The three files
 
 | File | Git | Scope | Owner | Example values |
 |---|---|---|---|---|
 | `.agent-project-settings.yml` | **committed** | team / repo | lead maintainer | `project.stack`, `quality.php.tools`, `memory.dogfood` |
-| `.agent-settings.yml` | **gitignored** | developer workstation | individual | `personal.ide`, `personal.user_name`, `subagents.max_parallel` |
+| `~/.config/agent-config/agent-settings.yml` | **n/a** (outside repo) | individual developer · cross-project | individual | `name`, `ide`, `cost_profile`, `personal.bot_icon`, `personal.autonomy`, `caveman.speak_scope` |
+| `.agent-settings.yml` | **gitignored** | individual developer · this project | individual | `personal.ide`, `personal.user_name`, `subagents.max_parallel`, `onboarding.onboarded` |
 
-Both are YAML. Schema is documented in
-[`agent-settings.md`](../../templates/agent-settings.md) (dev layer)
-and [`agent-project-settings.example.yml`](../../templates/agents/agent-project-settings.example.yml)
-(team layer).
+All three are YAML. Schemas:
+
+- Developer (project-local): [`agent-settings.md`](../../templates/agent-settings.md).
+- Team: [`agent-project-settings.example.yml`](../../templates/agents/agent-project-settings.example.yml).
+- User-global: six exact dotted paths — whitelist in
+  [`scripts/_lib/agent_settings.py`](../../../scripts/_lib/agent_settings.py).
 
 ## Merge order
 
 Lowest priority → highest priority:
 
 ```
-1. Package defaults       (shipped by event4u/agent-config)
-2. .agent-project-settings.yml   (team file, committed)
-3. .agent-settings.yml           (developer file, gitignored)
+1. Package defaults                                   (shipped by event4u/agent-config)
+2. ~/.config/agent-config/agent-settings.yml          (user-global · whitelist-filtered)
+3. .agent-project-settings.yml                        (team file, committed)
+4. .agent-settings.yml                                (developer file, gitignored)
+```
+
+Keys from higher layers win unless a lower layer marks them
+`locked` (team file only). The user-global file does **not** support
+`locked` — its purpose is cross-project comfort, never policy.
+
+## User-global whitelist
+
+Only these exact dotted paths are mergeable from the user-global file;
+every other key is silently dropped by the loader. The whitelist is
+intentionally tiny — adding a key requires an ADR.
+
+```
+name
+ide
+cost_profile
+personal.bot_icon
+personal.autonomy
+caveman.speak_scope
 ```
 
-Keys from higher layers win unless the lower layer marks them
-`locked`. Locked keys cannot be shadowed by a higher layer.
+Loader contract:
+
+- **Read-only.** The loader never creates, modifies, or deletes the
+  user-global file. Writes are the exclusive responsibility of the
+  `/onboard` command on explicit user opt-in.
+- **Tolerant.** Missing file, malformed YAML, empty file — all fall
+  back to the next tier without raising.
+- **Silent on out-of-whitelist keys.** `verbose=True` logs which keys
+  were dropped for debugging; default mode is silent.
+- **Never auto-creates `~/.config/agent-config/`.** That directory
+  pre-exists from key installation; `/onboard` `mkdir -p`s on opt-in.
 
 ## Lock semantics
 

package/docs/setup/mcp-client-config.md

@@ -0,0 +1,152 @@
+# MCP Client Config — Remote agent-config
+
+Connect any MCP-capable client to the hosted `agent-config-mcp` Worker
+at `https://agent-config-mcp.event4u.workers.dev`. Read-only,
+identity-stable per release, no auth.
+
+For URL shapes (latest vs. pinned `/v<X.Y.Z>`) see
+[`mcp-cloud-endpoints.md`](mcp-cloud-endpoints.md). For operator
+setup of your own deployment see [`mcp-cloud-setup.md`](mcp-cloud-setup.md).
+
+## Transport note
+
+The Worker speaks JSON-RPC over HTTP POST. Clients that support
+HTTP transport natively (Claude Code, Cursor) talk to it directly.
+Clients that only support stdio (Claude Desktop, Zed) need the
+[`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge from
+npm — invoked via `npx`, no install required.
+
+## Where settings live — `.agent-settings.yml` vs. MCP config
+
+These are **two different files** for two different layers. Don't
+look for MCP server config inside `.agent-settings.yml`.
+
+| File | Where | Who reads it | Purpose |
+|---|---|---|---|
+| MCP client config (this page) | client-specific path per section above | the MCP client at startup | which MCP servers to talk to (name + URL / command) |
+| `.agent-settings.yml` | consumer project root (`<repo>/.agent-settings.yml`) | the agent at runtime (Claude / Cursor / …) | per-developer preferences: `name`, `ide`, `cost_profile`, `personal.autonomy`, `pipelines.skill_improvement`, `caveman.speak_scope`, … |
+
+The hosted MCP is **stateless** and **project-agnostic** — it serves
+the same skill / rule / command catalog to every client. Personalization
+happens agent-side after the MCP delivers its content blob; the Worker
+itself does not read `.agent-settings.yml`.
+
+First-time setup of `.agent-settings.yml` runs through `/onboard`;
+template drift is handled by `/sync-agent-settings`.
+
+## Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
+(macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "agent-config": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://agent-config-mcp.event4u.workers.dev"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The connector appears in the dropdown.
+
+Newer builds also support **Settings → Connectors → Add Custom
+Connector** with the URL directly — no `mcp-remote` wrapper needed.
+
+## Claude Code
+
+Native HTTP transport — one command:
+
+```bash
+claude mcp add --transport http agent-config https://agent-config-mcp.event4u.workers.dev
+```
+
+Verify:
+
+```bash
+claude mcp list
+```
+
+## Cursor
+
+`~/.cursor/mcp.json` (global) or `<repo>/.cursor/mcp.json`
+(project-local):
+
+```json
+{
+  "mcpServers": {
+    "agent-config": {
+      "url": "https://agent-config-mcp.event4u.workers.dev"
+    }
+  }
+}
+```
+
+Reload Cursor (`Cmd+Shift+P → Reload Window`).
+
+## Zed
+
+`~/.config/zed/settings.json`:
+
+```json
+{
+  "context_servers": {
+    "agent-config": {
+      "source": "custom",
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://agent-config-mcp.event4u.workers.dev"]
+    }
+  }
+}
+```
+
+Zed has no native remote-MCP transport yet, so the `mcp-remote`
+bridge is required.
+
+## Continue
+
+`~/.continue/config.yaml` (or `<repo>/.continue/config.yaml`):
+
+```yaml
+mcpServers:
+  - name: agent-config
+    command: npx
+    args: ["-y", "mcp-remote", "https://agent-config-mcp.event4u.workers.dev"]
+```
+
+## Verify
+
+After reload, every client should:
+
+1. List `agent-config` under connectors / tools with a release-key
+   matching the live deploy. Probe the endpoint to see the current
+   release:
+
+   ```bash
+   curl https://agent-config-mcp.event4u.workers.dev
+   # → { "ok": true, "release_key": "v…", "signature": "…", … }
+   ```
+
+2. Expose skill + command prompts under URIs like `skill://…` and
+   `command://…`.
+3. Expose rule + guideline + context resources under `rule://…`,
+   `guideline://…`, `context://…`.
+
+If the client shows the connector but no prompts / resources,
+re-probe the URL — a 5xx from the Worker indicates the deploy is
+mid-roll, retry after a minute.
+
+## Local stdio alternative
+
+If you have the repo cloned and prefer running the MCP server
+locally (faster startup, no network), the stdio kernel under
+`scripts/mcp_server/` is the same wire surface. Setup:
+`task mcp:setup`, run details in [`../mcp-server.md`](../mcp-server.md).
+
+## See also
+
+- URL shapes & DNS — [`mcp-cloud-endpoints.md`](mcp-cloud-endpoints.md)
+- Operator setup (your own deploy) — [`mcp-cloud-setup.md`](mcp-cloud-setup.md)
+- A0-cloud contract — [`../contracts/mcp-cloud-scope.md`](../contracts/mcp-cloud-scope.md)

package/docs/setup/mcp-cloud-endpoints.md

@@ -10,6 +10,21 @@ by `docs/contracts/mcp-cloud-scope.md` (A0-cloud) and Phase 5.2 of
 shapes below are pinned for the lifetime of the *experimental* window;
 breaking changes require a stability-label bump.
 
+## Scope — Lite surface
+
+The hosted endpoint exposes the **read-only governance surface**
+(skills, commands, rules, guidelines, contexts) as MCP prompts +
+resources. `tools/list` returns two **deprecated stubs**
+(`lint_skills`, `chat_history_append`) that point at their local-stdio
+successors; `tools/call` against either returns `isError=true`. No
+script execution, no FS access, no shell.
+
+Full power — the ~112 Python scripts (linters, audits, `task ci`,
+work-engine hooks) — requires the local install. See
+[`../contracts/mcp-cloud-scope.md`](../contracts/mcp-cloud-scope.md)
+for the execution-safety boundary and the Phase-7-DEFERRED gate that
+governs any future tool restoration.
+
 ## URL shapes (pinned)
 
 Two surfaces, both serve identical wire contracts (JSON-RPC over POST,
@@ -88,6 +103,7 @@ serving on `/latest/`.
 
 ## See also
 
+- Per-client config snippets: [`mcp-client-config.md`](mcp-client-config.md)
 - A0-cloud contract: `docs/contracts/mcp-cloud-scope.md`
 - R2 bootstrap: `docs/setup/mcp-r2-bootstrap.md`
 - Local stdio fallback: `scripts/mcp_server/` (unchanged)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "1.38.0",
+    "version": "1.39.0",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,

package/scripts/_lib/agent_settings.py

@@ -0,0 +1,168 @@
+"""Centralized loader for ``.agent-settings.yml`` with user-global fallback.
+
+Phase 1 of road-to-portable-dev-preferences. Single source of truth for
+how scripts read agent settings — replaces ~15 ad-hoc loaders in P3.
+
+Resolution order (project wins, user-global fills gaps for whitelisted
+keys only):
+
+  1. Project ``./.agent-settings.yml``                  (full file, all keys)
+  2. ``~/.config/agent-config/agent-settings.yml``      (whitelist only)
+  3. Built-in defaults                                  (currently empty)
+
+Whitelisted keys (``MERGEABLE_KEYS``) are exact dotted paths. A
+non-whitelisted key in the user-global file is silently ignored — the
+``verbose=True`` flag surfaces ignored paths via ``logging.info`` for
+debugging.
+
+Contract — pure, read-only, tolerant:
+
+* Lazy PyYAML import; no yaml installed → defaults returned.
+* Missing project file → user-global + defaults.
+* Missing user-global file → project + defaults.
+* Both missing → defaults.
+* Malformed YAML / unreadable file → defaults, logged at WARNING.
+* No file is ever created or written by this module.
+"""
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_PROJECT_FILE = ".agent-settings.yml"
+DEFAULT_USER_GLOBAL_FILE = (
+    Path.home() / ".config" / "agent-config" / "agent-settings.yml"
+)
+
+#: Exact dotted paths allowed to cascade from user-global into the merged
+#: settings. Anything not listed here is silently ignored when present in
+#: the user-global file. Adding a key requires an ADR — see
+#: ``agents/roadmaps/road-to-portable-dev-preferences.md``.
+MERGEABLE_KEYS: tuple[str, ...] = (
+    "name",
+    "ide",
+    "cost_profile",
+    "personal.bot_icon",
+    "personal.autonomy",
+    "caveman.speak_scope",
+)
+
+_DEFAULTS: dict[str, Any] = {}
+
+
+def load_agent_settings(
+    project_path: Path | str | None = None,
+    user_global_path: Path | str | None = None,
+    verbose: bool = False,
+) -> dict[str, Any]:
+    """Return the merged settings dict.
+
+    ``project_path`` defaults to ``./.agent-settings.yml`` (CWD-relative).
+    ``user_global_path`` defaults to
+    ``~/.config/agent-config/agent-settings.yml``. Both arguments accept
+    ``Path`` or ``str``. Pass ``verbose=True`` to log keys present in
+    user-global that are not on the whitelist.
+    """
+    project = _read_yaml(
+        Path(project_path) if project_path else Path(DEFAULT_PROJECT_FILE),
+    ) or {}
+    user_global_raw = _read_yaml(
+        Path(user_global_path) if user_global_path else DEFAULT_USER_GLOBAL_FILE,
+    ) or {}
+
+    user_global_filtered, ignored = _filter_whitelist(
+        user_global_raw, MERGEABLE_KEYS,
+    )
+    if verbose and ignored:
+        logger.info(
+            "agent_settings: ignored non-whitelisted user-global keys: %s",
+            sorted(ignored),
+        )
+
+    merged: dict[str, Any] = _deep_copy_defaults(_DEFAULTS)
+    _deep_merge(merged, user_global_filtered)
+    _deep_merge(merged, project)
+    return merged
+
+
+def _read_yaml(path: Path) -> dict[str, Any] | None:
+    """Best-effort YAML read; never raises. Returns ``None`` on any failure."""
+    if not path.is_file():
+        return None
+    try:
+        import yaml  # type: ignore[import-untyped]
+    except ImportError:
+        return None
+    try:
+        with path.open(encoding="utf-8") as fh:
+            data = yaml.safe_load(fh) or {}
+    except (OSError, yaml.YAMLError):
+        logger.warning("agent_settings: unreadable or malformed YAML at %s", path)
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def _filter_whitelist(
+    raw: dict[str, Any], allowed: tuple[str, ...],
+) -> tuple[dict[str, Any], list[str]]:
+    """Return ``(filtered_dict, ignored_paths)`` from a user-global blob."""
+    filtered: dict[str, Any] = {}
+    for dotted in allowed:
+        value = _get_dotted(raw, dotted)
+        if value is not None:
+            _set_dotted(filtered, dotted, value)
+    ignored = [p for p in _leaf_paths(raw) if p not in allowed]
+    return filtered, ignored
+
+
+def _get_dotted(data: dict[str, Any], dotted: str) -> Any:
+    cursor: Any = data
+    for part in dotted.split("."):
+        if not isinstance(cursor, dict) or part not in cursor:
+            return None
+        cursor = cursor[part]
+    return cursor
+
+
+def _set_dotted(target: dict[str, Any], dotted: str, value: Any) -> None:
+    parts = dotted.split(".")
+    cursor = target
+    for part in parts[:-1]:
+        nxt = cursor.setdefault(part, {})
+        if not isinstance(nxt, dict):
+            nxt = {}
+            cursor[part] = nxt
+        cursor = nxt
+    cursor[parts[-1]] = value
+
+
+def _leaf_paths(data: dict[str, Any], prefix: str = "") -> list[str]:
+    paths: list[str] = []
+    for key, value in data.items():
+        path = f"{prefix}.{key}" if prefix else key
+        if isinstance(value, dict) and value:
+            paths.extend(_leaf_paths(value, path))
+        else:
+            paths.append(path)
+    return paths
+
+
+def _deep_merge(dst: dict[str, Any], src: dict[str, Any]) -> None:
+    """Merge ``src`` into ``dst`` in-place; nested dicts are merged recursively."""
+    for key, value in src.items():
+        if (
+            isinstance(value, dict)
+            and isinstance(dst.get(key), dict)
+        ):
+            _deep_merge(dst[key], value)
+        else:
+            dst[key] = value
+
+
+def _deep_copy_defaults(src: dict[str, Any]) -> dict[str, Any]:
+    out: dict[str, Any] = {}
+    _deep_merge(out, src)
+    return out