Markdown format

​

Directory layout

.tiny-brain/
├── config.json                    ← project connection (teamId, projectId)
├── auth-flow/                     ← one directory per epic
│   ├── epic.md                    ← epic definition (required if directory exists)
│   ├── google-oauth.md            ← feature
│   ├── token-refresh.md           ← feature
│   └── logout-bug.md              ← fix
└── billing-portal/
    └── ...

• .tiny-brain/ lives at the repo root.
• Every subdirectory of .tiny-brain/ is an epic. The directory name is the epic’s id.
• Every .md file inside an epic directory is either an epic.md or a feature/fix file. There is no other document type.
• File names are slugs; id in the frontmatter must match the file name minus .md.

​

Document types

​

Pages

• Epics — epic file format
• Features — feature file format
• Fixes — fix file format
• Frontmatter — exhaustive field reference
• Task syntax — how ## Tasks sections parse

​

Design principles

1. Plain markdown. Renders correctly on GitHub, GitLab, in any IDE preview, in any LLM context. No proprietary syntax.
2. Minimal required fields. Templates that ship with the CLI use the minimum that lets the dashboard render something useful. Everything else is optional.
3. meta is the escape hatch. Tool-specific fields live under meta: so they don’t pollute the core schema. Other tools (tiny-brain, custom internal tooling) attach their own data there.
4. The format IS the API. The HTTP API speaks the same shape as the files. There is no separate “database schema” — projections are derived from the files you push.