@event4u/agent-config 1.39.0 → 1.41.0

package/docs/contracts/file-ownership-matrix.json

@@ -435,6 +435,12 @@
       "load_context": [],
       "load_context_eager": []
     },
+    ".agent-src.uncompressed/commands/orchestrate.md": {
+      "kind": "command",
+      "rule_type": null,
+      "load_context": [],
+      "load_context_eager": []
+    },
     ".agent-src.uncompressed/commands/override.md": {
       "kind": "command",
       "rule_type": null,
@@ -585,6 +591,12 @@
       "load_context": [],
       "load_context_eager": []
     },
+    ".agent-src.uncompressed/commands/sync-gitignore/fix.md": {
+      "kind": "command",
+      "rule_type": null,
+      "load_context": [],
+      "load_context_eager": []
+    },
     ".agent-src.uncompressed/commands/tests.md": {
       "kind": "command",
       "rule_type": null,
@@ -3495,6 +3507,20 @@
       "via": "self",
       "depth": 0
     },
+    {
+      "source": ".agent-src.uncompressed/commands/orchestrate.md",
+      "target": ".agent-src.uncompressed/commands/orchestrate.md",
+      "type": "WRITE",
+      "via": "self",
+      "depth": 0
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/orchestrate.md",
+      "target": ".agent-src.uncompressed/skills/subagent-orchestration/SKILL.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
     {
       "source": ".agent-src.uncompressed/commands/override.md",
       "target": ".agent-src.uncompressed/commands/override.md",
@@ -4055,6 +4081,27 @@
       "via": "self",
       "depth": 0
     },
+    {
+      "source": ".agent-src.uncompressed/commands/sync-gitignore.md",
+      "target": ".agent-src.uncompressed/commands/sync-gitignore/fix.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/sync-gitignore/fix.md",
+      "target": ".agent-src.uncompressed/commands/sync-gitignore.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/sync-gitignore/fix.md",
+      "target": ".agent-src.uncompressed/commands/sync-gitignore/fix.md",
+      "type": "WRITE",
+      "via": "self",
+      "depth": 0
+    },
     {
       "source": ".agent-src.uncompressed/commands/tests.md",
       "target": ".agent-src.uncompressed/commands/tests.md",

package/docs/contracts/mcp-discovery-phase-notice.md

@@ -0,0 +1,56 @@
+# MCP Discovery-Phase Notice
+
+**Audience:** MCP consumers integrating with `event4u/agent-config` — host
+applications, CLIs, agents calling our stdio server or the Cloudflare Worker.
+**Status:** active during Phase 1 of
+[`road-to-mcp-full-coverage`](../../agents/roadmaps/road-to-mcp-full-coverage.md).
+
+## What you will see
+
+`tools/list` advertises ~20 tools. Most return a `not_implemented` envelope when
+called — wire shape in [`mcp-tool-stub-envelope`](mcp-tool-stub-envelope.md).
+This is intentional. Phase 1 is *discovery*: every call — implemented, stub, or
+unknown — is logged so Phase 2's implementation cut is derived from real
+consumer behaviour, not guesses.
+
+## What we need from you
+
+**Keep calling the tools you would naturally call.** A call against a stub is
+not a failed integration; it is a vote. Telemetry records carry
+`{tool_name, client_id_hash, ts, transport, outcome}` — no payload bodies, no
+raw identifiers (J4 in the roadmap). Three outcomes are logged:
+
+- `implemented` — a real handler ran.
+- `stub` — catalog entry, no transport handler; you received the envelope.
+- `latent_demand` — name not in the catalog at all. **The most valuable
+  signal.** If you want a tool that does not exist, call it — do not work
+  around the absence silently.
+
+## How to verify telemetry is flowing
+
+On any host running the stdio server:
+
+```bash
+python3 scripts/mcp_telemetry_health.py
+```
+
+Healthy → exit 0 with the 24 h count. Silent → exit 1; treat as an alert.
+Wire it into Sentry, a GitHub Actions cron, a mailer, or `launchd` — whatever
+you already trust. Worker telemetry lands in Cloudflare Workers Logs
+(structured `mcp.telemetry` lines); query via the dashboard or `wrangler tail`.
+
+## Phase 1 → Phase 2 gate
+
+When the gate fires (≥ 4 weeks of healthy telemetry, ≥ 500 logged attempts,
+≥ 50 distinct `client_id_hash` values), the council ranks tools by demand and
+picks the implementation cut. Tools above the line move from stub → real;
+tools below stay stubbed and may be removed. Silent windows ≥ 24 h refuse the
+K3 gate and restart the observation period — that is why the healthcheck
+output matters.
+
+## Contact
+
+Open an issue against
+[`event4u-app/agent-config`](https://github.com/event4u-app/agent-config) with
+the `mcp-discovery` label if a call returns something other than the documented
+envelope or if `latent_demand` is not landing for a tool you call.

package/docs/contracts/mcp-tool-stub-envelope.md

@@ -0,0 +1,78 @@
+---
+stability: experimental
+---
+
+# MCP Tool Stub Envelope — Phase 1 Discovery Contract
+
+> **Status:** Active · governs Phase 1 (J1–J6) of
+> [`road-to-mcp-full-coverage.md`](../../agents/roadmaps/road-to-mcp-full-coverage.md).
+> **Stability:** experimental — internal index reference only per
+> `STABILITY.md`.
+
+## Purpose
+
+Locks the wire shape of the `not_implemented` envelope returned by
+`tools/call` when a consumer agent invokes a catalog entry that has no
+implementation on the active transport. Every denied call returns a
+structured payload with a recovery hint, never a silent 404 and never
+a 500.
+
+## Source of truth
+
+`scripts/mcp_server/consumer_tool_catalog.json` (schema_version 1).
+Both the stdio server and the Cloud Worker bundle (`workers/mcp/`,
+packed by `scripts/pack_mcp_content.py`) read from this file. The
+manifest returned by `tools/list` is byte-identical apart from
+per-tool `implemented_on` metadata.
+
+## Catalog entry
+
+```json
+{
+  "name": "<snake_case>",
+  "description": "<≤500 chars; agent-facing>",
+  "side_effect": "ro | fs-write | shell",
+  "implemented_on": ["stdio"],
+  "input_schema": { "type": "object", "...": "JSON Schema draft-7" }
+}
+```
+
+`implemented_on` lists transports where a real handler is wired;
+missing transports return the envelope.
+
+## Envelope wire shape
+
+```json
+{
+  "code": "not_implemented",
+  "tool": "<catalog name>",
+  "transport": "stdio | worker",
+  "install_hint": "<copyable shell command>",
+  "alternative": "stdio",
+  "message": "<one-sentence explainer>"
+}
+```
+
+Stdio returns this as the JSON-RPC `result` (SDK wraps in
+`TextContent`); the Worker returns it as `error.data` alongside
+`code: -32601`. Field invariants: `code` is the frozen literal
+`not_implemented`; `tool` echoes the caller; `transport` is set per
+surface; `install_hint` comes from the catalog's `install_hint_stdio`
+field; `alternative` is the frozen literal `stdio` until Phase 3.
+Consumer agents must drive logic from `code`, not `message`.
+
+## Unknown-tool / latent-demand path
+
+A call to a name not in the catalog returns JSON-RPC error `-32601`
+with the same envelope shape, `code: "unknown_tool"`. Both transports
+log the attempt with `outcome: "latent_demand"` so Phase 2 can
+promote unforeseen names.
+
+## Acceptance
+
+- Both transports return `code == "not_implemented"` for every
+  catalog entry whose `implemented_on` excludes the transport.
+- Both transports return `code == "unknown_tool"` for any name not in
+  the catalog.
+- Schema version bumps on any incompatible field rename; new optional
+  fields are compatible.

package/docs/contracts/orchestration-dsl-v1.md

@@ -0,0 +1,152 @@
+---
+stability: beta
+---
+
+# Orchestration DSL v1
+
+**Purpose.** Pin the YAML schema that the `/orchestrate` command
+reads to chain personas / skills / sub-agents into reproducible
+pipelines. A pipeline file is a deterministic, reviewable artifact
+that re-runs the same step sequence with the same inputs.
+
+**Scope.** Defines the file location, top-level shape, step kinds,
+input / output wiring, and the linter contract. Does **not** define
+the runtime semantics of each step kind — those live in the
+[`/orchestrate`](../../.agent-src.uncompressed/commands/orchestrate.md)
+command and the `work_engine` directive modules it delegates to.
+
+Last refreshed: 2026-05-11.
+
+## File location
+
+```
+.agent-config/orchestrations/<name>.yaml
+```
+
+`<name>` is kebab-case, matches the `name` field inside the file,
+and is unique across the consumer project's orchestrations directory.
+The directory is opt-in — `/orchestrate` falls back to the prompt
+when no file exists.
+
+## Top-level shape
+
+```yaml
+schema_version: 1
+name: pr-readiness-check
+description: |
+  Run the four review-lens judges against the current diff, then
+  consolidate verdicts into a single Markdown report.
+inputs:
+  - id: diff_target
+    description: Git ref to diff against. Default origin/main.
+    default: origin/main
+steps:
+  - id: bug
+    kind: skill
+    ref: judge-bug-hunter
+    with:
+      diff_target: ${{ inputs.diff_target }}
+  - id: security
+    kind: skill
+    ref: judge-security-auditor
+    with:
+      diff_target: ${{ inputs.diff_target }}
+  - id: tests
+    kind: skill
+    ref: judge-test-coverage
+    with:
+      diff_target: ${{ inputs.diff_target }}
+  - id: quality
+    kind: skill
+    ref: judge-code-quality
+    with:
+      diff_target: ${{ inputs.diff_target }}
+  - id: consolidate
+    kind: command
+    ref: review-changes
+    with:
+      verdicts:
+        - ${{ steps.bug.output }}
+        - ${{ steps.security.output }}
+        - ${{ steps.tests.output }}
+        - ${{ steps.quality.output }}
+outputs:
+  report: ${{ steps.consolidate.output }}
+```
+
+## Field semantics
+
+| Field | Type | Required | Meaning |
+|---|---|---|---|
+| `schema_version` | int | yes | Always `1`. Major bump on breaking changes. |
+| `name` | string | yes | Kebab-case identifier; matches filename. |
+| `description` | string | yes | One-paragraph statement of intent. |
+| `inputs[]` | list | no | Named pipeline inputs. Each has `id`, `description`, optional `default`. |
+| `steps[]` | list | yes | Ordered list of steps. Min 1, max 32. |
+| `steps[].id` | string | yes | Snake-case identifier; unique within the pipeline. |
+| `steps[].kind` | enum | yes | One of `skill` · `command` · `persona` · `subagent`. |
+| `steps[].ref` | string | yes | Reference id matching the `kind` namespace. |
+| `steps[].with` | map | no | Inputs to the step. Values MAY use `${{ inputs.X }}` / `${{ steps.Y.output }}` interpolation. |
+| `steps[].when` | string | no | Conditional expression — runs the step only if truthy. Limited to `${{ steps.X.output }}` equality and `success` / `failure` predicates. |
+| `outputs` | map | no | Named pipeline outputs. Surfaced in the final delivery report. |
+
+## Step kinds
+
+| `kind` | `ref` resolves to | Runtime |
+|---|---|---|
+| `skill` | `.agent-src.uncompressed/skills/<ref>/SKILL.md` | Dispatched via `work_engine` directive matching the skill's domain. |
+| `command` | `.agent-src.uncompressed/commands/<ref>.md` | Same dispatch path the slash-command takes when typed by the user. |
+| `persona` | `.agent-src.uncompressed/personas/<ref>.md` | Sets `roles.active_role` for the next dependent step; does not produce its own output. |
+| `subagent` | `subagent-orchestration` mode name | Spawned per [`subagent-orchestration`](../../.agent-src.uncompressed/skills/subagent-orchestration/SKILL.md). |
+
+## Interpolation
+
+Two namespaces only:
+
+```
+${{ inputs.<input-id> }}
+${{ steps.<step-id>.output }}
+```
+
+Unknown namespaces hard-fail at lint time. The interpolation engine
+does string substitution — there are no expressions, no arithmetic,
+no shell-out.
+
+## Linter contract
+
+`scripts/lint_orchestration_dsl.py` hard-fails on:
+
+- missing or malformed top-level keys (`schema_version`, `name`,
+  `description`, `steps`)
+- `schema_version != 1`
+- `name` not matching `[a-z][a-z0-9-]*` or not matching the filename
+- duplicate `steps[].id`
+- `steps[].kind` outside the enum
+- `steps[].ref` pointing at a non-existent skill / command / persona
+- `${{ ... }}` reference to an unknown input or step id
+- `steps[]` length > 32 or < 1
+- `outputs` referencing an unknown step
+
+Exit codes mirror [`lint_hook_manifest.py`](../../scripts/lint_hook_manifest.py): `0` clean, `1` failure, `2` schema-load error.
+
+## Privacy floor
+
+Pipeline files are committed artifacts. They MUST NOT contain:
+
+- Secrets, tokens, environment values.
+- Conversation bodies or transcripts.
+- File contents (only paths and refs).
+
+## Stability
+
+Beta. Breaking changes between v1 and v2 are allowed in a minor
+release if the change appears in `CHANGELOG.md` under a `### Breaking`
+heading. Engines MUST gate on `schema_version` and refuse unknown
+majors.
+
+## Cross-references
+
+- Command surface: [`/orchestrate`](../../.agent-src.uncompressed/commands/orchestrate.md).
+- Linter: [`lint_orchestration_dsl.py`](../../scripts/lint_orchestration_dsl.py).
+- Runtime dispatcher precedent: [`implement-ticket-flow.md`](implement-ticket-flow.md).
+- Subagent runtime: [`subagent-orchestration`](../../.agent-src.uncompressed/skills/subagent-orchestration/SKILL.md).

package/docs/getting-started.md

@@ -153,7 +153,7 @@ Your agent now understands slash commands:
 | `/quality-fix` | Run and fix all quality checks |
 | `/chat-history` | Inspect the persistent chat-history log (read-only `show`) |
 
-→ [Browse all 104 active commands](../.agent-src/commands/)
+→ [Browse all 106 active commands](../.agent-src/commands/)
 
 ---
 

package/docs/installation.md

@@ -3,6 +3,41 @@
 **Principle:** Project-installed by default, plugin-enhanced when available.
 No Task, no Make, no build tools required for installation.
 
+## Per-IDE setup — quick index
+
+Pick your editor, follow the linked page, done. Each page lists its
+own one-liner, verification, and troubleshooting. The mechanisms
+section below this index is reference material for advanced installs
+(Composer, npm, manual, plugin marketplaces).
+
+| Surface | One-liner | Per-IDE page |
+|---|---|---|
+| **Claude Code** | `npx @event4u/create-agent-config init --tools=claude-code` | [`per-ide/claude-code.md`](setup/per-ide/claude-code.md) |
+| **Claude Desktop** | (uses `~/.claude/skills/` from Claude Code global install) | [`per-ide/claude-desktop.md`](setup/per-ide/claude-desktop.md) |
+| **Cursor** | `npx @event4u/create-agent-config init --tools=cursor` | [`per-ide/cursor.md`](setup/per-ide/cursor.md) |
+| **Windsurf** | `npx @event4u/create-agent-config init --tools=windsurf` | [`per-ide/windsurf.md`](setup/per-ide/windsurf.md) |
+| **Cline** | `npx @event4u/create-agent-config init --tools=cline` | [`per-ide/cline.md`](setup/per-ide/cline.md) |
+| **Aider** | `npx @event4u/create-agent-config init --tools=aider` | [`per-ide/aider.md`](setup/per-ide/aider.md) |
+| **Codex CLI** | `npx @event4u/create-agent-config init --tools=codex` | [`per-ide/codex.md`](setup/per-ide/codex.md) |
+| **Gemini CLI** | `npx @event4u/create-agent-config init --tools=gemini` | [`per-ide/gemini-cli.md`](setup/per-ide/gemini-cli.md) |
+| **GitHub Copilot** | `npx @event4u/create-agent-config init --tools=copilot` | [`per-ide/copilot.md`](setup/per-ide/copilot.md) |
+| **All surfaces** | `npx @event4u/create-agent-config init` (default) | (each page above applies) |
+
+Combine surfaces by comma-separating: `--tools=claude-code,cursor,windsurf`.
+
+> Looking for **global** (cross-project) install? Each per-IDE page
+> documents its own `npx @event4u/agent-config global --tools=<ide>`
+> command.
+
+---
+
+## Mechanisms reference
+
+The rest of this page documents the underlying install mechanisms
+(Composer, npm, manual clone, plugin marketplaces). Most users want
+the per-IDE index above.
+
+
 > **Primary installer:** `scripts/install` — a small bash orchestrator that
 > runs the two real installer stages in order:
 >
@@ -42,6 +77,63 @@ No Task, no Make, no build tools required for installation.
 
 ---
 
+## Quickstart — one-liner entrypoints
+
+Try `@event4u/agent-config` in any directory in under 30 seconds, without
+`composer require` or `git clone` first. Both entrypoints are thin
+wrappers around `scripts/install` — same payload, same flags, no extra
+state.
+
+### `npx` (Node ≥ 18)
+
+```bash
+# Pick tools interactively (TTY checkbox prompt)
+npx @event4u/create-agent-config init
+
+# Pick tools explicitly, non-interactive
+npx @event4u/create-agent-config init --tools=claude-code,cursor --yes
+
+# Install everything (the default — backward-compatible)
+npx @event4u/create-agent-config init --tools=all --yes
+
+# Test a specific git ref (branch, tag, sha) instead of the latest npm tag
+npx @event4u/create-agent-config init --ref=main --yes
+```
+
+The `@event4u/create-agent-config` package is a thin wrapper: it
+downloads the latest `@event4u/agent-config` tarball into a temp
+directory, runs `bash scripts/install --target <cwd> ...`, and cleans
+up after itself. The project-local payload package
+(`@event4u/agent-config`) is unchanged.
+
+### `curl | bash` (no Node required)
+
+```bash
+# Defaults (interactive picker if your terminal is a TTY, else --tools=all)
+curl -sSL https://raw.githubusercontent.com/event4u-app/agent-config/main/setup.sh | bash
+
+# Explicit tools, non-interactive (same flags as scripts/install)
+curl -sSL https://raw.githubusercontent.com/event4u-app/agent-config/main/setup.sh \
+  | bash -s -- --tools=claude-code,cursor --yes
+
+# Install from a specific git ref
+curl -sSL https://raw.githubusercontent.com/event4u-app/agent-config/main/setup.sh \
+  | bash -s -- --ref=v1.39.0 --tools=cursor --yes
+```
+
+Requires `bash`, `tar`, `curl` (or `wget`), and Python ≥ 3.10 on the
+host. Mirrors the agent-os `setup.sh` pattern.
+
+### Interactive `--tools` picker
+
+When `scripts/install` runs without an explicit `--tools` flag in an
+interactive terminal (stdin + stdout both TTYs, `--yes` not passed), it
+prompts for a comma-separated tool selection. In CI / piped invocations
+the picker is skipped and the backward-compatible `all` default is
+used. Pass `--yes` (or `-y`) to force non-interactive mode anywhere.
+
+---
+
 ## Project-installed mode (recommended for teams)
 
 Install once in the project — available to everyone working on it.
@@ -426,6 +518,8 @@ Options:
   --quiet           Suppress non-error output
   --skip-sync       Skip payload sync (install.sh)
   --skip-bridges    Skip bridge files (install.py)
+  --global          Ship kernel rules + curated skills to user-scope dirs
+  --uninstall       With --global: remove the event4u/ namespace dir
   --help, -h        Show this help
 ```
 
@@ -434,6 +528,44 @@ The underlying stages keep their own CLI surfaces:
 
 ---
 
+## Global user-level install (`--global`)
+
+`--global` ships a curated subset of kernel rules + top-N skills into
+**per-tool user-scope directories**, so the agent has them in every
+project on the machine without a per-project install.
+
+```bash
+# Default: every supported surface, namespaced under event4u/.
+bash scripts/install --global
+
+# Scope to specific surfaces (mirrors the project install --tools flag).
+bash scripts/install --global --tools=claude-code,cursor
+
+# Remove only what we put there — never touches user files.
+bash scripts/install --global --uninstall
+```
+
+| Surface       | Target directory                                                |
+| ------------- | --------------------------------------------------------------- |
+| Claude Code   | `~/.claude/rules/event4u/`, `~/.claude/skills/event4u/`         |
+| Cursor        | `~/.cursor/rules/imported/event4u/{rules,skills}/`              |
+| Windsurf      | `~/.codeium/windsurf/global_workflows/event4u/{rules,skills}/`  |
+| Fallback      | `~/.config/agent-config/{rules,skills}/event4u/`                |
+
+The fallback path is always written so an editor we don't yet know
+about can still pick the files up.
+
+**Curation source:** `templates/global-install-manifest.yml`. Edit
+post-install to grow or shrink the global set; re-run `--global` to
+re-project. `--uninstall` only removes the `event4u/` namespace —
+user-added rules / skills under sibling paths stay untouched.
+
+**When to use:** running multiple unrelated projects where a per-project
+install is overkill, or wiring up a new editor (Claude Desktop, Cursor)
+that benefits from a baseline set of skills out of the box.
+
+---
+
 ## Updating
 
 When a new version of the package is published: