@event4u/agent-config 1.39.0 → 1.41.0

package/docs/setup/per-ide/copilot.md

@@ -0,0 +1,80 @@
+# GitHub Copilot Setup
+
+GitHub Copilot Chat (VS Code, JetBrains, Neovim, `gh copilot` CLI)
+reads `.github/copilot-instructions.md` for project-level guidance and
+falls back to `AGENTS.md` where supported.
+
+## Prerequisites
+
+- GitHub Copilot subscription (Individual, Business, or Enterprise).
+- Copilot Chat enabled in your IDE.
+- Node.js ≥ 18 for the install entrypoints.
+
+## Install
+
+```bash
+npx @event4u/create-agent-config init --tools=copilot
+```
+
+Populates:
+
+- `.github/copilot-instructions.md` — Copilot's project-level prompt
+- `AGENTS.md`                       — canonical agent self-orientation
+- `.agent-settings.yml`             — per-project knobs
+
+The package keeps `.github/copilot-instructions.md` deliberately thin
+(it points back to `AGENTS.md`) so all surfaces share a single source
+of truth.
+
+## VS Code Copilot Chat
+
+Auto-loads `.github/copilot-instructions.md` once you reload the VS
+Code window after install. Verify in the Copilot Chat panel —
+*"What is this repo?"* should answer using the AGENTS.md emergency
+triage block.
+
+## JetBrains Copilot
+
+JetBrains Copilot 1.5+ reads the same `.github/copilot-instructions.md`
+file. No extra steps; reload the project after install.
+
+## Neovim Copilot
+
+`copilot.lua` and `CopilotChat.nvim` honor
+`.github/copilot-instructions.md`. No extra config needed.
+
+## `gh copilot` CLI
+
+The `gh copilot` plugin (`gh extension install github/gh-copilot`)
+reads the repo context including `AGENTS.md` and
+`.github/copilot-instructions.md` when invoked from the repo root.
+
+## Suppressing Copilot PR review noise
+
+Copilot's PR auto-review can flag the package's own kernel rules as
+"unusual phrasing". The package ships a Copilot-suppression rule
+([`augment-portability`](../../../.augment/rules/augment-portability.md))
+that documents this trade-off.
+
+## Verification
+
+```bash
+test -f .github/copilot-instructions.md
+test -f AGENTS.md
+gh copilot --version             # if you want CLI plugin
+```
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| Copilot ignores the file | Reload the IDE window after install. |
+| File missing after install | Re-run `npx @event4u/create-agent-config init --tools=copilot`. |
+| Copilot PR review too noisy | See the `copilot-config` skill for suppression patterns. |
+
+## Cross-references
+
+- [`AGENTS.md`](../../../AGENTS.md) — canonical agent self-orientation.
+- [`.augment/skills/copilot-config/SKILL.md`](../../../.augment/skills/copilot-config/SKILL.md)
+  — tuning Copilot output and suppressing review noise.
+- [`docs/installation.md`](../../installation.md) — install matrix index.

package/docs/setup/per-ide/cursor.md

@@ -0,0 +1,125 @@
+# Cursor Setup
+
+Cursor reads two rule formats:
+
+- **Modern (`.mdc`)** — `.cursor/rules/<rule>.mdc` with YAML frontmatter
+  (`description`, `globs`, `alwaysApply`). Preferred for any 2025+
+  Cursor build.
+- **Legacy (`.cursorrules`)** — single-file aggregate at the repo root.
+  Still read by older Cursor versions; the package keeps it for
+  backward compatibility.
+
+The package ships **both** so you don't have to pick.
+
+## Prerequisites
+
+- Cursor 0.45+ (any 2025/2026 build): <https://cursor.com>.
+- Node.js ≥ 18.
+
+## Project install
+
+```bash
+npx @event4u/create-agent-config init --tools=cursor
+```
+
+This populates:
+
+- `.cursor/rules/*.mdc`     — one file per rule, modern frontmatter format
+- `.cursor/commands/*.md`   — slash commands mirrored from `.agent-src/commands/`
+- `.cursorrules`            — legacy single-file aggregate
+- `.agent-settings.yml`     — per-project knobs
+
+Combine surfaces if you use both Cursor and Claude Code:
+
+```bash
+npx @event4u/create-agent-config init --tools=cursor,claude-code
+```
+
+## Global install
+
+```bash
+npx @event4u/agent-config global --tools=cursor
+```
+
+Seeds `~/.cursor/rules/imported/event4u/` with the curated kernel +
+top-N skills. Cursor merges global + workspace rules — workspace wins
+on conflicts.
+
+## Modern `.mdc` frontmatter
+
+Each `.mdc` file has the Cursor-shaped header:
+
+```mdc
+---
+description: Scope control — no unsolicited architectural changes
+globs:
+alwaysApply: true
+---
+
+# Scope Control
+...
+```
+
+- `alwaysApply: true` ↔ source `type: "always"` (kernel rules).
+- `alwaysApply: false` ↔ Cursor model decides per turn (auto rules).
+- `globs:` is intentionally empty in the package's projection — apply
+  per-rule if you need path-scoped rules in your fork.
+
+## Cursor commands
+
+`.cursor/commands/<slug>.md` mirrors `.claude/commands/`. Nested
+clusters (e.g. `council/default.md`) flatten to `council-default.md` so
+Cursor's command palette stays flat.
+
+## Marketplace install (planned — Phase 7 / S35)
+
+The Cursor marketplace listing is filed in
+`road-to-simplicity-and-everywhere.md` Phase 7. Once accepted you'll
+be able to install via Cursor's Extensions panel without `npx`.
+
+## MCP block (when MCP Phase 3 ships)
+
+Add to `.cursor/mcp.json` (Cursor's project-scoped MCP config):
+
+```json
+{
+  "mcpServers": {
+    "event4u-agent-config": {
+      "command": "npx",
+      "args": ["-y", "@event4u/agent-config-mcp"]
+    }
+  }
+}
+```
+
+Track <https://github.com/event4u-app/agent-config> for the actual
+release tag — until `road-to-mcp-full-coverage` Phase 3 ships, this
+block is informational.
+
+## Verification
+
+```bash
+ls -la .cursor/rules/   | head -5      # *.mdc files exist
+ls -la .cursor/commands/| head -5      # *.md command files exist
+test -f .cursorrules                   # legacy aggregate exists
+```
+
+In Cursor itself: open the chat panel — settings should show the rules
+under **Project Rules**.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| Rules not picked up | Cursor < 0.45 — upgrade or rely on `.cursorrules`. |
+| Modern + legacy duplicate triggers | Disable `.cursorrules` in Cursor settings. |
+| Command missing in palette | `task generate-tools` then reload Cursor window. |
+| Global rules ignored | Cursor needs `~/.cursor/rules/` — check OS path expansion. |
+
+## Cross-references
+
+- [`docs/installation.md`](../../installation.md) — install matrix index.
+- [`AGENTS.md`](../../../AGENTS.md) — package self-orientation; Cursor
+  reads it via the projected rules.
+- [`templates/cursor-rule.mdc.j2`](../../../templates/cursor-rule.mdc.j2) —
+  template used by the projection generator.

package/docs/setup/per-ide/gemini-cli.md

@@ -0,0 +1,45 @@
+# Gemini CLI Setup
+
+Google's Gemini CLI reads `GEMINI.md` (which is a symlink to `AGENTS.md`
+in the package's projection) for project context.
+
+## Prerequisites
+
+- Gemini CLI installed: <https://github.com/google-gemini/gemini-cli>.
+- Node.js ≥ 18 (for the install entrypoints).
+
+## Install
+
+```bash
+npx @event4u/create-agent-config init --tools=gemini
+```
+
+Populates:
+
+- `GEMINI.md` → `AGENTS.md` — symlink so Gemini CLI loads the same
+  self-orientation as Codex / Aider / Augment.
+- `AGENTS.md`             — canonical content (single source of truth).
+- `.agent-settings.yml`   — per-project knobs.
+
+## Verification
+
+```bash
+test -L GEMINI.md && readlink GEMINI.md   # → AGENTS.md
+gemini --version                           # confirm CLI installed
+```
+
+In a Gemini CLI session: `GEMINI.md` informs every turn — verify by
+asking *"what is this repo?"* and confirming the answer matches
+`AGENTS.md`'s emergency-triage block.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| Gemini CLI doesn't see `GEMINI.md` | Some Gemini versions require absolute paths — `gemini --context $(pwd)/GEMINI.md`. |
+| Symlink broken on Windows | Re-run installer; on Windows the projection may emit a copy instead of a symlink. |
+
+## Cross-references
+
+- [`AGENTS.md`](../../../AGENTS.md) — canonical agent self-orientation.
+- [`docs/installation.md`](../../installation.md) — install matrix index.

package/docs/setup/per-ide/windsurf.md

@@ -0,0 +1,120 @@
+# Windsurf Setup
+
+Windsurf reads two rule formats:
+
+- **Wave-8 (`.windsurf/rules/`)** — per-rule `.md` files with
+  `trigger`, `description`, `globs` frontmatter. Preferred for
+  Windsurf 1.5+.
+- **Legacy (`.windsurfrules`)** — single-file aggregate at the repo
+  root. Older Windsurf builds and the Cascade chat fallback both still
+  read it.
+
+The package ships **both**.
+
+## Prerequisites
+
+- Windsurf 1.0+ (Codeium): <https://codeium.com/windsurf>.
+- Node.js ≥ 18.
+
+## Project install
+
+```bash
+npx @event4u/create-agent-config init --tools=windsurf
+```
+
+Populates:
+
+- `.windsurf/rules/*.md`        — modern Wave-8 per-rule files
+- `.windsurf/workflows/*.md`    — slash-command workflows
+- `.windsurfrules`              — legacy single-file aggregate
+- `.agent-settings.yml`         — per-project knobs
+
+Combine with other surfaces:
+
+```bash
+npx @event4u/create-agent-config init --tools=windsurf,claude-code,cursor
+```
+
+## Global install
+
+```bash
+npx @event4u/agent-config global --tools=windsurf
+```
+
+Seeds `~/.codeium/windsurf/global_workflows/` with the curated
+workflow set (see [`templates/global-install-manifest.yml`](../../../templates/global-install-manifest.yml)).
+Available across every project; per-workspace `.windsurf/workflows/`
+takes precedence on slug collisions.
+
+## Wave-8 frontmatter
+
+Each rule under `.windsurf/rules/` has the Windsurf-shaped header:
+
+```md
+---
+trigger: always_on
+description: Scope control — no unsolicited architectural changes
+globs:
+---
+
+# Scope Control
+...
+```
+
+- `trigger: always_on` ↔ source `type: "always"` (kernel rules).
+- `trigger: model_decision` ↔ Cascade decides per turn (auto rules).
+- `globs:` is intentionally empty in the package's projection — set
+  per-rule in your fork if you want path-scoped triggering.
+
+## Workflows
+
+`.windsurf/workflows/<slug>.md` mirrors `.claude/commands/`. Cluster
+commands flatten to `<cluster>-<name>.md`. Cascade lists all workflow
+files in its workflow palette.
+
+## Cascade integration
+
+Cascade (Windsurf's built-in agent) reads `.windsurf/rules/` and
+`.windsurf/workflows/` automatically. No separate registration step is
+needed once the files are on disk.
+
+When Cascade asks a clarifying question, the package's `user-interaction`
+rule (kernel, `always_on`) applies — Cascade will surface numbered
+options with a single recommendation.
+
+## Workspace vs global precedence
+
+| Layer | Path | Precedence |
+|---|---|---|
+| Workspace | `.windsurf/rules/` + `.windsurf/workflows/` | wins on conflicts |
+| Global | `~/.codeium/windsurf/global_workflows/` | falls back when workspace silent |
+
+Reuse the same `--tools=windsurf` flag for both — `init` writes
+workspace, `global` writes user-level.
+
+## Verification
+
+```bash
+ls .windsurf/rules/     | head -5      # *.md per-rule files
+ls .windsurf/workflows/ | head -5      # *.md workflow files
+test -f .windsurfrules                 # legacy aggregate exists
+```
+
+In Windsurf itself: open Cascade → Workflows panel — listed workflows
+should match `ls .windsurf/workflows/`.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| Rules not picked up | Windsurf < 1.0 — upgrade or rely on `.windsurfrules`. |
+| Workflow not in Cascade panel | Reload window after `task generate-tools`. |
+| Global workflows missing | Check `~/.codeium/windsurf/global_workflows/` exists. |
+| Frontmatter parse error | Re-run `python3 scripts/compress.py --generate-tools`. |
+
+## Cross-references
+
+- [`docs/installation.md`](../../installation.md) — install matrix index.
+- [`templates/windsurf-rule.md.j2`](../../../templates/windsurf-rule.md.j2)
+  — template used by the projection generator.
+- [`AGENTS.md`](../../../AGENTS.md) — package self-orientation.

package/package.json

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

package/scripts/_lib/script_output.py

@@ -43,20 +43,24 @@ def _read_settings_level(settings_path: Path) -> str | None:
     """Read verbosity.script_output from .agent-settings.yml.
 
     Returns None when the file is missing, PyYAML is unavailable, or
-    the key is absent. Errors fall through to the default level.
+    the key is absent. Errors fall through to the default level. Goes
+    through the centralized loader (road-to-portable-dev-preferences P3)
+    so the tolerance contract — missing file, malformed YAML, no PyYAML
+    — degrades uniformly across scripts. ``verbosity.script_output`` is
+    not on the user-global whitelist, so a value there is silently
+    ignored; the project file is the only source for this knob.
     """
-    if not settings_path.is_file():
-        return None
+    # Lazy import — supports both `python3 scripts/foo.py` (sys.path
+    # contains scripts/) and `pytest` (scripts._lib is a proper package).
     try:
-        import yaml  # type: ignore[import-untyped]
+        from _lib.agent_settings import load_agent_settings  # type: ignore[import-not-found]  # noqa: PLC0415
     except ImportError:
-        return None
-    try:
-        with settings_path.open(encoding="utf-8") as fh:
-            data = yaml.safe_load(fh) or {}
-    except (OSError, yaml.YAMLError):
-        return None
-    section = data.get("verbosity") if isinstance(data, dict) else None
+        from scripts._lib.agent_settings import (  # noqa: PLC0415
+            load_agent_settings,
+        )
+
+    data = load_agent_settings(project_path=settings_path)
+    section = data.get("verbosity")
     if not isinstance(section, dict):
         return None
     value = section.get("script_output")

package/scripts/ai_council/session.py

@@ -88,15 +88,21 @@ def _load_retention_days(settings_path: Path | None = None) -> int:
     file, invalid YAML, missing key, non-int value). Pruning never
     blocks the council on a settings error.
     """
-    path = settings_path or SETTINGS_FILE
-    if not path.exists():
-        return DEFAULT_RETENTION_DAYS
+    # Centralized loader (road-to-portable-dev-preferences P3): tolerance
+    # contract handles missing file / malformed YAML / no PyYAML uniformly.
+    # ``ai_council.session_retention_days`` is not whitelisted, so the
+    # user-global file cannot override the project value.
     try:
-        import yaml  # type: ignore[import-not-found]
-        data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
-    except Exception:  # noqa: BLE001 - never block on settings parse
-        return DEFAULT_RETENTION_DAYS
-    ai = data.get("ai_council") if isinstance(data, dict) else None
+        from scripts._lib.agent_settings import load_agent_settings
+    except ImportError:  # pragma: no cover — script-style invocation
+        import sys as _sys
+        from pathlib import Path as _Path
+        _sys.path.insert(0, str(_Path(__file__).resolve().parent.parent))
+        from _lib.agent_settings import load_agent_settings  # type: ignore[import-not-found]
+
+    path = settings_path or SETTINGS_FILE
+    data = load_agent_settings(project_path=path)
+    ai = data.get("ai_council")
     if not isinstance(ai, dict):
         return DEFAULT_RETENTION_DAYS
     raw = ai.get("session_retention_days", DEFAULT_RETENTION_DAYS)

package/scripts/chat_history.py

@@ -609,27 +609,36 @@ def status(*, path: Path | None = None) -> dict[str, Any]:
     }
 
 
+def _load_chat_history_section(settings_path: Path) -> dict | None:
+    """Return the ``chat_history`` mapping from .agent-settings.yml or None.
+
+    Centralized loader (road-to-portable-dev-preferences P3): tolerance
+    contract handles missing file / malformed YAML / no PyYAML uniformly.
+    No ``chat_history.*`` keys are whitelisted, so user-global cannot
+    leak into this section — the project file remains authoritative.
+    """
+    try:
+        from scripts._lib.agent_settings import load_agent_settings
+    except ImportError:  # pragma: no cover — script-style invocation
+        import sys as _sys
+        from pathlib import Path as _Path
+        _sys.path.insert(0, str(_Path(__file__).resolve().parent))
+        from _lib.agent_settings import load_agent_settings  # type: ignore[import-not-found]
+
+    data = load_agent_settings(project_path=settings_path)
+    section = data.get("chat_history")
+    return section if isinstance(section, dict) else None
+
+
 def _read_chat_history_enabled(settings_path: Path) -> bool:
     """Read chat_history.enabled from .agent-settings.yml.
 
     Returns False when the file is missing, malformed, lacks the
     `chat_history` section, or sets enabled to false. Default-deny so
     `turn-check` is safe to run from projects that have not opted in.
-    PyYAML is imported lazily — the rest of this module works without it.
     """
-    if not settings_path.is_file():
-        return False
-    try:
-        import yaml  # type: ignore[import-untyped]
-    except ImportError:
-        return True  # fail open: settings file present but no parser
-    try:
-        with settings_path.open(encoding="utf-8") as fh:
-            data = yaml.safe_load(fh) or {}
-    except (OSError, yaml.YAMLError):
-        return False
-    section = data.get("chat_history") if isinstance(data, dict) else None
-    if not isinstance(section, dict):
+    section = _load_chat_history_section(settings_path)
+    if section is None:
         return False
     return bool(section.get("enabled", False))
 
@@ -739,19 +748,8 @@ VALID_PLATFORMS = tuple(PLATFORM_EVENT_MAP.keys())
 
 def _read_chat_history_frequency(settings_path: Path) -> str:
     """Read chat_history.frequency from .agent-settings.yml. Default per_phase."""
-    if not settings_path.is_file():
-        return "per_phase"
-    try:
-        import yaml  # type: ignore[import-untyped]
-    except ImportError:
-        return "per_phase"
-    try:
-        with settings_path.open(encoding="utf-8") as fh:
-            data = yaml.safe_load(fh) or {}
-    except (OSError, yaml.YAMLError):
-        return "per_phase"
-    section = data.get("chat_history") if isinstance(data, dict) else None
-    if not isinstance(section, dict):
+    section = _load_chat_history_section(settings_path)
+    if section is None:
         return "per_phase"
     val = str(section.get("frequency", "per_phase")).lower()
     return val if val in VALID_FREQS else "per_phase"
@@ -764,19 +762,8 @@ def _read_chat_history_max_sessions(settings_path: Path) -> int:
     Used by ``prune_sessions`` to decide how many distinct ``s`` tags
     survive in the body.
     """
-    if not settings_path.is_file():
-        return DEFAULT_MAX_SESSIONS
-    try:
-        import yaml  # type: ignore[import-untyped]
-    except ImportError:
-        return DEFAULT_MAX_SESSIONS
-    try:
-        with settings_path.open(encoding="utf-8") as fh:
-            data = yaml.safe_load(fh) or {}
-    except (OSError, yaml.YAMLError):
-        return DEFAULT_MAX_SESSIONS
-    section = data.get("chat_history") if isinstance(data, dict) else None
-    if not isinstance(section, dict):
+    section = _load_chat_history_section(settings_path)
+    if section is None:
         return DEFAULT_MAX_SESSIONS
     try:
         n = int(section.get("max_sessions", DEFAULT_MAX_SESSIONS))
@@ -794,19 +781,8 @@ def _read_text_limits(settings_path: Path) -> dict[str, int]:
     values are clamped to 0. Non-int values are silently dropped.
     """
     out = dict(DEFAULT_TEXT_LIMITS)
-    if not settings_path.is_file():
-        return out
-    try:
-        import yaml  # type: ignore[import-untyped]
-    except ImportError:
-        return out
-    try:
-        with settings_path.open(encoding="utf-8") as fh:
-            data = yaml.safe_load(fh) or {}
-    except (OSError, yaml.YAMLError):
-        return out
-    section = data.get("chat_history") if isinstance(data, dict) else None
-    if not isinstance(section, dict):
+    section = _load_chat_history_section(settings_path)
+    if section is None:
         return out
     overrides = section.get("text_limits")
     if not isinstance(overrides, dict):

package/scripts/command_suggester/settings.py

@@ -42,20 +42,22 @@ def load_settings(settings_path: Path | str | None = None) -> Settings:
 
 
 def _read_section(path: Path) -> dict[str, Any] | None:
-    """Return the ``commands.suggestion`` mapping or ``None`` on any miss."""
-    if not path.is_file():
-        return None
-    try:
-        import yaml  # type: ignore[import-untyped]
-    except ImportError:
-        return None
+    """Return the ``commands.suggestion`` mapping or ``None`` on any miss.
+
+    Centralized loader (road-to-portable-dev-preferences P3): tolerance
+    contract handles missing file / malformed YAML / no PyYAML uniformly.
+    No ``commands.*`` keys are whitelisted, so user-global cannot cascade
+    into this section.
+    """
     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
+        from scripts._lib.agent_settings import load_agent_settings
+    except ImportError:  # pragma: no cover — script-style invocation
+        import sys as _sys
+        from pathlib import Path as _Path
+        _sys.path.insert(0, str(_Path(__file__).resolve().parent.parent))
+        from _lib.agent_settings import load_agent_settings  # type: ignore[import-not-found]
+
+    data = load_agent_settings(project_path=path)
     commands = data.get("commands")
     if not isinstance(commands, dict):
         return None

package/scripts/compile_router.py

@@ -100,16 +100,20 @@ def _normalize_trigger(item) -> dict | None:
 
 
 def _load_settings() -> dict:
-    """Read .agent-settings.yml for compile-time toggles. Stdlib-only fallback."""
-    if not SETTINGS_PATH.exists():
-        return {}
-    text = SETTINGS_PATH.read_text(encoding="utf-8")
+    """Read .agent-settings.yml for compile-time toggles.
+
+    Centralized loader (road-to-portable-dev-preferences P3): tolerance
+    contract handles missing file / malformed YAML / no PyYAML uniformly.
+    """
     try:
-        import yaml  # type: ignore
-        data = yaml.safe_load(text) or {}
-        return data if isinstance(data, dict) else {}
-    except ImportError:
-        return {}
+        from scripts._lib.agent_settings import load_agent_settings
+    except ImportError:  # pragma: no cover — script-style invocation
+        import sys as _sys
+        from pathlib import Path as _Path
+        _sys.path.insert(0, str(_Path(__file__).resolve().parent))
+        from _lib.agent_settings import load_agent_settings  # type: ignore[import-not-found]
+
+    return load_agent_settings(project_path=SETTINGS_PATH)
 
 
 def _collect(rules_dir: Path) -> dict: