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
 

PLAN.md

@@ -51,7 +51,7 @@ 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, postgres, brain, diataxis-docs)
+  skills/                   in-project skills (web-search, postgres, brain, picoclaw, diataxis-docs)
   bin/
     facts/extract.go audit.go crm.go  # D14 shebang; Python implementation
     kb/index                Python write path (called by bin/brain/index.go)
@@ -59,7 +59,7 @@ detective method: **a fact needs ≥2 independent sources or it is
     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 + OpenAPI/MCP (D20)
+    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)

README.md

@@ -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
 ```
 

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)

bin/tools/test_skills.py

@@ -37,3 +37,13 @@ class SkillsTest(unittest.TestCase):
         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/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.

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).