paracosm 0.4.346 → 0.4.363

package/README.md

@@ -177,6 +177,34 @@ npm run dashboard      # opens http://localhost:3456
 
 The dashboard includes a scenario editor where you can write, import, compile, and run custom worlds from the browser.
 
+### 4. Or run the standalone CLI
+
+After `npm install paracosm` you get two binaries:
+
+```bash
+paracosm                # run one leader once; prints turn-by-turn narrative
+paracosm-dashboard 6    # start the web dashboard and run a 6-turn sim
+```
+
+Both CLIs look for `leaders.json` in this order:
+
+1. `--leaders <path>` flag (explicit)
+2. `./leaders.json` in your current directory
+3. `./config/leaders.json` in your current directory
+4. A bundled `config/leaders.example.json` (so commands work out of the box)
+
+Copy the example to start customizing:
+
+```bash
+# Option 1: in your project root
+cp node_modules/paracosm/config/leaders.example.json leaders.json
+
+# Option 2: organized in a config/ folder
+mkdir -p config && cp node_modules/paracosm/config/leaders.example.json config/leaders.json
+```
+
+Then edit the HEXACO sliders and `instructions` fields to describe your own leaders — the simulation picks up the file on the next run.
+
 ## Scenario Compiler
 
 The compiler turns your JSON into a runnable scenario by generating TypeScript hooks via LLM calls:

package/config/leaders.example.json

@@ -0,0 +1,32 @@
+{
+  "leaders": [
+    {
+      "name": "Aria Chen",
+      "archetype": "The Visionary",
+      "colony": "Ares Horizon",
+      "hexaco": {
+        "openness": 0.95,
+        "conscientiousness": 0.35,
+        "extraversion": 0.85,
+        "agreeableness": 0.55,
+        "emotionality": 0.30,
+        "honestyHumility": 0.65
+      },
+      "instructions": "You are Commander Aria Chen. Bold expansion, calculated risks. Favor higher upside even when riskier. Respond with JSON."
+    },
+    {
+      "name": "Dietrich Voss",
+      "archetype": "The Engineer",
+      "colony": "Meridian Base",
+      "hexaco": {
+        "openness": 0.25,
+        "conscientiousness": 0.97,
+        "extraversion": 0.30,
+        "agreeableness": 0.45,
+        "emotionality": 0.70,
+        "honestyHumility": 0.90
+      },
+      "instructions": "You are Commander Dietrich Voss. Engineering discipline, safety margins. Favor lower risk. Respond with JSON."
+    }
+  ]
+}

package/config/leaders.json

@@ -0,0 +1,32 @@
+{
+  "leaders": [
+    {
+      "name": "Aria Chen",
+      "archetype": "The Visionary",
+      "colony": "Ares Horizon",
+      "hexaco": {
+        "openness": 0.95,
+        "conscientiousness": 0.35,
+        "extraversion": 0.85,
+        "agreeableness": 0.55,
+        "emotionality": 0.30,
+        "honestyHumility": 0.65
+      },
+      "instructions": "You are Commander Aria Chen. Bold expansion, calculated risks. Favor higher upside even when riskier. Respond with JSON."
+    },
+    {
+      "name": "Dietrich Voss",
+      "archetype": "The Engineer",
+      "colony": "Meridian Base",
+      "hexaco": {
+        "openness": 0.25,
+        "conscientiousness": 0.97,
+        "extraversion": 0.30,
+        "agreeableness": 0.45,
+        "emotionality": 0.70,
+        "honestyHumility": 0.90
+      },
+      "instructions": "You are Commander Dietrich Voss. Engineering discipline, safety margins. Demand data before decisions. Favor lower risk. Respond with JSON."
+    }
+  ]
+}

package/dist/cli/cli-run-options.d.ts

@@ -0,0 +1,11 @@
+import type { LlmProvider, SimulationModelConfig } from './sim-config.js';
+export interface CliRunOptions {
+    maxTurns?: number;
+    seed?: number;
+    startYear?: number;
+    liveSearch: boolean;
+    provider?: LlmProvider;
+    models?: Partial<SimulationModelConfig>;
+}
+export declare function parseCliRunOptions(argv: string[]): CliRunOptions;
+//# sourceMappingURL=cli-run-options.d.ts.map

package/dist/cli/cli-run-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-run-options.d.ts","sourceRoot":"","sources":["../../src/cli/cli-run-options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAE1E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,CAAC;CACzC;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CAwChE"}

package/dist/cli/cli-run-options.js

@@ -0,0 +1,39 @@
+export function parseCliRunOptions(argv) {
+    const options = { liveSearch: false };
+    for (let index = 0; index < argv.length; index++) {
+        const arg = argv[index];
+        if (!arg.startsWith('--') && options.maxTurns === undefined) {
+            const turns = Number.parseInt(arg, 10);
+            if (Number.isFinite(turns))
+                options.maxTurns = turns;
+            continue;
+        }
+        switch (arg) {
+            case '--live':
+                options.liveSearch = true;
+                break;
+            case '--seed':
+                options.seed = Number.parseInt(argv[++index] ?? '', 10);
+                break;
+            case '--start-year':
+                options.startYear = Number.parseInt(argv[++index] ?? '', 10);
+                break;
+            case '--provider':
+                options.provider = argv[++index];
+                break;
+            case '--commander-model':
+                options.models = { ...(options.models ?? {}), commander: argv[++index] };
+                break;
+            case '--department-model':
+                options.models = { ...(options.models ?? {}), departments: argv[++index] };
+                break;
+            case '--judge-model':
+                options.models = { ...(options.models ?? {}), judge: argv[++index] };
+                break;
+            default:
+                break;
+        }
+    }
+    return options;
+}
+//# sourceMappingURL=cli-run-options.js.map

package/dist/cli/cli-run-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-run-options.js","sourceRoot":"","sources":["../../src/cli/cli-run-options.ts"],"names":[],"mappings":"AAWA,MAAM,UAAU,kBAAkB,CAAC,IAAc;IAC/C,MAAM,OAAO,GAAkB,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IAErD,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;QACjD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QAExB,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC5D,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;YACvC,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;gBAAE,OAAO,CAAC,QAAQ,GAAG,KAAK,CAAC;YACrD,SAAS;QACX,CAAC;QAED,QAAQ,GAAG,EAAE,CAAC;YACZ,KAAK,QAAQ;gBACX,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;gBAC1B,MAAM;YACR,KAAK,QAAQ;gBACX,OAAO,CAAC,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;gBACxD,MAAM;YACR,KAAK,cAAc;gBACjB,OAAO,CAAC,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;gBAC7D,MAAM;YACR,KAAK,YAAY;gBACf,OAAO,CAAC,QAAQ,GAAI,IAAI,CAAC,EAAE,KAAK,CAA6B,CAAC;gBAC9D,MAAM;YACR,KAAK,mBAAmB;gBACtB,OAAO,CAAC,MAAM,GAAG,EAAE,GAAG,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC;gBACzE,MAAM;YACR,KAAK,oBAAoB;gBACvB,OAAO,CAAC,MAAM,GAAG,EAAE,GAAG,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC;gBAC3E,MAAM;YACR,KAAK,eAAe;gBAClB,OAAO,CAAC,MAAM,GAAG,EAAE,GAAG,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC;gBACrE,MAAM;YACR;gBACE,MAAM;QACV,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/cli/compile-cli-options.d.ts

@@ -0,0 +1,14 @@
+import type { LlmProvider } from '../engine/types.js';
+export interface CompileCliOptions {
+    scenarioPath?: string;
+    provider: LlmProvider;
+    model: string;
+    cache: boolean;
+    cacheDir: string;
+    seedText?: string;
+    seedUrl?: string;
+    webSearch: boolean;
+    maxSearches?: number;
+}
+export declare function parseCompileCliOptions(argv: string[]): CompileCliOptions;
+//# sourceMappingURL=compile-cli-options.d.ts.map

package/dist/cli/compile-cli-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile-cli-options.d.ts","sourceRoot":"","sources":["../../src/cli/compile-cli-options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,MAAM,WAAW,iBAAiB;IAChC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,WAAW,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,iBAAiB,CAkDxE"}

package/dist/cli/compile-cli-options.js

@@ -0,0 +1,48 @@
+export function parseCompileCliOptions(argv) {
+    const options = {
+        provider: 'anthropic',
+        model: 'claude-sonnet-4-6',
+        cache: true,
+        cacheDir: '.paracosm/cache',
+        webSearch: true,
+    };
+    for (let index = 0; index < argv.length; index++) {
+        const arg = argv[index];
+        if (!arg.startsWith('--') && !options.scenarioPath) {
+            options.scenarioPath = arg;
+            continue;
+        }
+        switch (arg) {
+            case '--provider':
+                options.provider = argv[++index] ?? options.provider;
+                break;
+            case '--model':
+                options.model = argv[++index] ?? options.model;
+                break;
+            case '--no-cache':
+                options.cache = false;
+                break;
+            case '--cache-dir':
+                options.cacheDir = argv[++index] ?? options.cacheDir;
+                break;
+            case '--seed-text':
+                options.seedText = argv[++index];
+                break;
+            case '--seed-url':
+                options.seedUrl = argv[++index];
+                break;
+            case '--no-web-search':
+                options.webSearch = false;
+                break;
+            case '--max-searches': {
+                const value = Number.parseInt(argv[++index] ?? '', 10);
+                options.maxSearches = Number.isFinite(value) ? value : undefined;
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    return options;
+}
+//# sourceMappingURL=compile-cli-options.js.map

package/dist/cli/compile-cli-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile-cli-options.js","sourceRoot":"","sources":["../../src/cli/compile-cli-options.ts"],"names":[],"mappings":"AAcA,MAAM,UAAU,sBAAsB,CAAC,IAAc;IACnD,MAAM,OAAO,GAAsB;QACjC,QAAQ,EAAE,WAAW;QACrB,KAAK,EAAE,mBAAmB;QAC1B,KAAK,EAAE,IAAI;QACX,QAAQ,EAAE,iBAAiB;QAC3B,SAAS,EAAE,IAAI;KAChB,CAAC;IAEF,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;QACjD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QAExB,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC;YACnD,OAAO,CAAC,YAAY,GAAG,GAAG,CAAC;YAC3B,SAAS;QACX,CAAC;QAED,QAAQ,GAAG,EAAE,CAAC;YACZ,KAAK,YAAY;gBACf,OAAO,CAAC,QAAQ,GAAI,IAAI,CAAC,EAAE,KAAK,CAA6B,IAAI,OAAO,CAAC,QAAQ,CAAC;gBAClF,MAAM;YACR,KAAK,SAAS;gBACZ,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,EAAE,KAAK,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC;gBAC/C,MAAM;YACR,KAAK,YAAY;gBACf,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC;gBACtB,MAAM;YACR,KAAK,aAAa;gBAChB,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,EAAE,KAAK,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC;gBACrD,MAAM;YACR,KAAK,aAAa;gBAChB,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,EAAE,KAAK,CAAC,CAAC;gBACjC,MAAM;YACR,KAAK,YAAY;gBACf,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,EAAE,KAAK,CAAC,CAAC;gBAChC,MAAM;YACR,KAAK,iBAAiB;gBACpB,OAAO,CAAC,SAAS,GAAG,KAAK,CAAC;gBAC1B,MAAM;YACR,KAAK,gBAAgB,CAAC,CAAC,CAAC;gBACtB,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;gBACvD,OAAO,CAAC,WAAW,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;gBACjE,MAAM;YACR,CAAC;YACD;gBACE,MAAM;QACV,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/cli/compile.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * CLI: Compile a scenario JSON into a runnable ScenarioPackage.
+ *
+ * Usage:
+ *   npx tsx src/cli/compile.ts scenarios/submarine.json
+ *   npx tsx src/cli/compile.ts scenarios/submarine.json --provider anthropic --model claude-sonnet-4-6
+ *   npx tsx src/cli/compile.ts scenarios/submarine.json --no-cache
+ */
+export {};
+//# sourceMappingURL=compile.d.ts.map

package/dist/cli/compile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../src/cli/compile.ts"],"names":[],"mappings":";AACA;;;;;;;GAOG"}

package/dist/cli/compile.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+/**
+ * CLI: Compile a scenario JSON into a runnable ScenarioPackage.
+ *
+ * Usage:
+ *   npx tsx src/cli/compile.ts scenarios/submarine.json
+ *   npx tsx src/cli/compile.ts scenarios/submarine.json --provider anthropic --model claude-sonnet-4-6
+ *   npx tsx src/cli/compile.ts scenarios/submarine.json --no-cache
+ */
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { compileScenario } from '../engine/compiler/index.js';
+import { parseCompileCliOptions } from './compile-cli-options.js';
+async function main() {
+    const rawArgs = process.argv.slice(2);
+    const options = parseCompileCliOptions(rawArgs);
+    if (rawArgs.length === 0 || rawArgs.includes('--help') || rawArgs.includes('-h')) {
+        console.log(`
+paracosm compile — Generate runtime hooks for a scenario JSON
+
+Usage:
+  npx tsx src/cli/compile.ts <scenario.json> [options]
+
+Options:
+  --provider <provider>   LLM provider: openai | anthropic (default: anthropic)
+  --model <model>         Model name (default: claude-sonnet-4-6)
+  --no-cache              Skip disk cache
+  --cache-dir <dir>       Cache directory (default: .paracosm/cache)
+  --seed-text <text>      Seed scenario knowledge from inline text before hook generation
+  --seed-url <url>        Seed scenario knowledge from a URL before hook generation
+  --no-web-search         Skip live citation grounding during seed ingestion
+  --max-searches <n>      Cap the number of live grounding searches during seed ingestion
+  -h, --help              Show this help
+`);
+        process.exit(0);
+    }
+    if (!options.scenarioPath) {
+        console.error('  Scenario JSON path required. Run with --help for usage.');
+        process.exit(1);
+    }
+    const jsonPath = resolve(options.scenarioPath);
+    console.log(`\n  Compiling scenario: ${jsonPath}`);
+    console.log(`  Provider: ${options.provider} | Model: ${options.model} | Cache: ${options.cache}`);
+    if (options.seedUrl) {
+        console.log(`  Seed URL: ${options.seedUrl} | Web search: ${options.webSearch} | Max searches: ${options.maxSearches ?? 5}`);
+    }
+    else if (options.seedText) {
+        console.log(`  Seed text: ${Math.min(options.seedText.length, 160)} chars | Web search: ${options.webSearch} | Max searches: ${options.maxSearches ?? 5}`);
+    }
+    console.log();
+    let scenarioJson;
+    try {
+        scenarioJson = JSON.parse(readFileSync(jsonPath, 'utf-8'));
+    }
+    catch (err) {
+        console.error(`  Error reading ${jsonPath}: ${err}`);
+        process.exit(1);
+    }
+    const scenario = await compileScenario(scenarioJson, {
+        provider: options.provider,
+        model: options.model,
+        cache: options.cache,
+        cacheDir: options.cacheDir,
+        seedText: options.seedText,
+        seedUrl: options.seedUrl,
+        webSearch: options.webSearch,
+        maxSearches: options.maxSearches,
+        onProgress(hookName, status) {
+            const icons = {
+                generating: '...',
+                cached: '(cached)',
+                done: 'done',
+                fallback: 'FALLBACK',
+            };
+            if (status === 'generating') {
+                process.stdout.write(`  Generating ${hookName}... `);
+            }
+            else {
+                console.log(icons[status] ?? status);
+            }
+        },
+    });
+    console.log(`\n  Scenario compiled: ${scenario.id} v${scenario.version}`);
+    console.log(`  Departments: ${scenario.departments.map(d => d.id).join(', ')}`);
+    console.log(`  Hooks: ${Object.keys(scenario.hooks).filter(k => scenario.hooks[k]).join(', ')}`);
+    console.log(`  Ready for: runSimulation(leader, personnel, { scenario })\n`);
+}
+main().catch((err) => {
+    console.error('Compile failed:', err);
+    process.exit(1);
+});
+//# sourceMappingURL=compile.js.map

package/dist/cli/compile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile.js","sourceRoot":"","sources":["../../src/cli/compile.ts"],"names":[],"mappings":"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"}

package/dist/cli/custom-scenarios.d.ts

@@ -0,0 +1,10 @@
+import type { ScenarioPackage } from '../engine/types.js';
+export type CustomScenarioSource = 'memory' | 'disk' | 'compiled' | 'builtin';
+export interface CustomScenarioEntry {
+    scenario: ScenarioPackage;
+    source: CustomScenarioSource;
+}
+export declare function isRunnableScenarioPackage(value: unknown): value is ScenarioPackage;
+export declare function loadDiskCustomScenarios(scenarioDir: string): Map<string, CustomScenarioEntry>;
+export declare function describeCustomScenarioSource(source: CustomScenarioSource): string;
+//# sourceMappingURL=custom-scenarios.d.ts.map

package/dist/cli/custom-scenarios.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-scenarios.d.ts","sourceRoot":"","sources":["../../src/cli/custom-scenarios.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;AAE9E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,eAAe,CAAC;IAC1B,MAAM,EAAE,oBAAoB,CAAC;CAC9B;AAcD,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAwClF;AAED,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAmB7F;AAED,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAKjF"}

package/dist/cli/custom-scenarios.js

@@ -0,0 +1,93 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function hasString(value, key) {
+    return typeof value[key] === 'string' && value[key].length > 0;
+}
+function hasNumber(value, key) {
+    return typeof value[key] === 'number' && Number.isFinite(value[key]);
+}
+export function isRunnableScenarioPackage(value) {
+    if (!isRecord(value))
+        return false;
+    if (!hasString(value, 'id') || !hasString(value, 'version'))
+        return false;
+    if (value.engineArchetype !== 'closed_turn_based_settlement')
+        return false;
+    const labels = value.labels;
+    const theme = value.theme;
+    const setup = value.setup;
+    const world = value.world;
+    const ui = value.ui;
+    const policies = value.policies;
+    const hooks = value.hooks;
+    if (!isRecord(labels))
+        return false;
+    if (!hasString(labels, 'name') || !hasString(labels, 'shortName') || !hasString(labels, 'populationNoun') || !hasString(labels, 'settlementNoun') || !hasString(labels, 'currency'))
+        return false;
+    if (!isRecord(theme))
+        return false;
+    if (!hasString(theme, 'primaryColor') || !hasString(theme, 'accentColor') || !isRecord(theme.cssVariables))
+        return false;
+    if (!isRecord(setup))
+        return false;
+    if (!hasNumber(setup, 'defaultTurns') || !hasNumber(setup, 'defaultSeed') || !hasNumber(setup, 'defaultStartYear') || !hasNumber(setup, 'defaultPopulation') || !Array.isArray(setup.configurableSections))
+        return false;
+    if (!isRecord(world) || !isRecord(world.metrics) || !isRecord(world.capacities) || !isRecord(world.statuses) || !isRecord(world.politics) || !isRecord(world.environment))
+        return false;
+    if (!Array.isArray(value.departments) || !Array.isArray(value.metrics) || !Array.isArray(value.events) || !Array.isArray(value.effects) || !Array.isArray(value.presets))
+        return false;
+    if (!isRecord(ui))
+        return false;
+    if (!Array.isArray(ui.headerMetrics) || !Array.isArray(ui.tooltipFields) || !Array.isArray(ui.reportSections) || !isRecord(ui.departmentIcons) || !isRecord(ui.eventRenderers) || !Array.isArray(ui.setupSections))
+        return false;
+    if (!isRecord(policies))
+        return false;
+    if (!isRecord(policies.toolForging) || typeof policies.toolForging.enabled !== 'boolean')
+        return false;
+    if (!isRecord(policies.liveSearch) || typeof policies.liveSearch.enabled !== 'boolean' || typeof policies.liveSearch.mode !== 'string')
+        return false;
+    if (!isRecord(policies.bulletin) || typeof policies.bulletin.enabled !== 'boolean')
+        return false;
+    if (!isRecord(policies.characterChat) || typeof policies.characterChat.enabled !== 'boolean')
+        return false;
+    if (!isRecord(policies.sandbox) || !hasNumber(policies.sandbox, 'timeoutMs') || !hasNumber(policies.sandbox, 'memoryMB'))
+        return false;
+    if (!isRecord(value.knowledge) || !isRecord(value.knowledge.topics) || !isRecord(value.knowledge.categoryMapping))
+        return false;
+    if (!isRecord(hooks))
+        return false;
+    return true;
+}
+export function loadDiskCustomScenarios(scenarioDir) {
+    const catalog = new Map();
+    if (!existsSync(scenarioDir))
+        return catalog;
+    for (const entry of readdirSync(scenarioDir, { withFileTypes: true })) {
+        if (!entry.isFile() || !entry.name.endsWith('.json'))
+            continue;
+        const filePath = resolve(scenarioDir, entry.name);
+        try {
+            const parsed = JSON.parse(readFileSync(filePath, 'utf-8'));
+            if (!isRunnableScenarioPackage(parsed))
+                continue;
+            catalog.set(parsed.id, { scenario: parsed, source: 'disk' });
+        }
+        catch {
+            // Ignore unreadable or invalid custom scenario files at boot.
+        }
+    }
+    return catalog;
+}
+export function describeCustomScenarioSource(source) {
+    if (source === 'builtin')
+        return 'Built-in scenario';
+    if (source === 'disk')
+        return 'Custom scenario (disk)';
+    if (source === 'compiled')
+        return 'Custom compiled scenario';
+    return 'Custom scenario (memory)';
+}
+//# sourceMappingURL=custom-scenarios.js.map

package/dist/cli/custom-scenarios.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-scenarios.js","sourceRoot":"","sources":["../../src/cli/custom-scenarios.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAChE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAUpC,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,SAAS,SAAS,CAAC,KAA8B,EAAE,GAAW;IAC5D,OAAO,OAAO,KAAK,CAAC,GAAG,CAAC,KAAK,QAAQ,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;AACjE,CAAC;AAED,SAAS,SAAS,CAAC,KAA8B,EAAE,GAAW;IAC5D,OAAO,OAAO,KAAK,CAAC,GAAG,CAAC,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;AACvE,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,KAAc;IACtD,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACnC,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC;QAAE,OAAO,KAAK,CAAC;IAC1E,IAAI,KAAK,CAAC,eAAe,KAAK,8BAA8B;QAAE,OAAO,KAAK,CAAC;IAE3E,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAC5B,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;IAC1B,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;IAC1B,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;IAC1B,MAAM,EAAE,GAAG,KAAK,CAAC,EAAE,CAAC;IACpB,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;IAChC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;IAE1B,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;QAAE,OAAO,KAAK,CAAC;IACpC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,gBAAgB,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,gBAAgB,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,UAAU,CAAC;QAAE,OAAO,KAAK,CAAC;IAElM,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACnC,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,cAAc,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,YAAY,CAAC;QAAE,OAAO,KAAK,CAAC;IAEzH,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACnC,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,cAAc,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,kBAAkB,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,mBAAmB,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,oBAAoB,CAAC;QAAE,OAAO,KAAK,CAAC;IAEzN,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,WAAW,CAAC;QAAE,OAAO,KAAK,CAAC;IAExL,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC;QAAE,OAAO,KAAK,CAAC;IAEvL,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QAAE,OAAO,KAAK,CAAC;IAChC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,aAAa,CAAC;QAAE,OAAO,KAAK,CAAC;IAEjO,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAAE,OAAO,KAAK,CAAC;IACtC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,OAAO,QAAQ,CAAC,WAAW,CAAC,OAAO,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACvG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,OAAO,QAAQ,CAAC,UAAU,CAAC,OAAO,KAAK,SAAS,IAAI,OAAO,QAAQ,CAAC,UAAU,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACrJ,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,OAAO,QAAQ,CAAC,QAAQ,CAAC,OAAO,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACjG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,OAAO,QAAQ,CAAC,aAAa,CAAC,OAAO,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAC3G,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;QAAE,OAAO,KAAK,CAAC;IAEvI,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,SAAS,CAAC,eAAe,CAAC;QAAE,OAAO,KAAK,CAAC;IAChI,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAEnC,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,WAAmB;IACzD,MAAM,OAAO,GAAG,IAAI,GAAG,EAA+B,CAAC;IACvD,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC;QAAE,OAAO,OAAO,CAAC;IAE7C,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,WAAW,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;QACtE,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;YAAE,SAAS;QAE/D,MAAM,QAAQ,GAAG,OAAO,CAAC,WAAW,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QAElD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;YAC3D,IAAI,CAAC,yBAAyB,CAAC,MAAM,CAAC;gBAAE,SAAS;YACjD,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;QAC/D,CAAC;QAAC,MAAM,CAAC;YACP,8DAA8D;QAChE,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,4BAA4B,CAAC,MAA4B;IACvE,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,mBAAmB,CAAC;IACrD,IAAI,MAAM,KAAK,MAAM;QAAE,OAAO,wBAAwB,CAAC;IACvD,IAAI,MAAM,KAAK,UAAU;QAAE,OAAO,0BAA0B,CAAC;IAC7D,OAAO,0BAA0B,CAAC;AACpC,CAAC"}

package/dist/cli/leaders-resolver.d.ts

@@ -0,0 +1,26 @@
+import type { LeaderConfig } from './types.js';
+export interface ResolvedLeaders {
+    leaders: LeaderConfig[];
+    /** Absolute path of the file the leaders were read from. Surfaces
+     *  in CLI output so users know which file is actually in use. */
+    sourcePath: string;
+    /** Marker for whether the source was the shipped example (we
+     *  want to print a hint nudging users to create their own). */
+    isExample: boolean;
+}
+/**
+ * Walks the candidate paths and loads the first `leaders.json` that
+ * exists. Throws only when nothing (not even the bundled example)
+ * is available — which would indicate a broken install.
+ */
+export declare function resolveLeaders(options?: {
+    explicitPath?: string;
+}): ResolvedLeaders;
+/**
+ * Pulls `--leaders <path>` out of argv WITHOUT mutating the array.
+ * Returns undefined when the flag isn't present. Kept separate from
+ * the main CLI parser so run.ts / serve.ts can resolve leaders the
+ * same way without duplicating flag logic.
+ */
+export declare function parseLeadersFlag(args: readonly string[]): string | undefined;
+//# sourceMappingURL=leaders-resolver.d.ts.map

package/dist/cli/leaders-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"leaders-resolver.d.ts","sourceRoot":"","sources":["../../src/cli/leaders-resolver.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAK/C,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB;qEACiE;IACjE,UAAU,EAAE,MAAM,CAAC;IACnB;mEAC+D;IAC/D,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,GAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,eAAe,CAwBvF;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAM5E"}

package/dist/cli/leaders-resolver.js

@@ -0,0 +1,66 @@
+/**
+ * Resolve the active `leaders.json` for a paracosm CLI invocation.
+ *
+ * Search order (first match wins):
+ *   1. --leaders <path> CLI flag (explicit path)
+ *   2. $CWD/leaders.json          (user's project root)
+ *   3. $CWD/config/leaders.json   (user's config dir)
+ *   4. <package>/config/leaders.json        (paracosm-shipped fallback)
+ *   5. <package>/config/leaders.example.json (last-resort default)
+ *
+ * Covers three consumer shapes:
+ *   - Repo clone: users edit config/leaders.json at the repo root.
+ *   - npm install: users drop leaders.json (or config/leaders.json)
+ *     into their project CWD.
+ *   - npx one-off: falls back to the bundled example so `npx
+ *     paracosm` Just Works even before the user writes any config.
+ *
+ * @module paracosm/cli/leaders-resolver
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+/**
+ * Walks the candidate paths and loads the first `leaders.json` that
+ * exists. Throws only when nothing (not even the bundled example)
+ * is available — which would indicate a broken install.
+ */
+export function resolveLeaders(options = {}) {
+    const cwd = process.cwd();
+    const packageRoot = resolve(__dirname, '..', '..');
+    const candidates = [];
+    if (options.explicitPath) {
+        candidates.push({ path: resolve(cwd, options.explicitPath), isExample: false });
+    }
+    candidates.push({ path: resolve(cwd, 'leaders.json'), isExample: false });
+    candidates.push({ path: resolve(cwd, 'config', 'leaders.json'), isExample: false });
+    candidates.push({ path: resolve(packageRoot, 'config', 'leaders.json'), isExample: false });
+    candidates.push({ path: resolve(packageRoot, 'config', 'leaders.example.json'), isExample: true });
+    for (const { path, isExample } of candidates) {
+        if (!existsSync(path))
+            continue;
+        const raw = JSON.parse(readFileSync(path, 'utf-8'));
+        const leaders = Array.isArray(raw.leaders) ? raw.leaders : [];
+        return { leaders, sourcePath: path, isExample };
+    }
+    throw new Error(`paracosm: no leaders.json found. Create one at ${resolve(cwd, 'config', 'leaders.json')} ` +
+        `or pass --leaders <path>. A starter template lives at ${resolve(packageRoot, 'config', 'leaders.example.json')}.`);
+}
+/**
+ * Pulls `--leaders <path>` out of argv WITHOUT mutating the array.
+ * Returns undefined when the flag isn't present. Kept separate from
+ * the main CLI parser so run.ts / serve.ts can resolve leaders the
+ * same way without duplicating flag logic.
+ */
+export function parseLeadersFlag(args) {
+    const idx = args.indexOf('--leaders');
+    if (idx < 0)
+        return undefined;
+    const next = args[idx + 1];
+    if (!next || next.startsWith('--'))
+        return undefined;
+    return next;
+}
+//# sourceMappingURL=leaders-resolver.js.map

package/dist/cli/leaders-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"leaders-resolver.js","sourceRoot":"","sources":["../../src/cli/leaders-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGzC,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAYtC;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,UAAqC,EAAE;IACpE,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAC1B,MAAM,WAAW,GAAG,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IACnD,MAAM,UAAU,GAAgD,EAAE,CAAC;IAEnE,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;QACzB,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,YAAY,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;IAClF,CAAC;IACD,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,GAAG,EAAE,cAAc,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;IAC1E,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,GAAG,EAAE,QAAQ,EAAE,cAAc,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;IACpF,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,WAAW,EAAE,QAAQ,EAAE,cAAc,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;IAC5F,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,WAAW,EAAE,QAAQ,EAAE,sBAAsB,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAEnG,KAAK,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,UAAU,EAAE,CAAC;QAC7C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,SAAS;QAChC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAiC,CAAC;QACpF,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9D,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;IAClD,CAAC;IAED,MAAM,IAAI,KAAK,CACb,kDAAkD,OAAO,CAAC,GAAG,EAAE,QAAQ,EAAE,cAAc,CAAC,GAAG;QAC3F,yDAAyD,OAAO,CAAC,WAAW,EAAE,QAAQ,EAAE,sBAAsB,CAAC,GAAG,CACnH,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAuB;IACtD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IACtC,IAAI,GAAG,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;IAC3B,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IACrD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/cli/pair-runner.d.ts

@@ -0,0 +1,23 @@
+import { type NormalizedSimulationConfig } from './sim-config.js';
+import type { ScenarioPackage } from '../engine/types.js';
+export type BroadcastFn = (event: string, data: unknown) => void;
+export declare function runPairSimulations(simConfig: NormalizedSimulationConfig, broadcast: BroadcastFn, 
+/**
+ * Optional cancellation signal. When the server's disconnect watchdog
+ * trips (all SSE clients gone + grace period expired), it aborts this
+ * signal. Both leaders' runSimulation calls check it at turn
+ * boundaries and short-circuit cleanly, emitting a `sim_aborted`
+ * event and returning partial results. The event buffer is preserved
+ * so a returning user sees everything up to the cancel point.
+ */
+signal?: AbortSignal, 
+/**
+ * Scenario to run. Defaults to Mars Genesis when omitted so CLI
+ * callers that don't thread a scenario still work. The server path
+ * passes the currently-active scenario (set by /compile or
+ * /scenario/switch) so custom-compiled scenarios (e.g. "Brain Sim")
+ * actually get their own hooks + labels run instead of silently
+ * falling back to Mars while the page title shows the custom name.
+ */
+scenario?: ScenarioPackage): Promise<void>;
+//# sourceMappingURL=pair-runner.d.ts.map

package/dist/cli/pair-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pair-runner.d.ts","sourceRoot":"","sources":["../../src/cli/pair-runner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyB,KAAK,0BAA0B,EAAE,MAAM,iBAAiB,CAAC;AAIzF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAG1D,MAAM,MAAM,WAAW,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;AAyBjE,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,0BAA0B,EACrC,SAAS,EAAE,WAAW;AACtB;;;;;;;GAOG;AACH,MAAM,CAAC,EAAE,WAAW;AACpB;;;;;;;GAOG;AACH,QAAQ,GAAE,eAA8B,GACvC,OAAO,CAAC,IAAI,CAAC,CA2Lf"}