docs

Author: cmtonkinson

AGENTS.md

@@ -5,10 +5,9 @@ Additional instructions for working in this specific project:
 * @docs/*.md
 * `python -m pytest ...` for targeted verification
 * `ruff [format]` for linting / style enforcement
-* `gmake test docs` for Markdown style verification (<1s)
-* `gmake test` for unit tests (takes ~10)
-* `gmake test integration` for unit+integration tests (~20s)
-* `gmake test-all` for full suite (~2m)
+* `gmake test` for comprehensive basic checks - docs, lint, unit (takes ~12)
+* `gmake test integration` for unit+integration tests (~40s)
+* `gmake test-all` for full suite, incl. e2e smoke tests (~2m)
 * This is a new, unpublished, unsupported project. The author is the only
   contributor, and isn't even a user yet. As such, when making changes:
     * Never keep old naming, docs, functionality, specs, or expectations as

Makefile

@@ -83,7 +83,7 @@ ifeq ($(INTEGRATION),1)
 PYTEST_INTEGRATION_ENV := BRAIN_RUN_INTEGRATION_REAL=1
 endif
 
-.PHONY: all deps deps-upgrade switch-python clean check format test test-only test-all docs up down ps app-up app-down app-down-all o11y-up o11y-down stack-up stack-down integration outline smoke smoke-only smoke-e2e smoke-docker
+.PHONY: all deps deps-upgrade switch-python clean check format test test-only test-all docs docs-check up down ps app-up app-down app-down-all o11y-up o11y-down stack-up stack-down integration outline smoke smoke-only smoke-e2e smoke-docker
 
 define run_gate
 	@set +e; \
@@ -138,17 +138,20 @@ check:
 format:
 	$(PY) -m ruff format .
 
+docs-check:
+	$(call run_gate,Documentation Conventions,$(PY) scripts/check_documentation_conventions.py --check)
+
 ifneq (,$(and $(filter test,$(MAKECMDGOALS)),$(filter docs,$(MAKECMDGOALS))))
 test:
 	@:
 else
-test: check test-only
+test: docs-check check test-only
 endif
 
 test-only:
 	$(call run_gate,$(if $(filter 1,$(INTEGRATION)),Pytest (unit + integration),Pytest (unit)),$(PYTEST_INTEGRATION_ENV) $(PY) -m pytest --quiet tests resources services actors)
 
-test-all: check
+test-all: docs-check check
 	$(MAKE) test-only integration
 	$(MAKE) smoke-only
 	$(MAKE) smoke-e2e
@@ -168,7 +171,7 @@ smoke-e2e:
 smoke-docker:
 	$(call run_gate,Smoke Docker,$(PY) scripts/smoke_docker_turn.py)
 
-smoke: check smoke-only
+smoke: docs-check check smoke-only
 
 smoke-only:
 	$(call run_gate,Pytest Smoke,$(PY) -m pytest --quiet \
@@ -178,8 +181,7 @@ smoke-only:
 		tests/integration/test_agent_e2e_smoke.py)
 
 ifneq (,$(and $(filter test,$(MAKECMDGOALS)),$(filter docs,$(MAKECMDGOALS))))
-docs:
-	$(call run_gate,Documentation Conventions,$(PY) scripts/check_documentation_conventions.py --check)
+docs: docs-check
 else
 docs: $(GLOSSARY_DOC) $(SERVICE_API_DOC) $(HTTP_API_DOC) $(OP_DOC) $(DIAGRAM_PNGS)
 endif

README.md

@@ -4,7 +4,7 @@ turns it into durable memory, and takes (or proposes) bounded action on your
 behalf.
 
 More academically, it's an exocortex for attention, memory, and action:
-Cognitive infrastructure that prioritizes context, directs intent deliberately,
+cognitive infrastructure that prioritizes context, directs intent deliberately,
 and closes loops.
 
 ***NOTE:** This project is still in active development and somewhat unstable.
@@ -20,14 +20,12 @@ Don't @ me, bro.*
 
 ------------------------------------------------------------------------
 ## Motivation
-I wanted a Siri that didn't suck; a real Jarvis. A local-first,
-privacy respecting, security forward, personal virtual assistant.
+I wanted a Siri that didn't suck; a real Jarvis.
 
 My initial use case was to manage commitments: to look across messages, email,
-meetings, and calendars, and not just build up a todo list, but to actually
-capture the essence, impact, effort, and timeline of obligations and then
-support and facilitate timely action towards them, but without abusing my
-limited attention span. Think:
+meetings, etc. and not just build up a todo list, but actually capture the
+essence, impact, effort, and timeline of obligations and then facilitate timely
+action without abusing my limited attention span. Think:
 
 > Hey boss, I know we have that project meeting next Thursday but I don't think
 > we've prepped yet - tomorrow looks pretty open so I've put a 90 minute focus
@@ -37,107 +35,135 @@ January 1st, 2026, I decided to start an experiment, bolting [PydanticAI] on top
 of [Obsidian] and piping communication through [Signal]. What exists now is a
 maturation & formalization of that initial prototype, redesigned from the ground
 up with crisp boundaries to ensure:
-* extensibility
-* observability
-* transparency
 * governance
+* transparency
+* observability
+* extensibility
+
+------------------------------------------------------------------------
+## What It Does Today
+* Conversational interaction over [Signal] and a local console TUI.
+* Read/write your [Obsidian] vault with revision-safe edits, atomic moves, and
+  trash-aware deletes.
+* Semantic vault search using local embeddings and [Qdrant].
+* Governed tool execution: every Op is policy-gated and real-world side effects
+  flow through approval-aware gateways. Every invocation is auditable.
+* First-class [MCP] integration for third-party tools, with per-tool effect and
+  approval classification.
+* Commitment capture, miss detection, and timing-aware operator reminders.
+* Scheduled and background work via the Worker actor, plus optional Subagent
+  delegation for focused, budget-bounded subtasks.
+* Universal ingestion pipeline: capture → normalize → anchor →
+  index, for arbitrary content.
+
+See the [Roadmap](docs/roadmap.md) for what's next.
 
 ------------------------------------------------------------------------
-## Overview
-*Conceptually*, Brain has three primary domains:
+## Conceptual Model
+Brain has three primary domains:
 1. A **personal knowledge base**: durable, human-readable, locally-stored
    information. At its simplest, this could be a single (if very large) file.
 2. A **reasoning engine**: an LLM used to interpret context, propose actions,
    explain decisions, and interact with you conversationally.
-3. **Ops**: governed functions that interact with the real world (files,
-   calendars, messaging, etc.) via native APIs or MCP Servers.
+3. **Ops**: governed, testable units of action that wrap a single capability
+   (e.g. "create a calendar event") via native APIs or MCP Servers.
 
-*Operationally*, the system takes advantage of Docker for process isolation. In
-an ideal world every process would be containerized, but for various reasons
-(security, usability, performance) there are a limited number of services that
-need to run directly on your host system:
+Internally those domains are organized along two orthogonal axes — Planes
+(what does it own?) and Tiers (who is allowed to talk to whom?).
+
+### Planes
+* **State**: owns data
+* **Effect**: owns action
+* **Reason**: owns coordination
+
+### Tiers
+* **3 (Actors)**: operator interaction surface
+* **2 (Services)**: internal business logic
+* **1 (Resources)**: integrations with the outside world
+
+The Boundaries & Responsibilities diagram is a conceptual map of those axes. It
+is not a deployment or data flow diagram and it doesn't describe the full scope
+of the project, but it captures how control flow, cohesion, and decoupling are
+intended to work. See the full [Boundaries &
+Responsibilities](docs/boundaries-and-responsibilities.md) document for details.
+
+![Boundaries & Responsibilities](img/boundaries-and-responsibilities.png)
+
+------------------------------------------------------------------------
+## Runtime Topology
+Brain uses Docker for process isolation. In an ideal world every process would
+be containerized, but for security, usability, and performance reasons a
+limited number of services need to run directly on the host:
 * [Obsidian] with the [Local REST API] plugin — *required*
 * [Ollama] — *recommended* for embedding, *optional* for inference
+* Companion project [Host MCP Gateway] — a bridge to localhost APIs;
+  *optional*
 
-All other services are run in isolation with Docker Compose:
+All other services run in isolation under Docker Compose:
 * Brain Assistant, built with [PydanticAI]
 * Brain Core, which houses all runtime *State*, *Effect*, and *Reason*
   Components
 * Brain Worker and Subagent, for async/parallel work
 * Brain MCP Adapter sidecar, connecting to configured MCP servers
 * Secure messaging thanks to [Signal]
-* Durable working state and application logs are kept in [Postgres]
-* Caching and queueing are handled by [Valkey]
-* Vector search for semantic embeddings is powered by [Qdrant]
-* Object blobs are stored in [SeaweedFS]
+* Durable working state and application logs in [Postgres]
+* Caching and queueing handled by [Valkey]
+* Vector search for semantic embeddings powered by [Qdrant]
+* Object blobs stored in [SeaweedFS]
 
 There is also an optional OpenTelemetry-based observability stack in
 `docker-compose.observability.yaml`. It routes Brain traces through an OTel
 Collector to self-hosted [Langfuse] (backed by [ClickHouse]) and [Grafana]
-([Prometheus], [Loki], [cAdvisor]) as well as the existing [Postgres], [Valkey],
+([Prometheus], [Loki], [cAdvisor]), on top of the existing [Postgres], [Valkey],
 and [SeaweedFS] services. See [Observability](docs/observability.md) for
-connection details, required secrets, environment variables, and startup checks.
+connection details, required secrets, environment variables, and startup
+checks.
 
 ------------------------------------------------------------------------
-## Architecture
-The most useful way to understand the system structure is the Boundaries &
-Responsibilities diagram — a conceptual map of _Tiers_, _Planes_, _Actors_,
-_Services_, and _Resources_. It is not a deployment or data flow diagram and it
-does not describe the full scope of the project, but it does a good job at
-visualizing how I think about control flow, cohesion, and decoupling.
-
-### Planes
-* **State**: owns data
-* **Effect**: owns action
-* **Reason**: owns coordination
-
-### Tiers
-* **3 (Actors)**: operator interaction surface
-* **2 (Services)**: internal business logic
-* **1 (Resources)**: integrations with outside world
-
-See the full [Boundaries &
-Responsibilities](docs/boundaries-and-responsibilities.md) document for details.
-
-![Boundaries & Responsibilities](img/boundaries-and-responsibilities.png)
+## Quickstart
+On macOS, with Docker, Python 3.14, and [Obsidian] + the [Local REST API]
+plugin already installed:
+```sh
+make deps
+cp .env.sample .env
+mkdir -p ~/.config/brain
+for f in config/*.yaml.sample; do
+  cp "$f" ~/.config/brain/"$(basename "$f" .sample)"
+done
+# edit ~/.config/brain/secrets.yaml with your API keys, etc.
+make up
+```
+
+See the [Development Guide](docs/development-guide.md) for full prerequisites,
+configuration details, and the test/lint workflow.
 
 ------------------------------------------------------------------------
 ## Key Documentation
-- [Manifesto](docs/manifesto.md) — Design philosophy, first principles,
-  and architectural invariants.
-- [Boundaries & Responsibilities](docs/boundaries-and-responsibilities.md)
-  — Tier model, system model, service catalog, and shared infrastructure.
-- [Project Layout](docs/project-layout.md) — Directory structure mapped to
-  the conceptual model.
-- [Glossary](docs/glossary.md) — Term definitions (generated from YAML).
-- [Configuration Reference](docs/configuration.md) — Config file schema,
-  environment variable overrides, and per-section key reference.
-- [Service API Reference](docs/service-api.md) — Public API surface
-  (generated from code).
-- [Development Guide](docs/development-guide.md) — Setup, make targets,
+For the full index see the [`docs/`](docs/) directory, but this is where I'd
+start as a gentle introduction:
+* [Manifesto](docs/manifesto.md) — Design philosophy and first
+  principles.
+* [Boundaries & Responsibilities](docs/boundaries-and-responsibilities.md)
+  — Tier and Plane model, service catalog, and shared infrastructure.
+* [Development Guide](docs/development-guide.md) — Setup, make targets,
   testing, and contributor workflows.
-- [Roadmap](docs/roadmap.md) — Phased implementation plan and current
+* [Roadmap](docs/roadmap.md) — Phased implementation plan and current
   status.
 
 ------------------------------------------------------------------------
-## See Also
-* [OpenClaw]: Better than Brain in a lot of ways, but wihout privacy, security,
-  and governance as first-class architectural primitives.
-* [Hermes Agent]: Purportedly more dynamic and self-modifying than OpenClaw.
-* [Claude Cowork]: An agentic tool, but not long-lived, and largely bound by MCP
+## License
+Released under the [MIT License](LICENSE.txt).
 
-------------------------------------------------------------------------
-## Getting Started
-See the [Development Guide](docs/development-guide.md) for prerequisites,
-environment setup, and how to build/test.
 
 [Claude Cowork]: https://claude.com/product/cowork
 [ClickHouse]: https://clickhouse.com
 [Grafana]: https://grafana.com
 [Hermes Agent]: https://github.com/NousResearch/hermes-agent
+[issues]: https://github.com/cmtonkinson/brain/issues
 [Langfuse]: https://langfuse.com
 [Local REST API]: https://github.com/coddingtonbear/obsidian-local-rest-api
 [Loki]: https://grafana.com/oss/loki/
+[MCP]: https://modelcontextprotocol.io
 [Obsidian]: https://obsidian.md
 [Ollama]: https://ollama.com
 [OpenClaw]: https://github.com/openclaw/openclaw
@@ -149,6 +175,7 @@ environment setup, and how to build/test.
 [Signal]: https://signal.org
 [Valkey]: https://valkey.io
 [cAdvisor]: https://github.com/google/cadvisor
+[Host MCP Gateway]: https://github.com/cmtonkinson/host-mcp-gateway
 
 
 ------------------------------------------------------------------------