@nfinitmonkeys/clan-engine 0.1.1 → 0.3.0

package/README.md

@@ -9,18 +9,27 @@ tooling all render from here, so their output can never drift apart again.
 `.mcp.json` instead of clobbering, backs up every file it touches, and journals
 every run so it can be undone exactly.
 
+## Tiers
+
+As of 0.3.0 the engine is authoritative for **clan, district, and jungle**
+tiers — one template source renders the right `/clan:*`, `/district:*`, or
+`/jungle:*` pack from the repo's declared `<!-- geo-tier: X -->`. **Biome is
+unbuilt**: asking for a biome pack throws (`no pack template for tier biome
+yet`) rather than emitting something half-real.
+
 ## Verbs
 
 ```
-clan-engine inspect [--repo .] [--json]     # map a repo's state (never mutates)
-clan-engine plan    [--repo .] --alpha X --name Y [--tier clan] [--json]
-clan-engine apply   [--repo .] --alpha X --name Y     # write it (backups + journal)
-clan-engine undo    [--repo .] [--journal <path>]     # reverse the last apply
-clan-engine doctor  [--repo .] [--json]     # validate the whole loop
+clan-engine inspect     [--repo .] [--json]     # map a repo's state (never mutates)
+clan-engine plan        [--repo .] --alpha X --name Y [--tier clan] [--json]
+clan-engine apply       [--repo .] --alpha X --name Y     # write it (backups + journal)
+clan-engine brain-build [--repo .] [--write] [--memory] [--json]   # mine the brain
+clan-engine undo        [--repo .] [--journal <path>]     # reverse the last apply
+clan-engine doctor      [--repo .] [--json]     # validate the whole loop
 ```
 
 `plan` is a dry run; `apply` writes. Both are idempotent — a second `apply`
-is all skips.
+is all skips. `--json` output masks live key values as `[redacted]` everywhere.
 
 ## What it authors
 
@@ -28,7 +37,13 @@ is all skips.
   never rewritten; only the `<!-- geo-tier: X -->` marker is ensured).
 - **`.claude/skills/clan-awareness/SKILL.md`** — the awareness skill in the
   directory format Claude Code actually loads (a flat file never loads).
-- **`.claude/commands/<tier>/*.md`** — tier-named slash-command pack.
+- **`.claude/commands/<tier>/*.md`** — tier-named slash-command pack, including
+  **`/<tier>:up`** — the wizard door. Clan tier gets the full conversational
+  setup/convert/repair playbook (Claude Code improvises the conversation; the
+  engine does every write); district/jungle get a short repair wizard (their
+  identity is provisioned by node-up, never interviewed). Generated wizard text
+  **version-pins** the engine (`npx -y @nfinitmonkeys/clan-engine@0.3`) so an
+  older published engine can never overwrite the pack that invoked it.
 - **`.mcp.json`** — a correctly-named `jungle-local` server **merged** alongside
   any servers you already have, and gitignored (it holds a live key). Never the
   bare name `jungle` (it collides with the global council server).
@@ -39,6 +54,39 @@ is all skips.
 - **`.clan/inventory.json`** — the user's EXISTING agents/skills/commands/hooks,
   so the Alpha works *with* them instead of duplicating.
 
+## brain-build
+
+Mines README, `docs/` (recursive), CLAUDE.md, package manifests, code structure,
+the inventory, and (`--memory`) Claude Code session memory into brain pages.
+Every source passes `scanSensitive` first — secrets, infra identifiers, and PHI
+are **held back and reported, never written**. Dry-run by default; `--write` to
+save; create-only (your accumulated pages are never touched).
+
+**LLM curation is API-only.** The engine itself has no LLM and the CLI has no
+`--curate` flag. Callers pass a hook:
+
+```js
+const res = await brainBuild(repo, identity, { curate: async ({ pages, identity, sourceNotes }) => curatedPages });
+```
+
+The caller brings the LLM (this is what `clan brain build --curate` does with
+the clan's configured provider); the engine re-gates **every** curated page
+through `scanSensitive` + create-only, and falls back to the mechanical pages
+with a note if the curator throws. Sanitization is not optional at any layer.
+
+## Existing-vault detection
+
+`inspect` finds the repo's REAL vault so setup and brain-build never scaffold a
+tier-default duplicate nothing loads. Precedence:
+
+1. the vault a live `load-brain` SessionStart hook already hydrates — wins
+   outright (the hook is ground truth for what sessions actually load);
+2. vaults containing `wiki/identity.md`, in order `.district/brain` >
+   tier-default root > `.brain` > `.brains/<alpha>` > other `.brains/*`
+   (preferring `obsidian`) — a real identity beats debris;
+3. bare-existing vaults in the same order;
+4. none → the tier default applies.
+
 ## Reconciliation
 
 Every generated file carries a `clan-engine@<v>` + `layout: <n>` marker. That's
@@ -46,16 +94,20 @@ how the engine tells its own output (safe to update) from a file you wrote at
 the same path (backed up, then replaced). Brain pages are create-only — your
 accumulated memory is never clobbered.
 
+`ENGINE_VERSION` (in `src/types.ts`) always equals the package version — the
+test suite fails on drift. `LAYOUT_VERSION` bumps only when generated output
+changes shape (that's what triggers migrations); `ENGINE_VERSION` bumps freely.
+
 ## Programmatic API
 
 ```js
-import { inspect, reconcile, apply, undo, doctor, setup } from '@nfinitmonkeys/clan-engine';
+import { inspect, reconcile, apply, undo, doctor, setup, brainBuild } from '@nfinitmonkeys/clan-engine';
 
 const { plan, result } = setup(repo, identity, { at, today });   // inspect → reconcile → apply
 ```
 
-The conversational setup wizard drives these verbs — the LLM improvises the
-conversation, the engine does every write.
+The conversational setup wizard (`/clan:up`) drives these verbs — the LLM
+improvises the conversation, the engine does every write.
 
 ## License
 

package/dist/apply.js

@@ -74,9 +74,15 @@ export function apply(plan, opts) {
     }
     let journalPath;
     if (!opts.noJournal && ops.length > 0) {
+        // NEVER journal a live key. The journal lives under .claude/ (which many
+        // repos commit); identity here is undo metadata, not a credential store —
+        // undo only reads ops. The key itself stays in .jungle/config.yaml.
+        const journalIdentity = plan.identity.jungle
+            ? { ...plan.identity, jungle: { ...plan.identity.jungle, apiKey: '[redacted]' } }
+            : plan.identity;
         const journal = {
             engineVersion: ENGINE_VERSION, layoutVersion: LAYOUT_VERSION,
-            at: runId, repo, identity: plan.identity, ops,
+            at: runId, repo, identity: journalIdentity, ops,
         };
         const jRel = join(runDir, `journal-${runId}.json`);
         const jAbs = join(repo, jRel);

package/dist/brain-build.d.ts

@@ -0,0 +1,49 @@
+/**
+ * brain-build — mine a clan's EXISTING files into brain wiki pages, so a new
+ * clan doesn't start with an empty brain. Sources: README, docs/, CLAUDE.md,
+ * package manifests, top-level code structure, the engine's inventory of the
+ * user's existing Claude Code assets, and (opt-in) Claude Code session memory.
+ *
+ * SAFETY (non-negotiable): every candidate body is scanned with scanSensitive
+ * BEFORE it becomes a page; anything that trips (secrets / infra ids / PHI) is
+ * HELD BACK, never written, and reported for the operator to review. Pages are
+ * create-only — accumulated brain content is never clobbered.
+ *
+ * Mechanical (no LLM required) — the right no-key base layer. LLM curation is
+ * an opt-in HOOK (opts.curate): the caller brings the LLM, the engine stays
+ * zero-LLM and re-gates everything the curator returns.
+ */
+import type { ClanIdentity, GeneratedFile, BrainCurator } from './types.js';
+export interface HeldBack {
+    from: string;
+    reasons: string[];
+}
+export interface BrainBuildResult {
+    pages: GeneratedFile[];
+    heldBack: HeldBack[];
+    scanned: number;
+    /** Operator-facing report lines (e.g. curation fallback) — never secrets. */
+    notes: string[];
+}
+export interface BrainBuildOpts {
+    home?: string;
+    hipaa?: boolean;
+    includeMemory?: boolean;
+    /** LLM curation hook — API-only (the engine CLI has no LLM to drive one).
+     *  Curated output replaces the candidates but every returned page re-passes
+     *  scanSensitive + create-only; a throwing curator falls back to the
+     *  mechanical pages with a note in the report. */
+    curate?: BrainCurator;
+}
+/**
+ * Mine existing files into brain pages. Every candidate is scanned; flagged
+ * ones are held back. Returns create-candidate pages + the held-back report.
+ * Without opts.curate the call stays synchronous (existing callers unchanged);
+ * with a curator it returns a Promise of the curated (re-gated) result.
+ */
+export declare function brainBuild(repo: string, identity: ClanIdentity, opts?: BrainBuildOpts & {
+    curate?: undefined;
+}): BrainBuildResult;
+export declare function brainBuild(repo: string, identity: ClanIdentity, opts: BrainBuildOpts & {
+    curate: BrainCurator;
+}): Promise<BrainBuildResult>;

package/dist/brain-build.js

@@ -0,0 +1,278 @@
+/**
+ * brain-build — mine a clan's EXISTING files into brain wiki pages, so a new
+ * clan doesn't start with an empty brain. Sources: README, docs/, CLAUDE.md,
+ * package manifests, top-level code structure, the engine's inventory of the
+ * user's existing Claude Code assets, and (opt-in) Claude Code session memory.
+ *
+ * SAFETY (non-negotiable): every candidate body is scanned with scanSensitive
+ * BEFORE it becomes a page; anything that trips (secrets / infra ids / PHI) is
+ * HELD BACK, never written, and reported for the operator to review. Pages are
+ * create-only — accumulated brain content is never clobbered.
+ *
+ * Mechanical (no LLM required) — the right no-key base layer. LLM curation is
+ * an opt-in HOOK (opts.curate): the caller brings the LLM, the engine stays
+ * zero-LLM and re-gates everything the curator returns.
+ */
+import { readFileSync, existsSync, readdirSync, lstatSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { brainRoot, markerLines } from './templates.js';
+import { scanSensitive } from './sanitize.js';
+function slugify(s) {
+    return String(s).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 60) || 'untitled';
+}
+/** Collapse to a single clean line for a YAML scalar / title. */
+function oneLine(s) {
+    return String(s).replace(/\s+/g, ' ').trim();
+}
+function read(p) { try {
+    return readFileSync(p, 'utf-8');
+}
+catch {
+    return null;
+} }
+function listMd(dir, depth = 3) {
+    if (depth < 0 || !existsSync(dir))
+        return [];
+    const out = [];
+    let entries = [];
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return out;
+    }
+    for (const e of entries) {
+        if (e.startsWith('.') || e === 'node_modules')
+            continue;
+        const full = join(dir, e);
+        // lstat, not stat: never follow a symlink (a docs/x -> / link must not
+        // pull the whole filesystem into the brain).
+        let st;
+        try {
+            st = lstatSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (st.isSymbolicLink())
+            continue;
+        if (st.isDirectory())
+            out.push(...listMd(full, depth - 1));
+        else if (e.endsWith('.md'))
+            out.push(full);
+    }
+    return out;
+}
+/** README H2 sections → concept candidates. */
+function mineReadme(repo) {
+    const body = read(join(repo, 'README.md')) ?? read(join(repo, 'readme.md'));
+    if (!body)
+        return [];
+    const out = [];
+    const parts = body.split(/^##\s+/m);
+    for (let i = 1; i < parts.length; i++) {
+        const seg = parts[i];
+        const title = seg.split('\n')[0].trim();
+        const content = seg.slice(seg.indexOf('\n') + 1).trim();
+        if (title && content.length > 20)
+            out.push({ category: 'concepts', slug: slugify(title), title, type: 'concept', from: 'README.md', body: content });
+    }
+    return out;
+}
+/** docs/**.md → source candidates (recursive, bounded). */
+function mineDocs(repo) {
+    const out = [];
+    for (const f of listMd(join(repo, 'docs'))) {
+        const body = read(f);
+        if (!body || body.length < 40)
+            continue;
+        const rel = f.slice(repo.length + 1);
+        const title = (/^#\s+(.+)$/m.exec(body)?.[1] ?? rel).trim();
+        out.push({ category: 'sources', slug: slugify(rel.replace(/\.md$/, '')), title, type: 'source', from: rel, body });
+    }
+    return out;
+}
+/** CLAUDE.md → a source page (the thing bootstrap-clan never converted). Strips
+ *  the engine's own geo-tier/identity block so we don't re-ingest boilerplate. */
+function mineClaudeMd(repo) {
+    const body = read(join(repo, 'CLAUDE.md'));
+    if (!body || body.length < 40)
+        return [];
+    const cleaned = body.replace(/<!--\s*geo-tier:[^>]*-->/g, '').trim();
+    if (cleaned.length < 40)
+        return [];
+    return [{ category: 'sources', slug: 'project-claude-md', title: 'Project CLAUDE.md', type: 'source', from: 'CLAUDE.md', body: cleaned }];
+}
+/** package.json / pyproject / Cargo → an entity overview. */
+function mineManifest(repo) {
+    const pj = read(join(repo, 'package.json'));
+    if (pj) {
+        try {
+            const p = JSON.parse(pj);
+            const depsObj = (p.dependencies && typeof p.dependencies === 'object' && !Array.isArray(p.dependencies)) ? p.dependencies : {};
+            const devObj = (p.devDependencies && typeof p.devDependencies === 'object' && !Array.isArray(p.devDependencies)) ? p.devDependencies : {};
+            const deps = Object.keys({ ...depsObj, ...devObj });
+            const name = String(p.name ?? 'project');
+            const body = `**Name:** ${name}\n**Version:** ${String(p.version ?? '?')}\n**Description:** ${String(p.description ?? '(none)')}\n\n**Dependencies (${deps.length}):** ${deps.slice(0, 40).join(', ')}`;
+            return [{ category: 'entities', slug: 'project', title: name, type: 'entity', from: 'package.json', body }];
+        }
+        catch { /* ignore */ }
+    }
+    for (const [file, label] of [['pyproject.toml', 'Python project'], ['Cargo.toml', 'Rust crate']]) {
+        const c = read(join(repo, file));
+        if (c)
+            return [{ category: 'entities', slug: 'project', title: label, type: 'entity', from: file, body: c.slice(0, 800) }];
+    }
+    return [];
+}
+/** Top-level code directories → entity stubs. */
+function mineCodeDirs(repo) {
+    const skip = new Set(['.git', '.claude', '.clan', '.brain', '.jungle', '.district', '.brains', 'node_modules', 'dist', 'build', 'docs', '.github', '.vscode']);
+    const out = [];
+    let entries = [];
+    try {
+        entries = readdirSync(repo);
+    }
+    catch {
+        return out;
+    }
+    for (const e of entries) {
+        if (skip.has(e) || e.startsWith('.'))
+            continue;
+        let st;
+        try {
+            st = lstatSync(join(repo, e));
+        }
+        catch {
+            continue;
+        }
+        if (st.isDirectory())
+            out.push({ category: 'entities', slug: slugify(e), title: e, type: 'entity', from: e + '/', body: `Top-level code directory \`${e}/\`. (Stub — the Alpha fills this in as it learns the module.)` });
+    }
+    return out;
+}
+/** The engine's inventory of existing assets → a "tools this project already has" concept. */
+function mineInventory(repo) {
+    const raw = read(join(repo, '.clan', 'inventory.json'));
+    if (!raw)
+        return [];
+    try {
+        const items = (JSON.parse(raw).items ?? []);
+        if (!items.length)
+            return [];
+        const lines = items.map(i => `- **${i.name}** (${i.kind}, ${i.scope})${i.description ? ` — ${i.description}` : ''}`);
+        return [{ category: 'concepts', slug: 'existing-tools', title: 'Existing tools in this project', type: 'concept', from: '.clan/inventory.json', body: `The Alpha should PREFER these existing assets where they overlap, rather than duplicating:\n\n${lines.join('\n')}` }];
+    }
+    catch {
+        return [];
+    }
+}
+/** Claude Code project-path encoding: every non-alphanumeric char → '-'
+ *  (covers /, ., _, and on Windows \ and the drive colon). */
+function encodeRepoPath(repo) {
+    return repo.replace(/[^a-zA-Z0-9]/g, '-');
+}
+/** Opt-in: Claude Code session memory for THIS repo → source candidates. */
+function mineMemory(repo, home) {
+    const dir = join(home, '.claude', 'projects', encodeRepoPath(repo), 'memory');
+    const out = [];
+    for (const f of listMd(dir, 1)) {
+        const base = f.slice(dir.length + 1);
+        if (base === 'MEMORY.md')
+            continue; // the index, not content
+        const body = read(f);
+        if (!body || body.length < 40)
+            continue;
+        const title = (/^name:\s*(.+)$/m.exec(body)?.[1] ?? base.replace(/\.md$/, '')).trim();
+        out.push({ category: 'sources', slug: 'memory--' + slugify(base.replace(/\.md$/, '')), title, type: 'source', from: `session-memory/${base}`, body });
+    }
+    return out;
+}
+export function brainBuild(repo, identity, opts = {}) {
+    const home = opts.home ?? homedir();
+    const candidates = [
+        ...mineManifest(repo),
+        ...mineReadme(repo),
+        ...mineClaudeMd(repo),
+        ...mineDocs(repo),
+        ...mineCodeDirs(repo),
+        ...mineInventory(repo),
+        ...(opts.includeMemory ? mineMemory(repo, home) : []),
+    ];
+    const root = brainRoot(identity);
+    const pages = [];
+    const heldBack = [];
+    const sourceNotes = [];
+    const seen = new Set();
+    for (const c of candidates) {
+        // Scan the body AND the derived title AND the source path — a secret/PHI in
+        // a filename or heading is just as leaky as one in the body.
+        const scan = scanSensitive(`${c.body}\n${c.title}\n${c.from}`, { hipaa: opts.hipaa });
+        if (scan.flagged) {
+            heldBack.push({ from: c.from, reasons: scan.reasons });
+            continue;
+        }
+        // Unique slug within its category (suffix on collision — never silently drop).
+        let path = `${root}/wiki/${c.category}/${c.slug}.md`;
+        for (let n = 2; seen.has(path); n++)
+            path = `${root}/wiki/${c.category}/${c.slug}-${n}.md`;
+        seen.add(path);
+        // Create-only guaranteed here (not just in the CLI): never clobber an
+        // existing brain page, so a programmatic caller can't overwrite memory.
+        if (existsSync(join(repo, path)))
+            continue;
+        // Safe frontmatter: JSON-quote scalars so a title/path containing ':' '#'
+        // a newline, or a leading '-' can't break the YAML.
+        const title = oneLine(c.title);
+        pages.push({
+            path,
+            managed: true,
+            content: `---\nname: ${JSON.stringify(title)}\ndescription: ${JSON.stringify('mined from ' + c.from)}\ntype: ${JSON.stringify(c.type)}\nsource: ${JSON.stringify(c.from)}\n${markerLines()}\n---\n\n# ${title}\n\n${c.body}\n`,
+        });
+        sourceNotes.push(`${path} ← ${c.from}`);
+    }
+    const mech = { pages, heldBack, scanned: candidates.length, notes: [] };
+    if (!opts.curate)
+        return mech;
+    return runCurate(repo, identity, opts, mech, sourceNotes);
+}
+/** Apply the caller's curation hook, then re-gate its output. The curated set
+ *  REPLACES the mechanical pages, but the invariants survive curation:
+ *  scanSensitive on every body+path, create-only, and vault-root confinement
+ *  (an LLM cannot aim a write at .claude/, .mcp.json, or outside the brain). */
+async function runCurate(repo, identity, opts, mech, sourceNotes) {
+    let curated;
+    try {
+        curated = await opts.curate({ pages: mech.pages, identity, sourceNotes });
+        if (!Array.isArray(curated))
+            throw new Error('curator returned non-array');
+    }
+    catch (e) {
+        return { ...mech, notes: [...mech.notes, `curation failed: ${e.message}; mechanical pages used`] };
+    }
+    const root = brainRoot(identity);
+    const pages = [];
+    const heldBack = [...mech.heldBack];
+    const notes = [...mech.notes];
+    let outside = 0;
+    for (const p of curated) {
+        if (typeof p?.path !== 'string' || typeof p?.content !== 'string')
+            continue;
+        if (p.path.includes('..') || !p.path.startsWith(root + '/')) {
+            outside++;
+            continue;
+        }
+        const scan = scanSensitive(`${p.content}\n${p.path}`, { hipaa: opts.hipaa });
+        if (scan.flagged) {
+            heldBack.push({ from: `curated:${p.path}`, reasons: scan.reasons });
+            continue;
+        }
+        if (existsSync(join(repo, p.path)))
+            continue;
+        pages.push({ path: p.path, content: p.content, managed: true });
+    }
+    if (outside)
+        notes.push(`curation dropped ${outside} page(s) targeting paths outside ${root}/`);
+    return { pages, heldBack, scanned: mech.scanned, notes };
+}

package/dist/cli.d.ts

@@ -6,7 +6,7 @@
  *
  *   clan-engine inspect [--repo .] [--json]
  *   clan-engine plan    [--repo .] [--tier clan] [--alpha X] [--name Y] [--json]
- *   clan-engine apply   [--repo .] [--alpha X] [--name Y] [--yes]
+ *   clan-engine apply   [--repo .] [--alpha X] [--name Y]
  *   clan-engine undo    [--repo .] [--journal <path>]
  *   clan-engine doctor  [--repo .] [--json]
  */

package/dist/cli.js

@@ -6,16 +6,18 @@
  *
  *   clan-engine inspect [--repo .] [--json]
  *   clan-engine plan    [--repo .] [--tier clan] [--alpha X] [--name Y] [--json]
- *   clan-engine apply   [--repo .] [--alpha X] [--name Y] [--yes]
+ *   clan-engine apply   [--repo .] [--alpha X] [--name Y]
  *   clan-engine undo    [--repo .] [--journal <path>]
  *   clan-engine doctor  [--repo .] [--json]
  */
-import { resolve } from 'path';
+import { resolve, join } from 'path';
+import { existsSync } from 'fs';
 import { inspect } from './inspect.js';
 import { reconcile } from './reconcile.js';
 import { apply } from './apply.js';
 import { undo, listJournals } from './undo.js';
 import { doctor } from './doctor.js';
+import { brainBuild } from './brain-build.js';
 import { ENGINE_VERSION, LAYOUT_VERSION } from './types.js';
 function parseFlags(argv) {
     const out = {};
@@ -61,9 +63,25 @@ function resolveIdentity(ins, flags) {
         description: flags['description'] ?? base?.description ?? '',
         alphaId: flags['alpha-id'] ?? base?.alphaId ?? jungle?.alphaId,
         mode: jungle ? 'connected' : 'standalone',
+        boxPort: flags['box-port'] ?? base?.boxPort,
+        // Existing-vault detection must survive into every verb — without this,
+        // brain-build would target the tier-default vault on multi-root repos
+        // (reconcile has its own safety net; brainBuild does not).
+        brainRoot: base?.brainRoot ?? ins.brainRoot,
         jungle,
     };
 }
+/** JSON output with secret VALUES masked. The /tier:up wizard pipes --json
+ *  straight into an LLM conversation, so a live jungle apiKey must never
+ *  appear — neither in identity.jungle nor embedded in a planned .mcp.json
+ *  merge content. */
+function redactedJson(value, secrets) {
+    let out = JSON.stringify(value, null, 2);
+    for (const s of secrets)
+        if (s)
+            out = out.split(s).join('[redacted]');
+    return out;
+}
 function printPlan(plan) {
     const glyph = { create: '+', update: '~', 'backup-replace': '!', merge: '~', append: '»', remove: '-', skip: '·' };
     const acting = plan.actions.filter(a => a.kind !== 'skip');
@@ -82,7 +100,7 @@ async function main() {
         case 'inspect': {
             const ins = inspect(repo, { tierFlag: flags['tier'] });
             if (json) {
-                console.log(JSON.stringify(ins, null, 2));
+                console.log(redactedJson(ins, [ins.identity?.jungle?.apiKey]));
                 break;
             }
             console.log(`\nclan-engine inspect — ${repo}`);
@@ -104,7 +122,7 @@ async function main() {
             const plan = reconcile(identity, ins, { jungle: identity.jungle, today: today() });
             if (cmd === 'plan') {
                 if (json)
-                    console.log(JSON.stringify(plan, null, 2));
+                    console.log(redactedJson(plan, [identity.jungle?.apiKey]));
                 else {
                     printPlan(plan);
                     console.log(`\n(dry-run — run \`clan-engine apply\` to write)\n`);
@@ -116,7 +134,7 @@ async function main() {
                 printPlan(plan);
             const res = apply(plan, { at: stamp() });
             if (json)
-                console.log(JSON.stringify(res, null, 2));
+                console.log(redactedJson(res, [identity.jungle?.apiKey]));
             else {
                 console.log(`\n✓ applied ${res.applied.length} action(s).`);
                 if (res.backupDir)
@@ -127,6 +145,51 @@ async function main() {
             }
             break;
         }
+        case 'brain-build': {
+            // LLM curation is API-only: brainBuild({ curate }) from a caller that has
+            // an LLM (e.g. @nfinitmonkeys/clan `brain build --curate`). This CLI has
+            // no LLM to drive one, so it deliberately grows no --curate flag.
+            const ins = inspect(repo, { tierFlag: flags['tier'] });
+            const identity = resolveIdentity(ins, flags);
+            const { pages, heldBack, scanned, notes } = brainBuild(repo, identity, {
+                includeMemory: flags['memory'] === 'true',
+                // PHI scanning is ON by default; --no-phi opts out.
+                hipaa: flags['no-phi'] === 'true' ? false : undefined,
+            });
+            // Create-only: never clobber an existing brain page.
+            const toCreate = pages
+                .filter(p => !existsSync(join(repo, p.path)))
+                .map(p => ({ kind: 'create', path: p.path, content: p.content, note: `brain page` }));
+            const plan = { identity, repo, actions: toCreate };
+            // Default dry-run — brain-build reads broadly (docs, code, optionally
+            // session memory), so writing is opt-in via --write.
+            const doWrite = flags['write'] === 'true' || flags['apply'] === 'true';
+            if (json) {
+                console.log(JSON.stringify({ scanned, built: toCreate.length, heldBack, notes, wrote: doWrite }, null, 2));
+            }
+            else {
+                console.log(`\nclan-engine brain-build — scanned ${scanned} source(s)`);
+                console.log(`  ${toCreate.length} new brain page(s)${doWrite ? ' written' : ' (dry-run — pass --write to save)'}`);
+                for (const a of toCreate.slice(0, 12))
+                    console.log(`  + ${a.path}`);
+                if (toCreate.length > 12)
+                    console.log(`  … +${toCreate.length - 12} more`);
+                if (heldBack.length) {
+                    console.log(`\n  ⚠ ${heldBack.length} source(s) HELD BACK (sensitive — review before publishing):`);
+                    for (const h of heldBack)
+                        console.log(`    · ${h.from} — ${h.reasons.join(', ')}`);
+                }
+                for (const n of notes)
+                    console.log(`  ⚠ ${n}`);
+            }
+            if (doWrite && toCreate.length) {
+                const res = apply(plan, { at: stamp() });
+                if (!json && res.journalPath)
+                    console.log(`\n  undo: clan-engine undo --journal ${res.journalPath}`);
+            }
+            console.log();
+            break;
+        }
         case 'undo': {
             let jp = flags['journal'];
             if (!jp) {
@@ -166,9 +229,13 @@ async function main() {
 
   inspect   map a repo's state (add --json for machine output)
   plan      show what setup would write (dry-run; --alpha --name --tier)
-  apply     write it (uniform backups + a journal for undo)
-  undo      reverse the last apply (--journal <path> to pick one)
-  doctor    validate the whole loop (config, mcp name, brain, hook, creds)
+  apply       write it (uniform backups + a journal for undo)
+  brain-build mine existing files (README/docs/CLAUDE.md/code/inventory,
+              +--memory) into brain pages; sensitive content held back.
+              dry-run by default; --write to save. LLM curation is API-only
+              (brainBuild({curate}) — this CLI has no LLM, so no --curate flag)
+  undo        reverse the last apply (--journal <path> to pick one)
+  doctor      validate the whole loop (config, mcp name, brain, hook, creds)
 `);
     }
 }

package/dist/index.d.ts

@@ -6,14 +6,16 @@
  * from here, so their output can never drift again. The conversational wizard
  * drives these same verbs; the LLM improvises the conversation, never the writes.
  */
-export { ENGINE_VERSION, LAYOUT_VERSION, GENERATED_BY, type Tier, type Mode, type ClanIdentity, type GeneratedFile, type PlanAction, type Plan, type InspectResult, type InventoryItem, type NodeState, type McpServerInfo, type Journal, type JournalOp, type ApplyResult, type DoctorCheck, } from './types.js';
+export { ENGINE_VERSION, LAYOUT_VERSION, GENERATED_BY, type Tier, type Mode, type ClanIdentity, type GeneratedFile, type PlanAction, type Plan, type InspectResult, type InventoryItem, type NodeState, type McpServerInfo, type Journal, type JournalOp, type ApplyResult, type DoctorCheck, type BrainCurateInput, type BrainCurator, } from './types.js';
 export { inspect } from './inspect.js';
 export { reconcile, type ReconcileOptions } from './reconcile.js';
 export { apply, type ApplyOptions } from './apply.js';
 export { undo, listJournals, type UndoResult } from './undo.js';
 export { doctor } from './doctor.js';
 export { scanInventory, writeInventoryManifest } from './inventory.js';
-export { planMcpJson, jungleLocalServer, type JungleCreds } from './mcp.js';
+export { brainBuild, type BrainBuildResult, type BrainBuildOpts, type HeldBack } from './brain-build.js';
+export { scanSensitive, type ScanResult } from './sanitize.js';
+export { planMcpJson, planDistrictMcpJson, jungleLocalServer, districtBoxCreds, type JungleCreds } from './mcp.js';
 export { planBrainHook } from './hooks.js';
 export { claudeSurface, brainScaffold, claudeMdIdentity, loadBrainScript, geoTierMarker, hasManagedMarker, findGeoTierMarker, markerLines, hookCommand, brainRoot, } from './templates.js';
 import type { ClanIdentity, Plan, ApplyResult } from './types.js';

package/dist/index.js

@@ -13,7 +13,9 @@ export { apply } from './apply.js';
 export { undo, listJournals } from './undo.js';
 export { doctor } from './doctor.js';
 export { scanInventory, writeInventoryManifest } from './inventory.js';
-export { planMcpJson, jungleLocalServer } from './mcp.js';
+export { brainBuild } from './brain-build.js';
+export { scanSensitive } from './sanitize.js';
+export { planMcpJson, planDistrictMcpJson, jungleLocalServer, districtBoxCreds } from './mcp.js';
 export { planBrainHook } from './hooks.js';
 export { claudeSurface, brainScaffold, claudeMdIdentity, loadBrainScript, geoTierMarker, hasManagedMarker, findGeoTierMarker, markerLines, hookCommand, brainRoot, } from './templates.js';
 /**