feat(mcp): register brain_update + brain_get, extend brain_write handle

Wires the #45 verbs into the MCP surface (all three sites: tools()
descriptors, handleCall dispatch, package doc comment).

- brain_update: supersede-by-slug or full path; rebuilds wing _index and
  re-tunnels cross-wing matches against the new body (idempotent,
  best-effort), re-indexes the graph, returns {id, path, content_hash,
  superseded}.
- brain_get: fetch by id or path (both are the brain-relative handle);
  returns {id, path, content_hash, frontmatter, body}.
- brain_write: return contract extended from {path} to {id, path,
  content_hash} — path kept for backward compat — so the create path
  also yields a stable handle.

id == relPath; content_hash == sha256 of the file bytes. Tests cover the
supersede happy path, missing-target error + no-create, get by id/path,
write handle, and an end-to-end re-embed test that drives the real
vectorstore.Sync re-index after an update.

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

ingestion/internal/mcp/handlers.go

@@ -61,6 +61,26 @@ func (s *Server) tools() []map[string]any {
 				"hall":     enum("optional memory type (requires wing)", halls...),
 			}),
 		},
+		{
+			"name":        "brain_update",
+			"description": "Supersede an existing brain note in place: whole-note body replace + frontmatter re-stamp (updated_at, supersedes=prior content hash, supersede_reason). Errors if the target does not exist — use brain_write to create. Returns {id, path, content_hash, superseded}. Prior version recoverable from git.",
+			"inputSchema": schema([]string{"content"}, map[string]any{
+				"content": str("new full body (whole-note replace)"),
+				"slug":    str("target note slug within wing/hall, OR a full brain-relative path (e.g. wiki/jepa-fx/facts/x.md)"),
+				"wing":    str("wing of the target (required unless slug/path is a full path)"),
+				"hall":    enum("hall of the target (required unless slug/path is a full path)", halls...),
+				"path":    str("full brain-relative path to the target; takes precedence over slug/wing/hall"),
+				"reason":  str("optional short note on why superseded — stamped into frontmatter"),
+			}),
+		},
+		{
+			"name":        "brain_get",
+			"description": "Fetch a single brain note by id or path (both are the brain-relative path — the note handle). Returns {id, path, content_hash, frontmatter, body}. Read-after-write confirmation without a lexical re-query.",
+			"inputSchema": schema([]string{}, map[string]any{
+				"id":   str("note id (brain-relative path) as returned by brain_write/brain_update"),
+				"path": str("brain-relative path to the note; equivalent to id"),
+			}),
+		},
 		{
 			"name":        "brain_tunnel",
 			"description": "Create an explicit bidirectional [[wikilink]] between two notes in different wings. Idempotent.",
@@ -222,7 +242,111 @@ func (s *Server) brainWrite(ctx context.Context, args json.RawMessage) (json.Raw
 		}
 	}
 	s.indexInGraph(ctx, "brain_write", relPath)
-	return json.Marshal(map[string]string{"path": relPath})
+	// Read-after-write handle: id == relPath, content_hash == sha256 of
+	// the bytes just written. path is kept for backward compatibility.
+	_, _, hash, _ := api.ReadNote(s.brainDir, relPath)
+	return json.Marshal(map[string]string{"id": relPath, "path": relPath, "content_hash": hash})
+}
+
+type brainUpdateArgs struct {
+	Slug    string `json:"slug,omitempty"`
+	Wing    string `json:"wing,omitempty"`
+	Hall    string `json:"hall,omitempty"`
+	Path    string `json:"path,omitempty"`
+	Content string `json:"content"`
+	Reason  string `json:"reason,omitempty"`
+}
+
+// brainUpdate supersedes an existing note in place: whole-note body
+// replace, frontmatter re-stamp (updated_at/supersedes/supersede_reason),
+// graph re-index, and wing _index rebuild. It never creates — a missing
+// target is an error so the caller can fall back to brain_write.
+//
+// Embedding re-sync is delegated to the out-of-band vectorstore.Sync
+// ticker: the rewritten file's mtime advances, so the next pass re-embeds
+// it. This mirrors brain_write, which likewise does not embed in-handler.
+func (s *Server) brainUpdate(ctx context.Context, args json.RawMessage) (json.RawMessage, error) {
+	var a brainUpdateArgs
+	if err := json.Unmarshal(args, &a); err != nil {
+		return nil, fmt.Errorf("parse args: %w", err)
+	}
+	if a.Content == "" {
+		return nil, fmt.Errorf("content is required")
+	}
+
+	opts := api.UpdateNoteOptions{Content: a.Content, Reason: a.Reason}
+	switch {
+	case a.Path != "":
+		opts.Path = a.Path
+	case strings.Contains(a.Slug, "/"):
+		// slug carries a full path (issue #45: "slug ... OR full path").
+		opts.Path = a.Slug
+	default:
+		opts.Wing, opts.Hall, opts.Slug = a.Wing, a.Hall, a.Slug
+	}
+
+	relPath, hash, _, err := api.UpdateNote(s.brainDir, opts)
+	if err != nil {
+		return nil, err
+	}
+
+	// Best-effort wiki upkeep, mirroring brain_write: rebuild the wing
+	// _index and re-tunnel cross-wing matches against the new body. Both
+	// are idempotent and never block — the note is already superseded.
+	if wing := wingFromRelPath(relPath); wing != "" {
+		if err := brain.BuildWingIndex(s.brainDir, wing); err != nil {
+			slog.Warn("brain_update: auto-index failed", "wing", wing, "err", err)
+		}
+		if err := brain.AutoTunnel(s.brainDir, relPath, a.Content); err != nil {
+			slog.Warn("brain_update: auto-tunnel failed", "src", relPath, "err", err)
+		}
+	}
+	s.indexInGraph(ctx, "brain_update", relPath)
+
+	return json.Marshal(map[string]any{
+		"id": relPath, "path": relPath, "content_hash": hash, "superseded": true,
+	})
+}
+
+// wingFromRelPath extracts the wing segment from a structured wiki path
+// (wiki/<wing>/<hall>/<slug>.md). Returns "" for legacy/non-wiki paths.
+func wingFromRelPath(relPath string) string {
+	parts := strings.Split(relPath, "/")
+	if len(parts) >= 4 && parts[0] == "wiki" {
+		return parts[1]
+	}
+	return ""
+}
+
+type brainGetArgs struct {
+	ID   string `json:"id,omitempty"`
+	Path string `json:"path,omitempty"`
+}
+
+// brainGet fetches a note by id or path (both are the brainDir-relative
+// path — the de-facto handle). Read-only; the create-path read-after-
+// write primitive that lets callers confirm a write landed without a
+// lexical re-query.
+func (s *Server) brainGet(_ context.Context, args json.RawMessage) (json.RawMessage, error) {
+	var a brainGetArgs
+	if err := json.Unmarshal(args, &a); err != nil {
+		return nil, fmt.Errorf("parse args: %w", err)
+	}
+	target := a.Path
+	if target == "" {
+		target = a.ID
+	}
+	if target == "" {
+		return nil, fmt.Errorf("id or path is required")
+	}
+	fm, body, hash, err := api.ReadNote(s.brainDir, target)
+	if err != nil {
+		return nil, err
+	}
+	return json.Marshal(map[string]any{
+		"id": target, "path": target, "content_hash": hash,
+		"frontmatter": fm, "body": body,
+	})
 }
 
 // indexInGraph is a best-effort wrapper around graphsync.IndexDoc that