@nfinitmonkeys/clan-engine 0.1.0

package/dist/inspect.js

@@ -0,0 +1,171 @@
+/**
+ * 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 { readFileSync, existsSync, readdirSync } from 'fs';
+import { join } from 'path';
+import YAML from 'yaml';
+import { LAYOUT_VERSION, } from './types.js';
+import { hasManagedMarker, findGeoTierMarker } from './templates.js';
+import { scanInventory } from './inventory.js';
+function read(p) {
+    try {
+        return readFileSync(p, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+function isDir(p) {
+    try {
+        return existsSync(p) && readdirSync(p) !== undefined;
+    }
+    catch {
+        return false;
+    }
+}
+/** Tier: explicit flag > REAL CLAUDE.md geo-tier declaration > .district dir >
+ *  .brains dir > default. A marker inside a code fence / prose does not count. */
+function detectTier(repo, tierFlag) {
+    if (tierFlag)
+        return { tier: tierFlag, source: 'flag' };
+    const claude = read(join(repo, 'CLAUDE.md'));
+    if (claude) {
+        const found = findGeoTierMarker(claude);
+        if (found)
+            return { tier: found.tier, source: 'marker' };
+    }
+    if (existsSync(join(repo, '.district')))
+        return { tier: 'district', source: 'district-dir' };
+    if (existsSync(join(repo, '.brains')))
+        return { tier: 'jungle', source: 'brains-dir' };
+    return { tier: 'clan', source: 'default' };
+}
+/** Tier-aware brain root (mirrors templates.brainRoot without needing identity
+ *  when only the tier + optional alpha are known). */
+function brainRootFor(tier, alphaName) {
+    if (tier === 'district')
+        return '.district/brain';
+    if (tier === 'jungle')
+        return `.brains/${(alphaName ?? '').toLowerCase()}`;
+    return '.brain';
+}
+export function inspect(repo, opts = {}) {
+    const notes = [];
+    const { tier, source: tierSource } = detectTier(repo, opts.tierFlag);
+    // ── .jungle/config.yaml ──
+    let cfg = null;
+    let hasConfig = false;
+    let configError;
+    const cfgRaw = read(join(repo, '.jungle', 'config.yaml'));
+    if (cfgRaw !== null) {
+        hasConfig = true;
+        try {
+            cfg = YAML.parse(cfgRaw);
+        }
+        catch (e) {
+            configError = e.message;
+            notes.push('.jungle/config.yaml is unparseable');
+        }
+    }
+    const connected = cfg?.jungle?.status === 'connected' || cfg?.jungle?.status === 'approved';
+    const mode = connected ? 'connected' : 'standalone';
+    const identity = cfg?.project?.name && cfg?.project?.alphaName ? {
+        name: cfg.project.name,
+        alphaName: cfg.project.alphaName,
+        description: cfg.project.description ?? '',
+        tier,
+        mode,
+        alphaId: cfg.jungle?.alphaId,
+        jungle: connected && cfg.jungle?.apiUrl && cfg.jungle?.alphaId && cfg.jungle?.apiKey
+            ? { apiUrl: cfg.jungle.apiUrl, alphaId: cfg.jungle.alphaId, apiKey: cfg.jungle.apiKey }
+            : undefined,
+    } : undefined;
+    if (connected && identity && !identity.jungle) {
+        notes.push('connected clan but .mcp.json cannot be generated — config.yaml is missing apiKey/apiUrl/alphaId');
+    }
+    // ── .mcp.json servers ──
+    const mcpServers = [];
+    let hasMcp = false;
+    const mcpRaw = read(join(repo, '.mcp.json'));
+    if (mcpRaw !== null) {
+        hasMcp = true;
+        try {
+            const doc = JSON.parse(mcpRaw);
+            for (const name of Object.keys(doc.mcpServers ?? {})) {
+                const misnamed = name === 'jungle';
+                mcpServers.push({ name, isJungle: name === 'jungle-local' || misnamed, misnamed });
+                if (misnamed)
+                    notes.push('.mcp.json has a server named "jungle" — collides with the global council server; should be "jungle-local"');
+            }
+        }
+        catch {
+            notes.push('.mcp.json is unparseable');
+        }
+    }
+    // ── brain (at the tier-aware root) ──
+    const bRoot = brainRootFor(tier, cfg?.project?.alphaName);
+    let hasBrain = false;
+    let brainLayoutVersion;
+    const metaRaw = read(join(repo, bRoot, '.brain-meta.json'));
+    if (metaRaw !== null) {
+        hasBrain = true;
+        try {
+            brainLayoutVersion = JSON.parse(metaRaw).layoutVersion;
+        }
+        catch { /* ignore */ }
+    }
+    else if (existsSync(join(repo, bRoot, 'wiki'))) {
+        hasBrain = true; // brain exists but pre-versioning
+    }
+    // ── managed-surface signals for state classification ──
+    const cmdDir = join(repo, '.claude', 'commands', tier);
+    const hasTierPack = existsSync(cmdDir);
+    const otherTierPacks = ['clan', 'district', 'jungle', 'biome']
+        .filter(t => t !== tier && existsSync(join(repo, '.claude', 'commands', t)));
+    const skillDir = join(repo, '.claude', 'skills', 'clan-awareness', 'SKILL.md');
+    const flatSkill = join(repo, '.claude', 'skills', 'clan-awareness.md');
+    const hasSkillDir = existsSync(skillDir);
+    const hasFlatSkill = existsSync(flatSkill);
+    const statusMd = read(join(cmdDir, 'status.md'));
+    const packIsOurs = statusMd !== null && hasManagedMarker(statusMd);
+    // ── OS + git ──
+    const os = process.platform;
+    const isGit = existsSync(join(repo, '.git'));
+    // ── state classification ──
+    let state;
+    const anyClanArtifact = hasConfig || hasTierPack || hasFlatSkill || hasSkillDir || hasBrain;
+    if (!anyClanArtifact) {
+        state = 'fresh';
+    }
+    else if (otherTierPacks.length > 0 || (configError !== undefined)) {
+        state = 'drifted';
+        if (otherTierPacks.length)
+            notes.push(`stale command packs from other tier(s): ${otherTierPacks.join(', ')}`);
+    }
+    else if (hasFlatSkill || (hasTierPack && !packIsOurs) || (hasBrain && (brainLayoutVersion ?? 0) < LAYOUT_VERSION)) {
+        state = 'legacy';
+        if (hasFlatSkill)
+            notes.push('legacy flat awareness skill (.claude/skills/clan-awareness.md) never loads — will migrate to SKILL.md dir');
+        if (hasTierPack && !packIsOurs)
+            notes.push('command pack present but not engine-managed (published-only install) — will adopt');
+        if (hasBrain && (brainLayoutVersion ?? 0) < LAYOUT_VERSION)
+            notes.push(`brain at layout v${brainLayoutVersion ?? 0} < current v${LAYOUT_VERSION}`);
+    }
+    else if (hasTierPack && packIsOurs && hasSkillDir && hasBrain && brainLayoutVersion === LAYOUT_VERSION) {
+        // The managed surface is fully at the current layout. (.jungle/config.yaml
+        // is the CLI's concern — the engine owns the .claude/.brain surface.)
+        state = 'current';
+    }
+    else {
+        state = 'partial';
+        notes.push('some clan artifacts present, setup incomplete — re-run to complete');
+    }
+    return {
+        repo, os, isGit, tier, tierSource, mode, identity,
+        hasConfig, configError, hasMcp, mcpServers,
+        inventory: scanInventory(repo, { home: opts.home }),
+        hasBrain, brainLayoutVersion, state, notes,
+    };
+}

package/dist/inventory.d.ts

@@ -0,0 +1,18 @@
+/**
+ * claude-inventory — discover the user's EXISTING Claude Code assets (agents,
+ * skills, commands, hooks) at both project and global (~/.claude) scope, so the
+ * clan can work WITH them instead of ignoring or duplicating them.
+ *
+ * The manifest it writes (.clan/inventory.json) is what the awareness skill
+ * points the Alpha at ("prefer these where they overlap").
+ */
+import type { InventoryItem } from './types.js';
+/**
+ * Inventory the user's existing Claude Code assets. Excludes the engine's own
+ * clan-awareness skill and tier command packs (those are ours, not "existing").
+ */
+export declare function scanInventory(repo: string, opts?: {
+    home?: string;
+}): InventoryItem[];
+/** Write the manifest the awareness skill references. Returns the repo-relative path. */
+export declare function writeInventoryManifest(repo: string, items: InventoryItem[]): string;

package/dist/inventory.js

@@ -0,0 +1,136 @@
+/**
+ * claude-inventory — discover the user's EXISTING Claude Code assets (agents,
+ * skills, commands, hooks) at both project and global (~/.claude) scope, so the
+ * clan can work WITH them instead of ignoring or duplicating them.
+ *
+ * The manifest it writes (.clan/inventory.json) is what the awareness skill
+ * points the Alpha at ("prefer these where they overlap").
+ */
+import { readFileSync, existsSync, readdirSync, statSync, mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+/** Pull `name:`/`description:` from a leading YAML frontmatter block, if any. */
+function frontmatter(content) {
+    if (!content.startsWith('---'))
+        return {};
+    const end = content.indexOf('\n---', 3);
+    if (end === -1)
+        return {};
+    const block = content.slice(3, end);
+    const out = {};
+    for (const line of block.split('\n')) {
+        const m = /^(name|description):\s*(.+)$/.exec(line.trim());
+        if (m)
+            out[m[1]] = m[2].replace(/^["']|["']$/g, '').trim();
+    }
+    return out;
+}
+function safeRead(p) {
+    try {
+        return readFileSync(p, 'utf-8');
+    }
+    catch {
+        return '';
+    }
+}
+/** Recursively list *.md files under a dir (bounded depth for safety). */
+function listMd(dir, depth = 2) {
+    if (depth < 0 || !existsSync(dir))
+        return [];
+    const out = [];
+    let entries = [];
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return out;
+    }
+    for (const e of entries) {
+        const full = join(dir, e);
+        let st;
+        try {
+            st = statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (st.isDirectory())
+            out.push(...listMd(full, depth - 1));
+        else if (e.endsWith('.md'))
+            out.push(full);
+    }
+    return out;
+}
+function scanDir(base, kind, scope, sub) {
+    const dir = join(base, sub);
+    const items = [];
+    for (const file of listMd(dir)) {
+        const fm = frontmatter(safeRead(file));
+        // Skill dirs use <name>/SKILL.md; commands use <ns>/<name>.md; agents flat.
+        const rel = file.slice(dir.length + 1);
+        const name = fm.name ?? rel.replace(/\.md$/, '').replace(/\/SKILL$/, '');
+        items.push({ kind, name, path: file, scope, description: fm.description });
+    }
+    return items;
+}
+/** Hooks declared in a settings.json (project or global). */
+function scanHooks(base, scope) {
+    const out = [];
+    for (const f of ['settings.json', 'settings.local.json']) {
+        const p = join(base, f);
+        let doc;
+        try {
+            doc = JSON.parse(readFileSync(p, 'utf-8'));
+        }
+        catch {
+            continue;
+        }
+        const hooks = doc?.hooks ?? {};
+        for (const event of Object.keys(hooks)) {
+            const entries = Array.isArray(hooks[event]) ? hooks[event] : [];
+            for (const entry of entries) {
+                for (const h of entry?.hooks ?? []) {
+                    if (h?.command && !/load-brain\.(mjs|sh)/.test(h.command)) {
+                        out.push({ kind: 'hook', name: `${event}:${h.command.slice(0, 40)}`, path: p, scope, description: `${event} hook` });
+                    }
+                }
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Inventory the user's existing Claude Code assets. Excludes the engine's own
+ * clan-awareness skill and tier command packs (those are ours, not "existing").
+ */
+export function scanInventory(repo, opts = {}) {
+    const home = opts.home ?? homedir();
+    const projClaude = join(repo, '.claude');
+    const globalClaude = join(home, '.claude');
+    const items = [
+        ...scanDir(projClaude, 'agent', 'project', 'agents'),
+        ...scanDir(projClaude, 'skill', 'project', 'skills'),
+        ...scanDir(projClaude, 'command', 'project', 'commands'),
+        ...scanHooks(projClaude, 'project'),
+        ...scanDir(globalClaude, 'agent', 'global', 'agents'),
+        ...scanDir(globalClaude, 'skill', 'global', 'skills'),
+        ...scanDir(globalClaude, 'command', 'global', 'commands'),
+        ...scanHooks(globalClaude, 'global'),
+    ];
+    // Drop the engine's own artifacts — they aren't "existing user assets".
+    return items.filter(it => {
+        if (it.kind === 'skill' && it.name === 'clan-awareness')
+            return false;
+        if (it.kind === 'command' && /^(clan|district|jungle|biome):/.test(it.name))
+            return false;
+        return true;
+    });
+}
+/** Write the manifest the awareness skill references. Returns the repo-relative path. */
+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 }));
+    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

@@ -0,0 +1,27 @@
+/**
+ * Non-destructive .mcp.json authoring. Merges a correctly-named `jungle-local`
+ * server alongside whatever the user already has — the primitive that makes
+ * "convert an existing setup" non-destructive. Never clobbers; the bare name
+ * `jungle` silently collides with the global human-council server, so we always
+ * use `jungle-local`.
+ */
+import type { PlanAction } from './types.js';
+export interface JungleCreds {
+    apiUrl: string;
+    alphaId: string;
+    apiKey: string;
+    humanEmail?: string;
+}
+export declare function jungleLocalServer(c: JungleCreds): {
+    command: string;
+    args: string[];
+    env: Record<string, string>;
+};
+/**
+ * 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
+ * created and the repo is git, a gitignore append — or a 'skip' when the
+ * jungle-local entry is already present and identical, or the file is
+ * unparseable (never clobber).
+ */
+export declare function planMcpJson(repo: string, creds: JungleCreds, isGit: boolean): PlanAction[];

package/dist/mcp.js

@@ -0,0 +1,74 @@
+/**
+ * Non-destructive .mcp.json authoring. Merges a correctly-named `jungle-local`
+ * server alongside whatever the user already has — the primitive that makes
+ * "convert an existing setup" non-destructive. Never clobbers; the bare name
+ * `jungle` silently collides with the global human-council server, so we always
+ * use `jungle-local`.
+ */
+import { readFileSync } from 'fs';
+import { join } from 'path';
+export function jungleLocalServer(c) {
+    const env = {
+        JUNGLE_API_URL: c.apiUrl,
+        JUNGLE_ALPHA_ID: c.alphaId,
+        JUNGLE_API_KEY: c.apiKey,
+    };
+    if (c.humanEmail)
+        env.JUNGLE_HUMAN_EMAIL = c.humanEmail;
+    return { command: 'npx', args: ['-y', '@nfinitmonkeys/jungle-mcp'], env };
+}
+/**
+ * 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
+ * created and the repo is git, a gitignore append — or a 'skip' when the
+ * jungle-local entry is already present and identical, or the file is
+ * unparseable (never clobber).
+ */
+export function planMcpJson(repo, creds, isGit) {
+    const mcpPath = join(repo, '.mcp.json');
+    const server = jungleLocalServer(creds);
+    let doc = {};
+    let existed = false;
+    try {
+        const parsed = JSON.parse(readFileSync(mcpPath, 'utf-8'));
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+            return [{ kind: 'skip', path: '.mcp.json', note: '.mcp.json root is not a JSON object — fix by hand, then re-run', reason: 'malformed' }];
+        }
+        doc = parsed;
+        existed = true;
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT') {
+            return [{ kind: 'skip', path: '.mcp.json', note: '.mcp.json is not valid JSON — fix by hand, then re-run', reason: 'unparseable' }];
+        }
+    }
+    if (doc.mcpServers !== undefined && (typeof doc.mcpServers !== 'object' || doc.mcpServers === null || Array.isArray(doc.mcpServers))) {
+        return [{ kind: 'skip', path: '.mcp.json', note: '.mcp.json "mcpServers" is not an object — fix by hand, then re-run', reason: 'malformed' }];
+    }
+    doc.mcpServers = doc.mcpServers ?? {};
+    const prior = doc.mcpServers['jungle-local'];
+    if (prior && JSON.stringify(prior) === JSON.stringify(server)) {
+        return [{ kind: 'skip', path: '.mcp.json', note: 'jungle-local already present', reason: 'identical' }];
+    }
+    doc.mcpServers['jungle-local'] = server;
+    const actions = [{
+            kind: 'merge',
+            path: '.mcp.json',
+            content: JSON.stringify(doc, null, 2) + '\n',
+            note: existed ? 'merge jungle-local alongside existing servers' : 'create .mcp.json (jungle-local)',
+            reason: existed ? 'other MCP servers preserved' : 'holds a live key',
+        }];
+    if (isGit) {
+        const giPath = join(repo, '.gitignore');
+        let gi = '';
+        try {
+            gi = readFileSync(giPath, 'utf-8');
+        }
+        catch { /* absent */ }
+        if (!gi.split('\n').some(l => l.trim() === '.mcp.json')) {
+            const prefix = gi.length === 0 || gi.endsWith('\n') ? '' : '\n';
+            actions.push({ kind: 'append', path: '.gitignore', content: prefix + '.mcp.json\n', note: 'gitignore .mcp.json (holds a live API key)' });
+        }
+    }
+    return actions;
+}

package/dist/reconcile.d.ts

@@ -0,0 +1,27 @@
+/**
+ * reconcile — the plan builder. Given a target identity and an inspect result,
+ * produce an idempotent, non-destructive Plan of actions. This is where the
+ * "our output vs the user's file" decision lives:
+ *
+ *   identical             → skip
+ *   our managed file      → update (content changed)
+ *   a user file at path    → backup-replace (their bytes are saved first)
+ *   absent                → create
+ *   brain page present    → skip (never clobber accumulated memory)
+ *   JSON with user content → merge (.mcp.json / settings.json)
+ */
+import { type ClanIdentity, type InspectResult, type Plan } from './types.js';
+export interface ReconcileOptions {
+    /** write .mcp.json from these creds (connected mode). */
+    jungle?: {
+        apiUrl: string;
+        alphaId: string;
+        apiKey: string;
+        humanEmail?: string;
+    };
+    /** include the brain scaffold (default true). */
+    brain?: boolean;
+    /** a deterministic YYYY-MM-DD for brain timestamps (CLI passes today). */
+    today?: string;
+}
+export declare function reconcile(identity: ClanIdentity, ins: InspectResult, opts?: ReconcileOptions): Plan;

package/dist/reconcile.js

@@ -0,0 +1,109 @@
+/**
+ * reconcile — the plan builder. Given a target identity and an inspect result,
+ * produce an idempotent, non-destructive Plan of actions. This is where the
+ * "our output vs the user's file" decision lives:
+ *
+ *   identical             → skip
+ *   our managed file      → update (content changed)
+ *   a user file at path    → backup-replace (their bytes are saved first)
+ *   absent                → create
+ *   brain page present    → skip (never clobber accumulated memory)
+ *   JSON with user content → merge (.mcp.json / settings.json)
+ */
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { claudeMdIdentity, geoTierMarker, claudeSurface, brainScaffold, hasManagedMarker, findGeoTierMarker, ALL_TIER_DIRS, } from './templates.js';
+import { planMcpJson } from './mcp.js';
+import { planBrainHook } from './hooks.js';
+import { scanInventory } from './inventory.js';
+function read(repo, rel) {
+    try {
+        return readFileSync(join(repo, rel), 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+/** Reconcile one managed template file against what's on disk. */
+function reconcileFile(repo, f) {
+    const existing = read(repo, f.path);
+    if (existing === null) {
+        return { kind: 'create', path: f.path, content: f.content, note: 'create', chmod: f.chmod };
+    }
+    if (existing === f.content) {
+        return { kind: 'skip', path: f.path, note: 'identical', reason: 'unchanged' };
+    }
+    // Ours (marker as a real frontmatter key, or a known script path) → update;
+    // else the user wrote a file at our path → back it up and replace.
+    const ours = f.managed ? hasManagedMarker(existing) : true; // scripts are ours by path
+    if (ours) {
+        return { kind: 'update', path: f.path, content: f.content, note: 'update (engine-managed, content changed)', chmod: f.chmod };
+    }
+    return { kind: 'backup-replace', path: f.path, content: f.content, note: 'a non-engine file exists here — backed up, then replaced', chmod: f.chmod, reason: 'not engine-managed' };
+}
+/** CLAUDE.md: create fresh with the identity block, or (existing file) ensure
+ *  only a REAL top-level geo-tier declaration line — never rewrite the user's
+ *  prose, and never touch a marker that appears inside a code block or example. */
+function reconcileClaudeMd(repo, i) {
+    const existing = read(repo, 'CLAUDE.md');
+    const marker = geoTierMarker(i.tier);
+    if (existing === null) {
+        return { kind: 'create', path: 'CLAUDE.md', content: claudeMdIdentity(i), note: 'create CLAUDE.md with identity block' };
+    }
+    const found = findGeoTierMarker(existing);
+    if (found) {
+        if (found.line.trim() === marker)
+            return { kind: 'skip', path: 'CLAUDE.md', note: 'geo-tier marker present', reason: 'unchanged' };
+        // Replace exactly the one real declaration line; prose + any in-fence
+        // examples are untouched.
+        return { kind: 'merge', path: 'CLAUDE.md', content: existing.replace(found.line, marker), note: `retier CLAUDE.md marker → ${i.tier}`, reason: 'only the declaration line changes' };
+    }
+    // No real declaration (a marker inside a code fence doesn't count) → prepend one.
+    return { kind: 'merge', path: 'CLAUDE.md', content: `${marker}\n${existing}`, note: 'prepend geo-tier marker (prose untouched)' };
+}
+export function reconcile(identity, ins, opts = {}) {
+    const repo = ins.repo;
+    const actions = [];
+    // 1. CLAUDE.md declaration
+    actions.push(reconcileClaudeMd(repo, identity));
+    // 2. legacy flat skill at the awareness path → backed up, then removed
+    //    (superseded by the SKILL.md dir which is the only loadable format).
+    if (read(repo, '.claude/skills/clan-awareness.md') !== null) {
+        actions.push({ kind: 'remove', path: '.claude/skills/clan-awareness.md', note: 'legacy awareness-skill path — superseded by SKILL.md dir (backed up)' });
+    }
+    // 3. stale command packs from other tiers → backup-remove (only our own)
+    for (const t of ALL_TIER_DIRS.filter(x => x !== identity.tier)) {
+        for (const name of ['status', 'inbox', 'log', 'policies', 'request', 'health']) {
+            const rel = `.claude/commands/${t}/${name}.md`;
+            const c = read(repo, rel);
+            if (c !== null && hasManagedMarker(c))
+                actions.push({ kind: 'remove', path: rel, note: `remove stale ${t} command (repo is ${identity.tier})` });
+        }
+    }
+    // 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);
+    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` });
+    else if (invExisting !== invContent)
+        actions.push({ kind: 'update', path: '.clan/inventory.json', content: invContent, note: `refresh inventory (${inv.length} 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));
+    // 7. SessionStart brain hook (tier-aware command)
+    actions.push(...planBrainHook(repo, identity));
+    // 8. brain scaffold — create-only (never overwrite accumulated brain pages)
+    if (opts.brain !== false) {
+        for (const f of brainScaffold(identity, opts.today ?? '1970-01-01')) {
+            if (read(repo, f.path) === null)
+                actions.push({ kind: 'create', path: f.path, content: f.content, note: 'brain scaffold' });
+        }
+    }
+    return { identity, actions, repo };
+}

package/dist/templates.d.ts

@@ -0,0 +1,58 @@
+/**
+ * THE authoritative template set. This is the single source of truth for every
+ * file the engine writes into a node — the whole point of the engine is that
+ * the published CLIs AND the internal fleet tooling both render from here, so
+ * they can never drift again.
+ *
+ * Every generated file carries a marker (`generated-by: clan-engine@<v>` +
+ * `layout: <n>`) so reconciliation can distinguish our output (safe to update)
+ * from a user's hand-written file at the same path (must be backed up).
+ */
+import { type ClanIdentity, type GeneratedFile, type Tier } from './types.js';
+/** Frontmatter marker lines (inside a YAML block). */
+export declare function markerLines(): string;
+/**
+ * True only when the file carries an engine (or predecessor) marker as a real
+ * frontmatter KEY — not merely a substring somewhere in the body. This stops a
+ * user file that happens to mention "clan-engine:" in prose from being
+ * misclassified as ours and silently overwritten.
+ */
+export declare function hasManagedMarker(content: string): boolean;
+/** Geo-tier HTML-comment marker for CLAUDE.md (declared identity, never inferred). */
+export declare function geoTierMarker(tier: Tier): string;
+/**
+ * Find a REAL top-level geo-tier declaration: a standalone line (its trimmed
+ * content is exactly the marker) that is NOT inside a fenced code block. A
+ * marker mentioned inside ``` fences or in prose is documentation, not a
+ * declaration, and must be ignored (else tier is mis-detected and retier
+ * corrupts the user's docs). Returns the declared tier + the exact line, or null.
+ */
+export declare function findGeoTierMarker(content: string): {
+    tier: Tier;
+    line: string;
+} | null;
+/** The identity block prepended to CLAUDE.md when the file is created fresh.
+ *  When CLAUDE.md already exists we only ensure the geo-tier marker line
+ *  (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). */
+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
+ *  run at project root) + the script self-locates via import.meta, so it is
+ *  cwd- and OS-independent. Tier-aware because the brain root is. */
+export declare function hookCommand(i: ClanIdentity): string;
+/** Regex matching any load-brain hook command (bash or node, any brain root) —
+ *  used to detect + migrate a previously-wired hook. */
+export declare const LOAD_BRAIN_HOOK_RE: RegExp;
+export declare function loadBrainScript(i: ClanIdentity): GeneratedFile;
+/**
+ * Every managed file the engine authors into .claude/ + .brain/ for one
+ * identity, EXCEPT the merge-based artifacts (.mcp.json, settings.json hook,
+ * CLAUDE.md) which reconcile handles specially because they touch user content.
+ */
+export declare function claudeSurface(i: ClanIdentity): GeneratedFile[];
+/** All tier command directories the engine owns — used to prune stale packs
+ *  from a different tier (e.g. a repo re-tiered clan → district). */
+export declare const ALL_TIER_DIRS: Tier[];