feat: PicoClaw compose profile exposes brain MCP on localhost (#23)

Agent is not shipped. docker compose --profile picoclaw up brain-mcp
and point the client at 127.0.0.1:8630/mcp.

AGENTS.md

@@ -15,6 +15,9 @@ Read first: [PLAN](PLAN.md) → [docs](docs/).
 - `info` root = descriptive/narrative leafs, searchable, never asserted as fact.
 - Search is deduction: `facts` → `info` → `web-search` (second independent
   source). An answer is `confirmed` only if it comes off the facts root.
+- Fact-check every *claim* (facts → info → live → web), not every edit or
+  syntax tweak. PicoClaw: `search` then `get` then `audit` before a factual
+  reply (`skills/picoclaw/SKILL.md`). `throttled` is not a negative finding.
 
 ## Hard rules
 
@@ -77,14 +80,15 @@ bin/brain/index.go --rebuild                                            # rebuil
 ## Tools
 
 ```bash
-bin/facts/audit ["self"|"facts"|"info"|"stale"]   # 2-source + staleness gate
+bin/facts/audit.go ["self"|"facts"|"info"|"stale"]  # 2-source + staleness gate
-bin/facts/crm [--dry-run]                         # proof person↔company/company↔project (ooCRM × corpus SoT)
+bin/facts/crm.go [--dry-run]                       # proof person↔company/company↔project (ooCRM × corpus SoT)
 bin/kb/search "query" [--repo X]                  # deprecated wrapper → bin/brain/search.go
 bin/brain/search.go "query" [--root facts|info]   # deduction search → YAML
 bin/brain/search.go "query" --no-web              # local graph only
 bin/brain/get.go <id> [--body] [--json]          # Go read; Python bin/kb/get CI fallback
 bin/brain/stats.go [--json]
 bin/brain/eval.go [--json]                       # recall@5; questions in internal/brain/rank
+bin/brain/serve.go                               # HTTP :8630; GET /openapi.json POST /mcp
 bin/markdown/import.go [dir]                      # mistune leaves → YAML
 bin/git/import.go [REPO] [--json] [--limit N]     # go-git history → commit leafs
 bin/web/search.go "query" [--json]                # SearXNG; throttled ≠ absence

PLAN.md

@@ -43,6 +43,7 @@ detective method: **a fact needs ≥2 independent sources or it is
 | D17 | assertion gate | Fact-check every *claim* (facts → info → live → web), not every edit. `bin/brain/search.go` adds a `web` block when there is no facts hit (`throttled`/`skipped`/`refused` ≠ absence). `--root` and `--no-web` stay local. Missing graph ≠ “does not exist”. |
 | D18 | reasoner | Pluggable OpenAI-compatible URL. RAM: Qwen3.5-9B. Quality: Bonsai-27B or Qwen3.6-27B. No official Qwen3.6-9B. |
 | D19 | git history | [go-git](https://github.com/go-git/go-git) via `bin/git/import.go`. No subprocess of the git binary. Conversion prints commit leafs; brain write is `bin/brain/index.go`. |
+| D20 | agent API | OpenAPI + MCP are generated from the same `internal/httpapi.Ops` table as `bin/brain/serve.go` handlers. `GET /openapi.json`, `POST /mcp` (JSON-RPC tools/list + tools/call). Tool names match OpenAPI paths (`search`/`get`/`stats`/`audit`). |
 
 ## Architecture
 
@@ -50,16 +51,15 @@ detective method: **a fact needs ≥2 independent sources or it is
 2dph/
   PLAN.md / AGENTS.md
   docs/                     published docs (this conversation → docs/ as md)
-  skills/                   in-project skills (web-search, db-yaml, brain, diataxis-docs)
+  skills/                   in-project skills (web-search, postgres, brain, picoclaw, diataxis-docs)
   bin/
-    facts/extract           auto-pair 2 sources → lexicon yaml + graph
+    facts/extract.go audit.go crm.go  # D14 shebang; Python implementation
-    facts/audit             ["self"|"facts"|"info"|"stale"] 2-source + staleness gate
     kb/index                Python write path (called by bin/brain/index.go)
     brain/index.go          rebuild FTS + HNSW (incl. --with-mail)
     brain/get.go stats.go eval.go  # Go read (cgo); Python bin/kb/* CI fallback
     brain/watch.go
     brain/search.go         deduction: facts → info → web-search
-    brain/serve.go          HTTP API in-process (internal/httpapi + internal/brain)
+    brain/serve.go          HTTP API in-process + OpenAPI/MCP (D20); compose profile picoclaw
     mail/import.go          JSON → markdown (no brain write)
     markdown/import.go      mistune leaves
     postgres/query.go       read-only YAML (wraps bin/db/psql-yq)
@@ -133,7 +133,7 @@ Common props on every node/edge: `root`, `confidence`, `evidence[]`, `how`,
 1. go vet + go test ./... (root module; packages without ladybug cgo)
 2. `go test ./internal/brain/rank` (cgo-free ranking + flag parser)
 3. python -m unittest discover -s bin/tools (includes published-docs SoT)
-4. bin/facts/audit self  (lexicon internal consistency)
+4. `bin/facts/audit self` (lexicon internal consistency; `bin/facts/audit.go` is the D14 wrapper)
 5. `bin/kb/eval` (recall@5 ≥ 0.95). Local SoT is `bin/brain/eval.go`; CI uses
    the Python twin until the runner has ladybug cgo. Questions live in
    `internal/brain/rank`.
@@ -146,7 +146,7 @@ Feedback loop: every commit → PR → CI → green/gate → merge. Same discipl
 
 1. scaffold repo (:done after this file + AGENTS.md + .gitignore + ci)
 2. gh repo create eSlider/2dph --private + initial commit + CI
-3. vendored skill integration (web-search, db-yaml, brain, diataxis-docs) — no remote links
+3. vendored skill integration (web-search, postgres, brain, diataxis-docs) — no remote links
 4. .venv: ladybug + model2vec + mistune
 5. schema + tools with TDD (kb + md + facts + brain)
 6. ~/.config/brain config

README.md

@@ -28,8 +28,8 @@ graph TB
     end
 
     subgraph dph["2dph tools"]
-        EX["bin/facts/extract<br/>2-source pairing"]
+        EX["bin/facts/extract.go<br/>2-source pairing"]
-        AU["bin/facts/audit<br/>confidence + staleness"]
+        AU["bin/facts/audit.go<br/>confidence + staleness"]
         IDX["bin/brain/index.go<br/>chunk + embed"]
         MD["bin/markdown/import.go<br/>mistune leaves"]
         SR["bin/brain/search.go<br/>deduction"]
@@ -141,14 +141,14 @@ bin/brain/search.go "invoice from last week"                            # same s
 `bin/{subject}/{method}.go` — self-describing: shebang on line 1, usage comment
 from line 2. Shared code in `internal/`. YAML default output, `--json` for
 machines. Tests gate every commit. HTTP: `bin/brain/serve.go` calls
-`internal/brain` in-process (`/health` `/search` `/get` `/stats` `/audit` `/ingest`).
+`internal/brain` in-process (`/health` `/search` `/get` `/stats` `/audit` `/ingest` `/openapi.json` `/mcp`).
 
 ## Development
 
 ```bash
 uv venv .venv                                  # Python 3.12, uv-managed
 uv pip install -r requirements.lock.txt        # pinned toolchain
-bin/facts/audit self                           # lexicon consistency gate
+bin/facts/audit.go self                        # lexicon consistency gate
 go test ./... && python -m unittest discover -s bin/tools -t .
 ```
 
@@ -158,6 +158,7 @@ Docker (optional, cached model + var volumes):
 docker compose run --rm brain index            # (re)index corpus
 docker compose run --rm brain search "query"   # one-shot query
 docker compose run --rm brain serve            # bin/brain/serve.go
+docker compose --profile picoclaw up brain-mcp # MCP on 127.0.0.1:8630
 docker compose up brain-watch                  # auto re-index on change
 ```
 
@@ -166,7 +167,7 @@ docker compose up brain-watch                  # auto re-index on change
 - [go-second-brain](https://github.com/eSlider/go-second-brain) — the earlier
   Neo4j + Qdrant + Matrix RAG brain
 - [agent-skills](https://github.com/eSlider/agent-skills) — upstream
-  skills (`web-search`, `db-yaml`, …) that 2dph integrates
+  skills (`web-search`, `postgres`, …) that 2dph integrates
 - detective method — the two-source method
 
 Work board (issues): [git.produktor.io/eSlider/2dph/issues](https://git.produktor.io/eSlider/2dph/issues).

bin/brain/serve.go

@@ -6,6 +6,9 @@
 //	KB_ROOT=/path/to/2dph ./bin/brain/serve.go
 //	KB_WORKERS=4 KB_PORT=8630 ./bin/brain/serve.go
 //
+//	GET  /openapi.json  same Ops table as the handlers
+//	POST /mcp           JSON-RPC tools/list + tools/call
+//
 // Needs CGO + libladybug (same as bin/brain/search.go).
 // NOTE: never run `gofmt -w` on this file — it breaks the shebang.
 package main

bin/facts/audit.go

@@ -0,0 +1,21 @@
+//usr/bin/env go run -tags=facts_audit "$0" "$@"; exit
+//go:build facts_audit
+//
+// bin/facts/audit.go - 2-source + lexicon checks.
+//
+//	./bin/facts/audit.go self
+//	./bin/facts/audit.go db
+//
+// Python bin/facts/audit is the implementation (CI runs it directly).
+// NOTE: never run `gofmt -w` on this file — it breaks the shebang.
+package main
+
+import (
+	"os"
+
+	"github.com/eSlider/2dph/internal/cmdbin"
+)
+
+func main() {
+	os.Exit(cmdbin.ExecFile("bin/facts/audit", os.Args[1:]))
+}

bin/facts/crm.go

@@ -0,0 +1,20 @@
+//usr/bin/env go run -tags=facts_crm "$0" "$@"; exit
+//go:build facts_crm
+//
+// bin/facts/crm.go - prove person↔company / company↔project (ooCRM × corpus).
+//
+//	./bin/facts/crm.go [--dry-run] [--mismatches]
+//
+// Python bin/facts/crm is the implementation. Graph write stays Python.
+// NOTE: never run `gofmt -w` on this file — it breaks the shebang.
+package main
+
+import (
+	"os"
+
+	"github.com/eSlider/2dph/internal/cmdbin"
+)
+
+func main() {
+	os.Exit(cmdbin.ExecFile("bin/facts/crm", os.Args[1:]))
+}

bin/facts/extract.go

@@ -0,0 +1,20 @@
+//usr/bin/env go run -tags=facts_extract "$0" "$@"; exit
+//go:build facts_extract
+//
+// bin/facts/extract.go - acquire confirmed facts (2-source each).
+//
+//	./bin/facts/extract.go [--json] [--dry-run]
+//
+// Python bin/facts/extract is the implementation. Graph write stays Python.
+// NOTE: never run `gofmt -w` on this file — it breaks the shebang.
+package main
+
+import (
+	"os"
+
+	"github.com/eSlider/2dph/internal/cmdbin"
+)
+
+func main() {
+	os.Exit(cmdbin.ExecFile("bin/facts/extract", os.Args[1:]))
+}

bin/tools/test_bin_layout.py

@@ -108,6 +108,13 @@ class BinLayoutTest(unittest.TestCase):
             self.assertIn(frag, py)
         self.assertIn("0.95", rank)
 
+    def test_facts_methods_are_shebangs(self) -> None:
+        for method in ("audit.go", "extract.go", "crm.go"):
+            self._assert_shebang(f"bin/facts/{method}")
+            text = (ROOT / "bin" / "facts" / method).read_text()
+            self.assertIn("cmdbin.ExecFile", text)
+            self.assertIn(f"bin/facts/{method.removesuffix('.go')}", text)
+
     def test_mail_import_is_shebang_not_brain_write(self) -> None:
         self._assert_shebang("bin/mail/import.go")
         index_mail = (ROOT / "bin" / "mail" / "index_mail").read_text()

bin/tools/test_published_docs.py

@@ -59,6 +59,18 @@ class PublishedDocsTest(unittest.TestCase):
         self.assertNotIn("password", settings.lower())
         self.assertIn("json", settings)
 
+    def test_picoclaw_compose_profile_has_mcp_example(self) -> None:
+        compose = (ROOT / "compose.yaml").read_text()
+        self.assertIn('profiles: ["picoclaw"]', compose)
+        self.assertIn("127.0.0.1:8630", compose)
+        example = (ROOT / "deploy" / "picoclaw" / "mcp.json.example").read_text()
+        self.assertIn("127.0.0.1:8630/mcp", example)
+        self.assertNotIn("password", example.lower())
+        self.assertNotIn("token", example.lower())
+        docs = (ROOT / "docs" / "picoclaw.md").read_text()
+        self.assertIn("search", docs)
+        self.assertIn("throttled", docs)
+
     def test_readme_read_path_is_go(self) -> None:
         plan = (ROOT / "PLAN.md").read_text()
         self.assertIn("get.go", plan)
@@ -67,6 +79,16 @@ class PublishedDocsTest(unittest.TestCase):
         self.assertIn("internal/brain/rank", design)
         self.assertIn("They do not exec Python", design)
 
+    def test_openapi_mcp_from_same_handlers(self) -> None:
+        plan = (ROOT / "PLAN.md").read_text()
+        self.assertIn("D20", plan)
+        self.assertIn("/openapi.json", (ROOT / "README.md").read_text())
+        self.assertIn("/mcp", (ROOT / "README.md").read_text())
+        skill = (ROOT / "skills" / "brain" / "SKILL.md").read_text()
+        self.assertIn("/mcp", skill)
+        self.assertFalse((ROOT / "skills" / "db-yaml").exists())
+        self.assertTrue((ROOT / "skills" / "postgres" / "SKILL.md").is_file())
+
     def test_readme_search_escalates_web(self) -> None:
         text = (ROOT / "README.md").read_text()
         self.assertIn("--no-web", text)

bin/tools/test_skills.py

@@ -0,0 +1,49 @@
+"""Skills must name live commands; every bin/ path in SKILL.md must exist."""
+from __future__ import annotations
+
+import re
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+BIN_PATH = re.compile(r"(bin/[A-Za-z0-9_./-]+)")
+
+
+class SkillsTest(unittest.TestCase):
+    def test_db_yaml_renamed_to_postgres(self) -> None:
+        self.assertFalse(
+            (ROOT / "skills" / "db-yaml").exists(),
+            "skills/db-yaml must be skills/postgres",
+        )
+        self.assertTrue((ROOT / "skills" / "postgres" / "SKILL.md").is_file())
+        text = (ROOT / "skills" / "postgres" / "SKILL.md").read_text()
+        self.assertIn("bin/postgres/query.go", text)
+        self.assertNotIn("search.ops.io", text)
+
+    def test_every_bin_path_in_skills_exists(self) -> None:
+        missing: list[str] = []
+        for path in (ROOT / "skills").rglob("SKILL.md"):
+            text = path.read_text()
+            for m in BIN_PATH.finditer(text):
+                rel = m.group(1).rstrip(")`.,;")
+                candidate = ROOT / rel
+                if not candidate.exists():
+                    missing.append(f"{path.relative_to(ROOT)}: {rel}")
+        self.assertEqual(missing, [], "skill bin paths must exist")
+
+    def test_brain_skill_lists_generated_tools(self) -> None:
+        tools = (ROOT / "skills" / "brain" / "tools.md").read_text()
+        skill = (ROOT / "skills" / "brain" / "SKILL.md").read_text()
+        self.assertIn("tools.md", skill)
+        for name in ("search", "get", "stats", "audit"):
+            self.assertIn(f"`{name}`", tools)
+
+    def test_picoclaw_lists_tool_order(self) -> None:
+        skill = (ROOT / "skills" / "picoclaw" / "SKILL.md").read_text()
+        agents = (ROOT / "AGENTS.md").read_text()
+        self.assertIn("**`search`**", skill)
+        self.assertIn("**`get`**", skill)
+        self.assertIn("**`audit`**", skill)
+        self.assertIn("throttled", skill.lower())
+        self.assertIn("not a negative finding", agents)
+        self.assertIn("Fact-check every", agents)

compose.yaml

@@ -76,6 +76,25 @@ services:
       - ./deploy/searxng/limiter.toml:/etc/searxng/limiter.toml:ro
     restart: unless-stopped
 
+  # MCP endpoint for an external agent (PicoClaw is not shipped here).
+  #   docker compose --profile picoclaw up brain-mcp
+  # Point the agent at http://127.0.0.1:8630/mcp (see deploy/picoclaw/).
+  brain-mcp:
+    profiles: ["picoclaw"]
+    image: ghcr.io/eslider/2dph:latest
+    environment: *env
+    volumes:
+      - kb-model:/data/hf
+      - kb-var:/data
+      - ~/.config/brain:/secret:ro
+    command: ["brain", "serve"]
+    ports:
+      - "127.0.0.1:8630:8630"
+    read_only: true
+    tmpfs:
+      - /tmp
+    restart: unless-stopped
+
 volumes:
   kb-model:
   kb-var:

deploy/picoclaw/mcp.json.example

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "2dph": {
+      "url": "http://127.0.0.1:8630/mcp",
+      "description": "2dph fact gate. Tool order: search → get → audit. throttled is not absence."
+    }
+  }
+}

docs/design.md

@@ -69,4 +69,11 @@ Conflicting pairings (≥2 yes vs ≥2 no) = hypothesis (OQ1 → v2 resolution).
 (`system_ladybug`). They do not exec Python. Control questions for recall@5
 live in `internal/brain/rank` so CI can test the table without libladybug.
 Python `bin/kb/{get,stats,eval}` remain for GitHub Actions until the runner
-has ladybug cgo. Index/write is still `bin/kb/index`.
+has ladybug cgo. Index/write is still `bin/kb/index`.
+
+## Agent API (D20)
+
+`bin/brain/serve.go` exposes the same `internal/httpapi.Ops` table as OpenAPI
+(`GET /openapi.json`) and MCP (`POST /mcp` JSON-RPC `tools/list` +
+`tools/call`). Tool names match paths: `search`, `get`, `stats`, `audit`.
+Agents should use these endpoints instead of shebang CLIs.

docs/picoclaw.md

@@ -0,0 +1,18 @@
+# PicoClaw profile (reference agent)
+
+2dph is the memory/fact gate. PicoClaw (or any MCP client) is the agent loop
+and is **not** shipped in this repo.
+
+```bash
+docker compose --profile picoclaw up brain-mcp
+```
+
+The API listens on `127.0.0.1:8630`. Point the agent at
+`http://127.0.0.1:8630/mcp` using [deploy/picoclaw/mcp.json.example](../deploy/picoclaw/mcp.json.example).
+
+OpenAPI: `GET http://127.0.0.1:8630/openapi.json`.
+
+Before a factual reply: `search` → `get` → `audit`. `throttled` is not a
+negative finding. See `skills/picoclaw/SKILL.md`.
+
+No Cursor required. A live PicoClaw binary/image is an operator choice.

internal/httpapi/mcp.go

@@ -0,0 +1,185 @@
+package httpapi
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strconv"
+	"strings"
+)
+
+type rpcReq struct {
+	JSONRPC string          `json:"jsonrpc"`
+	ID      json.RawMessage `json:"id"`
+	Method  string          `json:"method"`
+	Params  json.RawMessage `json:"params"`
+}
+
+type rpcErr struct {
+	Code    int    `json:"code"`
+	Message string `json:"message"`
+}
+
+func (s *Server) handleOpenAPI(w http.ResponseWriter, _ *http.Request) {
+	writeJSON(w, http.StatusOK, OpenAPI())
+}
+
+func (s *Server) handleMCP(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		writeJSON(w, http.StatusMethodNotAllowed, map[string]any{"error": "POST JSON-RPC"})
+		return
+	}
+	raw, err := io.ReadAll(io.LimitReader(r.Body, 1<<20))
+	if err != nil {
+		writeJSON(w, http.StatusBadRequest, map[string]any{"error": "read body"})
+		return
+	}
+	var req rpcReq
+	if err := json.Unmarshal(raw, &req); err != nil {
+		writeJSON(w, http.StatusOK, rpcResult(nil, nil, &rpcErr{-32700, "parse error"}))
+		return
+	}
+	result, rpcErrv, callErr := s.mcpDispatch(r, req)
+	if callErr != nil {
+		writeJSON(w, http.StatusOK, rpcResult(req.ID, nil, &rpcErr{-32603, callErr.Error()}))
+		return
+	}
+	writeJSON(w, http.StatusOK, rpcResult(req.ID, result, rpcErrv))
+}
+
+func (s *Server) mcpDispatch(r *http.Request, req rpcReq) (any, *rpcErr, error) {
+	switch req.Method {
+	case "initialize":
+		return map[string]any{
+			"protocolVersion": "2024-11-05",
+			"capabilities":    map[string]any{"tools": map[string]any{}},
+			"serverInfo":      map[string]any{"name": "2dph", "version": "1"},
+		}, nil, nil
+	case "notifications/initialized", "notifications/cancelled":
+		return map[string]any{}, nil, nil
+	case "tools/list":
+		return map[string]any{"tools": MCPTools()}, nil, nil
+	case "tools/call":
+		out, err := s.mcpCall(r, req.Params)
+		return out, nil, err
+	case "ping":
+		return map[string]any{}, nil, nil
+	default:
+		return nil, &rpcErr{-32601, "method not found"}, nil
+	}
+}
+
+func (s *Server) mcpCall(r *http.Request, params json.RawMessage) (any, error) {
+	var p struct {
+		Name      string         `json:"name"`
+		Arguments map[string]any `json:"arguments"`
+	}
+	if err := json.Unmarshal(params, &p); err != nil {
+		return nil, fmt.Errorf("params")
+	}
+	if p.Arguments == nil {
+		p.Arguments = map[string]any{}
+	}
+	var (
+		body []byte
+		err  error
+	)
+	switch p.Name {
+	case "search":
+		q := strings.TrimSpace(fmt.Sprint(p.Arguments["q"]))
+		if q == "" || q == "<nil>" {
+			return mcpText(`{"error":"q required"}`, true), nil
+		}
+		limit := 10
+		if raw, ok := p.Arguments["n"]; ok {
+			switch n := raw.(type) {
+			case float64:
+				limit = int(n)
+			case string:
+				if v, e := strconv.Atoi(n); e == nil {
+					limit = v
+				}
+			}
+		}
+		if limit < 1 || limit > 100 {
+			return mcpText(`{"error":"n must be int 1..100"}`, true), nil
+		}
+		if !s.tryAcquire(r) {
+			return nil, fmt.Errorf("cancelled")
+		}
+		defer s.release()
+		body, err = s.api.Search(r.Context(), q, limit)
+	case "get":
+		id := strings.TrimSpace(fmt.Sprint(p.Arguments["id"]))
+		if id == "" || id == "<nil>" {
+			return mcpText(`{"error":"id required"}`, true), nil
+		}
+		full := false
+		switch v := p.Arguments["body"].(type) {
+		case bool:
+			full = v
+		case string:
+			full = v == "1" || v == "true"
+		}
+		if !s.tryAcquire(r) {
+			return nil, fmt.Errorf("cancelled")
+		}
+		defer s.release()
+		body, err = s.api.Get(r.Context(), id, full)
+	case "stats":
+		if !s.tryAcquire(r) {
+			return nil, fmt.Errorf("cancelled")
+		}
+		defer s.release()
+		body, err = s.api.Stats(r.Context())
+	case "audit":
+		if !s.tryAcquire(r) {
+			return nil, fmt.Errorf("cancelled")
+		}
+		defer s.release()
+		body, err = s.api.Audit(r.Context())
+	case "ingest":
+		if !s.tryAcquire(r) {
+			return nil, fmt.Errorf("cancelled")
+		}
+		defer s.release()
+		body, err = s.api.Ingest(r.Context())
+	default:
+		return nil, fmt.Errorf("unknown tool %s", p.Name)
+	}
+	if err != nil {
+		return mcpText(err.Error(), true), nil
+	}
+	return mcpText(string(body), false), nil
+}
+
+func mcpText(text string, isError bool) map[string]any {
+	return map[string]any{
+		"content": []any{map[string]any{"type": "text", "text": text}},
+		"isError": isError,
+	}
+}
+
+type rpcResp struct {
+	JSONRPC string          `json:"jsonrpc"`
+	ID      json.RawMessage `json:"id"`
+	Result  any             `json:"result,omitempty"`
+	Error   *rpcErr         `json:"error,omitempty"`
+}
+
+func rpcResult(id json.RawMessage, result any, err *rpcErr) rpcResp {
+	out := rpcResp{JSONRPC: "2.0", ID: id}
+	if len(id) == 0 {
+		out.ID = []byte("null")
+	}
+	if err != nil {
+		out.Error = err
+		return out
+	}
+	if result == nil {
+		result = map[string]any{}
+	}
+	out.Result = result
+	return out
+}

internal/httpapi/server.go

@@ -48,18 +48,22 @@ func NewServer(api API, workers int) http.Handler {
 
 func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	switch r.URL.Path {
-	case "/health":
+	case PathHealth:
 		writeJSON(w, http.StatusOK, map[string]any{"status": "ok"})
-	case "/search":
+	case PathSearch:
 		s.handleSearch(w, r)
-	case "/get":
+	case PathGet:
 		s.handleGet(w, r)
-	case "/stats":
+	case PathStats:
 		s.handleJSON(w, r, s.api.Stats)
-	case "/audit":
+	case PathAudit:
 		s.handleJSON(w, r, s.api.Audit)
-	case "/ingest":
+	case PathIngest:
 		s.handleJSON(w, r, s.api.Ingest)
+	case PathOpenAPI:
+		s.handleOpenAPI(w, r)
+	case PathMCP:
+		s.handleMCP(w, r)
 	default:
 		writeJSON(w, http.StatusNotFound, map[string]any{"error": "not found"})
 	}
@@ -112,6 +116,16 @@ func (s *Server) handleJSON(w http.ResponseWriter, r *http.Request, fn func(cont
 	writeAPI(w, body, err)
 }
 
+func (s *Server) tryAcquire(r *http.Request) bool {
+	return s.acquire(nopWriter{}, r)
+}
+
+type nopWriter struct{}
+
+func (nopWriter) Header() http.Header       { return http.Header{} }
+func (nopWriter) Write([]byte) (int, error) { return 0, nil }
+func (nopWriter) WriteHeader(int)           {}
+
 func (s *Server) acquire(w http.ResponseWriter, r *http.Request) bool {
 	select {
 	case s.semaphore <- struct{}{}:

internal/httpapi/spec.go

@@ -0,0 +1,144 @@
+package httpapi
+
+import "strings"
+
+// Shared HTTP surface: OpenAPI paths and MCP tools are generated from Ops.
+// ServeHTTP must keep the same path strings.
+
+type Param struct {
+	Name, In, Type, Description string
+	Required                    bool
+}
+
+type Op struct {
+	Path, Method, ID, Summary string
+	Params                    []Param
+	MCP                       bool
+}
+
+const (
+	PathHealth  = "/health"
+	PathSearch  = "/search"
+	PathGet     = "/get"
+	PathStats   = "/stats"
+	PathAudit   = "/audit"
+	PathIngest  = "/ingest"
+	PathOpenAPI = "/openapi.json"
+	PathMCP     = "/mcp"
+)
+
+var Ops = []Op{
+	{Path: PathHealth, Method: "get", ID: "health", Summary: "liveness"},
+	{
+		Path: PathSearch, Method: "get", ID: "search", Summary: "deduction search (facts → info → web)",
+		MCP: true,
+		Params: []Param{
+			{Name: "q", In: "query", Type: "string", Description: "search query", Required: true},
+			{Name: "n", In: "query", Type: "integer", Description: "hit limit 1..100 (default 10)"},
+		},
+	},
+	{
+		Path: PathGet, Method: "get", ID: "get", Summary: "read one leaf by id",
+		MCP: true,
+		Params: []Param{
+			{Name: "id", In: "query", Type: "string", Description: "leaf id", Required: true},
+			{Name: "body", In: "query", Type: "boolean", Description: "include full text"},
+		},
+	},
+	{Path: PathStats, Method: "get", ID: "stats", Summary: "index health", MCP: true},
+	{Path: PathAudit, Method: "get", ID: "audit", Summary: "facts confidence histogram", MCP: true},
+	{Path: PathIngest, Method: "get", ID: "ingest", Summary: "rebuild hint (write is v2)", MCP: true},
+	{Path: PathOpenAPI, Method: "get", ID: "openapi", Summary: "OpenAPI 3 document for this server"},
+}
+
+func OpenAPI() map[string]any {
+	paths := map[string]any{}
+	for _, op := range Ops {
+		params := make([]any, 0, len(op.Params))
+		for _, p := range op.Params {
+			params = append(params, map[string]any{
+				"name":        p.Name,
+				"in":          p.In,
+				"required":    p.Required,
+				"description": p.Description,
+				"schema":      map[string]any{"type": p.Type},
+			})
+		}
+		item := map[string]any{
+			"operationId": op.ID,
+			"summary":     op.Summary,
+			"responses": map[string]any{
+				"200": map[string]any{
+					"description": "JSON",
+					"content": map[string]any{
+						"application/json": map[string]any{
+							"schema": map[string]any{"type": "object"},
+						},
+					},
+				},
+			},
+		}
+		if len(params) > 0 {
+			item["parameters"] = params
+		}
+		paths[op.Path] = map[string]any{op.Method: item}
+	}
+	return map[string]any{
+		"openapi": "3.0.3",
+		"info": map[string]any{
+			"title":       "2dph brain",
+			"version":     "1",
+			"description": "Same handlers as bin/brain/serve.go. MCP tools at POST /mcp match these paths.",
+		},
+		"paths": paths,
+	}
+}
+
+type MCPTool struct {
+	Name        string         `json:"name"`
+	Description string         `json:"description"`
+	InputSchema map[string]any `json:"inputSchema"`
+}
+
+func MCPTools() []MCPTool {
+	out := make([]MCPTool, 0, len(Ops))
+	for _, op := range Ops {
+		if !op.MCP {
+			continue
+		}
+		props := map[string]any{}
+		var required []string
+		for _, p := range op.Params {
+			props[p.Name] = map[string]any{"type": p.Type, "description": p.Description}
+			if p.Required {
+				required = append(required, p.Name)
+			}
+		}
+		schema := map[string]any{"type": "object", "properties": props}
+		if len(required) > 0 {
+			schema["required"] = required
+		}
+		out = append(out, MCPTool{
+			Name:        op.ID,
+			Description: op.Summary,
+			InputSchema: schema,
+		})
+	}
+	return out
+}
+
+// SkillMarkdown is the Cursor skill fragment generated from Ops/MCPTools.
+func SkillMarkdown() string {
+	var b strings.Builder
+	b.WriteString("# brain HTTP / MCP tools\n\n")
+	b.WriteString("Generated from `internal/httpapi.Ops`. Do not edit by hand.\n\n")
+	b.WriteString("Serve: `bin/brain/serve.go` (`GET /openapi.json`, `POST /mcp`).\n\n")
+	for _, t := range MCPTools() {
+		b.WriteString("- `")
+		b.WriteString(t.Name)
+		b.WriteString("` — ")
+		b.WriteString(t.Description)
+		b.WriteString("\n")
+	}
+	return b.String()
+}

internal/httpapi/spec_test.go

@@ -0,0 +1,99 @@
+package httpapi
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestOpenAPIIncludesCorePaths(t *testing.T) {
+	doc := OpenAPI()
+	raw, err := json.Marshal(doc)
+	if err != nil {
+		t.Fatal(err)
+	}
+	paths, _ := doc["paths"].(map[string]any)
+	for _, p := range []string{"/search", "/get", "/stats", "/audit"} {
+		if _, ok := paths[p]; !ok {
+			t.Fatalf("openapi missing path %s (%s)", p, raw)
+		}
+	}
+}
+
+func TestMCPToolsMatchOpenAPIPaths(t *testing.T) {
+	paths, _ := OpenAPI()["paths"].(map[string]any)
+	tools := MCPTools()
+	if len(tools) == 0 {
+		t.Fatal("no MCP tools")
+	}
+	names := map[string]bool{}
+	for _, tool := range tools {
+		names[tool.Name] = true
+		path := "/" + tool.Name
+		if _, ok := paths[path]; !ok {
+			t.Fatalf("MCP tool %s has no OpenAPI path %s", tool.Name, path)
+		}
+	}
+	for _, need := range []string{"search", "get", "stats", "audit"} {
+		if !names[need] {
+			t.Fatalf("MCP tools missing %s: %v", need, names)
+		}
+	}
+}
+
+func TestOpenAPIHTTP(t *testing.T) {
+	h := NewServer(&fakeSearcher{}, 1)
+	code, body := get(t, h, "/openapi.json")
+	if code != http.StatusOK {
+		t.Fatalf("code = %d body=%s", code, body)
+	}
+	var doc map[string]any
+	if err := json.Unmarshal(body, &doc); err != nil {
+		t.Fatalf("not json: %v", err)
+	}
+	if doc["openapi"] == nil {
+		t.Fatalf("missing openapi version: %s", body)
+	}
+}
+
+func TestMCPToolsListAndCall(t *testing.T) {
+	h := NewServer(&fakeSearcher{}, 1)
+	code, body := postJSON(t, h, "/mcp", `{"jsonrpc":"2.0","id":1,"method":"tools/list"}`)
+	if code != http.StatusOK {
+		t.Fatalf("list code = %d body=%s", code, body)
+	}
+	if !strings.Contains(string(body), `"search"`) {
+		t.Fatalf("tools/list missing search: %s", body)
+	}
+	code, body = postJSON(t, h, "/mcp", `{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search","arguments":{"q":"matrix","n":3}}}`)
+	if code != http.StatusOK {
+		t.Fatalf("call code = %d body=%s", code, body)
+	}
+	if !strings.Contains(string(body), "matrix") {
+		t.Fatalf("search call body %s", body)
+	}
+}
+
+func TestSkillMarkdownMatchesCommittedFile(t *testing.T) {
+	want, err := os.ReadFile(filepath.Join("..", "..", "skills", "brain", "tools.md"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	got := SkillMarkdown()
+	if got != string(want) {
+		t.Fatalf("skills/brain/tools.md stale; regenerate from SkillMarkdown()\n--- got ---\n%s\n--- want ---\n%s", got, want)
+	}
+}
+
+func postJSON(t *testing.T, h http.Handler, path, raw string) (int, []byte) {
+	t.Helper()
+	req := httptest.NewRequest(http.MethodPost, path, strings.NewReader(raw))
+	req.Header.Set("Content-Type", "application/json")
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, req)
+	return rec.Code, rec.Body.Bytes()
+}

skills/brain/SKILL.md

@@ -44,4 +44,7 @@ are not wired yet); do not treat it as a graph walk.
   are not evidence of absence. `--root facts|info` and `--no-web` skip the web.
 - If recall looks wrong, run `bin/brain/eval.go`; it gates control questions and
   should stay at or above 95% recall@5.
+- Agents: `GET /openapi.json` and `POST /mcp` on `bin/brain/serve.go` (same
+  handlers; tool names match paths `search`/`get`/`stats`/`audit`). Generated
+  list: [tools.md](tools.md).
 - Never report an unconfirmed single-source local answer as fact.

skills/brain/tools.md

@@ -0,0 +1,11 @@
+# brain HTTP / MCP tools
+
+Generated from `internal/httpapi.Ops`. Do not edit by hand.
+
+Serve: `bin/brain/serve.go` (`GET /openapi.json`, `POST /mcp`).
+
+- `search` — deduction search (facts → info → web)
+- `get` — read one leaf by id
+- `stats` — index health
+- `audit` — facts confidence histogram
+- `ingest` — rebuild hint (write is v2)

skills/db-yaml/SKILL.md

@@ -1,39 +0,0 @@
----
-name: db-yaml
-description: >-
-  Read any Postgres as compact YAML through db/psql-yq, with a read-only guard and
-  named profiles. Use when a task needs table contents, column types or a SELECT
-  against cs_brain or another project database.
----
-
-# db-yaml
-
-`bin/db/psql-yq` (vendored in this repo) talks to Postgres and returns YAML,
-which is far cheaper than a psql ASCII table and easy to slice with `yq`.
-
-```bash
-bin/db/psql-yq --profile onlyoffice -s document_asset   # column list
-bin/db/psql-yq --profile onlyoffice -t task_result -l 20  # sample rows as YAML
-bin/db/psql-yq --profile onlyoffice -c 'SELECT ...'     # query -> YAML
-```
-
-Ad-hoc targets without a profile:
-
-```bash
-bin/db/psql-yq --container my-pg --db app -c 'SELECT 1'
-bin/db/psql-yq --dsn 'postgres://user@host:5432/db' -c 'SELECT 1'
-```
-
-## Profiles
-
-Connection details live in `~/.config/brain/db-profiles.yml` (mode 600), never in a
-project repo. A profile names either a `container` or a `host`; passwords are read
-from a separate `password_env_file` and never appear in argv.
-
-## Rules
-
-- **Read-only.** Any `insert|update|delete|drop|truncate|alter|create|grant|
-  revoke|vacuum|copy` is rejected with exit 3. Do not work around it.
-- **PII.** `cs_brain` holds client data. Aggregate and count freely; never copy
-  names or addresses into chat, issues or docs.
-- Use `-l` to keep samples small. Twenty rows answer most questions.

skills/picoclaw/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: picoclaw
+description: >-
+  2dph is the memory/fact gate, not the agent loop. Use when wiring PicoClaw
+  or any MCP client: call brain search/get/audit before a factual reply.
+  throttled is not a negative finding.
+---
+
+# PicoClaw — fact-check before assert
+
+PicoClaw (or any agent) speaks MCP at `POST /mcp` on `bin/brain/serve.go`.
+2dph does not run the agent loop. Compose: `docker compose --profile picoclaw up brain-mcp`
+(see [docs/picoclaw.md](../../docs/picoclaw.md)).
+
+## Tool order (before a factual reply)
+
+1. **`search`** — facts root first, then info. The `web` block is a second
+   source when there is no facts hit. Status `throttled` / `skipped` /
+   `refused` is **not** evidence of absence.
+2. **`get`** — full leaf body only when a hit `id` is needed.
+3. **`audit`** — if recall or confidence looks wrong.
+
+Then answer. Confirmed only from facts (≥2 independent sources). Anything
+else is `(not confirmed)`. Missing graph ≠ “does not exist”.
+
+Generated tool list: [../brain/tools.md](../brain/tools.md).

skills/postgres/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: postgres
+description: >-
+  Read Postgres as compact YAML through bin/postgres/query.go (read-only
+  guard, named profiles). Use when a task needs table contents, column types,
+  or a SELECT against an ops database.
+---
+
+# postgres
+
+`bin/postgres/query.go` wraps vendored `bin/db/psql-yq`. Output is YAML
+(cheaper than psql ASCII, easy to slice with `yq`).
+
+```bash
+bin/postgres/query.go --profile onlyoffice -s document_asset   # column list
+bin/postgres/query.go --profile onlyoffice -t task_result -l 20  # sample rows
+bin/postgres/query.go --profile onlyoffice -c 'SELECT ...'     # query → YAML
+```
+
+Ad-hoc targets without a profile:
+
+```bash
+bin/postgres/query.go --container my-pg --db app -c 'SELECT 1'
+bin/postgres/query.go --dsn 'postgres://user@host:5432/db' -c 'SELECT 1'
+```
+
+## Profiles
+
+Connection details live in `$HOME/.config/brain/db-profiles.yml` (mode 600),
+never in a project repo. A profile names either a `container` or a `host`;
+passwords are read from a separate `password_env_file` and never appear in argv.
+
+## Rules
+
+- **Read-only.** Any `insert|update|delete|drop|truncate|alter|create|grant|
+  revoke|vacuum|copy` is rejected with exit 3. Do not work around it.
+- **PII.** Client CRM databases: aggregate and count freely; never copy names
+  or addresses into chat, issues or docs.
+- Use `-l` to keep samples small. Twenty rows answer most questions.