Brain Routing Convention

Cross-cutting rules for which brain and which source an operation targets. Applies to every skill that reads or writes brain pages. Full mental model lives in docs/architecture/brains-and-sources.md — read it once.

The two axes (one-line summary)

• Brain = which DATABASE. --brain, GBRAIN_BRAIN_ID, .gbrain-mount.
• Source = which REPO INSIDE the database. --source, GBRAIN_SOURCE, .gbrain-source.

Orthogonal. Pick one on each axis per operation.

Default behavior (ALWAYS)

Start in the brain + source resolved by the environment:

1. Run gbrain mounts list if you haven't seen the user's mounts yet.
2. Trust the resolver. If the user is in ~/team-brains/media/, their .gbrain-mount pins brain=media-team. Don't override that silently.
3. For every brain op, pass the resolved brain id explicitly when calling tools (even if it matches the default). Makes routing visible in logs.

Bare gbrain query "X" routes to the default brain's default source. That is the right answer 90% of the time. Don't cross the boundary without a reason.

When to switch brain

Switch brain (--brain <id>) when:

• The user's question is specifically about a team the user belongs to ("what did team X decide?", "what's the status of project Y at team X?"). Switch BEFORE searching, not after a failed search in host.
• The user is asking you to ingest data that belongs to a specific team (meeting notes from a team meeting, letters from a team's pipeline). The data owner determines the brain.
• The user explicitly names a team/brain ("check the media-team brain for...").

Do NOT switch brain when:

• The user asks a general question that might pull from anywhere. Start in host, then cross-query on-demand if host doesn't have it.
• You're unsure. Stay in host, surface what you found, let the user point you at a specific brain.

Source resolution chain (7-tier, v0.41.13+)

gbrain resolves the active source via resolveSourceId() in src/core/source-resolver.ts. Seven tiers, highest priority first:

#	Tier	Signal
1	flag	Explicit --source <id> CLI flag (or --source-id <id> on gbrain extract / gbrain import)
2	env	GBRAIN_SOURCE environment variable
3	dotfile	.gbrain-source file in CWD or any ancestor directory
4	local_path	A registered source whose local_path contains CWD (longest prefix wins)
5	brain_default	Brain-level sources.default config key (explicit user intent)
5.5	sole_non_default	When tiers 1–5 missed AND exactly one registered source has a local_path AND isn't 'default', auto-route to it. Fires a one-time stderr nudge per CLI invocation. Suppress with GBRAIN_NO_SOLE_NON_DEFAULT_NUDGE=1.
6	seed_default	Literal 'default' (always exists post-migration v16)

v0.41.13 tier 5.5 (sole_non_default): added for single-source brains (typical for users with one Obsidian vault, one notes folder, one project). Pre-fix, gbrain sync from /tmp against a brain registering only studiovault silently routed to 'default' and every edit failed at createVersion because the slug didn't exist there. The tier auto-routes to the obvious single answer. Multi-source brains (2+ non-default registered) still fall through to seed_default and require explicit --source.

Placement AFTER brain_default is deliberate: a user who explicitly set sources.default via gbrain sources default <id> has stated intent that wins over the auto-route. Archived sources are excluded from the count.

v0.37.7.0 tooling:

• gbrain sources current [--json] echoes the resolved source AND which tier won. Run this before any destructive op to verify what you're about to target.
• gbrain sources current --source X shows what an explicit flag WOULD resolve to (validates X exists in the sources table).

CLI commands honoring this chain: gbrain sync, gbrain import, gbrain search, gbrain extract (via --source-id <id> since --source is the fs|db data-source axis), gbrain graph-query (via --include-foreign for cross-source traversal).

Trust boundary (v0.34.1.0): the resolver is CLI-layer only. Operations.ts handlers do NOT read .gbrain-source or GBRAIN_SOURCE. MCP/remote callers go through ctx.auth.sourceId / ctx.auth.allowedSources instead. A remote caller cannot inherit the server process's CLI source context.

When to switch source

Switch source (--source <id>) when:

• The user is working in a specific repo (the .gbrain-source dotfile usually handles this — don't fight it).
• The user asks about something scoped to a repo ("what's in my gstack notes about retry policy?").
• You're writing a page that logically belongs to one repo. The data origin determines the source.

Do NOT switch source when:

• The user's intent crosses repos. Keep federated=true sources for cross-source search.
• You'd lose a cross-repo match by isolating.

Cross-brain queries (latent-space federation)

v0.19 does NOT do deterministic cross-brain federation. No SQL fan-out. No unified ranking. The AGENT federates.

Pattern when the user asks something that might span brains:

1. Query host with the obvious query.
2. Check gbrain mounts list for relevant brain ids.
3. If you think another brain has the answer, re-query THAT brain explicitly (--brain <id>).
4. Synthesize across results. Cite <brain>:<source>:<slug> so the user can trace.

Never silently mix brains. Every finding is citable to its brain.

Writing across brains

Writing is stricter than reading. ASK before writing cross-brain.

• A fact about a team's work → team's brain, not host.
• A fact the user confirmed about a person ONLY they know → host/personal, not a team brain.
• An enrichment discovered from public data → usually host unless the user says otherwise.

If you're about to put_page --brain <team-brain>, confirm with the user unless they explicitly said "save this to team-X". Default brain for writes is the user's personal brain.

Citations with brain context

Standard citation format stays the same ([Source: ...]), but when pages come from a mounted brain, add the brain context for human traceability:

• Single-brain query: [Source: Meeting, 2026-04-10] (unchanged).
• Cross-brain synthesis: [Source: media-team:meetings/2026-04-10] or [Source: policy-team:research/retry-budgets].

This matches v0.18.0's source-aware citation ([source-id:slug]) extended with a brain prefix when relevant.

Decision table

Situation	Brain	Source
User cd's into a team-brain checkout and asks a general question	dotfile-resolved team brain	dotfile-resolved source
User asks "what did team X decide?"	team-x explicitly	resolver default
User asks "what are we doing across all teams?"	fan out across mounts, agent-driven	resolver default
User asks "add this to my gstack notes"	host	gstack
User asks "save this meeting note for team X"	team-x (confirm if ambiguous)	team's meetings source
User asks "write me an essay"	host (personal)	essays
Unknown — can't classify	stay in host, ask the user	resolver default

Anti-patterns

• Silently jumping brains to "find" an answer when the user clearly meant host. That's an audit-trail hole.
• Writing to host when the data is clearly team-owned ("the team's plans are now in your personal brain" = bad surprise).
• Cross-brain federation in a single query without citations that name the source brain. The user cannot trace the answer back.
• Ignoring .gbrain-mount / .gbrain-source dotfiles. They're load-bearing context — the user set them up for a reason.

Read more

• docs/architecture/brains-and-sources.md — the full mental model with topology diagrams (single-person, personal-with-repos, CEO-class with multiple team brains).
• skills/conventions/brain-first.md — reads the brain BEFORE asking.
• skills/conventions/quality.md — citation format (extended here with brain prefix).