@nfinitmonkeys/clan-engine 0.2.0 → 0.4.0

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')