docs: document brain MCP endpoint at koala:30330

- README architecture diagram now shows two MCP servers (supervisor +
  brain) with the brain hosted by ingestion directly.
- Connect-a-project example includes both servers.
- .context/PROJECT.md replaces the boilerplate "Knowledge base access"
  block with the actual hyperguild MCP endpoints.
- Adapters regenerated via task context:sync.

Captures the transitional state where two MCPs coexist; the supervisor
MCP will shrink as skill workers move to SKILL.md.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.aider.conventions.md

@@ -216,13 +216,21 @@ Key skills:
 - Client data never leaves local network unless explicitly cleared
 - Dependencies: audit with `govulncheck` before adding
 
-## Knowledge base access
+## MCP endpoints
 
-This project can query the shared knowledge base via MCP or HTTP:
+Two MCP servers expose this project's tooling, both reachable over Tailscale:
 
-- **MCP endpoint**: `mcp://localhost:3100/knowledge`
+- **`brain`** at `http://koala:30330/mcp` — preferred path for `brain_query`,
-- **HTTP fallback**: `http://localhost:3100/api/v1/search`
+  `brain_write`, `brain_ingest`, `brain_ingest_raw`, and `session_log`. Hosted
-- **Scoping**: queries are filtered to collection `personal` + `public`
+  by the ingestion service directly.
+- **`supervisor`** at `http://koala:30320/mcp` — skill workers (`tdd_red`,
+  `tdd_green`, `tdd_refactor`, `review`, `debug`, `spec`, `retrospective`,
+  `trainer`, `tier`). Will shrink as skill workers move to SKILL.md in a later
+  migration.
+
+The brain HTTP REST API (`/query`, `/write`, `/ingest`, `/ingest-raw`,
+`/ingest-path`, `/backfill-refs`) remains available on the same port (3300) for
+shell scripts and non-MCP clients.
 
 ## Agent instructions
 

.context/PROJECT.md

@@ -45,13 +45,21 @@
 - Client data never leaves local network unless explicitly cleared
 - Dependencies: audit with `govulncheck` before adding
 
-## Knowledge base access
+## MCP endpoints
 
-This project can query the shared knowledge base via MCP or HTTP:
+Two MCP servers expose this project's tooling, both reachable over Tailscale:
 
-- **MCP endpoint**: `mcp://localhost:3100/knowledge`
+- **`brain`** at `http://koala:30330/mcp` — preferred path for `brain_query`,
-- **HTTP fallback**: `http://localhost:3100/api/v1/search`
+  `brain_write`, `brain_ingest`, `brain_ingest_raw`, and `session_log`. Hosted
-- **Scoping**: queries are filtered to collection `personal` + `public`
+  by the ingestion service directly.
+- **`supervisor`** at `http://koala:30320/mcp` — skill workers (`tdd_red`,
+  `tdd_green`, `tdd_refactor`, `review`, `debug`, `spec`, `retrospective`,
+  `trainer`, `tier`). Will shrink as skill workers move to SKILL.md in a later
+  migration.
+
+The brain HTTP REST API (`/query`, `/write`, `/ingest`, `/ingest-raw`,
+`/ingest-path`, `/backfill-refs`) remains available on the same port (3300) for
+shell scripts and non-MCP clients.
 
 ## Agent instructions
 

.context/system-prompt.txt

@@ -221,13 +221,21 @@ Key skills:
 - Client data never leaves local network unless explicitly cleared
 - Dependencies: audit with `govulncheck` before adding
 
-## Knowledge base access
+## MCP endpoints
 
-This project can query the shared knowledge base via MCP or HTTP:
+Two MCP servers expose this project's tooling, both reachable over Tailscale:
 
-- **MCP endpoint**: `mcp://localhost:3100/knowledge`
+- **`brain`** at `http://koala:30330/mcp` — preferred path for `brain_query`,
-- **HTTP fallback**: `http://localhost:3100/api/v1/search`
+  `brain_write`, `brain_ingest`, `brain_ingest_raw`, and `session_log`. Hosted
-- **Scoping**: queries are filtered to collection `personal` + `public`
+  by the ingestion service directly.
+- **`supervisor`** at `http://koala:30320/mcp` — skill workers (`tdd_red`,
+  `tdd_green`, `tdd_refactor`, `review`, `debug`, `spec`, `retrospective`,
+  `trainer`, `tier`). Will shrink as skill workers move to SKILL.md in a later
+  migration.
+
+The brain HTTP REST API (`/query`, `/write`, `/ingest`, `/ingest-raw`,
+`/ingest-path`, `/backfill-refs`) remains available on the same port (3300) for
+shell scripts and non-MCP clients.
 
 ## Agent instructions
 

.cursorrules

@@ -219,13 +219,21 @@ Key skills:
 - Client data never leaves local network unless explicitly cleared
 - Dependencies: audit with `govulncheck` before adding
 
-## Knowledge base access
+## MCP endpoints
 
-This project can query the shared knowledge base via MCP or HTTP:
+Two MCP servers expose this project's tooling, both reachable over Tailscale:
 
-- **MCP endpoint**: `mcp://localhost:3100/knowledge`
+- **`brain`** at `http://koala:30330/mcp` — preferred path for `brain_query`,
-- **HTTP fallback**: `http://localhost:3100/api/v1/search`
+  `brain_write`, `brain_ingest`, `brain_ingest_raw`, and `session_log`. Hosted
-- **Scoping**: queries are filtered to collection `personal` + `public`
+  by the ingestion service directly.
+- **`supervisor`** at `http://koala:30320/mcp` — skill workers (`tdd_red`,
+  `tdd_green`, `tdd_refactor`, `review`, `debug`, `spec`, `retrospective`,
+  `trainer`, `tier`). Will shrink as skill workers move to SKILL.md in a later
+  migration.
+
+The brain HTTP REST API (`/query`, `/write`, `/ingest`, `/ingest-raw`,
+`/ingest-path`, `/backfill-refs`) remains available on the same port (3300) for
+shell scripts and non-MCP clients.
 
 ## Agent instructions
 

.mcp.json

@@ -3,6 +3,10 @@
     "supervisor": {
       "type": "http",
       "url": "http://koala:30320/mcp"
+    },
+    "brain": {
+      "type": "http",
+      "url": "http://koala:30330/mcp"
     }
   }
 }

AGENTS.md

@@ -216,13 +216,21 @@ Key skills:
 - Client data never leaves local network unless explicitly cleared
 - Dependencies: audit with `govulncheck` before adding
 
-## Knowledge base access
+## MCP endpoints
 
-This project can query the shared knowledge base via MCP or HTTP:
+Two MCP servers expose this project's tooling, both reachable over Tailscale:
 
-- **MCP endpoint**: `mcp://localhost:3100/knowledge`
+- **`brain`** at `http://koala:30330/mcp` — preferred path for `brain_query`,
-- **HTTP fallback**: `http://localhost:3100/api/v1/search`
+  `brain_write`, `brain_ingest`, `brain_ingest_raw`, and `session_log`. Hosted
-- **Scoping**: queries are filtered to collection `personal` + `public`
+  by the ingestion service directly.
+- **`supervisor`** at `http://koala:30320/mcp` — skill workers (`tdd_red`,
+  `tdd_green`, `tdd_refactor`, `review`, `debug`, `spec`, `retrospective`,
+  `trainer`, `tier`). Will shrink as skill workers move to SKILL.md in a later
+  migration.
+
+The brain HTTP REST API (`/query`, `/write`, `/ingest`, `/ingest-raw`,
+`/ingest-path`, `/backfill-refs`) remains available on the same port (3300) for
+shell scripts and non-MCP clients.
 
 ## Agent instructions
 

CLAUDE.md

@@ -45,13 +45,21 @@
 - Client data never leaves local network unless explicitly cleared
 - Dependencies: audit with `govulncheck` before adding
 
-## Knowledge base access
+## MCP endpoints
 
-This project can query the shared knowledge base via MCP or HTTP:
+Two MCP servers expose this project's tooling, both reachable over Tailscale:
 
-- **MCP endpoint**: `mcp://localhost:3100/knowledge`
+- **`brain`** at `http://koala:30330/mcp` — preferred path for `brain_query`,
-- **HTTP fallback**: `http://localhost:3100/api/v1/search`
+  `brain_write`, `brain_ingest`, `brain_ingest_raw`, and `session_log`. Hosted
-- **Scoping**: queries are filtered to collection `personal` + `public`
+  by the ingestion service directly.
+- **`supervisor`** at `http://koala:30320/mcp` — skill workers (`tdd_red`,
+  `tdd_green`, `tdd_refactor`, `review`, `debug`, `spec`, `retrospective`,
+  `trainer`, `tier`). Will shrink as skill workers move to SKILL.md in a later
+  migration.
+
+The brain HTTP REST API (`/query`, `/write`, `/ingest`, `/ingest-raw`,
+`/ingest-path`, `/backfill-refs`) remains available on the same port (3300) for
+shell scripts and non-MCP clients.
 
 ## Agent instructions
 

README.md

@@ -11,9 +11,10 @@ into a searchable brain.
 Your Claude Code session (in any project)
     │
     │  MCP over HTTP (Tailscale)
-    ▼
+    ├──▶ supervisor  :3200 (NodePort 30320 on koala) — skill workers: tdd, debug, spec, …
-supervisor  :3200 (NodePort 30320 on koala) — skill workers: tdd, retrospective
+    └──▶ brain       :3300 (NodePort 30330 on koala) — brain_query, brain_write, brain_ingest, session_log
-ingestion   :3300                            — brain HTTP API: query wiki, write notes
+                       │
+                       └─ also serves the legacy REST endpoints (/query, /write, /ingest, …)
     │
     ▼
 brain/
@@ -57,16 +58,26 @@ Create `.mcp.json` in your project root:
     "supervisor": {
       "type": "http",
       "url": "http://koala:30320/mcp"
+    },
+    "brain": {
+      "type": "http",
+      "url": "http://koala:30330/mcp"
     }
   }
 }
 ```
 
-The supervisor MCP server is reachable over Tailscale at `koala:30320` (NodePort
+Two MCP servers are exposed today, both reachable over Tailscale:
-to the in-cluster service on port 3200). No local binary or stdio shim is
-required — Claude Code talks to it directly via HTTP.
 
-Open Claude Code in your project — run `/mcp` to confirm `supervisor` is listed.
+- **`supervisor`** at `koala:30320` — skill workers (`tdd_red/green/refactor`,
+  `review`, `debug`, `spec`, `retrospective`, `trainer`, `tier`).
+- **`brain`** at `koala:30330` — knowledge access (`brain_query`, `brain_write`,
+  `brain_ingest`, `brain_ingest_raw`) and `session_log`. Hosted by the ingestion
+  service directly, no separate pod.
+
+No local binary or stdio shim is required — Claude Code talks to both via HTTP.
+
+Open Claude Code in your project — run `/mcp` to confirm both servers are listed.
 
 ## A typical TDD session