@nfinitmonkeys/clan-engine 0.1.0

package/README.md

@@ -0,0 +1,62 @@
+# @nfinitmonkeys/clan-engine
+
+The deterministic setup engine for Nfinit Monkeys **clans** — the single
+template + reconciliation authority. The published CLIs
+(`@nfinitmonkeys/clan`, `@nfinitmonkeys/clan-claude`) and the internal fleet
+tooling all render from here, so their output can never drift apart again.
+
+**Non-destructive by construction.** It merges into an existing `.claude/` +
+`.mcp.json` instead of clobbering, backs up every file it touches, and journals
+every run so it can be undone exactly.
+
+## 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
+```
+
+`plan` is a dry run; `apply` writes. Both are idempotent — a second `apply`
+is all skips.
+
+## What it authors
+
+- **`CLAUDE.md`** — geo-tier declaration + identity block (existing prose is
+  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.
+- **`.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).
+- **`.claude/settings.json`** — a cross-platform Node SessionStart hook that
+  hydrates the brain and self-noops when there's no brain (safe to commit).
+- **`.brain/`** — a versioned vault (`.brain-meta.json` carries `layoutVersion`
+  so future engines can migrate it).
+- **`.clan/inventory.json`** — the user's EXISTING agents/skills/commands/hooks,
+  so the Alpha works *with* them instead of duplicating.
+
+## Reconciliation
+
+Every generated file carries a `clan-engine@<v>` + `layout: <n>` marker. That's
+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.
+
+## Programmatic API
+
+```js
+import { inspect, reconcile, apply, undo, doctor, setup } 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.
+
+## License
+
+MIT

package/dist/apply.d.ts

@@ -0,0 +1,14 @@
+/**
+ * apply — execute a Plan with the safety DNA: before modifying or removing any
+ * existing file, copy it into a per-run backup dir; write a journal of every op
+ * so `undo` can reverse the run exactly. One uniform rule, no per-path
+ * exceptions to forget.
+ */
+import { type Plan, type ApplyResult } from './types.js';
+export interface ApplyOptions {
+    /** timestamp string used for the backup dir + journal name (determinism). */
+    at: string;
+    /** don't write a journal (e.g. transient/test). Default false. */
+    noJournal?: boolean;
+}
+export declare function apply(plan: Plan, opts: ApplyOptions): ApplyResult;

package/dist/apply.js

@@ -0,0 +1,88 @@
+/**
+ * apply — execute a Plan with the safety DNA: before modifying or removing any
+ * existing file, copy it into a per-run backup dir; write a journal of every op
+ * so `undo` can reverse the run exactly. One uniform rule, no per-path
+ * exceptions to forget.
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync, rmSync, chmodSync, cpSync } from 'fs';
+import { join, dirname } from 'path';
+import { ENGINE_VERSION, LAYOUT_VERSION } from './types.js';
+/** Flatten a repo-relative path to a single backup filename. */
+function flat(rel) { return rel.replace(/[\\/]/g, '__'); }
+export function apply(plan, opts) {
+    const repo = plan.repo;
+    const runDir = join('.claude', '.clan-engine');
+    // Collision-proof run id: if the backup dir OR journal for this `at` already
+    // exists, suffix it. Reusing an `at` (two runs in the same ms, or a fleet
+    // driver passing a fixed stamp) must NEVER overwrite a prior run's backup or
+    // journal — that is the one unrecoverable data-loss path.
+    let runId = opts.at;
+    for (let n = 1; existsSync(join(repo, runDir, `backup-${runId}`)) || existsSync(join(repo, runDir, `journal-${runId}.json`)); n++) {
+        runId = `${opts.at}-${n}`;
+    }
+    const backupRel = join(runDir, `backup-${runId}`);
+    const backupAbs = join(repo, backupRel);
+    const ops = [];
+    const applied = [];
+    const backup = (rel) => {
+        const abs = join(repo, rel);
+        if (!existsSync(abs))
+            return undefined;
+        const dest = join(backupAbs, flat(rel));
+        mkdirSync(dirname(dest), { recursive: true });
+        cpSync(abs, dest, { recursive: true });
+        return join(backupRel, flat(rel));
+    };
+    for (const a of plan.actions) {
+        if (a.kind === 'skip')
+            continue;
+        const abs = join(repo, a.path);
+        const existedBefore = existsSync(abs);
+        switch (a.kind) {
+            case 'create':
+            case 'update':
+            case 'backup-replace':
+            case 'merge': {
+                const bkp = (a.kind !== 'create' && existedBefore) ? backup(a.path) : undefined;
+                mkdirSync(dirname(abs), { recursive: true });
+                writeFileSync(abs, a.content ?? '', 'utf-8');
+                if (a.chmod !== undefined) {
+                    try {
+                        chmodSync(abs, a.chmod);
+                    }
+                    catch { /* best-effort on win */ }
+                }
+                ops.push({ kind: a.kind, path: a.path, backup: bkp, created: !existedBefore });
+                break;
+            }
+            case 'append': {
+                const bkp = existedBefore ? backup(a.path) : undefined;
+                const prev = existedBefore ? readFileSync(abs, 'utf-8') : '';
+                mkdirSync(dirname(abs), { recursive: true });
+                writeFileSync(abs, prev + (a.content ?? ''), 'utf-8');
+                ops.push({ kind: a.kind, path: a.path, backup: bkp, created: !existedBefore });
+                break;
+            }
+            case 'remove': {
+                const bkp = backup(a.path);
+                rmSync(abs, { recursive: true, force: true });
+                ops.push({ kind: a.kind, path: a.path, backup: bkp, created: false });
+                break;
+            }
+        }
+        applied.push(a);
+    }
+    let journalPath;
+    if (!opts.noJournal && ops.length > 0) {
+        const journal = {
+            engineVersion: ENGINE_VERSION, layoutVersion: LAYOUT_VERSION,
+            at: runId, repo, identity: plan.identity, ops,
+        };
+        const jRel = join(runDir, `journal-${runId}.json`);
+        const jAbs = join(repo, jRel);
+        mkdirSync(dirname(jAbs), { recursive: true });
+        writeFileSync(jAbs, JSON.stringify(journal, null, 2) + '\n', 'utf-8');
+        journalPath = jRel;
+    }
+    return { applied, journalPath, backupDir: ops.some(o => o.backup) ? backupRel : undefined };
+}

package/dist/cli.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * clan-engine — the deterministic setup door. Verbs: inspect · plan · apply ·
+ * undo · doctor. Non-interactive and JSON-capable so the conversational wizard
+ * (Claude Code) and the internal fleet tooling both drive the SAME engine.
+ *
+ *   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 undo    [--repo .] [--journal <path>]
+ *   clan-engine doctor  [--repo .] [--json]
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+/**
+ * clan-engine — the deterministic setup door. Verbs: inspect · plan · apply ·
+ * undo · doctor. Non-interactive and JSON-capable so the conversational wizard
+ * (Claude Code) and the internal fleet tooling both drive the SAME engine.
+ *
+ *   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 undo    [--repo .] [--journal <path>]
+ *   clan-engine doctor  [--repo .] [--json]
+ */
+import { resolve } from 'path';
+import { inspect } from './inspect.js';
+import { reconcile } from './reconcile.js';
+import { apply } from './apply.js';
+import { undo, listJournals } from './undo.js';
+import { doctor } from './doctor.js';
+import { ENGINE_VERSION, LAYOUT_VERSION } from './types.js';
+function parseFlags(argv) {
+    const out = {};
+    for (let i = 0; i < argv.length; i++) {
+        const t = argv[i];
+        if (t.startsWith('--')) {
+            const k = t.slice(2);
+            const v = argv[i + 1];
+            if (v && !v.startsWith('--')) {
+                out[k] = v;
+                i++;
+            }
+            else
+                out[k] = 'true';
+        }
+    }
+    return out;
+}
+function stamp() {
+    // ISO time + pid so two runs in the same millisecond can't collide (apply
+    // additionally suffixes on any residual collision).
+    return `${new Date().toISOString().replace(/[:.]/g, '-')}-${process.pid}`;
+}
+function today() {
+    return new Date().toISOString().slice(0, 10);
+}
+/** Build the target identity from the existing config (inspect) + flag overrides. */
+function resolveIdentity(ins, flags) {
+    const base = ins.identity;
+    const name = flags['name'] ?? base?.name;
+    const alphaName = flags['alpha'] ?? base?.alphaName;
+    if (!name || !alphaName) {
+        console.error('✗ Need an identity: pass --name <node> --alpha <AlphaName> (or run in a repo with .jungle/config.yaml).');
+        process.exit(1);
+    }
+    const tier = flags['tier'] ?? ins.tier;
+    // connected iff we have full creds (from config or flags)
+    const jungle = base?.jungle ?? (flags['api-url'] && flags['alpha-id'] && flags['api-key']
+        ? { apiUrl: flags['api-url'], alphaId: flags['alpha-id'], apiKey: flags['api-key'] }
+        : undefined);
+    return {
+        name, alphaName, tier,
+        description: flags['description'] ?? base?.description ?? '',
+        alphaId: flags['alpha-id'] ?? base?.alphaId ?? jungle?.alphaId,
+        mode: jungle ? 'connected' : 'standalone',
+        jungle,
+    };
+}
+function printPlan(plan) {
+    const glyph = { create: '+', update: '~', 'backup-replace': '!', merge: '~', append: '»', remove: '-', skip: '·' };
+    const acting = plan.actions.filter(a => a.kind !== 'skip');
+    console.log(`\nPlan for ${plan.identity.alphaName} of ${plan.identity.name} (${plan.identity.tier}, ${plan.identity.mode}) — ${acting.length} action(s):\n`);
+    for (const a of plan.actions) {
+        const g = glyph[a.kind] ?? '?';
+        console.log(`  ${g} ${a.path}  ${a.kind === 'skip' ? '' : `— ${a.note}`}`.trimEnd());
+    }
+}
+async function main() {
+    const [cmd, ...rest] = process.argv.slice(2);
+    const flags = parseFlags(rest);
+    const repo = resolve(flags['repo'] ?? process.cwd());
+    const json = flags['json'] === 'true';
+    switch (cmd) {
+        case 'inspect': {
+            const ins = inspect(repo, { tierFlag: flags['tier'] });
+            if (json) {
+                console.log(JSON.stringify(ins, null, 2));
+                break;
+            }
+            console.log(`\nclan-engine inspect — ${repo}`);
+            console.log(`  state:     ${ins.state}`);
+            console.log(`  tier:      ${ins.tier} (from ${ins.tierSource})`);
+            console.log(`  mode:      ${ins.mode}${ins.identity ? ` — ${ins.identity.alphaName} of ${ins.identity.name}` : ''}`);
+            console.log(`  os/git:    ${ins.os} / ${ins.isGit ? 'git' : 'no-git'}`);
+            console.log(`  mcp:       ${ins.mcpServers.map(s => s.name).join(', ') || '(none)'}`);
+            console.log(`  brain:     ${ins.hasBrain ? `yes (layout v${ins.brainLayoutVersion ?? '?'})` : 'no'}`);
+            console.log(`  inventory: ${ins.inventory.length} existing asset(s)${ins.inventory.length ? ' — ' + ins.inventory.slice(0, 6).map(i => i.name).join(', ') : ''}`);
+            for (const n of ins.notes)
+                console.log(`  ⚠ ${n}`);
+            break;
+        }
+        case 'plan':
+        case 'apply': {
+            const ins = inspect(repo, { tierFlag: flags['tier'] });
+            const identity = resolveIdentity(ins, flags);
+            const plan = reconcile(identity, ins, { jungle: identity.jungle, today: today() });
+            if (cmd === 'plan') {
+                if (json)
+                    console.log(JSON.stringify(plan, null, 2));
+                else {
+                    printPlan(plan);
+                    console.log(`\n(dry-run — run \`clan-engine apply\` to write)\n`);
+                }
+                break;
+            }
+            // apply
+            if (!json)
+                printPlan(plan);
+            const res = apply(plan, { at: stamp() });
+            if (json)
+                console.log(JSON.stringify(res, null, 2));
+            else {
+                console.log(`\n✓ applied ${res.applied.length} action(s).`);
+                if (res.backupDir)
+                    console.log(`  backups: ${res.backupDir}`);
+                if (res.journalPath)
+                    console.log(`  undo with: clan-engine undo --journal ${res.journalPath}`);
+                console.log();
+            }
+            break;
+        }
+        case 'undo': {
+            let jp = flags['journal'];
+            if (!jp) {
+                const all = listJournals(repo);
+                jp = all[all.length - 1];
+            }
+            if (!jp) {
+                console.error('✗ no journal found to undo (nothing was applied here).');
+                process.exit(1);
+            }
+            const res = undo(repo, jp);
+            if (json)
+                console.log(JSON.stringify(res, null, 2));
+            else
+                console.log(`\n✓ undo ${res.journal}: restored ${res.restored.length}, removed ${res.removed.length}.\n`);
+            break;
+        }
+        case 'doctor': {
+            const checks = await doctor(repo);
+            if (json) {
+                console.log(JSON.stringify(checks, null, 2));
+                break;
+            }
+            console.log(`\nclan-engine doctor — ${repo}\n`);
+            for (const c of checks)
+                console.log(`  ${c.ok ? '✓' : '✗'} ${c.name}: ${c.detail}`);
+            const bad = checks.filter(c => !c.ok).length;
+            console.log(`\n${bad === 0 ? '✓ all checks passed' : `✗ ${bad} check(s) failed`}\n`);
+            process.exit(bad === 0 ? 0 : 1);
+        }
+        case 'version':
+        case '--version':
+            console.log(`clan-engine ${ENGINE_VERSION} (layout v${LAYOUT_VERSION})`);
+            break;
+        default:
+            console.log(`clan-engine ${ENGINE_VERSION} — deterministic clan setup
+
+  inspect   map a repo's state (add --json for machine output)
+  plan      show what setup would write (dry-run; --alpha --name --tier)
+  apply     write it (uniform backups + a journal for undo)
+  undo      reverse the last apply (--journal <path> to pick one)
+  doctor    validate the whole loop (config, mcp name, brain, hook, creds)
+`);
+    }
+}
+main().catch(e => { console.error('clan-engine error:', e.message); process.exit(1); });

package/dist/doctor.d.ts

@@ -0,0 +1,9 @@
+/**
+ * doctor — validate that a clan is actually wired correctly, end to end. Catches
+ * the silent-failure footguns (mis-named MCP server, flat skill that never
+ * loads, a brain hook that errors, bad credentials) before the user hits them.
+ */
+import type { DoctorCheck } from './types.js';
+export declare function doctor(repo: string, opts?: {
+    home?: string;
+}): Promise<DoctorCheck[]>;

package/dist/doctor.js

@@ -0,0 +1,85 @@
+/**
+ * doctor — validate that a clan is actually wired correctly, end to end. Catches
+ * the silent-failure footguns (mis-named MCP server, flat skill that never
+ * loads, a brain hook that errors, bad credentials) before the user hits them.
+ */
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { execFileSync } from 'child_process';
+import { inspect } from './inspect.js';
+import { LAYOUT_VERSION } from './types.js';
+import { brainRoot } from './templates.js';
+async function verifyCreds(apiUrl, apiKey, alphaId) {
+    try {
+        const res = await fetch(`${apiUrl.replace(/\/$/, '')}/mcp`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', 'X-Api-Key': apiKey, 'X-Alpha-Id': alphaId },
+            body: JSON.stringify({ toolCall: { tool: 'jungle_whoami', arguments: {} } }),
+        });
+        if (!res.ok)
+            return { name: 'credentials', ok: false, detail: `jungle_whoami → HTTP ${res.status} (check api-key / alpha-id)` };
+        const body = await res.json();
+        if (body.success)
+            return { name: 'credentials', ok: true, detail: `authenticated as ${body.data?.alphaName ?? body.data?.clanName ?? alphaId}` };
+        return { name: 'credentials', ok: false, detail: 'jungle_whoami returned success:false' };
+    }
+    catch (e) {
+        return { name: 'credentials', ok: false, detail: `could not reach the Jungle: ${e.message}` };
+    }
+}
+export async function doctor(repo, opts = {}) {
+    const checks = [];
+    const ins = inspect(repo, { home: opts.home });
+    // identity / config
+    if (ins.configError)
+        checks.push({ name: 'config', ok: false, detail: `.jungle/config.yaml unparseable: ${ins.configError}` });
+    else if (!ins.hasConfig)
+        checks.push({ name: 'config', ok: false, detail: 'no .jungle/config.yaml — run attach/wild' });
+    else
+        checks.push({ name: 'config', ok: true, detail: `${ins.identity?.alphaName ?? '?'} of ${ins.identity?.name ?? '?'} (${ins.mode})` });
+    // awareness skill in the loadable directory format
+    const skillDir = existsSync(join(repo, '.claude/skills/clan-awareness/SKILL.md'));
+    const flatSkill = existsSync(join(repo, '.claude/skills/clan-awareness.md'));
+    checks.push(skillDir
+        ? { name: 'skill', ok: true, detail: 'clan-awareness SKILL.md (loadable dir format)' }
+        : { name: 'skill', ok: false, detail: flatSkill ? 'flat clan-awareness.md never loads — re-run to migrate' : 'awareness skill missing' });
+    // .mcp.json name hygiene
+    if (ins.mode === 'connected') {
+        const jl = ins.mcpServers.find(s => s.name === 'jungle-local');
+        const bad = ins.mcpServers.find(s => s.misnamed);
+        if (jl)
+            checks.push({ name: 'mcp', ok: true, detail: 'jungle-local server present' });
+        else if (bad)
+            checks.push({ name: 'mcp', ok: false, detail: 'server named "jungle" collides with the global council server — rename to "jungle-local"' });
+        else
+            checks.push({ name: 'mcp', ok: false, detail: '.mcp.json has no jungle-local server' });
+    }
+    // brain + layout version
+    if (!ins.hasBrain)
+        checks.push({ name: 'brain', ok: false, detail: 'no .brain/ vault' });
+    else if (ins.brainLayoutVersion !== undefined && ins.brainLayoutVersion < LAYOUT_VERSION)
+        checks.push({ name: 'brain', ok: false, detail: `brain at layout v${ins.brainLayoutVersion} < v${LAYOUT_VERSION} — re-run to migrate` });
+    else
+        checks.push({ name: 'brain', ok: true, detail: `brain present (layout v${ins.brainLayoutVersion ?? '?'})` });
+    // brain hook actually runs (cross-platform Node) and exits 0. Spawn the
+    // CURRENT interpreter (process.execPath) — a bare 'node' via execFileSync
+    // does no shell/PATHEXT resolution and throws on Windows node.cmd shims.
+    const bRoot = ins.identity ? brainRoot(ins.identity) : '.brain';
+    const hookScript = join(repo, bRoot, 'scripts/load-brain.mjs');
+    if (!existsSync(hookScript))
+        checks.push({ name: 'hook', ok: false, detail: 'SessionStart brain hook script missing' });
+    else {
+        try {
+            execFileSync(process.execPath, [hookScript], { cwd: repo, stdio: 'ignore', timeout: 10000 });
+            checks.push({ name: 'hook', ok: true, detail: 'brain hook runs (exit 0)' });
+        }
+        catch (e) {
+            checks.push({ name: 'hook', ok: false, detail: `brain hook errored: ${e.message}` });
+        }
+    }
+    // live credential check (connected only)
+    if (ins.mode === 'connected' && ins.identity?.jungle) {
+        checks.push(await verifyCreds(ins.identity.jungle.apiUrl, ins.identity.jungle.apiKey, ins.identity.jungle.alphaId));
+    }
+    return checks;
+}

package/dist/hooks.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Cross-platform Claude Code hook wiring. The SessionStart hook hydrates the
+ * Alpha's brain; it is a Node command (not bash), so it runs on macOS, Windows,
+ * and Linux, and it self-noops when there is no brain — safe in a committed
+ * settings.json for collaborators who clone the repo.
+ *
+ * The settings.json merge is STRUCTURAL: existing hooks and keys are preserved,
+ * and a stale entry pointing at an old load-brain path (bash .sh or a moved
+ * location) is migrated in place.
+ */
+import type { PlanAction, ClanIdentity } from './types.js';
+/**
+ * Plan the SessionStart brain hook in .claude/settings.json. Returns a single
+ * 'merge' action with the new settings content, a 'skip' if already wired, or a
+ * 'skip' if settings.json is unparseable OR malformed (never clobber a user's
+ * config, never throw mid-plan on a valid-JSON-but-wrong-shape file).
+ */
+export declare function planBrainHook(repo: string, identity: ClanIdentity): PlanAction[];

package/dist/hooks.js

@@ -0,0 +1,76 @@
+/**
+ * Cross-platform Claude Code hook wiring. The SessionStart hook hydrates the
+ * Alpha's brain; it is a Node command (not bash), so it runs on macOS, Windows,
+ * and Linux, and it self-noops when there is no brain — safe in a committed
+ * settings.json for collaborators who clone the repo.
+ *
+ * The settings.json merge is STRUCTURAL: existing hooks and keys are preserved,
+ * and a stale entry pointing at an old load-brain path (bash .sh or a moved
+ * location) is migrated in place.
+ */
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { hookCommand, LOAD_BRAIN_HOOK_RE } from './templates.js';
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/**
+ * Plan the SessionStart brain hook in .claude/settings.json. Returns a single
+ * 'merge' action with the new settings content, a 'skip' if already wired, or a
+ * 'skip' if settings.json is unparseable OR malformed (never clobber a user's
+ * config, never throw mid-plan on a valid-JSON-but-wrong-shape file).
+ */
+export function planBrainHook(repo, identity) {
+    const settingsPath = join(repo, '.claude', 'settings.json');
+    const cmd = hookCommand(identity);
+    let settings = {};
+    let existed = false;
+    try {
+        const parsed = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+        if (!isPlainObject(parsed)) {
+            return [{ kind: 'skip', path: '.claude/settings.json', note: 'settings.json is not a JSON object — brain hook NOT wired, fix by hand', reason: 'malformed' }];
+        }
+        settings = parsed;
+        existed = true;
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT') {
+            return [{ kind: 'skip', path: '.claude/settings.json', note: 'settings.json unparseable — brain hook NOT wired, fix by hand', reason: 'unparseable' }];
+        }
+    }
+    if (!isPlainObject(settings.hooks))
+        settings.hooks = {};
+    if (!Array.isArray(settings.hooks.SessionStart)) {
+        // A non-array SessionStart is malformed — don't iterate/clobber it.
+        if (settings.hooks.SessionStart !== undefined) {
+            return [{ kind: 'skip', path: '.claude/settings.json', note: 'hooks.SessionStart is not an array — brain hook NOT wired, fix by hand', reason: 'malformed' }];
+        }
+        settings.hooks.SessionStart = [];
+    }
+    let found = false, migrated = false;
+    for (const entry of settings.hooks.SessionStart) {
+        for (const h of entry?.hooks ?? []) {
+            if (h?.type === 'command' && LOAD_BRAIN_HOOK_RE.test(h.command ?? '')) {
+                if (h.command === cmd)
+                    found = true;
+                else {
+                    h.command = cmd;
+                    found = true;
+                    migrated = true;
+                }
+            }
+        }
+    }
+    if (!found)
+        settings.hooks.SessionStart.push({ hooks: [{ type: 'command', command: cmd }] });
+    if (found && !migrated) {
+        return [{ kind: 'skip', path: '.claude/settings.json', note: 'SessionStart brain hook already wired', reason: 'present' }];
+    }
+    return [{
+            kind: 'merge',
+            path: '.claude/settings.json',
+            content: JSON.stringify(settings, null, 2) + '\n',
+            note: migrated ? 'SessionStart brain hook (path migrated to cross-platform Node)' : (existed ? 'SessionStart brain hook (merged into existing settings)' : 'SessionStart brain hook (settings.json created)'),
+            reason: 'existing hooks preserved',
+        }];
+}

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @nfinitmonkeys/clan-engine — deterministic, non-destructive clan setup.
+ *
+ * The single template + reconciliation authority. The published CLIs
+ * (@nfinitmonkeys/clan, clan-claude) and the internal fleet tooling all render
+ * 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 { inspect } from './inspect.js';
+export { reconcile, type ReconcileOptions } from './reconcile.js';
+export { apply, type ApplyOptions } from './apply.js';
+export { undo, listJournals, type UndoResult } from './undo.js';
+export { doctor } from './doctor.js';
+export { scanInventory, writeInventoryManifest } from './inventory.js';
+export { planMcpJson, jungleLocalServer, type JungleCreds } from './mcp.js';
+export { 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';
+export declare function setup(repo: string, identity: ClanIdentity, opts: {
+    at: string;
+    today: string;
+    dryRun?: boolean;
+}): {
+    plan: Plan;
+    result?: ApplyResult;
+};

package/dist/index.js

@@ -0,0 +1,32 @@
+/**
+ * @nfinitmonkeys/clan-engine — deterministic, non-destructive clan setup.
+ *
+ * The single template + reconciliation authority. The published CLIs
+ * (@nfinitmonkeys/clan, clan-claude) and the internal fleet tooling all render
+ * 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, } from './types.js';
+export { inspect } from './inspect.js';
+export { reconcile } from './reconcile.js';
+export { apply } from './apply.js';
+export { undo, listJournals } from './undo.js';
+export { doctor } from './doctor.js';
+export { scanInventory, writeInventoryManifest } from './inventory.js';
+export { planMcpJson, jungleLocalServer } from './mcp.js';
+export { planBrainHook } from './hooks.js';
+export { claudeSurface, brainScaffold, claudeMdIdentity, loadBrainScript, geoTierMarker, hasManagedMarker, findGeoTierMarker, markerLines, hookCommand, brainRoot, } from './templates.js';
+/**
+ * One-call convenience: inspect → reconcile → apply. Returns the plan + result.
+ * `at` and `today` are injected by the caller for determinism.
+ */
+import { inspect as _inspect } from './inspect.js';
+import { reconcile as _reconcile } from './reconcile.js';
+import { apply as _apply } from './apply.js';
+export function setup(repo, identity, opts) {
+    const ins = _inspect(repo, { tierFlag: identity.tier });
+    const plan = _reconcile(identity, ins, { jungle: identity.jungle, today: opts.today });
+    if (opts.dryRun)
+        return { plan };
+    return { plan, result: _apply(plan, { at: opts.at }) };
+}

package/dist/inspect.d.ts

@@ -0,0 +1,10 @@
+/**
+ * inspect — build a full, non-mutating state map of a target directory before
+ * anything is written. The wizard/CLI adapts to the detected scenario (fresh /
+ * partial / current / legacy / drifted), and reconcile plans against it.
+ */
+import { type InspectResult, type Tier } from './types.js';
+export declare function inspect(repo: string, opts?: {
+    tierFlag?: Tier;
+    home?: string;
+}): InspectResult;