brain-setup

Setup is one short conversation and the harness does the rest. The person may never have used git or a terminal: decide what you can, ask only what only they know, say what each step does in plain words, and run every command yourself. Never ask them to type a command or edit a file you can.

Where this sits

Runs after: nothing — an entry point into the tree.

Hand to next: brain-retro · brain-sync · brain-write-practice · brain-write-script · brain-write-skill

Call it directly when: someone says "set this up", doctor reports a BLOCK, the person wants an online backup, or the template's latest improvements; nothing needs to run first.

Which mode

Read brain.json role, and look for a local/ folder at the root:

• role is template, no local/: a copy of the template never set up (a download, a clone, a "Use this template" repository). Take the copy route. Only if the person says they want to develop the template itself do they create local/ instead.
• role is template with local/: the template's own checkout. Never run init here.
• Anything else: a brain. Go to "In a brain".

0. Check the computer first

Run these yourself and handle each in plain words before any question about the brain:

• python3 --version (3.9 or newer) and git --version. Missing on a Mac: run xcode-select --install and tell them a box will offer to install the developer tools: click Install and wait. On Linux: the package manager, with their password typed by them. On Windows outside WSL: stop, and say a brain needs WSL there.
• _meta/brain not executable (a download can lose that): chmod +x _meta/brain.
• git config --global user.name and user.email. If either is empty, ask: "What name and email should label the brain's saved history? They stay on this computer unless you back it up online." Set both with git config --global on their answer. A setting in this folder alone is lost when init starts the fresh history.

The copy route

1. Quick or thorough. Ask: "I can set this up in a few minutes with sensible defaults, or interview you first, about 10 to 15 minutes, so the brain starts out knowing your goals, your systems and how you work. Which would you like?" For the interview ("grill me"), read references/interview.md and run it now: its answers feed every step below. Quick is not a lesser brain: everything the interview would record can be added later, as the work shows it.
2. The shape. Read references/shapes.md. From the interview, or from what they asked for, pick one: a single project, several projects, a large brain with several kinds of work, or a hub that routes work to other brains. Say it in one line ("your site will live in site/ inside the brain"); ask only when it is unclear. A brain with no projects yet is a single-project brain whose project comes later.
3. Work out, don't quiz. Take the name and the one-line description from what they asked for, and ask only if it is unclear. Derive the prefix yourself (2 to 16 lowercase letters or digits, starting with a letter, never brain or template: "Home Lab" → lab) and say only "its routines will be called lab-…".
4. Ask about privacy: "Is there anything that must never be saved in this brain's history: server names, addresses, client or customer names, unreleased project names? Say them as you would write them. Never a password." Each answer is one --private term, as written; it matches in any case as a whole word. An address range or a family of names becomes one re: pattern you write (re:\b192\.168\.1\.\d{1,3}\b) and explain. Setup refuses a term under 3 characters, one that looks like a pattern without re:, and one that matches the brain's own name: say why, and adjust it with them. Tell them to keep their own copy of the list: it lives only on this computer.
5. Ask about the guides: "The template comes with guides on setting up and growing a brain, with pictures. Keep them in the brain for now? I can remove them whenever you like." Yes adds --keep-guides; they stay in docs/guides/, docs/images/ and docs/reference/ until asked.
6. Rehearse: _meta/brain init --name "N" --prefix P --description "D" --private "TERM" --dry-run, one --private per term, plus --keep-guides on a yes. It changes nothing. Summarise it: it removes the template's own instructions, tests and GitHub files (they are for people developing the template), adds the brain's starter files and saves the first version; say whether the history starts fresh.
7. On a yes, run it without --dry-run. It writes the brain, installs the safety check on saving (the pre-commit hook) and makes the first commit. Then _meta/brain doctor; fix any BLOCK with references/doctor.md.
8. Lay out the shape as references/shapes.md says: folders, projects cloned in on a yes, the CLAUDE.md folder map, brains add for a hub. After an interview, write its CLAUDE.md sections, then offer its hand-offs one at a time, in the order references/interview.md gives: glossary terms to brain-write-practice, each system to brain-write-script, recurring work to brain-retro as unclassified rows, a first routine or a hub's routing skill to brain-write-skill. Commit what this step wrote through brain-sync.
9. Ask about a backup once: "Do you want an online backup copy? It needs a free GitHub account." Yes: "Online backup" below. No: set brain.json "backup": "local" and commit it through brain-sync, so the session-start check stops asking.
10. Hand over: tell them to start a new chat in this same folder now (desktop app: the folder picker beside the environment selector, "Open folder…"), and to start every chat here: Claude Code reads the brain's settings, so its safety checks, only from the folder a chat starts in, and a chat inside a project folder misses them. Offer three things to say first, from README.md.

When init refuses, say why in plain words and do the fix with them: changes not yet saved → show them and ask whether to keep or throw them away (never discard yourself); commits only in this copy → explain they would be lost, and save them elsewhere first on a yes. Terms go to .brain-private only; never copy one into a tracked file.

Online backup

Read references/backup.md and follow it with the person: gh if it is there, else a private, empty repository made on github.com. They sign in in their own browser; never ask for a password or token, and never type one for them.

In a brain

Explain what is here when asked, in a few lines: brain.json (name, prefix, template version); _meta/brain routing show (entry points, skills nothing routes to); its own skills next to the brain-* ones; open rows in docs/RETRO-LOG.md; docs/UNCLASSIFIED-LOG.md (a kind seen twice is a skill waiting to be written); open suggestions from _meta/brain upstream list.

Run _meta/brain doctor (--quick skips the script tests, nested repos and the network). Fix every BLOCK; offer a fix for each WARN in plain words and make it on a yes; read references/doctor.md for the fix to each line. Then run it again. Every session starts with doctor --brief, which prints only WARN and BLOCK lines: when it printed any, tell the person what each means and offer the fix.

Hand-offs from other brains wait in docs/INBOX.md, and the session-start check names them. Read each out; on a yes, work it through the routing map like any request, then set its status to done (or declined: <reason>) and commit through brain-sync. A brain never writes into another: a hub hands work over with _meta/brain brains handoff, which writes only that inbox.

Remove the template's guides when asked: git rm -r docs/guides docs/images docs/reference, take their lines out of docs/README.md, and commit through brain-sync. The latest guides stay online at brain.json template.source.

Change shape or add a project with references/shapes.md: a new project is cloned into the brain on a yes and gets a folder-map line; a project is never moved without a yes.

Update from the template

1. Commit pending work first, through brain-sync, so the update's commit holds only the update.
2. _meta/brain update --dry-run. The source is brain.json template.source, or brain.local.json on this machine; pass --from <path or URL> if it moved. Show the person what it brings.
3. If it refuses over a local edit to a template-owned file, hand that to brain-upstream first.
4. On a yes, _meta/brain update, then _meta/brain doctor --quick. Skeleton files it reports as changed are the brain's own now: show the difference; merge it on a yes, or not.
5. Hand to brain-sync, which commits it alone as meta(brain): update template to <version> and marks the answered suggestions. update never commits.

Done when

• Copy route: the computer check passed; the person chose quick or the interview, and heard the shape in one line; they saw the rehearsal and said yes; init made the first commit; the shape's folders and CLAUDE.md lines are written and committed; every interview hand-off was offered; doctor shows no BLOCK; backup is set up or recorded as local; they know to start every chat in this folder.
• In a brain: doctor shows no BLOCK, and each WARN is fixed or the person chose to leave it.
• Update: the dry run was shown, update ran on a yes, doctor --quick shows no BLOCK, and the change is handed to brain-sync.
• Nothing was deleted, restored or untracked without a yes, and no .env value was read or printed.