Glossary

Capability. A dependency Brainlyy probed for and found. Not a config setting. Config says what you would like; a capability is what is actually there.

Drift. A gap between what the system claims and what is true. An agent whose SOUL lists a schedule that no cron job implements; a knowledge file that says it is loaded when nothing loads it. brainlyy doctor looks for these.

Instance. One configured deployment: a config file, its tokens, its vault and its rendered knowledge base. Lives under ~/.brainlyy, or wherever BRAINLYY_HOME points. Separate from the installed package.

Loopback guard. The write server's startup check. It reads its bind address and exits if that address is not loopback. An exit code, not a policy.

Mesh address. The private address your machine holds on a VPN such as Tailscale or WireGuard, usually in the carrier-grade NAT range (100.64.0.0/10). Binding to it narrowly is the access control; a firewall rule you cannot verify is not one.

Provenance marker. The tag every claim in the knowledge base carries: ✅ VERIFIED, ⚠️ ESTIMATE, or ❓ UNRESOLVED, with a date. An unmarked claim is treated as suspect, not as true.

Property test. A test that asserts a boundary rather than a behaviour. Behaviour tests tell you a feature works; property tests tell you a boundary still holds. Brainlyy's suite asserts bind addresses, the loopback guard, allowlist refusals, and that no deployment-specific value travels with the package.

Read server. The MCP server that binds your mesh address and exposes only non-mutating tools.

SOUL. A markdown file defining one agent: its role, what it owns, its schedule, and explicitly what it is not responsible for. Named for being the thing loaded on every run.

Tier. A description of what your machine can currently do, 0 through 4. Tiers gate nothing; they exist so doctor can tell you what adding one more dependency would buy.

Vault. The folder of markdown notes Brainlyy searches. Plain files, no database, no import step.

Write server. The MCP server that binds loopback only and exposes the mutating tools. Holds a different token from the read server.