@nfinitmonkeys/clan-engine 0.2.0 → 0.4.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

@@ -9,10 +9,16 @@
  * 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 can
- * layer on top later.
+ * 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 } from './types.js';
+import type { ClanIdentity, GeneratedFile, BrainCurator, BrainOwner } from './types.js';
+/** Fence tag that holds a serialized EncryptedPage inside a private page's body.
+ *  A private page keeps its Markdown frontmatter (with `private: true`) so the
+ *  vault stays browsable/round-trippable, but the body is replaced by this fenced
+ *  JSON block — the plaintext body never touches disk. */
+export declare const ENCRYPTED_FENCE = "clan-encrypted";
 export interface HeldBack {
     from: string;
     reasons: string[];
@@ -21,13 +27,56 @@ export interface BrainBuildResult {
     pages: GeneratedFile[];
     heldBack: HeldBack[];
     scanned: number;
+    /** Operator-facing report lines (e.g. curation fallback) — never secrets. */
+    notes: string[];
 }
-/**
- * Mine existing files into brain pages. Every candidate is scanned; flagged
- * ones are held back. Returns create-candidate pages + the held-back report.
- */
-export declare function brainBuild(repo: string, identity: ClanIdentity, opts?: {
+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;
+    /** The clan itself as an encrypted-brain recipient (alphaId + X25519 public
+     *  key). Required to WRITE a page whose source frontmatter carries
+     *  `private: true`: such a page is sanitizer-EXEMPT (that is the whole point)
+     *  but its body is encrypted to this owner BEFORE any write. Without an owner,
+     *  a private page is HELD BACK ("run clan keys init first") and its plaintext
+     *  is NEVER written. The private key never reaches the engine. */
+    owner?: BrainOwner;
+}
+/** True when a rendered page's content carries an encrypted (private) body —
+ *  i.e. it holds a fenced `clan-encrypted` block. Used by scanners/tests to
+ *  assert a private page never persisted plaintext. */
+export declare function isPrivatePageContent(content: string): boolean;
+/** Extract the EncryptedPage JSON from a private page's rendered content (the
+ *  fenced `clan-encrypted` block). Returns null when the page is not private /
+ *  the fence is absent or unparseable. The inverse of the write-time encode. */
+export declare function decodePrivatePage(content: string): unknown | null;
+/**
+ * Encrypt a private page's plaintext body to the owner and render the full page
+ * content (frontmatter preserved, body replaced by a fenced `clan-encrypted`
+ * block). clan-crypto is imported lazily so the engine core loads without it;
+ * the owner's private key is NEVER involved — only its public identity. Throws
+ * if clan-crypto is unavailable so the caller can hold the page back rather than
+ * write plaintext.
+ */
+export declare function encryptPrivatePage(frontmatterBlock: string, title: string, plaintextBody: string, owner: BrainOwner): Promise<string>;
+/**
+ * Mine existing files into brain pages. Every NON-PRIVATE candidate is scanned;
+ * flagged ones are held back. A candidate whose source frontmatter declares
+ * `private: true` is sanitizer-EXEMPT but is ENCRYPTED to opts.owner before its
+ * page is emitted (its plaintext body never appears on disk); without an owner
+ * it is HELD BACK ("run clan keys init first") — plaintext is never written.
+ *
+ * The call stays synchronous ONLY when there is neither a curator nor a private
+ * candidate (existing callers unchanged); a curator OR any private page (which
+ * needs async encryption) makes it return a Promise of the (re-gated) result.
+ */
+export declare function brainBuild(repo: string, identity: ClanIdentity, opts?: BrainBuildOpts & {
+    curate?: undefined;
+    owner?: undefined;
 }): BrainBuildResult;
+export declare function brainBuild(repo: string, identity: ClanIdentity, opts: BrainBuildOpts): BrainBuildResult | Promise<BrainBuildResult>;

package/dist/brain-build.js

@@ -9,14 +9,21 @@
  * 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 can
- * layer on top later.
+ * 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 YAML from 'yaml';
 import { brainRoot, markerLines } from './templates.js';
 import { scanSensitive } from './sanitize.js';
+/** Fence tag that holds a serialized EncryptedPage inside a private page's body.
+ *  A private page keeps its Markdown frontmatter (with `private: true`) so the
+ *  vault stays browsable/round-trippable, but the body is replaced by this fenced
+ *  JSON block — the plaintext body never touches disk. */
+export const ENCRYPTED_FENCE = 'clan-encrypted';
 function slugify(s) {
     return String(s).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 60) || 'untitled';
 }
@@ -30,6 +37,66 @@ function read(p) { try {
 catch {
     return null;
 } }
+/** Read the YAML frontmatter of a source file (between the first two `---`).
+ *  Returns null when there is no leading frontmatter block or it won't parse. */
+function frontmatter(content) {
+    if (!content.startsWith('---'))
+        return null;
+    const end = content.indexOf('\n---', 3);
+    if (end === -1)
+        return null;
+    try {
+        const doc = YAML.parse(content.slice(3, end));
+        return doc && typeof doc === 'object' && !Array.isArray(doc) ? doc : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** True when a source file's frontmatter declares `private: true`. A private
+ *  page is exempt from sanitizer hold-back but MUST be encrypted before write. */
+function declaredPrivate(content) {
+    return frontmatter(content)?.private === true;
+}
+/** Serialize an EncryptedPage into a fenced `clan-encrypted` block. This is the
+ *  on-disk body of a private page: the plaintext body is replaced by this fence
+ *  so no plaintext ever touches the vault. Round-trippable via decodePrivatePage. */
+function fenceEncrypted(page) {
+    return '```' + ENCRYPTED_FENCE + '\n' + JSON.stringify(page) + '\n```';
+}
+/** True when a rendered page's content carries an encrypted (private) body —
+ *  i.e. it holds a fenced `clan-encrypted` block. Used by scanners/tests to
+ *  assert a private page never persisted plaintext. */
+export function isPrivatePageContent(content) {
+    return new RegExp('```' + ENCRYPTED_FENCE + '\\b').test(content);
+}
+/** Extract the EncryptedPage JSON from a private page's rendered content (the
+ *  fenced `clan-encrypted` block). Returns null when the page is not private /
+ *  the fence is absent or unparseable. The inverse of the write-time encode. */
+export function decodePrivatePage(content) {
+    const m = new RegExp('```' + ENCRYPTED_FENCE + '\\s*\\n([\\s\\S]*?)\\n```').exec(content);
+    if (!m)
+        return null;
+    try {
+        return JSON.parse(m[1]);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Encrypt a private page's plaintext body to the owner and render the full page
+ * content (frontmatter preserved, body replaced by a fenced `clan-encrypted`
+ * block). clan-crypto is imported lazily so the engine core loads without it;
+ * the owner's private key is NEVER involved — only its public identity. Throws
+ * if clan-crypto is unavailable so the caller can hold the page back rather than
+ * write plaintext.
+ */
+export async function encryptPrivatePage(frontmatterBlock, title, plaintextBody, owner) {
+    const crypto = await import('@nfinitmonkeys/clan-crypto');
+    const page = crypto.encryptPage(plaintextBody, [{ alphaId: owner.alphaId, spkiB64: owner.spkiB64 }]);
+    return `---\n${frontmatterBlock}\n---\n\n# ${title}\n\n${fenceEncrypted(page)}\n`;
+}
 function listMd(dir, depth = 3) {
     if (depth < 0 || !existsSync(dir))
         return [];
@@ -88,7 +155,7 @@ function mineDocs(repo) {
             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 });
+        out.push({ category: 'sources', slug: slugify(rel.replace(/\.md$/, '')), title, type: 'source', from: rel, body, private: declaredPrivate(body) });
     }
     return out;
 }
@@ -184,14 +251,24 @@ function mineMemory(repo, home) {
         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 });
+        out.push({ category: 'sources', slug: 'memory--' + slugify(base.replace(/\.md$/, '')), title, type: 'source', from: `session-memory/${base}`, body, private: declaredPrivate(body) });
     }
     return out;
 }
-/**
- * Mine existing files into brain pages. Every candidate is scanned; flagged
- * ones are held back. Returns create-candidate pages + the held-back report.
- */
+/** Frontmatter block for a mined page. Private pages carry `private: true` so a
+ *  later query knows to decrypt; the body is JSON-quoted scalars only. */
+function pageFrontmatter(c, title) {
+    const lines = [
+        `name: ${JSON.stringify(title)}`,
+        `description: ${JSON.stringify('mined from ' + c.from)}`,
+        `type: ${JSON.stringify(c.type)}`,
+        `source: ${JSON.stringify(c.from)}`,
+    ];
+    if (c.private)
+        lines.push('private: true');
+    lines.push(markerLines());
+    return lines.join('\n');
+}
 export function brainBuild(repo, identity, opts = {}) {
     const home = opts.home ?? homedir();
     const candidates = [
@@ -206,14 +283,22 @@ export function brainBuild(repo, identity, opts = {}) {
     const root = brainRoot(identity);
     const pages = [];
     const heldBack = [];
+    const notes = [];
+    const sourceNotes = [];
     const seen = new Set();
+    // Private candidates that survived path/create-only gating, deferred for async
+    // encryption. { path, title, frontmatter, body } — body encrypted before write.
+    const privateJobs = [];
     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;
+        // A private page is EXEMPT from the sanitizer hold-back (that is the point —
+        // it will be encrypted, never written in the clear). Non-private pages are
+        // scanned on body + title + source path exactly as before.
+        if (!c.private) {
+            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`;
@@ -224,14 +309,91 @@ export function brainBuild(repo, identity, opts = {}) {
         // existing brain page, so a programmatic caller can't overwrite memory.
         if (existsSync(join(repo, path)))
             continue;
+        const title = oneLine(c.title);
+        const fm = pageFrontmatter(c, title);
+        if (c.private) {
+            if (!opts.owner) {
+                // No clan keypair → refuse to write plaintext. Hold it back with a clear
+                // remediation, exactly like a sanitizer trip.
+                heldBack.push({ from: c.from, reasons: ['private-page-needs-key: run `clan keys init` first'] });
+                continue;
+            }
+            privateJobs.push({ path, title, fm, body: c.body, from: c.from });
+            sourceNotes.push(`${path} ← ${c.from} (private)`);
+            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`,
+            content: `---\n${fm}\n---\n\n# ${title}\n\n${c.body}\n`,
         });
+        sourceNotes.push(`${path} ← ${c.from}`);
+    }
+    const scanned = candidates.length;
+    // Assemble: encrypt any private jobs (async), then optionally curate.
+    const needsAsync = privateJobs.length > 0 || !!opts.curate;
+    if (!needsAsync)
+        return { pages, heldBack, scanned, notes };
+    return (async () => {
+        for (const job of privateJobs) {
+            try {
+                const content = await encryptPrivatePage(job.fm, job.title, job.body, opts.owner);
+                pages.push({ path: job.path, managed: true, content });
+            }
+            catch (e) {
+                // clan-crypto unavailable → hold the page back rather than write plaintext.
+                heldBack.push({ from: job.from, reasons: [`private-page-encrypt-failed: ${e.message}`] });
+            }
+        }
+        const mech = { pages, heldBack, scanned, 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) {
+    // Encrypted (private) pages are NEVER handed to the curator — the LLM can't
+    // (and must not) rewrite ciphertext. They pass through verbatim; only the
+    // plaintext mechanical pages are offered for curation.
+    const encrypted = mech.pages.filter(p => isPrivatePageContent(p.content));
+    const plain = mech.pages.filter(p => !isPrivatePageContent(p.content));
+    let curated;
+    try {
+        curated = await opts.curate({ pages: plain, 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 = [...encrypted];
+    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 });
     }
-    return { pages, heldBack, scanned: candidates.length };
+    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,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]
  */
@@ -63,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');
@@ -84,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}`);
@@ -106,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`);
@@ -118,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)
@@ -130,9 +146,12 @@ 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 } = brainBuild(repo, identity, {
+            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,
@@ -146,7 +165,7 @@ async function main() {
             // 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, wrote: doWrite }, null, 2));
+                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)`);
@@ -160,6 +179,8 @@ async function main() {
                     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() });
@@ -211,7 +232,8 @@ async function main() {
   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
+              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,16 +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, type BrainOwner, } 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 { brainBuild, type BrainBuildResult, type HeldBack } from './brain-build.js';
+export { brainBuild, encryptPrivatePage, decodePrivatePage, isPrivatePageContent, ENCRYPTED_FENCE, type BrainBuildResult, type BrainBuildOpts, type HeldBack } from './brain-build.js';
 export { scanSensitive, type ScanResult } from './sanitize.js';
-export { planMcpJson, jungleLocalServer, type JungleCreds } from './mcp.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,9 +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 { brainBuild } from './brain-build.js';
+export { brainBuild, encryptPrivatePage, decodePrivatePage, isPrivatePageContent, ENCRYPTED_FENCE } from './brain-build.js';
 export { scanSensitive } from './sanitize.js';
-export { planMcpJson, jungleLocalServer } from './mcp.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';
 /**