ultimate-brain 0.0.0-stage → 0.2.0

package/.agents/skills/brain-sync/references/formats.md

@@ -0,0 +1,53 @@
+# Sync input formats
+
+A copy of the inputs in spec/cli.md §5.14, so the skill works from inside a brain where the product spec is not readable. If they ever disagree, the spec wins; report the difference.
+
+## Snapshot (input to `brain sync plan`)
+
+```json
+{
+  "as_of": "2026-12-05T09:00:00Z",
+  "rows": [
+    {
+      "database": "people",
+      "page_id": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
+      "last_edited": "2026-12-05T08:40:00Z",
+      "properties": {
+        "Name": "Maria López", "Summary": "Product lead at Acme.", "Role": "Product lead",
+        "Email": "maria@acme.example", "Lifecycle": "Reviewed",
+        "Brain ID": "per-3h8w2n6c", "Org": ["9b8a7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d"]
+      }
+    }
+  ]
+}
+```
+
+- `database`: the `brain.json` key: `areas`, `goals`, `key_results`, `projects`, `people`, `orgs`, `decisions`, `questions` or `review`.
+- `properties`: the Notion property names exactly, with normalized values:
+
+  | Notion type | Normalized value |
+  |---|---|
+  | title, text, select, status, url, email | string; empty → `null` |
+  | number | number or `null` |
+  | checkbox | boolean |
+  | date | `{"start": "<date or timestamp>", "end": "<…>" or null}` or `null` |
+  | relation | array of page ids, sorted |
+  | formula, rollup | their scalar result |
+- A property you did not read is left out, and is then not compared.
+
+## Plan (input to `brain sync apply` and `brain sync render --plan`)
+
+The `data` object of the `sync plan` reply, unchanged. Not the whole reply.
+
+## Record (input to `brain sync record`)
+
+```json
+{ "records": [
+  { "id": "per-3h8w2n6c", "notion": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
+    "synced_at": "2026-12-05T09:01:10Z", "published": { "Name": "Maria López", "Brain ID": "per-3h8w2n6c" } }
+] }
+```
+
+- One record per page actually written. `synced_at` is required.
+- `published`: the render item's `published`, unchanged.
+- `tasks` (meetings only): the new task page ids.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rodrigo Cano
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+# Ultimate Brain
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An AI-assisted second brain for solo knowledge workers. Knowledge lives in Markdown + Git, is maintained by coding agents (Claude Code, Codex), and is reviewed and navigated in Notion.
+
+This repository is the **product**: CLI, agent skills, schema, templates and the Notion space design. Each user's brain lives in its own private repository.
+
+**Status:** v1, in use by its author. Expect changes.
+
+## Install
+
+Needs Node 22.6 or later.
+
+```sh
+npm install -g ultimate-brain
+brain init ~/brain --set-default   # a new brain repository
+brain --help
+```
+
+The agent skills come with it: `brain init` copies them into the brain for Codex, and Claude Code gets them as the `ultimate-brain` plugin.
+
+## Update
+
+```sh
+npm install -g ultimate-brain@latest
+cd ~/brain && brain upgrade && git commit -am "upgrade: ultimate brain"
+```
+
+`brain upgrade` refreshes the brain's product-owned rules and skills. It never touches your notes.
+
+## Start here
+
+| Document | What it is |
+|---|---|
+| [docs/vision.md](docs/vision.md) | Product intent, v1 scope and success criterion |
+| [synthesis/synthesis.md](synthesis/synthesis.md) | The v1 design: schema, meeting-ingest workflow, Notion bridge |
+| [docs/notion-space-design.md](docs/notion-space-design.md) | Notion databases, views, and the Notion AI prompts to build them |
+| [decisions/](decisions/) | Every accepted architecture decision |
+| [build/TASKS.md](build/TASKS.md) | Build plan split between Claude Code and Codex |
+| [reviews/](reviews/) | Research: reviews of five open-source second-brain repos |
+
+Agent rules live in [AGENTS.md](AGENTS.md); `CLAUDE.md` imports it.

package/bin/brain.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+// Committed launcher, so the bin path exists before the build (npm checks bin paths before prepack).
+import { runCli } from "../dist/cli.js";
+
+process.exitCode = await runCli(process.argv.slice(2));

package/dist/cli.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { applyCommand } from "./commands/apply.js";
+import { indexCommand } from "./commands/index.js";
+import { initCommand } from "./commands/init.js";
+import { statusCommand } from "./commands/status.js";
+import { configGetCommand, configSetCommand } from "./commands/config.js";
+import { idNewCommand } from "./commands/id.js";
+import { lintCommand } from "./commands/lint.js";
+import { logCommand } from "./commands/log.js";
+import { noteNewCommand } from "./commands/note.js";
+import { linkCommand } from "./commands/link.js";
+import { upgradeCommand } from "./commands/upgrade.js";
+import { proposalListCommand, proposalNewCommand } from "./commands/proposal.js";
+import { queryCommand } from "./commands/query.js";
+import { syncApplyCommand, syncPlanCommand, syncRecordCommand, syncRenderCommand, syncTasksCommand } from "./commands/sync.js";
+import { viewsCommand } from "./commands/views.js";
+import { runCommand } from "./lib/command.js";
+import { exitCodeFor } from "./lib/errors.js";
+/** Registered commands, in help order. */
+export const COMMANDS = [
+    initCommand, statusCommand, configGetCommand, configSetCommand, idNewCommand, indexCommand, lintCommand, logCommand, noteNewCommand, proposalNewCommand, proposalListCommand, applyCommand,
+    syncPlanCommand, syncApplyCommand, syncRenderCommand, syncTasksCommand, syncRecordCommand, viewsCommand, linkCommand, queryCommand, upgradeCommand,
+];
+export const HELP_TEXT = `Usage: brain <command> [options]
+
+Operate an Ultimate Brain repository. Contract: spec/cli.md.
+
+Global options:
+  --brain <path>    Brain directory (else BRAIN_DIR, else ~/.config/ultimate-brain/config.json)
+  --json            Print one JSON document on stdout
+  --now <time>      Use this ISO 8601 UTC time as "now"
+  -h, --help        Show help
+
+Commands:
+${COMMANDS.map((command) => `  ${command.name.padEnd(16)}${command.summary.split(". ")[0].replace(/\.$/, "")}`).join("\n")}
+`;
+const defaultIo = {
+    stdout: process.stdout,
+    stderr: process.stderr,
+};
+export async function runCli(args, options = {}) {
+    const io = options.io ?? defaultIo;
+    const [first] = args;
+    if (first === undefined || first === "help" || first === "--help" || first === "-h") {
+        io.stdout.write(HELP_TEXT);
+        return 0;
+    }
+    const handlers = new Map();
+    for (const command of COMMANDS) {
+        handlers.set(command.name, (rest, commandIo) => runCommand(command, rest, commandIo, options));
+    }
+    for (const [name, handler] of options.commands ?? [])
+        handlers.set(name, handler);
+    // Longest command path first, so "note new" wins over "note".
+    for (const words of [2, 1]) {
+        const name = args.slice(0, words).join(" ");
+        const handler = args.length >= words ? handlers.get(name) : undefined;
+        if (handler !== undefined)
+            return handler(args.slice(words), io);
+    }
+    const message = `Unknown command: ${first}`;
+    if (args.includes("--json")) {
+        io.stdout.write(`${JSON.stringify({ ok: false, command: first, brain: null, error: { code: "USAGE", message } })}\n`);
+    }
+    else {
+        io.stderr.write(`${message}\nRun "brain --help" for usage.\n`);
+    }
+    return exitCodeFor("USAGE");
+}
+const entryPoint = process.argv[1];
+if (entryPoint !== undefined && isEntryPoint(entryPoint)) {
+    process.exitCode = await runCli(process.argv.slice(2));
+}
+function isEntryPoint(entryPoint) {
+    try {
+        return realpathSync(entryPoint) === fileURLToPath(import.meta.url);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/commands/apply.js

@@ -0,0 +1,34 @@
+import { applyAll, parseApplyInput } from "../lib/apply.js";
+import { readJsonInput } from "../lib/input.js";
+import { Workspace } from "../lib/workspace.js";
+import { lintWarnings } from "../lib/warnings.js";
+/** `brain apply [--input <file|->] [--record-only] [--dry-run]` (spec/cli.md §5.7). */
+export const applyCommand = {
+    name: "apply",
+    usage: "brain apply [--input <file|->] [--record-only] [--dry-run] [--json]",
+    summary: "Apply decided proposals and Notion corrections. Atomic per item; exits 1 if any item failed.",
+    options: { input: "string", "record-only": "boolean", "dry-run": "boolean" },
+    maxPositionals: 0,
+    needsBrain: true,
+    async run({ args, brain, now }) {
+        const path = args.options.input;
+        const input = path === undefined ? { corrections: [], decisions: null } : parseApplyInput(await readJsonInput(path, "apply"));
+        const dryRun = args.options["dry-run"] === true;
+        const workspace = await Workspace.open(brain);
+        const result = applyAll(workspace, input, { now, recordOnly: args.options["record-only"] === true });
+        const warnings = lintWarnings(workspace.warnings());
+        if (!dryRun) {
+            await workspace.commit(result.log, now);
+        }
+        const lines = [
+            ...result.corrections.map((item) => `${item.result} correction ${item.target} ${item.field}${item.reason === undefined ? "" : ` (${item.reason})`}`),
+            ...result.decisions.map((item) => `${item.result} ${item.proposal} ${item.action}${item.reason === undefined ? "" : ` (${item.reason})`}`),
+        ];
+        return {
+            data: { dry_run: dryRun, corrections: result.corrections, decisions: result.decisions, summary: result.summary },
+            warnings,
+            exitCode: result.summary.failed > 0 ? 1 : 0,
+            human: lines.length === 0 ? "Nothing to apply.\n" : `${lines.join("\n")}\n`,
+        };
+    },
+};

package/dist/commands/config.js

@@ -0,0 +1,96 @@
+import { BrainError } from "../lib/errors.js";
+import { atomicWriteFile } from "../lib/fs-safe.js";
+import { describeErrors, loadSchemas } from "../lib/schemas.js";
+/** `brain config get [<dot.path>]` (spec/cli.md §5.3). */
+export const configGetCommand = {
+    name: "config get",
+    usage: "brain config get [<dot.path>] [--json]",
+    summary: "Read brain.json, or one value selected by a dot path.",
+    options: {},
+    maxPositionals: 1,
+    needsBrain: true,
+    async run({ args, brain }) {
+        const [path] = args.positionals;
+        const value = path === undefined ? brain.config : readPath(brain.config, path);
+        return { data: path === undefined ? value : { path, value }, human: `${JSON.stringify(value, null, 2)}\n` };
+    },
+};
+/** `brain config set <dot.path> <json-value>` (spec/cli.md §5.3). */
+export const configSetCommand = {
+    name: "config set",
+    usage: "brain config set <dot.path> <json-value> [--json]",
+    summary: "Set one brain.json value after validating the complete configuration.",
+    options: {},
+    maxPositionals: 2,
+    needsBrain: true,
+    async run({ args, brain }) {
+        const [path, rawValue] = args.positionals;
+        if (path === undefined || rawValue === undefined) {
+            throw new BrainError("USAGE", "brain config set needs <dot.path> and <json-value>");
+        }
+        const segments = parsePath(path);
+        if (segments.length === 1 && segments[0] === "schema_version") {
+            throw new BrainError("INPUT_INVALID", "schema_version cannot be changed");
+        }
+        let value;
+        try {
+            value = JSON.parse(rawValue);
+        }
+        catch (error) {
+            throw new BrainError("INPUT_INVALID", `Config value is not JSON: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const next = structuredClone(brain.config);
+        const previous = setPath(next, segments, value);
+        const schemas = loadSchemas();
+        if (!schemas.brain(next)) {
+            throw new BrainError("INPUT_INVALID", `brain.json would be invalid: ${describeErrors(schemas.brain.errors).join("; ")}`);
+        }
+        await atomicWriteFile(brain.root, "brain.json", `${JSON.stringify(next, null, 2)}\n`);
+        return {
+            data: { path, previous: previous ?? null, value },
+            human: `${path}: ${JSON.stringify(previous)} → ${JSON.stringify(value)}\n`,
+        };
+    },
+};
+function readPath(config, path) {
+    const segments = parsePath(path);
+    let current = config;
+    for (const segment of segments) {
+        if (!isRecord(current) || !(segment in current)) {
+            throw new BrainError("USAGE", `No configuration value at ${path}`);
+        }
+        current = current[segment];
+    }
+    return current;
+}
+function setPath(config, segments, value) {
+    let current = config;
+    for (const segment of segments.slice(0, -1)) {
+        const next = current[segment];
+        if (next === undefined) {
+            const created = {};
+            current[segment] = created;
+            current = created;
+        }
+        else if (isRecord(next)) {
+            current = next;
+        }
+        else {
+            throw new BrainError("INPUT_INVALID", `Cannot create ${segments.join(".")}: ${segment} is not an object`);
+        }
+    }
+    const final = segments[segments.length - 1];
+    const previous = current[final];
+    current[final] = value;
+    return previous;
+}
+function parsePath(path) {
+    const segments = path.split(".");
+    if (path === "" || segments.some((segment) => !/^[A-Za-z_][A-Za-z0-9_]*$/.test(segment))) {
+        throw new BrainError("USAGE", `Invalid configuration path: ${path}`);
+    }
+    return segments;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/commands/id.js

@@ -0,0 +1,32 @@
+import { BrainError } from "../lib/errors.js";
+import { generateId, TYPE_PREFIX } from "../lib/ids.js";
+import { Workspace } from "../lib/workspace.js";
+/** `brain id new <type> [--count <n>]` (spec/cli.md §5.4). */
+export const idNewCommand = {
+    name: "id new",
+    usage: "brain id new <type> [--count <n>] [--json]",
+    summary: "Generate unused, prefixed note IDs. IDs are not reserved.",
+    options: { count: "string" },
+    maxPositionals: 1,
+    needsBrain: true,
+    async run({ args, brain }) {
+        const [type] = args.positionals;
+        const prefix = type === undefined ? undefined : TYPE_PREFIX[type];
+        if (prefix === undefined)
+            throw new BrainError("USAGE", `Unknown note type: ${type ?? "(missing)"}`);
+        const rawCount = args.options.count;
+        const count = rawCount === undefined ? 1 : Number(rawCount);
+        if (!Number.isInteger(count) || count < 1 || count > 100) {
+            throw new BrainError("USAGE", "--count must be an integer from 1 through 100");
+        }
+        const workspace = await Workspace.open(brain);
+        const existing = workspace.ids();
+        const ids = [];
+        for (let index = 0; index < count; index += 1) {
+            const id = generateId(prefix, existing);
+            existing.add(id);
+            ids.push(id);
+        }
+        return { data: { type, ids }, human: `${ids.join("\n")}\n` };
+    },
+};

package/dist/commands/index.js

@@ -0,0 +1,58 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { atomicWriteFile } from "../lib/fs-safe.js";
+import { buildIndex } from "../lib/index-builder.js";
+import { scanNotes } from "../lib/notes.js";
+/** `brain index [--check]` (spec/cli.md §5.8, spec/schema.md §13). */
+export const indexCommand = {
+    name: "index",
+    usage: "brain index [--check] [--json]",
+    summary: "Regenerate index.md from note frontmatter. --check writes nothing and exits 1 if index.md is out of date.",
+    options: { check: "boolean" },
+    maxPositionals: 0,
+    needsBrain: true,
+    async run({ args, brain }) {
+        const root = brain.root;
+        const check = args.options.check === true;
+        const { notes, problems } = await scanNotes(root);
+        const built = buildIndex(notes);
+        const warnings = [
+            ...problems.map((problem) => ({ code: problem.code, message: `${problem.path}: ${problem.message}`, path: problem.path })),
+            ...built.duplicates.map((duplicate) => ({
+                code: "DUPLICATE_ID",
+                message: `${duplicate.id} in ${duplicate.path} is also in ${duplicate.kept}; kept ${duplicate.kept}`,
+                path: duplicate.path,
+                id: duplicate.id,
+            })),
+        ];
+        let current;
+        try {
+            current = await readFile(join(root, "index.md"), "utf8");
+        }
+        catch {
+            current = null;
+        }
+        const differs = current !== built.markdown;
+        const written = !check && differs;
+        if (written)
+            await atomicWriteFile(root, "index.md", built.markdown);
+        // `stale`: index.md is out of date after this command (only possible with --check).
+        const stale = check && differs;
+        const human = check
+            ? differs ? "index.md is out of date (run brain index)\n" : "index.md is current\n"
+            : written ? `index.md updated (${built.entries.length} notes)\n` : "index.md already current\n";
+        return {
+            data: {
+                written,
+                stale,
+                path: "index.md",
+                counts: built.counts,
+                notes: built.entries,
+                backlinks: built.backlinks,
+            },
+            warnings,
+            exitCode: check && stale ? 1 : 0,
+            human,
+        };
+    },
+};

package/dist/commands/init.js

@@ -0,0 +1,233 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { lstat, mkdir, readdir, readFile, realpath } from "node:fs/promises";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { BrainError } from "../lib/errors.js";
+import { atomicWriteFile, ensureDirectory } from "../lib/fs-safe.js";
+import { buildIndex } from "../lib/index-builder.js";
+import { isProductRepository } from "../lib/brain-path.js";
+import { appendLog } from "../lib/log.js";
+import { scanNotes } from "../lib/notes.js";
+import { listShippedSkillFiles } from "../lib/skills.js";
+const exec = promisify(execFile);
+const TEMPLATE_ROOT = fileURLToPath(new URL("../../templates/brain/", import.meta.url));
+/** `brain init <path>` (spec/cli.md §5.1). */
+export const initCommand = {
+    name: "init",
+    usage: "brain init <path> [--owner <name>] [--force] [--no-git] [--set-default] [--json]",
+    summary: "Create a new Ultimate Brain repository from the versioned template.",
+    options: { owner: "string", force: "boolean", "no-git": "boolean", "set-default": "boolean" },
+    maxPositionals: 1,
+    needsBrain: false,
+    async run({ args, now, environment }) {
+        const [requested] = args.positionals;
+        if (requested === undefined)
+            throw new BrainError("USAGE", "brain init needs a target path");
+        const target = resolve(requested);
+        const present = await inspectTarget(target);
+        if (present.kind === "file")
+            throw new BrainError("TARGET_NOT_EMPTY", `Brain target is not a directory: ${target}`);
+        if (!present.exists)
+            await mkdir(target, { recursive: true });
+        const root = await realpath(target);
+        if (await isProductRepository(root)) {
+            throw new BrainError("BRAIN_IS_PRODUCT_REPO", `Refusing to initialize the Ultimate Brain product repository: ${root}`);
+        }
+        if (await exists(join(root, "brain.json"))) {
+            throw new BrainError("ALREADY_A_BRAIN", `Target already contains brain.json: ${root}`);
+        }
+        if (present.entries.length > 0 && args.options.force !== true) {
+            throw new BrainError("TARGET_NOT_EMPTY", `Brain target is not empty: ${root}`);
+        }
+        const owner = args.options.owner ?? await defaultOwner();
+        if (owner.trim() === "")
+            throw new BrainError("USAGE", "--owner must not be empty");
+        const created = [];
+        const skipped = [];
+        const template = await listTemplateFiles();
+        for (const file of template) {
+            if (await exists(join(root, file.relative))) {
+                skipped.push(file.relative);
+                continue;
+            }
+            let content = await readFile(file.source, "utf8");
+            if (file.relative === "brain.json")
+                content = initialConfig(content, owner);
+            await ensureDirectory(root, dirname(file.relative));
+            await atomicWriteFile(root, file.relative, content);
+            created.push(file.relative);
+        }
+        // Product-owned Codex skills (decision 0029); like template files, existing ones are never overwritten.
+        for (const skill of await listShippedSkillFiles()) {
+            const path = `.agents/skills/${skill.relative}`;
+            if (await exists(join(root, path))) {
+                skipped.push(path);
+                continue;
+            }
+            await ensureDirectory(root, dirname(path));
+            await atomicWriteFile(root, path, skill.content);
+            created.push(path);
+        }
+        // The template includes an empty index, but build it rather than trusting that snapshot.
+        // With --force an existing index is left untouched along with every other existing template file.
+        if (!skipped.includes("index.md")) {
+            const { notes } = await scanNotes(root);
+            const index = buildIndex(notes).markdown;
+            await atomicWriteFile(root, "index.md", index);
+        }
+        const logPath = `log/${now.toISOString().slice(0, 7)}.md`;
+        const hadLog = await exists(join(root, logPath));
+        await appendLog(root, now, [{ op: "init", id: "-", title: owner, pairs: [["schema", 1]] }]);
+        if (!hadLog)
+            created.push(logPath);
+        const warnings = [];
+        const git = await initializeGit(root, args.options["no-git"] === true, warnings);
+        let defaultConfig;
+        if (args.options["set-default"] === true) {
+            defaultConfig = await writeDefaultConfig(root, environment.homeDirectory);
+        }
+        else {
+            defaultConfig = { written: false, path_abs: null, previous: null };
+        }
+        created.sort(comparePath);
+        skipped.sort(comparePath);
+        return {
+            resolvedBrain: root,
+            warnings,
+            data: {
+                path_abs: root,
+                created,
+                skipped,
+                git,
+                default_config: defaultConfig,
+            },
+            human: `Initialized Ultimate Brain at ${root}\n`,
+        };
+    },
+};
+async function inspectTarget(target) {
+    try {
+        const metadata = await lstat(target);
+        if (!metadata.isDirectory())
+            return { exists: true, kind: "file", entries: [] };
+        return { exists: true, kind: "directory", entries: await readdir(target) };
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT")
+            return { exists: false, kind: "directory", entries: [] };
+        throw error;
+    }
+}
+async function listTemplateFiles() {
+    const root = await realpath(TEMPLATE_ROOT);
+    const files = [];
+    async function visit(folder) {
+        for (const entry of await readdir(folder, { withFileTypes: true })) {
+            const source = join(folder, entry.name);
+            if (entry.isSymbolicLink())
+                throw new BrainError("OUTSIDE_ROOT", `Template contains a symbolic link: ${source}`);
+            if (entry.isDirectory())
+                await visit(source);
+            else if (entry.isFile()) {
+                const actual = await realpath(source);
+                assertInside(root, actual);
+                const templatePath = relative(root, actual).split(sep).join("/");
+                files.push({ source: actual, relative: templatePath === "gitignore" ? ".gitignore" : templatePath });
+            }
+        }
+    }
+    await visit(root);
+    return files.sort((left, right) => comparePath(left.relative, right.relative));
+}
+function initialConfig(template, owner) {
+    let config;
+    try {
+        config = JSON.parse(template);
+    }
+    catch (error) {
+        throw new BrainError("INTERNAL", `Brain template has invalid brain.json: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!isRecord(config) || !isRecord(config.owner))
+        throw new BrainError("INTERNAL", "Brain template has no owner configuration");
+    config.schema_version = 1;
+    config.owner.name = owner;
+    return `${JSON.stringify(config, null, 2)}\n`;
+}
+async function defaultOwner() {
+    try {
+        const { stdout } = await exec("git", ["config", "--get", "user.name"]);
+        const name = stdout.trim();
+        return name === "" ? "Owner" : name;
+    }
+    catch {
+        return "Owner";
+    }
+}
+async function initializeGit(root, noGit, warnings) {
+    if (noGit)
+        return { initialized: false, committed: false };
+    try {
+        await exec("git", ["init"], { cwd: root });
+        await exec("git", ["add", "--all"], { cwd: root });
+    }
+    catch {
+        warnings.push({ code: "GIT_COMMIT_SKIPPED", message: "Git initialization or staging failed; brain files were kept." });
+        return { initialized: false, committed: false };
+    }
+    try {
+        await exec("git", ["commit", "-m", "init: ultimate brain (schema v1)"], { cwd: root });
+        return { initialized: true, committed: true };
+    }
+    catch {
+        warnings.push({ code: "GIT_COMMIT_SKIPPED", message: "Git commit was skipped; configure a Git identity and commit the brain files." });
+        return { initialized: true, committed: false };
+    }
+}
+async function writeDefaultConfig(brain, homeDirectory) {
+    // `homeDirectory` is injectable for isolated CLI tests; production uses the current user's home.
+    const home = homeDirectory ?? process.env.HOME;
+    if (home === undefined || home === "")
+        throw new BrainError("INTERNAL", "Cannot determine home directory for --set-default");
+    const absoluteHome = resolve(home);
+    const root = await realpath(absoluteHome);
+    const folder = join(root, ".config", "ultimate-brain");
+    await ensureDirectory(root, ".config/ultimate-brain");
+    const configPath = join(folder, "config.json");
+    let previous = null;
+    try {
+        previous = JSON.parse(await readFile(configPath, "utf8"));
+    }
+    catch (error) {
+        if (!isNodeError(error) || error.code !== "ENOENT")
+            previous = "<unreadable>";
+    }
+    await atomicWriteFile(root, configPath, `${JSON.stringify({ brain }, null, 2)}\n`);
+    return { written: true, path_abs: configPath, previous };
+}
+async function exists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+function assertInside(root, target) {
+    const path = relative(root, target);
+    if (path === ".." || path.startsWith(`..${sep}`)) {
+        throw new BrainError("OUTSIDE_ROOT", `Template file resolves outside its root: ${target}`);
+    }
+}
+function comparePath(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}