@event4u/agent-config 9.8.0 → 9.10.0

package/src/scripts/mcp_server/consumer_tool_catalog.json

@@ -1,278 +1,518 @@
 {
   "schema_version": 1,
-  "description": "Source-of-truth catalog of consumer-relevant MCP tools. Read by the stdio server (scripts/mcp_server/) and packed into the Cloud Worker bundle (internal/workers/mcp/). Phase 1 of road-to-mcp-full-coverage: tools without 'implemented' transports return the 'not_implemented' envelope defined in docs/contracts/mcp-tool-stub-envelope.md. The 'implemented_on' field lists transports where the real handler is wired; everything else is a discovery stub. See agents/roadmaps/archive/road-to-mcp-full-coverage.md.",
-  "install_hint_stdio": "pip install agent-config[mcp] && ./agent-config mcp:run",
+  "description": "Source-of-truth catalog of consumer-relevant MCP tools. Read by the stdio server (scripts/mcp_server/) and packed into the Cloud Worker bundle (internal/workers/mcp/). The 'implemented_on' field lists transports where the real handler is wired. Entries marked '[stub — implemented on demand]' are DOCUMENTATION of the on-demand backlog: per ADR-132 they are NOT registered on the stdio tools/list (the wire carries implemented tools only); the 'not_implemented' envelope contract (docs/contracts/mcp-tool-stub-envelope.md) remains for Worker parity. Generated by `src/scripts/build_mcp_catalog.ts` — never hand-edit this file.",
+  "install_hint_stdio": "npx -y @event4u/agent-config mcp-server",
   "tools": [
     {
-      "name": "lint_skills",
-      "description": "Lint skill, rule, command, guideline, and persona markdown files for frontmatter and structural errors. Use before committing or opening a PR that adds or edits any of those artifacts, to catch schema violations early. Read-only — never writes files or spawns git. Returns the `scripts/skill_linter.py --format json` payload: a `summary` object (pass / pass_with_warnings / fail / total counts) and a per-file `results` array with severity-tagged findings. Pass `paths` to lint a subset; omit for a full tree scan.",
-      "side_effect": "ro",
-      "implemented_on": ["stdio"],
+      "name": "capabilities_index",
+      "description": "Regenerate `CAPABILITIES.yaml`, the package's coverage index of skills, rules, commands, and guidelines. Use after adding or removing an artifact to keep the index current. Pass `check: true` to run in read-only CI mode (fails instead of writing on drift).",
+      "side_effect": "fs-write",
+      "implemented_on": [
+        "stdio"
+      ],
       "input_schema": {
         "type": "object",
         "properties": {
-          "paths": {
-            "type": "array",
-            "items": {"type": "string"},
-            "description": "Repo-relative paths to lint (files or directories). Empty or missing → full tree scan."
+          "check": {
+            "type": "boolean",
+            "default": false,
+            "description": "When true, run in read-only drift-check mode instead of writing the index."
           }
         },
         "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": false
       }
     },
     {
-      "name": "chat_history_append",
-      "description": "Append one structured entry to the consumer project's chat-history log (a JSONL file). Use to record a decision, note, or phase marker that should persist into a later session or be distilled by `mine_session`. Writes to the filesystem (`agents/runtime/.agent-chat-history` by default; `agents/.agent-chat-history` and `.agent-chat-history` accepted for back-compat) and returns the written entry plus its resolved target path. Path-scoped: a `path` outside the allowlist, or any traversal escaping the project root, raises an error before writing. Set `dry_run: true` to preview the entry and target path without touching disk.",
-      "side_effect": "fs-write",
-      "implemented_on": ["stdio"],
+      "name": "catalog_inspect",
+      "description": "[stub — implemented on demand] Return the metadata for one catalog entry by id (id, class, name, description, tags, path). Body is returned ONLY when include_body is true. Use after catalog_search to look at a candidate before loading it. Read-only. Activation deferred (see catalog_search).",
+      "side_effect": "ro",
+      "implemented_on": [],
       "input_schema": {
         "type": "object",
         "properties": {
-          "text": {"type": "string", "description": "The entry body to record."},
-          "entry_type": {"type": "string", "description": "Short `t` tag categorising the entry (e.g. note, decision, phase). Defaults to `note`."},
-          "path": {"type": "string", "description": "Optional path override. Must resolve to `agents/runtime/.agent-chat-history` (current default), `agents/.agent-chat-history`, or `.agent-chat-history` under consumer_root."},
-          "session": {"type": "string", "description": "Optional 16-char session id to group the entry under. Defaults to the current session."},
-          "dry_run": {"type": "boolean", "default": false, "description": "When true, return the entry and resolved target path without writing to disk."},
-          "min_schema_version": {"type": "integer", "description": "Refuse to write if the on-disk history schema is older than this version."}
+          "id": {
+            "type": "string",
+            "description": "Catalog id, e.g. `skill:api-design` or `persona:backend-architect`."
+          },
+          "include_body": {
+            "type": "boolean",
+            "default": false,
+            "description": "When true, include the full body. Defaults to false (metadata only)."
+          }
         },
-        "required": ["text"],
+        "required": [
+          "id"
+        ],
         "additionalProperties": false
       }
     },
     {
-      "name": "chat_history_read",
-      "description": "Read recent entries back from the consumer project's chat-history JSONL (`agents/runtime/.agent-chat-history`; `agents/.agent-chat-history` accepted for back-compat). Use to recover context from an earlier session — decisions, notes, phase markers — at the start of a new task. Read-only. Returns the resolved file path plus a list of matching entries (newest last). Combine `session`, `last`, and `entry_type` to narrow the result.",
+      "name": "catalog_load",
+      "description": "[stub — implemented on demand] Load the full body of one catalog entry by id, wrapped in a neutral reference preamble that subordinates it to the user's request and system instructions. Use to bring a skill/persona/command body into context on demand. Read-only, path-confined to the package root. Never injects or acts — the host decides what to do with the body. Activation deferred (see catalog_search).",
       "side_effect": "ro",
-      "implemented_on": ["stdio"],
+      "implemented_on": [],
       "input_schema": {
         "type": "object",
         "properties": {
-          "last": {"type": "integer", "description": "Return only the most recent N entries, after other filters apply.", "minimum": 1},
-          "session": {"type": "string", "description": "Filter to a single 16-char session id."},
-          "entry_type": {"type": "string", "description": "Filter by the `t` tag (e.g. note, decision, phase)."},
-          "path": {"type": "string", "description": "Optional history-file path override; defaults to the standard chat-history location under the project root."},
-          "around": {"type": "integer", "minimum": 0, "description": "Timeline anchor: return the entries around this ref (from a detail:\"index\" row) instead of the filtered list — depth_before/depth_after neighbours plus the anchor. Refs are within-file ordinals; rotation invalidates them."},
-          "depth_before": {"type": "integer", "minimum": 0, "default": 3, "description": "Neighbours before the anchor (with `around`). Defaults to 3."},
-          "depth_after": {"type": "integer", "minimum": 0, "default": 3, "description": "Neighbours after the anchor (with `around`). Defaults to 3."},
-          "detail": {"type": "string", "enum": ["index", "full"], "default": "full", "description": "'index' returns compact rows (ref, t tag, ~100-char preview, tokens_estimate) instead of full entries — scan first, then re-read the refs you need via `around` or a narrowed filter. 'full' (default) returns complete entries."}
+          "id": {
+            "type": "string",
+            "description": "Catalog id to load the body for."
+          }
         },
+        "required": [
+          "id"
+        ],
         "additionalProperties": false
       }
     },
     {
-      "name": "memory_lookup",
-      "description": "Retrieve engineering-memory entries for one or more memory types, optionally narrowed to specific anchor paths. Use before editing a security-sensitive or historically buggy file to surface prior incidents, ownership, and patterns tied to it. WORKFLOW: call with detail:\"index\" FIRST — each row carries id, title and tokens_estimate (the cost of fetching it) — then fetch full bodies via memory_get ONLY for the ids you will actually use, batching multiple ids into one call. Reads `agents/memory/<type>/*.yml` plus the `agents/memory/intake/*.jsonl` signal log. Read-only. Returns the v1 retrieval envelope: a `status` field plus per-type `slices` carrying the matched entries.",
+      "name": "catalog_search",
+      "description": "[stub — implemented on demand] Search the package's own artifact catalog (skills, personas, commands) by free-text query and return ranked summaries — name, description, tags, score — WITHOUT loading any body. Use to discover which skill or persona fits a task when the full catalog is not in context. Read-only, deterministic (BM25 over an on-disk index). Activation deferred behind a task-quality A/B (see catalog_tools.ts).",
       "side_effect": "ro",
-      "implemented_on": ["stdio"],
+      "implemented_on": [],
       "input_schema": {
         "type": "object",
         "properties": {
-          "types": {"type": "array", "items": {"type": "string"}, "minItems": 1, "description": "Memory types to scan, e.g. `historical-patterns`, `incident-learnings`, `ownership`. At least one required."},
-          "keys": {"type": "array", "items": {"type": "string"}, "description": "Optional anchor paths or globs to match entries against (e.g. a file you are about to edit)."},
-          "limit": {"type": "integer", "minimum": 1, "default": 5, "description": "Maximum entries to return per type. Defaults to 5."},
-          "detail": {"type": "string", "enum": ["index", "full"], "default": "full", "description": "'index' returns compact priced rows (id, title, tokens_estimate) instead of full bodies — call this first, then memory_get the ids you need. 'full' (default) returns complete entries."},
-          "token_budget": {"type": "integer", "minimum": 1, "description": "Optional token budget. When set, entries are rendered as one-line compact rows (id, type, confidence, `line`) and the row set is hard-cut at token_budget × 4 chars; omitted hits appear as a top-level `truncation` hint naming a concrete next step. Absent → the envelope is unchanged."}
+          "query": {
+            "type": "string",
+            "description": "Free-text search query."
+          },
+          "class": {
+            "type": "string",
+            "enum": [
+              "skill",
+              "persona",
+              "command"
+            ],
+            "description": "Optional: restrict to one artifact class."
+          },
+          "pack": {
+            "type": "string",
+            "description": "Optional: restrict to entries tagged with this pack/domain."
+          },
+          "limit": {
+            "type": "integer",
+            "minimum": 1,
+            "default": 8,
+            "description": "Maximum results. Defaults to 8."
+          }
         },
-        "required": ["types"],
+        "required": [
+          "query"
+        ],
         "additionalProperties": false
       }
     },
     {
-      "name": "memory_get",
-      "description": "Batch-fetch FULL memory entries by id — the second half of the index-first retrieval workflow. Call memory_lookup with detail:\"index\" first, pick the ids whose title/tokens_estimate justify the fetch, then fetch them here in ONE batched call. Unknown ids are reported per-id (ids[<id>]=\"unknown\"), never failing the batch. Read-only.",
+      "name": "chat_history_append",
+      "description": "Append one structured entry to the consumer project's chat-history log (a JSONL file). Use to record a decision, note, or phase marker that should persist into a later session or be distilled by `mine_session`. Writes to the filesystem (`agents/runtime/.agent-chat-history` by default; `agents/.agent-chat-history` and `.agent-chat-history` accepted for back-compat) and returns the written entry plus its resolved target path. Path-scoped: a `path` outside the allowlist, or any traversal escaping the project root, raises an error before writing. Set `dry_run: true` to preview the entry and target path without touching disk.",
+      "side_effect": "fs-write",
+      "implemented_on": [
+        "stdio"
+      ],
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "text": {
+            "type": "string",
+            "description": "The entry body to record."
+          },
+          "entry_type": {
+            "type": "string",
+            "description": "Short ``t`` tag categorising the entry (e.g. note, decision, phase). Defaults to ``note``."
+          },
+          "path": {
+            "type": "string",
+            "description": "Optional path override. Must resolve to `agents/runtime/.agent-chat-history` (current default), `agents/.agent-chat-history`, or `.agent-chat-history` under consumer_root."
+          },
+          "session": {
+            "type": "string",
+            "description": "Optional 16-char session id to group the entry under. Defaults to the current session."
+          },
+          "dry_run": {
+            "type": "boolean",
+            "default": false,
+            "description": "When true, return the entry and resolved target path without writing to disk."
+          },
+          "min_schema_version": {
+            "type": "integer",
+            "description": "Refuse to write if the on-disk history schema is older than this version."
+          }
+        },
+        "required": [
+          "text"
+        ],
+        "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": false
+      }
+    },
+    {
+      "name": "chat_history_read",
+      "description": "Read recent entries back from the consumer project's chat-history JSONL (`agents/runtime/.agent-chat-history`; `agents/.agent-chat-history` accepted for back-compat). Use to recover context from an earlier session — decisions, notes, phase markers — at the start of a new task. Read-only. Returns the resolved file path plus a list of matching entries (newest last). Combine `session`, `last`, and `entry_type` to narrow the result.",
       "side_effect": "ro",
-      "implemented_on": ["stdio"],
+      "implemented_on": [
+        "stdio"
+      ],
       "input_schema": {
         "type": "object",
         "properties": {
-          "ids": {"type": "array", "items": {"type": "string"}, "minItems": 1, "description": "Entry ids to fetch (from a detail:\"index\" lookup)."}
+          "last": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "Return only the most recent N entries, after other filters apply."
+          },
+          "session": {
+            "type": "string",
+            "description": "Filter to a single 16-char session id."
+          },
+          "entry_type": {
+            "type": "string",
+            "description": "Filter by the `t` tag (e.g. note, decision, phase)."
+          },
+          "path": {
+            "type": "string",
+            "description": "Optional history-file path override; defaults to the standard chat-history location under the project root."
+          },
+          "around": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Timeline anchor: return the entries around this ref (from a detail:\"index\" row) instead of the filtered list — depth_before/depth_after neighbours plus the anchor. Refs are within-file ordinals; rotation invalidates them."
+          },
+          "depth_before": {
+            "type": "integer",
+            "minimum": 0,
+            "default": 3,
+            "description": "Neighbours before the anchor (with `around`). Defaults to 3."
+          },
+          "depth_after": {
+            "type": "integer",
+            "minimum": 0,
+            "default": 3,
+            "description": "Neighbours after the anchor (with `around`). Defaults to 3."
+          },
+          "detail": {
+            "type": "string",
+            "enum": [
+              "index",
+              "full"
+            ],
+            "default": "full",
+            "description": "'index' returns compact rows (ref, t tag, ~100-char preview, tokens_estimate) instead of full entries — scan first, then re-read the refs you need via `around` or a narrowed filter. History entries are large, so index mode pays off here. 'full' (default) returns complete entries."
+          }
         },
-        "required": ["ids"],
         "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": true
       }
     },
     {
-      "name": "memory_signal",
-      "description": "Record an engineering-memory signal — a short, anchored observation such as a recurring bug pattern or an ownership note — to the monthly intake log `agents/memory/intake/signals-YYYY-MM.jsonl`. Use to capture a learning tied to a specific file so future `memory_lookup` calls surface it. Appends to the filesystem and is rate-limited per `(type, path)` within a rolling window. Returns the recorded signal.",
-      "side_effect": "fs-write",
-      "implemented_on": ["stdio"],
+      "name": "compile_router",
+      "description": "[stub — implemented on demand] Regenerate the compiled router (`router.compiled.json`) from the current rule, skill, and command frontmatter, so trigger-based routing reflects the latest artifacts. Use after adding or editing a rule / skill / command's trigger metadata. Shell-bound — wraps `scripts/compile_router.py` — and returns the regenerated router summary. Set `dry_run: true` to compute the result without writing the file.",
+      "side_effect": "shell",
+      "implemented_on": [],
       "input_schema": {
         "type": "object",
         "properties": {
-          "type": {"type": "string", "description": "Memory type the signal belongs to (e.g. historical-patterns, incident-learnings, ownership)."},
-          "path": {"type": "string", "description": "Repo-relative anchor path the signal is about."},
-          "body": {"type": "string", "description": "Free-form signal body — the observation to record."}
+          "dry_run": {
+            "type": "boolean",
+            "default": false,
+            "description": "When true, compute the router without writing `router.compiled.json` to disk."
+          }
         },
-        "required": ["type", "path", "body"],
         "additionalProperties": false
       }
     },
     {
-      "name": "memory_status",
-      "description": "Report the memory backend status. Memory is entirely file-backed (`agents/memory/`); there is no external backend. Read-only, takes no arguments. Returns a `status` (`file`), the active `backend` (`file`), and a short `reason`.",
+      "name": "conformance_check",
+      "description": "Run the consumer conformance contract (`doctor --ci` plus installed-and-firing checks) and return pass/fail per check. Use to verify a consumer project's install is fully wired before relying on it. Read-only.",
       "side_effect": "ro",
-      "implemented_on": ["stdio"],
-      "input_schema": {"type": "object", "properties": {}, "additionalProperties": false}
+      "implemented_on": [
+        "stdio"
+      ],
+      "input_schema": {
+        "type": "object",
+        "properties": {},
+        "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": true
+      }
     },
     {
-      "name": "skill_trigger_eval",
-      "description": "Score a user message against the compiled router and return the skills whose triggers match, each with the reason it fired. Use to predict which skills a given message would activate, for debugging trigger coverage. Read-only and deterministic. Returns a ranked list of matching skills with their trigger reasons.",
+      "name": "council_estimate",
+      "description": "Estimate the token cost of an AI-council debate over a given input (roadmap, diff, prompt, or file set) without spending — no network call, no billing. Use before deciding whether to authorize a real council run. Read-only.",
       "side_effect": "ro",
-      "implemented_on": [],
+      "implemented_on": [
+        "stdio"
+      ],
       "input_schema": {
         "type": "object",
         "properties": {
-          "message": {"type": "string", "description": "The user message to score against skill triggers."},
-          "context": {"type": "string", "description": "Optional recent-turn context to sharpen the match."},
-          "limit": {"type": "integer", "minimum": 1, "default": 5, "description": "Maximum number of matching skills to return. Defaults to 5."}
+          "input_path": {
+            "type": "string",
+            "description": "Path to the roadmap, diff, or file to estimate council cost for."
+          },
+          "depth": {
+            "type": "string",
+            "enum": [
+              "shallow",
+              "deep"
+            ],
+            "description": "Council depth tier to estimate for. Defaults to the configured default depth."
+          }
         },
-        "required": ["message"],
+        "required": [
+          "input_path"
+        ],
         "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": true
       }
     },
     {
-      "name": "suggest_command",
-      "description": "Run the command-suggestion engine: score the available slash commands against a user message and context, and return a ranked, numbered-options block of the best matches. Use to recommend a command for a free-form request without invoking anything. Read-only and deterministic. Returns the formatted suggestion block plus the scored candidates.",
+      "name": "doctor_report",
+      "description": "Run the consumer-project doctor diagnostic and return a structured health report (install drift, hook wiring, settings schema, discovery manifest freshness). Use to triage a misbehaving install. Read-only.",
       "side_effect": "ro",
-      "implemented_on": [],
+      "implemented_on": [
+        "stdio"
+      ],
       "input_schema": {
         "type": "object",
-        "properties": {
-          "message": {"type": "string", "description": "The user message to match commands against."},
-          "context": {"type": "string", "description": "Optional recent-turn context to sharpen the match."}
-        },
-        "required": ["message"],
+        "properties": {},
         "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": true
       }
     },
     {
-      "name": "suggest_skill_for_task",
-      "description": "Match a free-form task description to the most relevant skills, ranked by their frontmatter triggers. Use to pick a skill for a described task before starting work. Read-only. Returns a ranked list of skills with name, description, and match reason.",
+      "name": "lint_skills",
+      "description": "Lint skill, rule, command, guideline, and persona markdown files for frontmatter and structural errors. Use before committing or opening a PR that adds or edits any of those artifacts, to catch schema violations early. Read-only — never writes files or spawns git. Returns the `scripts/skill_linter.py --format json` payload: a `summary` object (pass / pass_with_warnings / fail / total counts) and a per-file `results` array with severity-tagged findings. Pass `paths` to lint a subset; omit for a full tree scan.",
       "side_effect": "ro",
-      "implemented_on": [],
+      "implemented_on": [
+        "stdio"
+      ],
       "input_schema": {
         "type": "object",
         "properties": {
-          "task": {"type": "string", "description": "Free-form description of the task to find a skill for."},
-          "limit": {"type": "integer", "minimum": 1, "default": 5, "description": "Maximum number of skills to return. Defaults to 5."}
+          "paths": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Repo-relative paths to lint (files or directories). Empty or missing → full tree scan via gather_all_candidate_files."
+          }
         },
-        "required": ["task"],
         "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": true
       }
     },
     {
-      "name": "mine_session",
-      "description": "Extract reusable patterns, decisions, and learnings from a single chat-history session, as candidate memory entries. Use to distill a finished session into durable memory before it ages out. Read-only. Returns the mined candidates grouped by kind.",
+      "name": "list_commands",
+      "description": "Enumerate every slash command the server currently exposes as a prompt, each with its name and description. Use to discover available commands before routing a user request to one. Read-only manifest view, takes no arguments. Returns a `count` plus a `commands` array.",
       "side_effect": "ro",
-      "implemented_on": [],
+      "implemented_on": [
+        "stdio"
+      ],
       "input_schema": {
         "type": "object",
-        "properties": {
-          "session": {"type": "string", "description": "Session id to mine."},
-          "path": {"type": "string", "description": "Optional path to a chat-history JSONL; defaults to the standard location."}
-        },
+        "properties": {},
         "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": true
       }
     },
     {
-      "name": "update_form_request_messages",
-      "description": "Synchronise the `messages()` method of a Laravel FormRequest class: add entries for validation rules that lack a custom message, link them to translation keys, and drop stale ones. Use after changing a FormRequest's `rules()`. Edits the class file on disk and returns the planned or applied message changes. Set `dry_run: true` to preview the diff without writing.",
-      "side_effect": "fs-write",
-      "implemented_on": [],
+      "name": "list_rules",
+      "description": "Enumerate every behavioral rule the server exposes as a resource, each with its URI, name, and description. Use to discover which rules are in effect, then fetch a body with `read_resource_body` or `resources/read`. Read-only manifest view, takes no arguments. Returns a `count` plus a `rules` array.",
+      "side_effect": "ro",
+      "implemented_on": [
+        "stdio"
+      ],
       "input_schema": {
         "type": "object",
-        "properties": {
-          "request_class": {"type": "string", "description": "Fully-qualified FormRequest class FQN or repo-relative file path."},
-          "dry_run": {"type": "boolean", "default": false, "description": "When true, return the planned message changes without editing the file."}
-        },
-        "required": ["request_class"],
+        "properties": {},
         "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": true
       }
     },
     {
-      "name": "sync_gitignore",
-      "description": "Synchronise the managed `event4u/agent-config` block in the consumer project's `.gitignore` — add missing canonical entries while preserving user-added lines. Use after upgrading the package or when generated paths are being tracked by mistake. Edits `.gitignore` and returns the added / removed entries. Set `dry_run: true` to preview the changes.",
-      "side_effect": "fs-write",
-      "implemented_on": [],
+      "name": "list_skills",
+      "description": "Enumerate every skill the server currently exposes as a prompt, each with its name, description, and source. Use to discover which skills are available before suggesting or invoking one. Read-only manifest view, takes no arguments. Returns a `count` plus a `skills` array.",
+      "side_effect": "ro",
+      "implemented_on": [
+        "stdio"
+      ],
       "input_schema": {
         "type": "object",
-        "properties": {
-          "dry_run": {"type": "boolean", "default": false, "description": "When true, return the planned `.gitignore` changes without writing the file."}
-        },
+        "properties": {},
         "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": true
       }
     },
     {
-      "name": "sync_agent_settings",
-      "description": "Synchronise `.agent-settings.yml` against the current template and active profile — add new sections and keys while preserving existing user values. Use after a package upgrade to pick up newly introduced settings. Edits the settings file and returns the keys that were (or would be) added. Set `dry_run: true` to preview.",
-      "side_effect": "fs-write",
-      "implemented_on": [],
+      "name": "memory_get",
+      "description": "Batch-fetch FULL memory entries by id — the second half of the index-first retrieval workflow. Call memory_lookup with detail:\"index\" first, pick the ids whose title/tokens_estimate justify the fetch, then fetch them here in ONE batched call. Unknown ids are reported per-id (ids[<id>]=\"unknown\"), never failing the batch. Read-only.",
+      "side_effect": "ro",
+      "implemented_on": [
+        "stdio"
+      ],
       "input_schema": {
         "type": "object",
         "properties": {
-          "profile": {"type": "string", "description": "Override the profile pinned in the settings file."},
-          "dry_run": {"type": "boolean", "default": false, "description": "When true, return the planned settings changes without writing the file."}
+          "ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "minItems": 1,
+            "description": "Entry ids to fetch (from a detail:\"index\" lookup)."
+          }
         },
+        "required": [
+          "ids"
+        ],
         "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": true
       }
     },
     {
-      "name": "run_tests",
-      "description": "Run the consumer project's vitest test suite under a compiled safety envelope: fixed argv (no shell interpolation), 120s timeout, 64KB output cap per stream. Shell-exec pilot per the 2026-07-07 council cut — vitest projects only; other runners (Pest / PHPUnit, pytest, Jest) return an error until a future council round approves them. Pass `filter` (vitest --testNamePattern) or `path` (in-tree file or directory) to narrow the run. Returns runner, passed, exit_code, timed_out, truncated stdout/stderr, and duration_ms.",
-      "side_effect": "shell",
-      "implemented_on": ["stdio"],
+      "name": "memory_lookup",
+      "description": "Retrieve engineering-memory entries for one or more memory types, optionally narrowed to specific anchor paths. Use before editing a security-sensitive or historically buggy file to surface prior incidents, ownership, and patterns tied to it. WORKFLOW: call with detail:\"index\" FIRST — each row carries id, title and tokens_estimate (the cost of fetching it) — then fetch full bodies via memory_get ONLY for the ids you will actually use, batching multiple ids into one call. Reads `agents/memory/<type>/*.yml` plus the `agents/memory/intake/*.jsonl` signal log. Read-only. Returns the v1 retrieval envelope: a `status` field plus per-type `slices` carrying the matched entries.",
+      "side_effect": "ro",
+      "implemented_on": [
+        "stdio"
+      ],
       "input_schema": {
         "type": "object",
         "properties": {
-          "filter": {"type": "string", "description": "Restrict to tests matching this name pattern."},
-          "path": {"type": "string", "description": "Restrict to tests under this directory."}
+          "types": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "minItems": 1,
+            "description": "Memory types to scan, e.g. `historical-patterns`, `incident-learnings`, `ownership`. At least one required."
+          },
+          "keys": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Optional anchor paths or globs to match entries against (e.g. a file you are about to edit)."
+          },
+          "limit": {
+            "type": "integer",
+            "minimum": 1,
+            "default": 5,
+            "description": "Maximum entries to return per type. Defaults to 5."
+          },
+          "detail": {
+            "type": "string",
+            "enum": [
+              "index",
+              "full"
+            ],
+            "default": "full",
+            "description": "'index' returns compact priced rows (id, title, tokens_estimate) instead of full bodies — call this first, then memory_get the ids you need. 'full' (default) returns complete entries."
+          },
+          "token_budget": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "Optional token budget. When set, entries are rendered as one-line compact rows (id, type, confidence, `line`) and the row set is hard-cut at token_budget × 4 chars; omitted hits appear as a top-level `truncation` hint naming a concrete next step. Absent → the envelope is unchanged."
+          }
         },
+        "required": [
+          "types"
+        ],
         "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": true
       }
     },
     {
-      "name": "run_quality_checks",
-      "description": "Run the consumer project's configured quality gate (PHPStan / Rector / ECS or the stack equivalent) and return a structured per-tool result. Use before committing to confirm static-analysis and style gates pass. Shell-bound. Pass `tool` to run a single gate; omit to run all.",
-      "side_effect": "shell",
-      "implemented_on": [],
+      "name": "memory_signal",
+      "description": "Record an engineering-memory signal — a short, anchored observation such as a recurring bug pattern or an ownership note — to the monthly intake log `agents/memory/intake/signals-YYYY-MM.jsonl`. Use to capture a learning tied to a specific file so future `memory_lookup` calls surface it. Appends to the filesystem and is rate-limited per `(type, path)` within a rolling window. Returns the recorded signal.",
+      "side_effect": "fs-write",
+      "implemented_on": [
+        "stdio"
+      ],
       "input_schema": {
         "type": "object",
         "properties": {
-          "tool": {"type": "string", "description": "Restrict to a single quality tool by name (e.g. phpstan, rector, ecs)."}
+          "type": {
+            "type": "string",
+            "description": "Memory type the signal belongs to (e.g. historical-patterns, incident-learnings, ownership)."
+          },
+          "path": {
+            "type": "string",
+            "description": "Repo-relative anchor path the signal is about."
+          },
+          "body": {
+            "type": "string",
+            "description": "Free-form signal body — the observation to record."
+          }
         },
+        "required": [
+          "type",
+          "path",
+          "body"
+        ],
         "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": false
       }
     },
     {
-      "name": "list_skills",
-      "description": "Enumerate every skill the server currently exposes as a prompt, each with its name, description, and source. Use to discover which skills are available before suggesting or invoking one. Read-only manifest view, takes no arguments. Returns a `count` plus a `skills` array.",
-      "side_effect": "ro",
-      "implemented_on": ["stdio"],
-      "input_schema": {"type": "object", "properties": {}, "additionalProperties": false}
-    },
-    {
-      "name": "list_commands",
-      "description": "Enumerate every slash command the server currently exposes as a prompt, each with its name and description. Use to discover available commands before routing a user request to one. Read-only manifest view, takes no arguments. Returns a `count` plus a `commands` array.",
+      "name": "memory_status",
+      "description": "Report the memory backend status. Memory is entirely file-backed (`agents/memory/`); there is no external backend. Read-only, takes no arguments. Returns a `status` (`file`), the active `backend` (`file`), and a short `reason`.",
       "side_effect": "ro",
-      "implemented_on": ["stdio"],
-      "input_schema": {"type": "object", "properties": {}, "additionalProperties": false}
+      "implemented_on": [
+        "stdio"
+      ],
+      "input_schema": {
+        "type": "object",
+        "properties": {},
+        "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": true
+      }
     },
     {
-      "name": "list_rules",
-      "description": "Enumerate every behavioral rule the server exposes as a resource, each with its URI, name, and description. Use to discover which rules are in effect, then fetch a body with `read_resource_body` or `resources/read`. Read-only manifest view, takes no arguments. Returns a `count` plus a `rules` array.",
+      "name": "mine_session",
+      "description": "[stub — implemented on demand] Extract reusable patterns, decisions, and learnings from a single chat-history session, as candidate memory entries. Use to distill a finished session into durable memory before it ages out. Read-only. Returns the mined candidates grouped by kind.",
       "side_effect": "ro",
-      "implemented_on": ["stdio"],
-      "input_schema": {"type": "object", "properties": {}, "additionalProperties": false}
-    },
-    {
-      "name": "compile_router",
-      "description": "Regenerate the compiled router (`router.compiled.json`) from the current rule, skill, and command frontmatter, so trigger-based routing reflects the latest artifacts. Use after adding or editing a rule / skill / command's trigger metadata. Shell-bound — wraps `scripts/compile_router.py` — and returns the regenerated router summary. Set `dry_run: true` to compute the result without writing the file.",
-      "side_effect": "shell",
       "implemented_on": [],
       "input_schema": {
         "type": "object",
         "properties": {
-          "dry_run": {"type": "boolean", "default": false, "description": "When true, compute the router without writing `router.compiled.json` to disk."}
+          "session": {
+            "type": "string",
+            "description": "Session id to mine."
+          },
+          "path": {
+            "type": "string",
+            "description": "Optional path to a chat-history JSONL; defaults to the standard location."
+          }
         },
         "additionalProperties": false
       }
@@ -281,134 +521,264 @@
       "name": "read_resource_body",
       "description": "Fetch the rendered body of a single resource URI (rule, guideline, or context document) in one call, without the two-step `resources/list` + `resources/read` handshake. Use when you already know the URI and want to inline its content into a tool-call result. Read-only. Returns the resource `uri`, `name`, `description`, and full text `body`.",
       "side_effect": "ro",
-      "implemented_on": ["stdio"],
+      "implemented_on": [
+        "stdio"
+      ],
       "input_schema": {
         "type": "object",
         "properties": {
-          "uri": {"type": "string", "description": "Resource URI to fetch, e.g. `rule://commit-policy`, `guideline://php/patterns/events`, or `context://authority/scope-mechanics`."}
+          "uri": {
+            "type": "string",
+            "description": "Resource URI to fetch, e.g. `rule://commit-policy`, `guideline://php/patterns/events`, or `context://authority/scope-mechanics`."
+          }
         },
-        "required": ["uri"],
+        "required": [
+          "uri"
+        ],
+        "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": true
+      }
+    },
+    {
+      "name": "roadmap_archive",
+      "description": "Archive every roadmap that has reached `count_open == 0` and was touched on the current branch — `git mv` to `agents/roadmaps/archive/`, migrate inbound references, and regenerate the dashboard. Use as the PR-gate sweep before opening a pull request. Mutates the git index (moves tracked files) but never commits or pushes.",
+      "side_effect": "fs-write",
+      "implemented_on": [
+        "stdio"
+      ],
+      "input_schema": {
+        "type": "object",
+        "properties": {},
         "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": false
       }
     },
     {
       "name": "roadmap_progress",
       "description": "Regenerate `agents/roadmaps-progress.md` from the current checkbox state of every active roadmap. Use after landing roadmap work to keep the dashboard in sync without a shell round-trip. Writes the dashboard file inside the project tree. Set `dry_run: true` to compute counts without writing.",
       "side_effect": "fs-write",
-      "implemented_on": ["stdio"],
+      "implemented_on": [
+        "stdio"
+      ],
       "input_schema": {
         "type": "object",
         "properties": {
-          "dry_run": {"type": "boolean", "default": false, "description": "When true, return the computed dashboard without writing the file."}
+          "dry_run": {
+            "type": "boolean",
+            "default": false,
+            "description": "When true, return the computed dashboard without writing the file."
+          }
         },
         "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": false
       }
     },
     {
-      "name": "roadmap_archive",
-      "description": "Archive every roadmap that has reached `count_open == 0` and was touched on the current branch — `git mv` to `agents/roadmaps/archive/`, migrate inbound references, and regenerate the dashboard. Use as the PR-gate sweep before opening a pull request. Mutates the git index (moves tracked files) but never commits or pushes.",
-      "side_effect": "fs-write",
-      "implemented_on": ["stdio"],
-      "input_schema": {"type": "object", "properties": {}, "additionalProperties": false}
+      "name": "run_quality_checks",
+      "description": "[stub — implemented on demand] Run the consumer project's configured quality gate (PHPStan / Rector / ECS or the stack equivalent) and return a structured per-tool result. Use before committing to confirm static-analysis and style gates pass. Shell-bound. Pass `tool` to run a single gate; omit to run all.",
+      "side_effect": "shell",
+      "implemented_on": [],
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "tool": {
+            "type": "string",
+            "description": "Restrict to a single quality tool by name (e.g. phpstan, rector, ecs)."
+          }
+        },
+        "additionalProperties": false
+      }
     },
     {
-      "name": "capabilities_index",
-      "description": "Regenerate `CAPABILITIES.yaml`, the package's coverage index of skills, rules, commands, and guidelines. Use after adding or removing an artifact to keep the index current. Pass `check: true` to run in read-only CI mode (fails instead of writing on drift).",
-      "side_effect": "fs-write",
-      "implemented_on": ["stdio"],
+      "name": "run_tests",
+      "description": "Run the consumer project's vitest test suite under a compiled safety envelope: fixed argv (no shell interpolation), 120s timeout, 64KB output cap per stream. Shell-exec pilot per the 2026-07-07 council cut — vitest projects only; other runners (Pest / PHPUnit, pytest, Jest) return an error until a future council round approves them. Pass `filter` (vitest --testNamePattern) or `path` (in-tree file or directory) to narrow the run. Returns runner, passed, exit_code, timed_out, truncated stdout/stderr, and duration_ms.",
+      "side_effect": "shell",
+      "implemented_on": [
+        "stdio"
+      ],
       "input_schema": {
         "type": "object",
         "properties": {
-          "check": {"type": "boolean", "default": false, "description": "When true, run in read-only drift-check mode instead of writing the index."}
+          "filter": {
+            "type": "string",
+            "description": "Restrict to tests matching this name pattern."
+          },
+          "path": {
+            "type": "string",
+            "description": "Restrict to tests under this directory."
+          }
         },
         "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": false
       }
     },
     {
-      "name": "doctor_report",
-      "description": "Run the consumer-project doctor diagnostic and return a structured health report (install drift, hook wiring, settings schema, discovery manifest freshness). Use to triage a misbehaving install. Read-only.",
+      "name": "skill_trigger_eval",
+      "description": "[stub — implemented on demand] Score a user message against the compiled router and return the skills whose triggers match, each with the reason it fired. Use to predict which skills a given message would activate, for debugging trigger coverage. Read-only and deterministic. Returns a ranked list of matching skills with their trigger reasons.",
       "side_effect": "ro",
-      "implemented_on": ["stdio"],
-      "input_schema": {"type": "object", "properties": {}, "additionalProperties": false}
+      "implemented_on": [],
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "message": {
+            "type": "string",
+            "description": "The user message to score against skill triggers."
+          },
+          "context": {
+            "type": "string",
+            "description": "Optional recent-turn context to sharpen the match."
+          },
+          "limit": {
+            "type": "integer",
+            "minimum": 1,
+            "default": 5,
+            "description": "Maximum number of matching skills to return. Defaults to 5."
+          }
+        },
+        "required": [
+          "message"
+        ],
+        "additionalProperties": false
+      }
     },
     {
-      "name": "conformance_check",
-      "description": "Run the consumer conformance contract (`doctor --ci` plus installed-and-firing checks) and return pass/fail per check. Use to verify a consumer project's install is fully wired before relying on it. Read-only.",
+      "name": "suggest_command",
+      "description": "[stub — implemented on demand] Run the command-suggestion engine: score the available slash commands against a user message and context, and return a ranked, numbered-options block of the best matches. Use to recommend a command for a free-form request without invoking anything. Read-only and deterministic. Returns the formatted suggestion block plus the scored candidates.",
       "side_effect": "ro",
-      "implemented_on": ["stdio"],
-      "input_schema": {"type": "object", "properties": {}, "additionalProperties": false}
+      "implemented_on": [],
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "message": {
+            "type": "string",
+            "description": "The user message to match commands against."
+          },
+          "context": {
+            "type": "string",
+            "description": "Optional recent-turn context to sharpen the match."
+          }
+        },
+        "required": [
+          "message"
+        ],
+        "additionalProperties": false
+      }
     },
     {
-      "name": "telemetry_report",
-      "description": "Return the artefact-engagement telemetry report — essential / useful / retirement-candidate skills and rules ranked by recorded consult+apply signals over a rolling window. Use to see which artifacts are actually load-bearing. Read-only. No-op (empty report) when telemetry recording is disabled.",
+      "name": "suggest_skill_for_task",
+      "description": "[stub — implemented on demand] Match a free-form task description to the most relevant skills, ranked by their frontmatter triggers. Use to pick a skill for a described task before starting work. Read-only. Returns a ranked list of skills with name, description, and match reason.",
       "side_effect": "ro",
-      "implemented_on": ["stdio"],
+      "implemented_on": [],
       "input_schema": {
         "type": "object",
         "properties": {
-          "window_days": {"type": "integer", "minimum": 1, "default": 30, "description": "Reporting window in days. Defaults to 30."}
+          "task": {
+            "type": "string",
+            "description": "Free-form description of the task to find a skill for."
+          },
+          "limit": {
+            "type": "integer",
+            "minimum": 1,
+            "default": 5,
+            "description": "Maximum number of skills to return. Defaults to 5."
+          }
         },
+        "required": [
+          "task"
+        ],
         "additionalProperties": false
       }
     },
     {
-      "name": "catalog_search",
-      "description": "Search the package's own artifact catalog (skills, personas, commands) by free-text query and return ranked summaries — name, description, tags, score — WITHOUT loading any body. Use to discover which skill or persona fits a task when the full catalog is not in context. Read-only, deterministic (BM25 over an on-disk index). DISCOVERY STUB — the real handler ships behind a task-quality A/B before activation (see road-to-persona-library-harvest.md Phase 2); until then this returns the not_implemented envelope.",
-      "side_effect": "ro",
+      "name": "sync_agent_settings",
+      "description": "[stub — implemented on demand] Synchronise `.agent-settings.yml` against the current template and active profile — add new sections and keys while preserving existing user values. Use after a package upgrade to pick up newly introduced settings. Edits the settings file and returns the keys that were (or would be) added. Set `dry_run: true` to preview.",
+      "side_effect": "fs-write",
       "implemented_on": [],
       "input_schema": {
         "type": "object",
         "properties": {
-          "query": {"type": "string", "description": "Free-text search query."},
-          "class": {"type": "string", "enum": ["skill", "persona", "command"], "description": "Optional: restrict to one artifact class."},
-          "pack": {"type": "string", "description": "Optional: restrict to entries tagged with this pack/domain."},
-          "limit": {"type": "integer", "minimum": 1, "default": 8, "description": "Maximum results. Defaults to 8."}
+          "profile": {
+            "type": "string",
+            "description": "Override the profile pinned in the settings file."
+          },
+          "dry_run": {
+            "type": "boolean",
+            "default": false,
+            "description": "When true, return the planned settings changes without writing the file."
+          }
         },
-        "required": ["query"],
         "additionalProperties": false
       }
     },
     {
-      "name": "catalog_inspect",
-      "description": "Return the metadata for one catalog entry by id (id, class, name, description, tags, path). Body is returned ONLY when include_body is true. Use after catalog_search to look at a candidate before loading it. Read-only. DISCOVERY STUB — real handler activation deferred (see catalog_search).",
-      "side_effect": "ro",
+      "name": "sync_gitignore",
+      "description": "[stub — implemented on demand] Synchronise the managed `event4u/agent-config` block in the consumer project's `.gitignore` — add missing canonical entries while preserving user-added lines. Use after upgrading the package or when generated paths are being tracked by mistake. Edits `.gitignore` and returns the added / removed entries. Set `dry_run: true` to preview the changes.",
+      "side_effect": "fs-write",
       "implemented_on": [],
       "input_schema": {
         "type": "object",
         "properties": {
-          "id": {"type": "string", "description": "Catalog id, e.g. `skill:api-design` or `persona:backend-architect`."},
-          "include_body": {"type": "boolean", "default": false, "description": "When true, include the full body. Defaults to false (metadata only)."}
+          "dry_run": {
+            "type": "boolean",
+            "default": false,
+            "description": "When true, return the planned `.gitignore` changes without writing the file."
+          }
         },
-        "required": ["id"],
         "additionalProperties": false
       }
     },
     {
-      "name": "catalog_load",
-      "description": "Load the full body of one catalog entry by id, wrapped in a neutral reference preamble that subordinates it to the user's request and system instructions. Use to bring a skill/persona/command body into context on demand. Read-only, path-confined to the package root. Never injects or acts — the host decides what to do with the body. DISCOVERY STUB — real handler activation deferred (see catalog_search).",
+      "name": "telemetry_report",
+      "description": "Return the artefact-engagement telemetry report — essential / useful / retirement-candidate skills and rules ranked by recorded consult+apply signals over a rolling window. Use to see which artifacts are actually load-bearing. Read-only. No-op (empty report) when telemetry recording is disabled.",
       "side_effect": "ro",
-      "implemented_on": [],
+      "implemented_on": [
+        "stdio"
+      ],
       "input_schema": {
         "type": "object",
         "properties": {
-          "id": {"type": "string", "description": "Catalog id to load the body for."}
+          "window_days": {
+            "type": "integer",
+            "minimum": 1,
+            "default": 30,
+            "description": "Reporting window in days. Defaults to 30."
+          }
         },
-        "required": ["id"],
         "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": true
       }
     },
     {
-      "name": "council_estimate",
-      "description": "Estimate the token cost of an AI-council debate over a given input (roadmap, diff, prompt, or file set) without spending — no network call, no billing. Use before deciding whether to authorize a real council run. Read-only.",
-      "side_effect": "ro",
-      "implemented_on": ["stdio"],
+      "name": "update_form_request_messages",
+      "description": "[stub — implemented on demand] Synchronise the `messages()` method of a Laravel FormRequest class: add entries for validation rules that lack a custom message, link them to translation keys, and drop stale ones. Use after changing a FormRequest's `rules()`. Edits the class file on disk and returns the planned or applied message changes. Set `dry_run: true` to preview the diff without writing.",
+      "side_effect": "fs-write",
+      "implemented_on": [],
       "input_schema": {
         "type": "object",
         "properties": {
-          "input_path": {"type": "string", "description": "Path to the roadmap, diff, or file to estimate council cost for."},
-          "depth": {"type": "string", "enum": ["shallow", "deep"], "description": "Council depth tier to estimate for. Defaults to the configured default depth."}
+          "request_class": {
+            "type": "string",
+            "description": "Fully-qualified FormRequest class FQN or repo-relative file path."
+          },
+          "dry_run": {
+            "type": "boolean",
+            "default": false,
+            "description": "When true, return the planned message changes without editing the file."
+          }
         },
-        "required": ["input_path"],
+        "required": [
+          "request_class"
+        ],
         "additionalProperties": false
       }
     }