| name | brain-page |
| description | Operating manual for reading and writing a project's brain — every read and write goes through the bundled zero-dependency `brain` CLI; never hand-edit brain files. Read it before creating or modifying any page or root page. |
brain-page
This skill is the operating manual for working with a project's brain under the Open Project Brain Standard. The protocol overview lives in the project's root BRAIN.md; here we expand the category taxonomy and the exact command for every operation.
The model is simple: everything goes through the brain CLI.
- Read =
brain read subcommands (brain-dir / list-pages / read-page <id> / read-root <slug>) — location-independent, no need to know where the brain lives.
- Write =
brain write subcommands. Every mutation (create / update / append / archive / tag / root-page rewrite / reindex) is correct-by-construction, so frontmatter can never be mis-shaped and a compiled_truth rewrite can never silently skip its timeline entry.
NEVER hand-edit any file under the brain directory. All reads and writes MUST go through the brain CLI. Manual edits are unsupported and illegitimate. Correctness is guaranteed by construction inside the CLI — there is no validator, and nothing at the file layer can catch or undo a bad manual edit, so a hand edit silently breaks the brain's invariants. Always reach for a brain subcommand instead of an editor.
Invoking the CLI
The CLI ships inside this skill bundle at bin/brain.mjs. It is zero-dependency Node (ESM) — run it directly:
node <this-skill-bundle>/bin/brain.mjs <subcommand> [flags]
Resolve <this-skill-bundle> to the directory this SKILL.md lives in. In the brain.md source repository itself that path is skills/brain-page/bin/brain.mjs; when the skill is installed globally it is wherever setup linked it (e.g. ~/.claude/skills/brain-page/bin/brain.mjs). Run all commands from the project root.
The CLI resolves the brain directory itself: it reads brainRoot from ./.mindmux/preferences.json when present (absolute or relative to the project root), otherwise falls back to ./brain. A missing file, broken JSON, or absent field all fall back silently. Run brain brain-dir to see the resolved directory and its source.
Run node <bundle>/bin/brain.mjs help for the full flag reference.
Read operations
Define a shell function (do not use BRAIN="node <bundle>/bin/brain.mjs"; $BRAIN … — VAR="node x"; $VAR only word-splits in bash; zsh, macOS's default shell, treats node /…/brain.mjs as a single command name and fails with exit 127. A function is portable across bash and zsh, so keep this form):
brain() { node <bundle>/bin/brain.mjs "$@"; }
brain init # ensure BRAIN.md, scaffold empty brain, default-wire CLAUDE.md + AGENTS.md
brain wire # default wire both agent config files (optional --agent subset / all)
brain install-hooks # opt-in Claude Code SessionStart snapshot (project-local .claude/settings.json)
brain uninstall-hooks # remove that SessionStart hook
brain brain-dir # print the resolved brain directory + its source (brainRoot / default)
brain list-pages # list every page: id / title / category / status
brain read-page <id> # print brain/pages/<id>.md
brain read-root <slug> # print a root page brain/<slug>.md
Session-companion discipline (while coding)
- Start of a task: load relevant brain context (
list-pages / read-page / read-root).
- When a decision/constraint settles: capture it immediately via the CLI — do not wait to be asked.
- Pure implementation with no new decision: do not write to the brain.
- When overturning a prior conclusion:
update-truth and/or append-timeline --kind reversal (or archive-page).
- Never hand-edit brain files.
The five page categories
Each page's category must be one of:
| category | boundary (what to write) | typical compiled_truth structure |
|---|
project | The state and intent of a self-contained piece of work / sub-project / module — the part that can't be read straight from the code | goal, scope, current status, key constraints |
concept | A concept / term / mechanism that needs a shared, lasting understanding | definition, why it's this way, boundaries and counter-examples |
decision | An established judgment and its reasoning (the most common) | what was decided, alternatives, rationale, blast radius |
person | A relevant person / role, their preferences and responsibilities | who they are, what they care about, collaboration conventions |
reference | An external resource / object of analysis worth keeping | what it is, key takeaways, links, implications for this project |
When in doubt, most knowledge lands in decision or concept.
Page id conventions
- Use kebab-case for
id, semantically clear, e.g. markdown-over-sqlite, auth-flow.
- The
id must equal the filename (brain/pages/<id>.md, without the extension). The CLI enforces this.
- Once an id is referenced via
[[ ]] it should stay stable; renaming means updating every reference and re-running lint-links.
Write operations (every one is a CLI subcommand)
Assume the brain shell function defined above (brain() { node <bundle>/bin/brain.mjs "$@"; }) and that you are in the project root.
Create a page
brain create-page --id <kebab-id> --category <category> --title "<one-line title>" \
[--tags a,b] [--status active] [--source "<where this came from>"]
Generates brain/pages/<id>.md from the template (frontmatter + <!-- compiled_truth --> + a visible ## Timeline seeded with one kind: decision creation entry), then reindexes. Fill in the real compiled_truth afterwards via update-truth.
Rewrite compiled_truth (atomic with its timeline entry)
echo "<new compiled_truth markdown>" | brain update-truth --id <id> \
--summary "<what changed and why>" [--source "<source>"]
Reads the new compiled_truth from stdin, rewrites the compiled_truth section (canonical marker: <!-- compiled_truth -->), and in the same atomic write appends a kind: decision entry to the visible ## Timeline section and bumps updated. Changing the understanding and recording why are inseparable — you cannot do one without the other.
Append a timeline entry (append-only)
brain append-timeline --id <id> --kind <decision|evidence|reversal|note> \
--summary "<one line>" [--source "<source>"] [--affects a,b]
Appends to the end of the timeline only; existing entries are never touched.
Archive a page
brain archive-page --id <id> [--reversal-summary "<why it was overturned>"]
Sets status: archived, optionally appends a kind: reversal entry, then reindexes.
Change tags
brain set-tags --id <id> --tags a,b,c
Rewrite a root page
echo "<root page body markdown>" | brain update-root <slug>
<slug> must be one of the six fixed root pages: background / architecture / flow / mindmap / stack / roadmap. The CLI validates the slug, rewrites the whole brain/<slug>.md, regenerates the frontmatter, and guarantees the canonical H1 heading is present. Root pages have no timeline — their history lives in git. Lean on ```mermaid blocks (graph / sequenceDiagram / mindmap / gantt) to keep them visual.
Index / checks
brain reindex # rebuild brain/index.md (also run automatically by the write commands above)
brain lint-links # verify current [[page-id]] links resolve
lint-links treats Page compiled_truth as the current knowledge graph and root page bodies as current root knowledge. It intentionally does not lint Page timeline entries, because timeline is append-only provenance and may contain historical syntax examples or obsolete references.
Why there is no validator
There is deliberately no validate command. Because every write goes through this CLI, the failure modes a validator used to guard are structurally impossible: frontmatter is always CLI-generated, and update-truth rewrites compiled_truth and appends its timeline entry in one atomic write. The guarantee holds only as long as you never hand-edit a brain file — there is nothing to catch a manual edit afterwards. reindex and lint-links remain as optional hygiene, not load-bearing gates.
Cross-page references
- Always reference another page with
[[page-id]] (the bare id, without brackets, is for filenames / CLI flags).
- After adding references, run
lint-links to confirm nothing is broken.
- Do not wrap root-page slugs, file paths, ordinary words, or uncertain entities in
[[ ]].
