README.md

@@ -5,6 +5,11 @@ Instead of letting Claude Code do whatever it wants, hyperguild enforces structu
 workflows (TDD red/green/refactor), logs every session, and accumulates learnings
 into a searchable brain.
 
+**This repo is also where `brain-mcp` lives** — the MCP server at
+`brain-mcp.d-ma.be` that `brain_query`, `brain_write`, `brain_read`, `brain_edit`
+and `capture` are served from. It is not a separate deployable; see
+[Where brain-mcp lives](#where-brain-mcp-lives).
+
 ## Hypothesis
 
 > We believe routing skill tasks through local models, backed by brain context,
@@ -44,6 +49,33 @@ brain/
 └── knowledge/      — legacy flat notes (migration pending: hyperguild#22)
 ```
 
+## Where brain-mcp lives
+
+`brain-mcp` is served from **`ingestion/internal/mcp`** in this repo, at
+**`brain-mcp.d-ma.be`**. It is a component *inside* the `ingestion` service, not
+a standalone deployable — one pod in the `supervisor` namespace serves the MCP
+endpoint, the REST API, and the claudewatcher together.
+
+| You are looking for | It is here |
+|---|---|
+| The MCP tool surface (`brain_query`, `brain_write`, `brain_read`, `brain_edit`, `capture`, …) | `ingestion/internal/mcp` |
+| The HTTP/REST API (`/query`, `/write`, `/ingest`) | `ingestion/internal/api` |
+| Session ingestion from Claude Code transcripts | `ingestion/internal/claudewatcher` |
+| The brain *content* (notes, wings, halls) | [`mathias/brain`](https://git.d-ma.be/mathias/brain) — a separate repo |
+| Deployment manifests | `config/supervisor` |
+
+### Why it is not its own repo
+
+Asked and decided in [#91](https://git.d-ma.be/mathias/hyperguild/issues/91)
+(part 2). `internal/mcp` imports 17 of ingestion's other internal packages and
+has exactly one importer — it is the MCP facade over the service's own
+internals, so "move it out" resolves to renaming `ingestion`, publishing 17
+packages as a shared library, or maintaining a shim. The discoverability problem
+that prompted the question is answered by naming it here instead.
+
+Full reasoning, including the reversal trigger: brain
+`wiki/hyperguild/decisions/brain-mcp-stays-in-ingestion-fix-discoverability-by-name`.
+
 ## Phase 1 tools (available now)
 
 | Tool | What it does |