brain-component-composition

name	brain-component-composition
description	Design and maintain composable data-backed Brain MDSvX components for pi-notes. Use when creating or editing `.brain/**/*.svx`, `.brain/components`, `.brain/data`, pi-notes Document Host components, review surfaces, or notes that should render JSONL, SQLite, Postgres, remote data, or reusable web shapes.
license	MIT

Brain Component Composition

Use this before substantial Brain note, MDSvX component, review surface, or data-backed documentation work.

This adapts the useful parts of Vercel's composition patterns to Svelte, MDSvX, and pi-notes. Brain is not flat markdown. Brain is frontmatter, prose, data contracts, and components composed into surfaces that agents and humans can both understand.

Mandate

• Treat .brain/components as a real project component library, not demo code.
• When a Brain shape repeats or depends on structured data, make or improve a component.
• Keep raw machine facts in .brain/data or a named data source. Keep .svx readable and sparse.
• Components should make the data easier for an agent to consume and a human to review. If the component hides provenance or schema, it is wrong.
• Prefer components that can later flow into local review pages, static reports, emails, or product pages.

Brain hierarchy

Before designing a Brain surface, locate the relevant layers:

1. System Brain: the user-level Brain, often ~/.brain, for global operator doctrine, reusable concepts, and cross-project context.
2. Project Brain: ./.brain, for local projects, areas, resources, archives, receipts, and private domain data.