Brain 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 install-hooks --agent codex   # Codex project-local hooks.json; startup/resume/compact
brain uninstall-hooks --agent codex # remove only the Codex 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:

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.