feat: bootstrap BoxBrain foundation

README.md

@@ -1,2 +1,26 @@
 # BoxBrain
 
+BoxBrain is an IdentityDB-backed TypeScript framework for creating synthetic personas that can behave like human-like DM contacts.
+
+The project is framework-first rather than product-first. It provides typed services and adapter contracts for:
+
+- initializing a persona from personality, history, values, preferences, and relationships
+- storing one persona per IdentityDB memory space
+- generating and persisting schedule and availability facts
+- running DM-style conversations with short multi-message replies and human-like typing delays
+- choosing AI text, structured-output, and image providers through simple adapters
+
+## Development
+
+```bash
+bun install
+bun run test
+bun run check
+bun run build
+```
+
+## Current status
+
+The repository is in foundation development. See the implementation plan:
+
+- `docs/plans/2026-05-11-boxbrain-foundation.md`