@event4u/agent-config 1.37.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.37.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,70 @@ 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
+
+* **mcp:** add cloud setup tasks + operator README ([c5aebba](https://github.com/event4u-app/agent-config/commit/c5aebba37a608d0a41b1586acacdb055996a961d))
+* **scripts:** MCP content packer + cloud parity smoke ([e0d132a](https://github.com/event4u-app/agent-config/commit/e0d132afb487b720386bd54b68e10f1a342d6b0c))
+
+### Documentation
+
+* **readme:** surface hosted Remote MCP as zero-install option ([de6161e](https://github.com/event4u-app/agent-config/commit/de6161e3660b81a460f057bc46c1b75e6fe8693c))
+* **mcp:** add A0-cloud invariant 8 — ingress protection via edge cache + platform rate-limit ([c4b9371](https://github.com/event4u-app/agent-config/commit/c4b9371da2db55958bca29a7d10291626d13782f))
+* **mcp:** drop archived-roadmap refs from stable contracts ([15418de](https://github.com/event4u-app/agent-config/commit/15418de5a65c3cd5968bbeecc20ed5ad5c4a4958))
+* **mcp:** surface experimental hosted-MCP channel ([cecae08](https://github.com/event4u-app/agent-config/commit/cecae08ad647c7e28931e7328047fdef5ca3d3a3))
+* **setup:** MCP cloud endpoints, R2 bootstrap, registry listing ([7cb3341](https://github.com/event4u-app/agent-config/commit/7cb334110ff940d3703ada013ef5163c899d96b2))
+* **mcp:** add A0-cloud contract + cross-links (Phase 1 of cloudflare-mcp-hosting) ([2fc5084](https://github.com/event4u-app/agent-config/commit/2fc50845c3b194e861b54f82c852ba4bb9fc406a))
+* **roadmap:** add Cloudflare-hosted MCP roadmap, archive distribution ([fd1c437](https://github.com/event4u-app/agent-config/commit/fd1c437ea8a918eebc8604ee7958d8c842c7aac8))
+
+### CI
+
+* **deploy-mcp-worker:** release-tag triggered Worker deploy ([4297514](https://github.com/event4u-app/agent-config/commit/4297514b80457852511ad90674f4d633a75a92bf))
+
+### Chores
+
+* **linter:** raise README overloaded threshold to 750 lines ([1e3fbb7](https://github.com/event4u-app/agent-config/commit/1e3fbb7c649398ba56bc32677c7b588131f7e949))
+* **mcp:** mark dev content.json stub with explanatory _comment ([8f6c7ff](https://github.com/event4u-app/agent-config/commit/8f6c7ffe493b72ccb2d0ec66121a9d32d0b2fe8c))
+* **roadmap:** archive road-to-cloudflare-mcp-hosting (100% complete) ([99e07f9](https://github.com/event4u-app/agent-config/commit/99e07f92293e62841ff87f315e41c5ceabd7b277))
+* **workers/mcp:** scaffold TypeScript Cloudflare Worker ([447e071](https://github.com/event4u-app/agent-config/commit/447e071984f86fc084058d05f22d0e0a7c936a5e))
+
+Tests: 2679 (+0 since 1.37.0)
+
 ## [1.37.0](https://github.com/event4u-app/agent-config/compare/1.36.1...1.37.0) (2026-05-10)
 
 ### Features