@nfinitmonkeys/clan-engine 0.1.1 → 0.3.0

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.1.1",
+  "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": {