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

@@ -9,10 +9,11 @@
  * 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 } from './types.js';
 export interface HeldBack {
     from: string;
     reasons: string[];
@@ -21,13 +22,28 @@ 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?: {
-    home?: string;
-    hipaa?: boolean;
-    includeMemory?: boolean;
+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

@@ -9,8 +9,9 @@
  * 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';
@@ -188,10 +189,6 @@ function mineMemory(repo, home) {
     }
     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.
- */
 export function brainBuild(repo, identity, opts = {}) {
     const home = opts.home ?? homedir();
     const candidates = [
@@ -206,6 +203,7 @@ export function brainBuild(repo, identity, opts = {}) {
     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
@@ -232,6 +230,49 @@ export function brainBuild(repo, identity, opts = {}) {
             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 });
     }
-    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, } 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, 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

@@ -15,7 +15,7 @@ export { doctor } from './doctor.js';
 export { scanInventory, writeInventoryManifest } from './inventory.js';
 export { brainBuild } 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';
 /**

package/dist/inspect.js

@@ -51,6 +51,70 @@ function brainRootFor(tier, alphaName) {
         return `.brains/${(alphaName ?? '').toLowerCase()}`;
     return '.brain';
 }
+/** Vault presence at a root: a wiki/ dir or a .brain-meta.json. */
+function vaultExists(repo, r) {
+    return existsSync(join(repo, r, 'wiki')) || existsSync(join(repo, r, '.brain-meta.json'));
+}
+/** The vault an EXISTING load-brain SessionStart hook already points at
+ *  (repo-relative), when that directory still exists. The live hook is ground
+ *  truth: it names the vault sessions ACTUALLY load, so setup must never
+ *  repoint away from it (e.g. the jungle repo's debris-only .brain/ vs the
+ *  real .brains/obsidian the hook hydrates). */
+function hookedBrainRoot(repo) {
+    const raw = read(join(repo, '.claude', 'settings.json'));
+    if (raw === null)
+        return undefined;
+    let doc;
+    try {
+        doc = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    const entries = Array.isArray(doc?.hooks?.SessionStart) ? doc.hooks.SessionStart : [];
+    for (const entry of entries) {
+        for (const h of entry?.hooks ?? []) {
+            const m = /(?:^|[\s"'=])((?:\$\{?CLAUDE_PROJECT_DIR\}?\/)?[^\s"']+)\/scripts\/load-brain\.(?:mjs|sh)/
+                .exec(h?.command ?? '');
+            if (!m)
+                continue;
+            const rel = m[1].replace(/^\$\{?CLAUDE_PROJECT_DIR\}?\//, '').replace(/^\.\//, '');
+            if (rel && !rel.startsWith('/') && !rel.includes('..') && existsSync(join(repo, rel)))
+                return rel;
+        }
+    }
+    return undefined;
+}
+/** An EXISTING vault at ANY known root. Precedence:
+ *   1. the vault a load-brain SessionStart hook already loads — wins outright;
+ *   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 (e.g. a
+ *      sources-only .brain/ left by a memory bridge);
+ *   3. bare-existing vaults in that same order;
+ *   4. none → undefined (tier default applies downstream).
+ *  Data safety: reconcile scaffolds at the detected root, never a tier-default
+ *  duplicate — and never away from the vault the live hook hydrates. */
+function detectBrainRoot(repo, tier, alphaName) {
+    const hooked = hookedBrainRoot(repo);
+    if (hooked)
+        return hooked;
+    const candidates = ['.district/brain', brainRootFor(tier, alphaName), '.brain'];
+    if (alphaName)
+        candidates.push(`.brains/${alphaName.toLowerCase()}`);
+    try {
+        const dirs = readdirSync(join(repo, '.brains')).filter(d => vaultExists(repo, `.brains/${d}`));
+        for (const d of [...dirs.filter(x => x === 'obsidian'), ...dirs.filter(x => x !== 'obsidian').sort()]) {
+            candidates.push(`.brains/${d}`);
+        }
+    }
+    catch { /* no .brains */ }
+    const uniq = [...new Set(candidates)].filter(c => c && !c.endsWith('/'));
+    const withIdentity = uniq.find(r => existsSync(join(repo, r, 'wiki', 'identity.md')));
+    if (withIdentity)
+        return withIdentity;
+    return uniq.find(r => vaultExists(repo, r));
+}
 export function inspect(repo, opts = {}) {
     const notes = [];
     const { tier, source: tierSource } = detectTier(repo, opts.tierFlag);
@@ -69,15 +133,48 @@ export function inspect(repo, opts = {}) {
             notes.push('.jungle/config.yaml is unparseable');
         }
     }
-    const connected = cfg?.jungle?.status === 'connected' || cfg?.jungle?.status === 'approved';
+    // 'registered' / 'onboarded' are older attach-era statuses pointing at a real
+    // Jungle (fleet: Funnel, Beacon) — flipping them to standalone would rewrite
+    // their packs with "the user is the approver" fiction. apiUrl is the
+    // connection intent (Funnel's apiKey is empty but its Jungle is real — the
+    // missing-key note below stays honest). Full creds with no status at all =
+    // legacy attach (old clan-ready treated apiUrl alone as connected).
+    const status = cfg?.jungle?.status;
+    const hasCreds = !!(cfg?.jungle?.apiUrl && cfg?.jungle?.alphaId && cfg?.jungle?.apiKey);
+    const connected = status === 'connected' || status === 'approved'
+        || ((status === 'registered' || status === 'onboarded') && !!cfg?.jungle?.apiUrl)
+        || (status === undefined && hasCreds);
     const mode = connected ? 'connected' : 'standalone';
-    const identity = cfg?.project?.name && cfg?.project?.alphaName ? {
+    // ── .district/district.config.yaml (the district box's identity) ──
+    let dcfg = null;
+    const dcfgRaw = read(join(repo, '.district', 'district.config.yaml'));
+    if (dcfgRaw !== null) {
+        try {
+            dcfg = YAML.parse(dcfgRaw);
+        }
+        catch {
+            notes.push('.district/district.config.yaml is unparseable');
+        }
+    }
+    // ── existing vault (any known root) — wins over the tier default ──
+    const existingBrainRoot = detectBrainRoot(repo, tier, dcfg?.district?.alphaName ?? cfg?.project?.alphaName);
+    const identity = dcfg?.district?.name && dcfg?.district?.alphaName ? {
+        name: dcfg.district.name,
+        alphaName: dcfg.district.alphaName,
+        description: dcfg.district.description ?? '',
+        tier,
+        mode,
+        alphaId: dcfg.district.alphaId,
+        boxPort: String(dcfg.http?.port ?? '7787'),
+        brainRoot: existingBrainRoot,
+    } : cfg?.project?.name && cfg?.project?.alphaName ? {
         name: cfg.project.name,
         alphaName: cfg.project.alphaName,
         description: cfg.project.description ?? '',
         tier,
         mode,
         alphaId: cfg.jungle?.alphaId,
+        brainRoot: existingBrainRoot,
         jungle: connected && cfg.jungle?.apiUrl && cfg.jungle?.alphaId && cfg.jungle?.apiKey
             ? { apiUrl: cfg.jungle.apiUrl, alphaId: cfg.jungle.alphaId, apiKey: cfg.jungle.apiKey }
             : undefined,
@@ -104,8 +201,8 @@ export function inspect(repo, opts = {}) {
             notes.push('.mcp.json is unparseable');
         }
     }
-    // ── brain (at the tier-aware root) ──
-    const bRoot = brainRootFor(tier, cfg?.project?.alphaName);
+    // ── brain (existing vault at any root > the tier-aware default) ──
+    const bRoot = existingBrainRoot ?? brainRootFor(tier, dcfg?.district?.alphaName ?? cfg?.project?.alphaName);
     let hasBrain = false;
     let brainLayoutVersion;
     const metaRaw = read(join(repo, bRoot, '.brain-meta.json'));
@@ -166,6 +263,6 @@ export function inspect(repo, opts = {}) {
         repo, os, isGit, tier, tierSource, mode, identity,
         hasConfig, configError, hasMcp, mcpServers,
         inventory: scanInventory(repo, { home: opts.home }),
-        hasBrain, brainLayoutVersion, state, notes,
+        hasBrain, brainLayoutVersion, brainRoot: existingBrainRoot, state, notes,
     };
 }

package/dist/inventory.d.ts

@@ -14,5 +14,7 @@ import type { InventoryItem } from './types.js';
 export declare function scanInventory(repo: string, opts?: {
     home?: string;
 }): InventoryItem[];
-/** Write the manifest the awareness skill references. Returns the repo-relative path. */
+/** Write the manifest the awareness skill references. Returns the repo-relative
+ *  path. PROJECT scope only — global (~/.claude) assets are the operator's
+ *  private tooling and must not be persisted into a committable repo file. */
 export declare function writeInventoryManifest(repo: string, items: InventoryItem[]): string;

package/dist/inventory.js

@@ -126,11 +126,13 @@ export function scanInventory(repo, opts = {}) {
         return true;
     });
 }
-/** Write the manifest the awareness skill references. Returns the repo-relative path. */
+/** Write the manifest the awareness skill references. Returns the repo-relative
+ *  path. PROJECT scope only — global (~/.claude) assets are the operator's
+ *  private tooling and must not be persisted into a committable repo file. */
 export function writeInventoryManifest(repo, items) {
     const dir = join(repo, '.clan');
     mkdirSync(dir, { recursive: true });
-    const rel = items.map(i => ({ kind: i.kind, name: i.name, scope: i.scope, description: i.description ?? null }));
+    const rel = items.filter(i => i.scope === 'project').map(i => ({ kind: i.kind, name: i.name, scope: i.scope, description: i.description ?? null }));
     writeFileSync(join(dir, 'inventory.json'), JSON.stringify({ generatedBy: 'clan-engine', items: rel }, null, 2) + '\n', 'utf-8');
     return '.clan/inventory.json';
 }

package/dist/mcp.d.ts

@@ -17,6 +17,16 @@ export declare function jungleLocalServer(c: JungleCreds): {
     args: string[];
     env: Record<string, string>;
 };
+/** District-tier creds: the jungle-local server speaks to the LOCAL district
+ *  box (localhost:<boxPort>), not the cloud Jungle. Same server shape — only
+ *  the URL differs. The self-row key is only capturable at district init (the
+ *  box stores its hash); callers pass it via env, never argv. */
+export declare function districtBoxCreds(boxPort: string, alphaId: string, apiKey: string): JungleCreds;
+/** .mcp.json plan for a district — jungle-local → the local box. */
+export declare function planDistrictMcpJson(repo: string, boxPort: string, creds: {
+    alphaId: string;
+    apiKey: string;
+}, isGit: boolean): PlanAction[];
 /**
  * Produce the reconciliation action(s) for .mcp.json given the target creds.
  * Returns a 'merge' action (new file content) plus, when a fresh file is

package/dist/mcp.js

@@ -17,6 +17,17 @@ export function jungleLocalServer(c) {
         env.JUNGLE_HUMAN_EMAIL = c.humanEmail;
     return { command: 'npx', args: ['-y', '@nfinitmonkeys/jungle-mcp'], env };
 }
+/** District-tier creds: the jungle-local server speaks to the LOCAL district
+ *  box (localhost:<boxPort>), not the cloud Jungle. Same server shape — only
+ *  the URL differs. The self-row key is only capturable at district init (the
+ *  box stores its hash); callers pass it via env, never argv. */
+export function districtBoxCreds(boxPort, alphaId, apiKey) {
+    return { apiUrl: `http://localhost:${boxPort}`, alphaId, apiKey };
+}
+/** .mcp.json plan for a district — jungle-local → the local box. */
+export function planDistrictMcpJson(repo, boxPort, creds, isGit) {
+    return planMcpJson(repo, districtBoxCreds(boxPort, creds.alphaId, creds.apiKey), isGit);
+}
 /**
  * Produce the reconciliation action(s) for .mcp.json given the target creds.
  * Returns a 'merge' action (new file content) plus, when a fresh file is

package/dist/reconcile.js

@@ -63,6 +63,11 @@ function reconcileClaudeMd(repo, i) {
 }
 export function reconcile(identity, ins, opts = {}) {
     const repo = ins.repo;
+    // Data safety: an EXISTING vault at any known root wins over the tier
+    // default — re-tiering (or the jungle repo's own .brain/) must never mint a
+    // duplicate vault. inspect detects it; every template downstream honors it.
+    if (ins.brainRoot && !identity.brainRoot)
+        identity = { ...identity, brainRoot: ins.brainRoot };
     const actions = [];
     // 1. CLAUDE.md declaration
     actions.push(reconcileClaudeMd(repo, identity));
@@ -83,19 +88,34 @@ export function reconcile(identity, ins, opts = {}) {
     // 4. managed .claude surface (awareness SKILL.md + tier command pack + hook script)
     for (const f of claudeSurface(identity))
         actions.push(reconcileFile(repo, f));
-    // 5. inventory manifest (refresh when changed — idempotent otherwise)
-    const inv = scanInventory(repo);
+    // 5. inventory manifest (refresh when changed — idempotent otherwise).
+    //    PROJECT scope only: persisting the operator's global ~/.claude asset
+    //    list would leak private tooling metadata into every (committable) repo
+    //    and churn on every machine change. Global items stay in the in-memory
+    //    InspectResult for the wizard.
+    const inv = scanInventory(repo).filter(i => i.scope === 'project');
     const invContent = JSON.stringify({ generatedBy: 'clan-engine', items: inv.map(i => ({ kind: i.kind, name: i.name, scope: i.scope, description: i.description ?? null })) }, null, 2) + '\n';
     const invExisting = read(repo, '.clan/inventory.json');
     if (invExisting === null)
-        actions.push({ kind: 'create', path: '.clan/inventory.json', content: invContent, note: `inventory ${inv.length} existing asset(s) the Alpha can use` });
+        actions.push({ kind: 'create', path: '.clan/inventory.json', content: invContent, note: `inventory ${inv.length} existing project asset(s) the Alpha can use` });
     else if (invExisting !== invContent)
-        actions.push({ kind: 'update', path: '.clan/inventory.json', content: invContent, note: `refresh inventory (${inv.length} asset(s))` });
+        actions.push({ kind: 'update', path: '.clan/inventory.json', content: invContent, note: `refresh inventory (${inv.length} project asset(s))` });
     else
         actions.push({ kind: 'skip', path: '.clan/inventory.json', note: 'inventory unchanged', reason: 'unchanged' });
     // 6. .mcp.json (connected mode)
     if (opts.jungle)
         actions.push(...planMcpJson(repo, opts.jungle, ins.isGit));
+    // 6b. journals + backups under .claude/.clan-engine/ can embed live-key
+    //     artifacts (a backed-up .mcp.json on merge) — never committable. Ignore
+    //     the dir in the same run that gitignores .mcp.json itself.
+    if (ins.isGit) {
+        const gi = read(repo, '.gitignore') ?? '';
+        if (!gi.split('\n').some(l => l.trim() === '.claude/.clan-engine/')) {
+            const priorAppend = actions.some(a => a.kind === 'append' && a.path === '.gitignore');
+            const prefix = priorAppend || gi.length === 0 || gi.endsWith('\n') ? '' : '\n';
+            actions.push({ kind: 'append', path: '.gitignore', content: prefix + '.claude/.clan-engine/\n', note: 'gitignore .claude/.clan-engine/ (journals + backups may hold backed-up keys)' });
+        }
+    }
     // 7. SessionStart brain hook (tier-aware command)
     actions.push(...planBrainHook(repo, identity));
     // 8. brain scaffold — create-only (never overwrite accumulated brain pages)

package/dist/templates.d.ts

@@ -36,7 +36,10 @@ export declare function findGeoTierMarker(content: string): {
  *  (reconcile handles that) — we never rewrite a user's prose. */
 export declare function claudeMdIdentity(i: ClanIdentity): string;
 /** Where the brain lives, per tier (matches the fleet's clan-ready layout so
- *  the engine never puts .brain/ where a district/jungle expects its vault). */
+ *  the engine never puts .brain/ where a district/jungle expects its vault).
+ *  An EXISTING vault (i.brainRoot, set from inspect) wins over the tier
+ *  default — applying to a repo with a vault elsewhere must never mint a
+ *  duplicate. */
 export declare function brainRoot(i: ClanIdentity): string;
 export declare function brainScaffold(i: ClanIdentity, today: string): GeneratedFile[];
 /** The command wired into .claude/settings.json SessionStart. Relative (hooks

package/dist/templates.js

@@ -85,13 +85,13 @@ This repo is a **${noun.toUpperCase()}** node in the Nfinit Monkeys geography
 ## Tool defaults
 
 - Default MCP prefix: \`mcp__jungle-local__*\` (this node's voice).
-- The Alpha's brain (persistent memory) lives under \`.brain/\` — hydrated at
-  session start by the SessionStart hook.
+- The Alpha's brain (persistent memory) lives under \`${brainRoot(i)}/\` — hydrated
+  at session start by the SessionStart hook.
 
 ## Scope
 
 Routine work here is node-local. Slash commands are tier-named:
-\`/${noun}:status\` · \`/${noun}:inbox\` · \`/${noun}:log\` · \`/${noun}:policies\` · \`/${noun}:request\`.
+\`/${noun}:status\` · \`/${noun}:inbox\` · \`/${noun}:log\` · \`/${noun}:policies\` · \`/${noun}:request\` · \`/${noun}:up\`.
 `;
 }
 // ─── awareness skill (SKILL.md directory format — loadable) ─────────────────
@@ -100,14 +100,43 @@ function awarenessSkill(i) {
     const modeLine = i.mode === 'connected'
         ? `- **Mode:** connected${i.jungle?.apiUrl ? ` to ${i.jungle.apiUrl}` : ''}${i.alphaId ? `\n- **Alpha ID:** \`${i.alphaId}\`` : ''}`
         : `- **Mode:** standalone — no Jungle, no approval queue. The developer IS the Human Council.`;
-    const governance = i.mode === 'connected'
-        ? `## Governance (connected)
+    const workingAs = noun === 'clan'
+        ? `## Working *as* the Alpha
+
+In this repo you act **as ${i.alphaName}**. But ${i.alphaName} is bigger than one
+chat: it has a **brain** (\`npx -y @nfinitmonkeys/clan brain "…"\` — persistent
+memory), an **inbox** (\`npx -y @nfinitmonkeys/clan talk "…"\`), and an
+**autonomous loop** (\`npx -y @nfinitmonkeys/clan start\`). If the user says "I
+want to talk to the Alpha," don't say "you already are" — point them to those.`
+        : noun === 'district'
+            ? `## Working *as* the Alpha
+
+In this repo you act **as ${i.alphaName}**. The district box (localhost:${i.boxPort ?? '7787'})
+is the node's substrate — speak through \`mcp__jungle-local__*\` tools, not the
+clan CLI.`
+            : `## Working *as* the Alpha
+
+In this repo you act **as ${i.alphaName}** — the org hub's Alpha. Speak through
+\`mcp__jungle-local__*\` (this repo's declared identity).`;
+    const governance = noun === 'district'
+        ? `## Governance (district)
+
+Be honest: **the district box has no policy engine yet**. Acts are ungated but
+logged (see /district:log). The composing rule: *a parent sees a child only by
+the child's consent; every child runs without its parent*.`
+        : noun === 'jungle'
+            ? `## Governance (jungle)
+
+The invariant: Alphas **propose**, humans **approve** — every sensitive act
+routes through the approval queue (BOSS).`
+            : i.mode === 'connected'
+                ? `## Governance (connected)
 
 Alphas **propose**, humans **approve**. Sensitive actions go through a gated
 approval flow (\`request_approval\` → Human Council reviews in BOSS → execute →
 logged). To change this node's permissions, tell the user to message the Alpha
 in natural language — it will propose the change for approval.`
-        : `## Governance (standalone)
+                : `## Governance (standalone)
 
 There is no remote council. The developer at this terminal IS the council. When
 they want to change a policy: confirm it, edit \`.jungle/config.yaml\`, restart
@@ -118,27 +147,24 @@ If the user already has agents, skills, or slash commands (e.g. from other
 tools), PREFER them where they overlap instead of duplicating. The clan is a
 teammate to the existing setup, not a replacement — check \`.clan/inventory.json\`
 (written by the engine) for what's available, and route to it by name.`;
+    const runVia = noun === 'clan' ? ` run via \`@nfinitmonkeys/clan\`` : '';
     return {
         path: '.claude/skills/clan-awareness/SKILL.md',
         managed: true,
         content: `---
 name: clan-awareness
-description: This project is a ${noun} node (${i.alphaName} / ${i.name}) run via @nfinitmonkeys/clan — how to answer status, governance, and "talk to the Alpha" questions
+description: This project is a ${noun} node (${i.alphaName} / ${i.name}) — how to answer status, governance, and "talk to the Alpha" questions
 ${markerLines()}
 ---
 
-# Clan Awareness — ${i.name}
-
-You are inside a **${noun}** node run via \`@nfinitmonkeys/clan\`, with its own
-Alpha (**${i.alphaName}**), policies, and accumulated memory (a "brain").
+# Node Awareness — ${i.name}
 
-## Working *as* the Alpha
+This repo is a **${noun.toUpperCase()}** node in the Nfinit Monkeys geography
+(Biome ⊃ Jungle ⊃ District ⊃ Clan)${runVia}, with its own Alpha
+(**${i.alphaName}**), policies, and accumulated memory (a "brain"). Identity is
+DECLARED here, never inferred.
 
-In this repo you act **as ${i.alphaName}**. But ${i.alphaName} is bigger than one
-chat: it has a **brain** (\`npx -y @nfinitmonkeys/clan brain "…"\` — persistent
-memory), an **inbox** (\`npx -y @nfinitmonkeys/clan talk "…"\`), and an
-**autonomous loop** (\`npx -y @nfinitmonkeys/clan start\`). If the user says "I
-want to talk to the Alpha," don't say "you already are" — point them to those.
+${workingAs}
 
 ## This node
 
@@ -149,10 +175,15 @@ ${modeLine}
 
 ## Slash commands (tier-named)
 
-\`/${noun}:status\` · \`/${noun}:inbox\` · \`/${noun}:log\` · \`/${noun}:policies\` · \`/${noun}:request\`
+\`/${noun}:status\` · \`/${noun}:inbox\` · \`/${noun}:log\` · \`/${noun}:policies\` · \`/${noun}:request\` · \`/${noun}:up\` (setup/repair wizard)
 
 If the user types a different tier's command (e.g. \`/clan:status\` in a
-district), point them to the right one — don't silently alias.
+district), point them to the right one — the correction teaches the tier; don't
+silently alias.
+
+The Alpha's brain (persistent memory) lives at \`${brainRoot(i)}\` — hydrated at
+session start by the SessionStart hook. The anatomy is identical at every tier:
+Alpha + brain + governance log + members + registry of children.
 
 ${usingExisting}
 
@@ -175,7 +206,127 @@ ${body}
 `,
     };
 }
+/** Every pack asserts the declared identity up front — the correction teaches the tier. */
+function header(i) {
+    return `Assert the declaration in the output header: **${i.alphaName} · ${i.name} · ${i.tier.toUpperCase()}**.`;
+}
 function commandPack(i) {
+    if (i.tier === 'biome')
+        throw new Error('no pack template for tier biome yet — biome is unbuilt');
+    const pack = i.tier === 'district' ? districtPack(i) : i.tier === 'jungle' ? junglePack(i) : clanPack(i);
+    // /tier:up — the wizard door (design §4 Layer 2) renders at every built tier.
+    return [...pack, upCmd(i)];
+}
+/** Version-pinned engine invocation for generated wizard text. Unpinned
+ *  `npx @nfinitmonkeys/clan-engine` would resolve to an OLDER published engine
+ *  (no district/jungle packs, no existing-vault detection, no --json
+ *  redaction) whose apply would overwrite the very pack that invoked it. */
+const ENGINE_NPX = `npx -y @nfinitmonkeys/clan-engine@${ENGINE_VERSION.split('.').slice(0, 2).join('.')}`;
+/** The /tier:up door — Claude Code IS the wizard; the engine does every write.
+ *  Clan tier gets the full greenfield/convert/repair playbook; district/jungle
+ *  get a short repair wizard (their identity is provisioned by node-up, never
+ *  interviewed here). */
+function upCmd(i) {
+    const t = i.tier;
+    if (t !== 'clan') {
+        return cmd(t, 'up', `Repair / update this ${t} node — engine inspect → plan → approval → apply → doctor`, `${header(i)}
+
+Repair/update wizard for this already-provisioned ${t} node. **You improvise the
+conversation; the engine does every write.** Never hand-author node files; never
+print API keys or secrets — credentials flow via env, not argv (the engine's
+--json output masks key values as \`[redacted]\`).
+
+1. \`${ENGINE_NPX} inspect --json\` — classify state (fresh / partial / current / legacy / drifted) and confirm tier=${t}.
+2. \`${ENGINE_NPX} plan --json\` — present the planned writes / merges / backups in plain language.
+3. Only on the user's explicit approval: \`${ENGINE_NPX} apply\`.
+4. \`${ENGINE_NPX} doctor\` — report honestly; a failing check is a finding, not noise.
+
+Re-runs are repairs, not errors. Identity is DECLARED here — this wizard never
+re-tiers or renames a node. Reverse any apply: \`${ENGINE_NPX} undo\`.
+Day-to-day verbs are the tier-named commands: /${t}:status · /${t}:inbox · /${t}:log · /${t}:policies · /${t}:request.`);
+    }
+    return cmd(t, 'up', `The one door — conversational clan setup/repair wizard (the engine does every write)`, `You are the setup wizard for this repo's clan — the ONE door. Doctrine, non-negotiable:
+
+- **You improvise the conversation; the engine does every write.** NEVER hand-author
+  clan files (the CLAUDE.md identity block, the .claude/ surface, .mcp.json, hooks,
+  brain pages).
+- Every mutation = engine plan → show the user exactly what will be written, merged,
+  and left untouched → explicit user approval → engine apply. No approval, no apply.
+- Never print API keys or secrets. Credentials flow via env vars, never argv
+  (the engine's --json output masks key values as \`[redacted]\`).
+- Re-runs are repairs, not errors. This repo currently declares **${i.alphaName} of
+  ${i.name}** — if that's still right, a re-run just repairs/updates the surface.
+
+## 1 · Inspect
+
+\`${ENGINE_NPX} inspect --json\`
+
+Classify out loud: state (fresh / partial / current / legacy / drifted) ×
+mode (connected / standalone) × tier. This decides everything downstream.
+
+## 2 · What they already have
+
+The inspect output inventories existing agents, skills, commands, and hooks.
+TELL the user what's already here — and that the clan will USE those rather than
+duplicate them (they're recorded in \`.clan/inventory.json\` for the Alpha).
+
+## 3 · Identity — a first-class moment
+
+Never silently derive the Alpha's name from the folder. Suggest a name with ONE
+line of reasoning ("I'd suggest **Relay** — this project relays CRM events"),
+then ask. Greenfield: interview first — "what is this clan for?" — the answer
+becomes the description and, later, the brain's first pages.
+
+## 4 · Plan
+
+\`${ENGINE_NPX} plan --json --alpha <Alpha> --name <Clan>\`
+
+Present it in plain language: what will be CREATED, what will be MERGED (their
+existing .mcp.json servers and settings.json hooks survive), what gets a BACKUP,
+and what stays UNTOUCHED.
+
+## 5 · Apply — only on explicit OK
+
+Only after the user explicitly approves the plan:
+
+\`${ENGINE_NPX} apply --alpha <Alpha> --name <Clan>\`
+
+Uniform backups + an undo journal are recorded automatically.
+
+## 6 · Doctor
+
+\`${ENGINE_NPX} doctor\`
+
+Report honestly — a failing check is a finding to fix or explain, never to hide.
+
+## 7 · Brain (offer, don't force)
+
+Offer: \`npx -y @nfinitmonkeys/clan brain build\` (dry-run by default). Present
+the result — "built N pages, M held back as sensitive" — and get consent BEFORE
+re-running with \`--write\`.
+
+## 8 · Registration
+
+Three honest options — ask which fits:
+
+1. **Standalone** — \`npx -y @nfinitmonkeys/clan wild --yes --alpha <Alpha> --name <Clan> --description "<one line>"\`
+   (the developer IS the council). ALWAYS pass \`--yes\` with the identity from
+   steps 3-4 — bare \`wild\` starts a TTY interview that dies silently (exit 0,
+   nothing written) in your non-TTY shell.
+2. **Attach** — provisioned credentials in env (\`ALPHA_ID\` + \`JUNGLE_API_KEY\`),
+   then \`npx -y @nfinitmonkeys/clan attach\`. Never paste credentials into argv or chat.
+3. **Not provisioned yet** — point them at their operator / Human Council.
+
+After either flow, confirm \`.jungle/config.yaml\` exists — that file IS the
+registration; without it the run failed regardless of exit code. Re-runs of any
+of these are repairs, not errors.
+
+## 9 · Epilogue
+
+Recap exactly what was written (from the apply output), where the backups are,
+and how to reverse it: \`${ENGINE_NPX} undo\`.`);
+}
+function clanPack(i) {
     const t = i.tier;
     const files = [
         cmd(t, 'status', `Show this ${t}'s live status — identity, policies, inbox, telemetry`, `Run the clan status command and present it as a clean dashboard. If MCP is wired, you may also call \`mcp__jungle-local__jungle_whoami\` and \`mcp__jungle-local__jungle_get_self\`.
@@ -218,10 +369,83 @@ Probes come from \`.jungle/config.yaml\` under \`health:\`. Summarize each check
     }
     return files;
 }
+/** District pack — the box's MCP tools (jungle-local → localhost:<boxPort>) are
+ *  the substrate, never the clan CLI. All 5 verbs render unconditionally.
+ *  Box-down recovery names the district CLI by its jungle-repo checkout path —
+ *  the bare npm name is a stranger's squattable package. */
+function districtPack(i) {
+    const t = i.tier;
+    const port = i.boxPort ?? '7787';
+    const db = '.district/db/district.db';
+    return [
+        cmd(t, 'status', `Show this district's live status — identity, member clans, inbox, work, discussion points`, `This repo is a **district** (${i.name} / Alpha ${i.alphaName}) — status comes from the district box's MCP tools (server \`jungle-local\` → localhost:${port}), NOT \`npx -y @nfinitmonkeys/clan\`.
+
+${header(i)}
+
+Gather in parallel: \`jungle_whoami\`, \`jungle_get_children\` (member clans), \`jungle_check_inbox\` (unreadOnly), \`jungle_list_work\`, \`jungle_list_discussion_points\` — all via \`mcp__jungle-local__*\`.
+
+Present one dashboard: identity header, member-clan roster with lastSeen, unread inbox, work by status, open discussion points.
+
+If MCP calls fail with a connection error, the box is down — offer: \`DISTRICT_DATA_DIR=.district node <jungle-checkout>/packages/district/dist/cli.js start\` from this repo root (port ${port}; the district CLI lives in the jungle repo checkout — the bare npm name is a stranger's package; the env var is required — without it the CLI would create a fresh ./data dir and mint a DUPLICATE district identity).`),
+        cmd(t, 'inbox', `View recent messages in ${i.alphaName}'s district inbox`, `${header(i)}
+
+Call \`mcp__jungle-local__jungle_check_inbox\` (unreadOnly first; if empty retry unreadOnly:false, limit 15). Show sender, subject, age. Threads via \`jungle_get_thread\`; mark read via \`jungle_mark_read\`; reply via \`jungle_send_message\` only after the user confirms content.`),
+        cmd(t, 'log', `Governance log — every recorded act on this district`, `${header(i)}
+
+The box exposes no log tool yet — read the district's own sqlite directly (folder-rooted, ours):
+
+\`\`\`bash
+sqlite3 -header -column ${db} "SELECT ts, actor, action, target FROM governance_log ORDER BY ts DESC LIMIT 25;"
+\`\`\`
+
+Newest first, human timestamps. A short log is a young district, not an error.`),
+        cmd(t, 'policies', `This district's governance posture — honest about enforced vs. not yet built`, `${header(i)}
+
+Be honest: **the district box has no policy engine yet** (Console P3 builds it). Show instead: (1) identity + posture from \`.district/district.config.yaml\` (never print apiKey lines); (2) the composing rule — *a parent sees a child only by the child's consent; every child runs without its parent*; (3) plainly: acts are ungated but logged (see /district:log).`),
+        cmd(t, 'request', `Raise a request or decision — discussion point, or escalate to the operating jungle`, `${header(i)}
+
+Two real forms — ask which if unclear: (1) a decision for THIS district → \`mcp__jungle-local__jungle_create_discussion_point\` (title + context; lifecycle open→in_discussion→decided→resolved, +parked); (2) a request to the operating jungle → raise from the jungle repo as its Alpha, or record a DP here tagged for escalation. Never fabricate an approval flow that doesn't exist.`),
+    ];
+}
+/** Jungle pack — the org hub. Registry-wide status via this repo's declared
+ *  identity; all 5 verbs render unconditionally. */
+function junglePack(i) {
+    const t = i.tier;
+    return [
+        cmd(t, 'status', `Show this jungle's live status — identity, council, districts + clans, inbox`, `This repo is a **jungle** (${i.name} / Alpha ${i.alphaName}) — the org hub. Status via \`mcp__jungle-local__*\` (this repo's declared identity).
+
+${header(i)}
+
+Gather in parallel: \`jungle_whoami\`, \`jungle_list_clans\` (the registry — group by geoTier: districts vs direct clans), \`jungle_check_inbox\` (unreadOnly), \`jungle_list_approvals\` (pending only).
+
+Dashboard: identity header, council roster (permission-tier council members), districts with child counts, direct clans, unread inbox, pending approvals count.`),
+        cmd(t, 'inbox', `View recent messages in ${i.alphaName}'s inbox`, `${header(i)}
+
+\`mcp__jungle-local__jungle_check_inbox\` (unreadOnly first, then all, limit 15). Sender, subject, age; threads via \`jungle_get_thread\`; reply via \`jungle_send_message\` only after the user confirms.`),
+        cmd(t, 'log', `Governance log for this jungle`, `${header(i)}
+
+Use \`npx -y @nfinitmonkeys/clan status --json | jq '.self.governanceLog // [] | .[0:15]'\` (this repo is attached via .jungle/config.yaml). Timeline, newest first: who/what/when/why.`),
+        cmd(t, 'policies', `This jungle's policies + the governance invariant`, `${header(i)}
+
+\`\`\`bash
+npx -y @nfinitmonkeys/clan policies
+\`\`\`
+
+Explain the buckets, and the invariant: Alphas propose, humans approve — every sensitive act routes through the approval queue (BOSS).`),
+        cmd(t, 'request', `Propose a policy or governance change for this jungle`, `${header(i)}
+
+Compose the change (actionType, bucket, rationale), confirm with the user, then send via \`npx -y @nfinitmonkeys/clan talk "..."\` or, for cross-clan governance acts, note that the human-council voice (\`mcp__jungle__*\`) is required and must be explicitly requested.`),
+    ];
+}
 // ─── brain scaffold (canonical layout — <brainRoot>/wiki + .brain-meta.json) ─
 /** Where the brain lives, per tier (matches the fleet's clan-ready layout so
- *  the engine never puts .brain/ where a district/jungle expects its vault). */
+ *  the engine never puts .brain/ where a district/jungle expects its vault).
+ *  An EXISTING vault (i.brainRoot, set from inspect) wins over the tier
+ *  default — applying to a repo with a vault elsewhere must never mint a
+ *  duplicate. */
 export function brainRoot(i) {
+    if (i.brainRoot)
+        return i.brainRoot;
     if (i.tier === 'district')
         return '.district/brain';
     if (i.tier === 'jungle')

package/dist/types.d.ts

@@ -6,7 +6,7 @@
  *  file's marker so a future engine can tell "my old output" from "my current
  *  output" and run migrations. Bump LAYOUT_VERSION when the template SHAPE
  *  changes (a path moves, a format changes); bump ENGINE_VERSION freely. */
-export declare const ENGINE_VERSION = "0.1.0";
+export declare const ENGINE_VERSION = "0.3.0";
 export declare const LAYOUT_VERSION = 1;
 /** The marker key written into generated-file frontmatter / headers. */
 export declare const GENERATED_BY = "clan-engine";
@@ -22,6 +22,12 @@ export interface ClanIdentity {
     description: string;
     tier: Tier;
     mode: Mode;
+    /** district box HTTP port (from .district/district.config.yaml http.port). */
+    boxPort?: string;
+    /** EXISTING vault root (repo-relative) when one was detected at a non-default
+     *  location — overrides the tier default so applying never mints a duplicate
+     *  vault (e.g. the jungle repo's own .brain/ despite tier jungle). */
+    brainRoot?: string;
     /** connected-mode credentials (drive .mcp.json). */
     jungle?: {
         apiUrl: string;
@@ -40,6 +46,19 @@ export interface GeneratedFile {
     /** POSIX chmod to apply after write (e.g. 0o755 for scripts). */
     chmod?: number;
 }
+/** Input handed to a brain-build curation hook. The engine stays zero-LLM —
+ *  the hook is supplied by a caller that has one (e.g. @nfinitmonkeys/clan). */
+export interface BrainCurateInput {
+    /** The mechanical candidate pages (already sanitized + create-only filtered). */
+    pages: GeneratedFile[];
+    identity: ClanIdentity;
+    /** Provenance, one line per candidate: "<page path> ← <source file>". */
+    sourceNotes: string[];
+}
+/** Returns the curated page set (replaces/augments the candidates). The engine
+ *  re-gates EVERY curated body through scanSensitive + create-only regardless —
+ *  an LLM echoing a secret from context is held back like a mined one. */
+export type BrainCurator = (input: BrainCurateInput) => Promise<GeneratedFile[]>;
 export type ActionKind = 'create' | 'update' | 'backup-replace' | 'merge' | 'append' | 'remove' | 'skip';
 export interface PlanAction {
     kind: ActionKind;
@@ -89,6 +108,10 @@ export interface InspectResult {
     /** brain vault present + its layout version (from .brain-meta.json). */
     hasBrain: boolean;
     brainLayoutVersion?: number;
+    /** where an EXISTING vault lives (repo-relative), checked across every known
+     *  root (.district/brain > .brain > .brains/*) — reconcile scaffolds THERE,
+     *  never a tier-default duplicate. Unset when no vault exists yet. */
+    brainRoot?: string;
     /** the reconciled state classification. */
     state: NodeState;
     /** actionable notes for the wizard / caller. */

package/dist/types.js

@@ -6,7 +6,7 @@
  *  file's marker so a future engine can tell "my old output" from "my current
  *  output" and run migrations. Bump LAYOUT_VERSION when the template SHAPE
  *  changes (a path moves, a format changes); bump ENGINE_VERSION freely. */
-export const ENGINE_VERSION = '0.1.0';
+export const ENGINE_VERSION = '0.3.0';
 export const LAYOUT_VERSION = 1;
 /** The marker key written into generated-file frontmatter / headers. */
 export const GENERATED_BY = 'clan-engine';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nfinitmonkeys/clan-engine",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Deterministic setup engine for Nfinit Monkeys clans \u2014 the single template + reconciliation authority behind the published CLIs and the internal fleet tooling. Idempotent, dry-run-by-default, non-destructive.",
   "type": "module",
   "bin": {