docs(api-surfaces): document missing MCP tools (write, evolve, insights, tune)

docs/api-surfaces.md

@@ -22,15 +22,17 @@ when to add or move an operation.
 | Concern | Owner | Reason |
 |---------|-------|--------|
 | Memory CRUD (write/recall/list/get/update/delete/transition) | REST + MCP | Universal; needed by every audience. |
-| Bulk write | REST + MCP | Same. |
-| Per-agent search profile (tune) | REST + MCP | Both administrators (REST) and agents tuning themselves (MCP) need it. |
+| Bulk write | REST + MCP (`memclaw_write` with `items`) | Same. |
+| Per-agent search profile (tune) | REST + MCP (`memclaw_tune`) | Both administrators (REST) and agents tuning themselves (MCP) need it. |
 | Doc CRUD | REST + MCP | Universal. |
 | Doc semantic search | MCP **and** REST | Was MCP-only; REST endpoint added so non-MCP clients can use vector search on documents. |
 | Doc list-collections | MCP **and** REST | Was MCP-only; REST endpoint added for parity with list use cases. |
 | Bulk delete | REST + MCP (`memclaw_manage op=bulk_delete`) | Admin sometimes; agents cleaning up after themselves sometimes. |
 | Memory lineage walk | REST + MCP (`memclaw_manage op=lineage`) | Agents reviewing their own writes need to trace supersession chains. |
 | Knowledge graph / `/graph` | REST only | Aggregation surface for UIs and analytics tools. Agents that need entity context use `memclaw_entity_get` (single entity) and `memclaw_recall` (with entity_links in results). |
 | Memory stats | REST + MCP (`memclaw_stats`) | Aggregate counts (total + breakdown by type, agent, status; opt-in `include_deleted=true` adds `deleted` and `total_including_deleted`) — useful for admin/dashboard usage on REST and for agent self-introspection on MCP. Read-only aggregations don't need a use-case gate. |
+| Outcome reporting / weight reinforcement | REST (`/evolve/report`) + MCP (`memclaw_evolve`) | Karpathy Loop feedback edge — agents report real-world outcomes (`success\|failure\|partial`) against the memories that influenced an action, adjusting weights and generating preventive rules on failure. `scope=agent` at trust ≥ 1; `fleet`/`all` at trust ≥ 2. |
+| Reflection / insights | REST (`/insights/generate`) + MCP (`memclaw_insights`) | Karpathy Loop reflection step — LLM analysis over targeted memory subsets (`contradictions\|failures\|stale\|divergence\|patterns\|discover`); findings persist as `insight` memories that compound across sessions. `scope=agent` at trust ≥ 1; `fleet`/`all` at trust ≥ 2. |
 | Skill sharing | REST (`/documents` + `/documents/search` on `collection="skills"`) + MCP (`memclaw_doc op=write\|read\|query\|delete\|search collection=skills`) | Skill sharing rides the generic document surface. Slugs (`doc_id`) are constrained to `^[a-z0-9][a-z0-9._-]{0,99}$` (filesystem-safe), and skills writes require `data["summary"]` (with back-compat fallback to `data["description"]`) so the catalog is semantic-searchable without ceremony. The dedicated `memclaw_share_skill`/`memclaw_unshare_skill` tools and `/skills/*` REST routes were dropped 2026-05; fleet auto-install (push to every node) is restored by Phase A's plugin-side reconciler. Trust ≥ 1 (inherited from `memclaw_doc`). |
 | Keystones (mandatory rules) | REST (`/memclaw/keystones`) + MCP (`memclaw_keystones` read, `memclaw_keystones_set` set\|delete) | Governance policies that agents MUST obey — fetched deterministically (no semantic search) and injected into every session by the OpenClaw plugin. Storage lives in the system-managed `_keystones` collection on `documents`; the dedicated surface exists so the read tool stays discoverable in MCP `instructions` and the write surface can be trust-gated separately. Reads are open. Writes are tiered: a freshly-registered (trust ≥ 1) agent can author its own `scope=agent` rule — self-authored autonomy — but `scope=fleet`, `scope=tenant`, and cross-agent `scope=agent` stay at trust ≥ 2 so a default-trust agent (or a prompt-injected one) can't plant a tenant-wide rule. |
 | Tenant settings | REST only | Settings are a tenant-administrator concern; not safe for arbitrary agents to flip global config. |
@@ -40,6 +42,32 @@ when to add or move an operation.
 | Heartbeat / fleet readiness | REST receives, plugin produces | Plugin is the natural producer (it knows the local node state). REST is the receiver. MCP doesn't need this — agents don't report their own runtime state. |
 | Agent registration | OpenClaw plugin | Local-runtime concern. |
 
+## MCP tool surface
+
+The MCP surface registers **12 agent-facing tools**. The source of truth is the
+`ToolSpec` declarations in `core-api/src/core_api/tools/*.py`, wired to the
+handlers in `core-api/src/core_api/mcp_server.py`. Every registered tool is
+listed below with the surfaces it is reachable on, the minimum trust it
+requires, and a one-line contract. "Trust required" is the baseline to invoke;
+op- and scope-specific floors are noted inline and enforced server-side. Tools
+exposed by the OpenClaw plugin (`plugin_exposed=True`) list `plugin` as a
+transport; `memclaw_keystones_set` is intentionally not plugin-exposed.
+
+| Tool | Transport(s) | Trust required | Contract |
+|------|--------------|----------------|----------|
+| `memclaw_recall` | MCP, REST, plugin | 0 | Hybrid semantic+keyword memory search; `include_brief=true` adds an LLM-synthesized summary. |
+| `memclaw_write` | MCP, REST, plugin | 0 (requires the `write` capability) | Store new memories — exactly one of `{content, items}` (batch ≤ 100); auto-classifies type, title, tags, and dates. |
+| `memclaw_manage` | MCP, REST, plugin | 0; `delete`/`bulk_delete` need ≥ 3 | Per-memory lifecycle: `read \| update \| transition \| delete \| bulk_delete \| lineage`. |
+| `memclaw_list` | MCP, REST, plugin | ≥ 1 (`agent`); ≥ 2 (`fleet`/`all`); 3 unlocks `include_deleted` | Non-semantic enumeration — filter, sort, and paginate memories by metadata. |
+| `memclaw_stats` | MCP, REST, plugin | ≥ 1 (`agent`); ≥ 2 (`fleet`/`all`) | Read-only aggregate counts: total plus breakdowns by type, agent, and status. |
+| `memclaw_entity_get` | MCP, REST, plugin | 0 | Look up a single entity by UUID (use an `entity_id` returned by a prior search). |
+| `memclaw_tune` | MCP, REST, plugin | 0 (requires the `write` capability) | Persist the caller's recall profile (top_k, min_similarity, fts_weight, freshness, graph hops); no fields → returns the current profile. |
+| `memclaw_doc` | MCP, REST, plugin | 0; `write`/`delete` need the `write` capability | Structured-document CRUD over named collections: `write \| read \| query \| delete \| list_collections \| search`. |
+| `memclaw_evolve` | MCP, REST, plugin | ≥ 1 (`agent`); ≥ 2 (`fleet`/`all`) | Report an outcome (`success \| failure \| partial`) against the memories that influenced an action: reinforce weights, generate preventive rules on failure. Closes the Karpathy Loop feedback edge. |
+| `memclaw_insights` | MCP, REST, plugin | ≥ 1 (`agent`); ≥ 2 (`fleet`/`all`) | Reflect over the store (`contradictions \| failures \| stale \| divergence \| patterns \| discover`) and persist findings as `insight` memories. The Karpathy Loop reflection step. |
+| `memclaw_keystones` | MCP, REST, plugin | 0 | Read the scope-merged set of mandatory keystone rules (deterministic; no semantic search). |
+| `memclaw_keystones_set` | MCP, REST | ≥ 1 (self-author `scope=agent`); ≥ 2 (`fleet`/`tenant`/cross-agent) | Author or remove keystone rules: `set \| delete`. Not plugin-exposed — governance authoring stays off the local runtime. |
+
 ## When to add an operation
 
 Before adding a new MCP tool that mirrors a REST endpoint, justify it with a