@ak--47/dungeon-master 1.5.2 → 1.5.4

package/.claude/skills/analyze-soup/SKILL.md

@@ -134,7 +134,12 @@ FROM (
 
 ## Step 3: Write Report
 
-Create `soup-analysis.md` in the project root with:
+Create `soup-analysis.md` with the structure below. For a user dungeon
+(`dungeons/user/<name>/<name>.js`) write it into the dungeon's folder
+(`dungeons/user/<name>/soup-analysis.md`) — everything about a dungeon lives in
+its folder. Otherwise write it to the project root. (The generated
+`./data/soup-analysis-EVENTS.json` is throwaway verification data — leave it in
+`./data/`.) Contents:
 
 1. **Config**: The soup parameters used (peaks, deviation, mean, numDays)
 2. **Summary stats**: Total events, event count, avg EPS

package/.claude/skills/create-dungeon/SKILL.md

@@ -18,7 +18,7 @@ box. It does **NOT** engineer story trends or magic numbers — those are the
 should be:
 
 ```
-/write-hooks dungeons/user/<your-dungeon>.js "describe the trends to engineer"
+/write-hooks dungeons/user/<name>/<name>.js "describe the trends to engineer"
 ```
 
 In scope here:
@@ -63,7 +63,7 @@ Before writing any code, scan:
 - `lib/utils/utils.js` — `pickAWinner`, `weighNumRange`, `initChance`, `exhaust`,
   `takeSome` for property value distributions
 - `dungeons/vertical/sass.js` — B2B reference dungeon with full identity model
-- `dungeons/user/my-buddy.js` — consumer-app reference (gitignored)
+- `dungeons/user/my-buddy/my-buddy.js` — consumer-app reference (gitignored)
 - `dungeons/technical/identity-model-verify.js` — minimal identity-model fixture
 
 ## File structure
@@ -524,9 +524,9 @@ userProps:  { Plan: PLANS, Region: REGIONS, Role: ROLES, ... },
 
 After writing the file:
 
-1. Smoke-test: `node scripts/verify-runner.mjs dungeons/user/<file>.js verify-<file> --small`. Confirm zero errors.
-2. Hand to the next skill: `/write-hooks dungeons/user/<file>.js "describe trends"`.
-3. After hooks land: `/verify-dungeon dungeons/user/<file>.js`.
+1. Smoke-test: `node scripts/verify-runner.mjs dungeons/user/<name>/<name>.js verify-<name> --small`. Confirm zero errors.
+2. Hand to the next skill: `/write-hooks dungeons/user/<name>/<name>.js "describe trends"`.
+3. After hooks land: `/verify-dungeon dungeons/user/<name>/<name>.js`.
 
 ## Property Type Reference
 
@@ -550,8 +550,20 @@ When designing event properties, always consider which Mixpanel type best repres
 
 ## Output
 
-Write the file to `dungeons/user/<descriptive-name>.js`. Do NOT inject hooks.
-Do NOT use `subscription`, `attribution`, `geo`, `features`, or `anomalies`
-(the engine will silently strip them and warn).
+**One folder per customer/dungeon.** Pick a short, kebab-case `<name>` from the
+app/customer, then **create `dungeons/user/<name>/` if it doesn't already exist**
+(`mkdir -p dungeons/user/<name>`) and write the dungeon to
+`dungeons/user/<name>/<name>.js` (e.g. `dungeons/user/acme/acme.js`). Folder and
+file share the name, matching `kodiak/kodiak.js`, `my-buddy/my-buddy.js`.
+
+This keeps `dungeons/user/` organized — EVERYTHING about this dungeon lives in
+the same folder: `hook-results.md` + `hook-query-log.txt` +
+`<name>-verifications.sql` (from `verify-dungeon`), `soup-analysis.md` (from
+`analyze-soup`), briefs, schema CSV/JSON, example data. The only thing kept
+outside is the throwaway verification data the runs write to `./data/` (cleaned
+after).
+
+Do NOT inject hooks. Do NOT use `subscription`, `attribution`, `geo`,
+`features`, or `anomalies` (the engine will silently strip them and warn).
 
 When done, tell the user the next skill to run.

package/.claude/skills/create-project/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: create-project
+description: Use when an existing dungeon needs a real Mixpanel project provisioned before sending data — creates the project, sets timezone UTC, mints a scoped service account, adds the dungeon's group keys, uploads business context (AI context), and writes the resulting credentials back into the dungeon so it "just runs". Follows create-dungeon / write-hooks / verify-dungeon.
+argument-hint: [dungeon path, e.g. dungeons/user/shopstream/shopstream.js]
+model: claude-opus-4-6
+effort: max
+---
+
+# Create a Mixpanel Project for a Dungeon
+
+Provision a fresh Mixpanel project for an existing dungeon and wire its credentials back in.
+
+**Dungeon file:** `$ARGUMENTS`
+
+This is the step after a dungeon is authored, reviewed, and tweaked. It turns a
+local dungeon into one you can actually send to Mixpanel by creating the project
+and stamping `credentials` back into the file.
+
+## What it does
+
+All work runs through the orchestrator `provision.mjs` (this skill's directory),
+which calls the [power-tools API](https://mixpanel-power-tools-api-lmozz6xkha-uc.a.run.app)
+in order:
+
+1. **createProject** — name derived from the dungeon's `OVERVIEW` (`NAME:` line), region `US`, timezone `UTC` (set as a follow-up by the endpoint).
+2. **mintServiceAccount** — `admin`, expires `+30 days`, scoped to the new project. This is what the dungeon uses to **send** data.
+3. **addGroupKey** — one per `groupKeys` entry in the dungeon (`property_name` + a titleized `display_name`). Skipped if the dungeon has no group keys.
+4. **setBusinessContext** — markdown built from the dungeon's `OVERVIEW` + `HOOK STORIES` comment blocks (via the package's `extractComments`) plus an events/funnels/props/group-keys summary, capped at 50k chars.
+5. **write-back** — replaces the dungeon's `credentials: { … }` block with `{ token, projectId, serviceAccount, serviceSecret, region }`.
+
+**Always creates a fresh project.** Re-running mints a new project and overwrites
+`credentials`. Auth for all four calls is the OAuth `BEARER_TOKEN`; the minted
+service account is only written into the dungeon for later data sends.
+
+## Prerequisites
+
+`.env` at the repo root must contain (both are gitignored):
+
+```
+BEARER_TOKEN=<oauth token>   # creates projects / mints SAs / adds group keys
+ORG_ID=<organization id>
+```
+
+If either is missing the orchestrator exits with a clear message — tell the user
+to add them to `.env`.
+
+User dungeons (`dungeons/user/`, `dungeons/customers/`, `dungeons/capstone/`) are
+gitignored, so writing plaintext credentials into them is expected and safe.
+
+## Steps
+
+### 1. Show the plan (dry run)
+
+```bash
+node .claude/skills/create-project/provision.mjs <dungeon-path> --dry-run
+```
+
+This makes **no** API calls. It prints the derived project name, group-key
+mapping, service-account name/expiry, and a business-context preview. Show this
+to the user.
+
+### 2. Confirm
+
+Creating a real project + service account is outward-facing and not easily
+undone. Confirm with the user before the live run (one line is enough).
+
+### 3. Provision (live)
+
+```bash
+node .claude/skills/create-project/provision.mjs <dungeon-path>
+```
+
+On success it writes `credentials` back into the dungeon and prints a non-secret
+summary (project URL + id, SA username/expiry, group keys added/skipped, context
+size). Token and secret are written into the dungeon, not printed.
+
+### 4. Report
+
+Relay the project URL and confirm credentials were written. Point the user at the
+run command:
+
+```bash
+node scripts/run-dungeon.mjs <dungeon-path>
+```
+
+## Error handling
+
+- **Missing `BEARER_TOKEN` / `ORG_ID`** — orchestrator exits; have the user fix `.env`.
+- **`createProject` fails** — nothing is provisioned; surface the power-tools error (`{ error }` or `{ errors:[{param,message}] }`) verbatim and stop.
+- **A later step fails** (mint / group keys / context / write-back) — the orchestrator continues, writes back whatever succeeded, and lists the failed step under `⚠ warnings`. Relay those warnings; the user may re-run or fix manually.
+
+## Notes
+
+- Region is always `US`; timezone is always `UTC` (matches the dungeon's UTC time window so Mixpanel day-bucketing aligns).
+- Group keys come straight from the dungeon's `groupKeys` (`[["parent_account", N, []], …]`) — author them there (via `create-dungeon`) before running this skill.
+- The orchestrator reuses the package's own exports (`loadFromFile`, `extractComments`) — no separate parser to keep in sync.

package/.claude/skills/create-project/provision.mjs

@@ -0,0 +1,289 @@
+#!/usr/bin/env node
+
+/**
+ * create-project orchestrator.
+ *
+ * Given an existing dungeon file, provisions a fresh Mixpanel project via the
+ * power-tools API and writes the resulting credentials back into the dungeon so
+ * it can "just run":
+ *
+ *   1. createProject       (sets timezone UTC as a follow-up)
+ *   2. mintServiceAccount  (admin, +30d) — scoped to the new project
+ *   3. addGroupKey         (only if the dungeon declares groupKeys)
+ *   4. setBusinessContext  (OVERVIEW + HOOK STORIES + schema summary)
+ *   5. write `credentials: { token, projectId, serviceAccount, serviceSecret, region }`
+ *      back into the dungeon (gitignored user dungeons — plaintext is fine)
+ *
+ * Auth: all calls use the OAuth BEARER_TOKEN from .env. The minted service
+ * account is for the dungeon to SEND data later, not for setup.
+ *
+ * Usage:
+ *   node .claude/skills/create-project/provision.mjs <dungeon-path> [--dry-run]
+ *
+ * Env (.env at repo root):
+ *   BEARER_TOKEN=<oauth token>
+ *   ORG_ID=<organization id>
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import path, { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import dotenv from 'dotenv';
+import { loadFromFile, extractComments } from '../../../index.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(__dirname, '../../../');
+
+dotenv.config({ path: resolve(REPO_ROOT, '.env') });
+
+const BASE = 'https://mixpanel-power-tools-api-lmozz6xkha-uc.a.run.app';
+const CLIENT_ID = 'dungeon-master';
+const REGION = 'US';
+const SA_TTL_DAYS = 30;
+
+// ── args ──────────────────────────────────────────────────────────────────
+const args = process.argv.slice(2);
+const dryRun = args.includes('--dry-run');
+const dungeonArg = args.find((a) => !a.startsWith('--'));
+
+if (!dungeonArg) {
+	fail('Usage: node .claude/skills/create-project/provision.mjs <dungeon-path> [--dry-run]');
+}
+
+const dungeonPath = resolve(process.cwd(), dungeonArg);
+if (!existsSync(dungeonPath)) fail(`dungeon file not found: ${dungeonPath}`);
+
+// ── main ──────────────────────────────────────────────────────────────────
+const config = await loadFromFile(dungeonPath);
+const comments = extractComments(dungeonPath);
+
+const name = deriveName(comments, dungeonPath);
+const groupKeys = Array.isArray(config.groupKeys)
+	? config.groupKeys.filter(Boolean).map(([prop]) => ({ property_name: prop, display_name: titleize(prop) }))
+	: [];
+const saName = `${slug(name)}-dungeon-sa`.slice(0, 64);
+const content = buildContext(name, config, comments, groupKeys);
+
+if (dryRun) {
+	printPlan();
+	process.exit(0);
+}
+
+// Live run needs auth.
+const { BEARER_TOKEN, ORG_ID } = process.env;
+if (!BEARER_TOKEN) fail('BEARER_TOKEN missing from .env (OAuth token required to create projects).');
+if (!ORG_ID) fail('ORG_ID missing from .env (organization id required to create projects).');
+
+const warnings = [];
+
+// 1. create project (timezone set to UTC as a follow-up by the endpoint)
+let project;
+try {
+	project = await post('/crud/createProject', { org_id: ORG_ID, name, timezone: 'UTC' });
+} catch (err) {
+	fail(`createProject failed — nothing provisioned.\n  ${err.message}`);
+}
+const projectId = String(project.id);
+const projectToken = project.token;
+
+// 2. mint service account (admin, +30d)
+let sa = null;
+const expires = isoInDays(SA_TTL_DAYS);
+try {
+	sa = await post('/crud/mintServiceAccount', {
+		org_id: ORG_ID,
+		project_id: projectId,
+		name: saName,
+		role: 'admin',
+		expires,
+	});
+} catch (err) {
+	warnings.push(`mintServiceAccount failed: ${err.message}`);
+}
+
+// 3. group keys (only if declared)
+let groupKeyResult = null;
+if (groupKeys.length) {
+	try {
+		groupKeyResult = await post('/crud/addGroupKey', { project_id: projectId, group_keys: groupKeys });
+	} catch (err) {
+		warnings.push(`addGroupKey failed: ${err.message}`);
+	}
+}
+
+// 4. business context
+try {
+	await post('/crud/setBusinessContext', { project_id: projectId, content });
+} catch (err) {
+	warnings.push(`setBusinessContext failed: ${err.message}`);
+}
+
+// 5. write credentials back into the dungeon
+const creds = {
+	token: projectToken,
+	projectId,
+	serviceAccount: sa?.username || '',
+	serviceSecret: sa?.secret || '',
+	region: REGION,
+};
+let wroteBack = true;
+try {
+	writeBackCredentials(dungeonPath, creds);
+} catch (err) {
+	wroteBack = false;
+	warnings.push(`credentials write-back failed: ${err.message}`);
+}
+
+printSummary();
+
+// ── helpers ─────────────────────────────────────────────────────────────────
+
+async function post(pathname, body) {
+	const res = await fetch(BASE + pathname, {
+		method: 'POST',
+		headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${process.env.BEARER_TOKEN}` },
+		body: JSON.stringify({ client_id: CLIENT_ID, region: REGION, ...body }),
+	});
+	const text = await res.text();
+	let json;
+	try {
+		json = JSON.parse(text);
+	} catch {
+		json = { raw: text };
+	}
+	if (!res.ok) {
+		const detail = Array.isArray(json.errors)
+			? json.errors.map((e) => `${e.param}: ${e.message}`).join('; ')
+			: json.error || text || `HTTP ${res.status}`;
+		throw new Error(`${res.status} ${detail}`);
+	}
+	return json;
+}
+
+function deriveName(comments, p) {
+	const m = (comments.overview || '').match(/^NAME:\s*(.+)$/m);
+	if (m) return m[1].trim();
+	return path.basename(p).replace(/\.(js|mjs|json)$/i, '');
+}
+
+function titleize(s) {
+	return String(s)
+		.split(/[_\s-]+/)
+		.map((w) => (w ? w[0].toUpperCase() + w.slice(1) : w))
+		.join(' ');
+}
+
+function slug(s) {
+	return String(s)
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, '-')
+		.replace(/^-+|-+$/g, '');
+}
+
+function isoInDays(days) {
+	const ms = Date.now() + days * 24 * 60 * 60 * 1000;
+	return new Date(ms).toISOString();
+}
+
+function buildContext(name, config, comments, groupKeys) {
+	const parts = [`# ${name}`, ''];
+	if (comments.overview) parts.push(comments.overview, '');
+	if (comments.hookStories) parts.push('## Engineered Behaviors', '', comments.hookStories, '');
+
+	parts.push('## Schema', '');
+	const events = config.events || [];
+	parts.push(`### Events (${events.length})`);
+	for (const e of events) {
+		const props = e.properties ? Object.keys(e.properties).join(', ') : '';
+		const weight = e.weight != null ? ` (weight ${e.weight})` : '';
+		parts.push(`- ${e.event}${weight}${props ? ` — ${props}` : ''}`);
+	}
+	parts.push('');
+
+	const funnels = config.funnels || [];
+	if (funnels.length) {
+		parts.push(`### Funnels (${funnels.length})`);
+		for (const f of funnels) {
+			const seq = (f.sequence || []).join(' → ');
+			const rate = f.conversionRate != null ? ` (${f.conversionRate}%)` : '';
+			parts.push(`- ${f.name || '(unnamed)'}: ${seq}${rate}`);
+		}
+		parts.push('');
+	}
+
+	if (groupKeys.length) {
+		parts.push('### Group keys', ...groupKeys.map((g) => `- ${g.property_name} (${g.display_name})`), '');
+	}
+
+	let md = parts.join('\n');
+	if (md.length > 50000) md = md.slice(0, 49900) + '\n\n…(truncated to 50,000 chars)';
+	return md;
+}
+
+function writeBackCredentials(p, creds) {
+	let src = readFileSync(p, 'utf-8');
+	const block =
+		`credentials: { token: ${q(creds.token)}, projectId: ${q(creds.projectId)}, ` +
+		`serviceAccount: ${q(creds.serviceAccount)}, serviceSecret: ${q(creds.serviceSecret)}, region: ${q(creds.region)} }`;
+
+	const existing = /credentials\s*:\s*\{[\s\S]*?\}/;
+	if (existing.test(src)) {
+		src = src.replace(existing, block);
+	} else {
+		const opener = /(const\s+\w+\s*=\s*\{)/;
+		if (opener.test(src)) {
+			src = src.replace(opener, `$1\n\t${block},`);
+		} else {
+			throw new Error('no `credentials` block or `const X = {` opener found — add a credentials block manually.');
+		}
+	}
+	writeFileSync(p, src, 'utf-8');
+}
+
+function q(v) {
+	return JSON.stringify(String(v ?? ''));
+}
+
+function printPlan() {
+	const preview = content.length > 600 ? content.slice(0, 600) + ' …' : content;
+	console.log('── create-project plan (dry run) ────────────────────────────');
+	console.log(`dungeon:        ${path.relative(process.cwd(), dungeonPath)}`);
+	console.log(`project name:   ${name}`);
+	console.log(`region:         ${REGION}    timezone: UTC`);
+	console.log(`service acct:   ${saName}  (role admin, expires +${SA_TTL_DAYS}d)`);
+	console.log(`group keys:     ${groupKeys.length ? groupKeys.map((g) => `${g.property_name} → "${g.display_name}"`).join(', ') : '(none)'}`);
+	console.log(`business ctx:   ${content.length} chars`);
+	console.log('');
+	console.log('would POST: createProject → mintServiceAccount' + (groupKeys.length ? ' → addGroupKey' : '') + ' → setBusinessContext');
+	console.log('then write credentials back into the dungeon.');
+	console.log('');
+	console.log('── business context preview ─────────────────────────────────');
+	console.log(preview);
+}
+
+function printSummary() {
+	console.log('── create-project: provisioned ──────────────────────────────');
+	console.log(`project:        ${name} (id ${projectId})`);
+	if (project.url) console.log(`url:            ${project.url}`);
+	console.log(`region:         ${REGION}    timezone: UTC`);
+	console.log(`service acct:   ${sa ? `${sa.username} (role ${sa.role}, expires ${sa.expires})` : '(FAILED — see warnings)'}`);
+	if (groupKeys.length) {
+		const added = groupKeyResult?.added?.map((g) => g.property_name).join(', ') || '(none)';
+		const skipped = groupKeyResult?.skipped?.join(', ') || '(none)';
+		console.log(`group keys:     added [${added}]  skipped [${skipped}]`);
+	}
+	console.log(`business ctx:   ${content.length} chars uploaded`);
+	console.log(`credentials:    ${wroteBack ? 'written back into dungeon ✓' : 'NOT written (see warnings)'}`);
+	if (warnings.length) {
+		console.log('');
+		console.log('⚠ warnings:');
+		for (const w of warnings) console.log(`  - ${w}`);
+	}
+	console.log('');
+	console.log(`next: node scripts/run-dungeon.mjs ${path.relative(process.cwd(), dungeonPath)}`);
+}
+
+function fail(msg) {
+	console.error(`✖ ${msg}`);
+	process.exit(1);
+}

package/.claude/skills/verify-dungeon/SKILL.md

@@ -102,13 +102,33 @@ For emulator details, identity-model dungeons (must pass `profiles`), and time-s
 - Experiment invariants (variant distribution, exposure timing, deterministic assignment) when any funnel uses `experiment:`
 - SuperProp consistency, SuperProp/UserProp mirror, Mixpanel default-property casing, funnel-pre dilution
 
-### Step 5: Stash query log (optional)
+### Artifact location
 
-If `./research/` exists locally, write every DuckDB query execution to `./research/hook-query-log.txt`. Format and conventions: see [report-format.md "Query log format"](references/report-format.md#query-log-format). If `./research/` does not exist, skip — do not create the directory.
+**Everything about a dungeon lives in its folder.** When the dungeon being
+verified is a user dungeon at `dungeons/user/<name>/<name>.js`, write ALL
+generated artifacts into `dungeons/user/<name>/`:
+- `hook-results.md` (Step 6)
+- `hook-query-log.txt` (Step 5)
+- `<name>-verifications.sql` (Step 6b)
 
-### Step 6: Write `./research/hook-results.md`
+The ONLY exception is the throwaway verification data the run writes to
+`./data/` (`verify-*` event/user files) — that stays in `./data/` and is
+deleted in Step 7.
 
-Use the templates in [report-format.md](references/report-format.md):
+For non-user dungeons (technical/vertical) or batch runs across many dungeons,
+fall back to `./research/` for `hook-results.md` / `hook-query-log.txt`.
+
+### Step 5: Stash query log
+
+Write every DuckDB query execution to `hook-query-log.txt`:
+- **User dungeon:** always write to `dungeons/user/<name>/hook-query-log.txt`.
+- **Otherwise:** if `./research/` exists locally, write to `./research/hook-query-log.txt`; if it doesn't exist, skip — do not create the directory.
+
+Format and conventions: see [report-format.md "Query log format"](references/report-format.md#query-log-format).
+
+### Step 6: Write `hook-results.md`
+
+Write to `dungeons/user/<name>/hook-results.md` for a user dungeon, else `./research/hook-results.md`. Use the templates in [report-format.md](references/report-format.md):
 - Single-dungeon report structure
 - Multi-dungeon report structure (when batch mode)
 - Per-hook detail block
@@ -118,7 +138,7 @@ Use the templates in [report-format.md](references/report-format.md):
 
 ### Step 6b: Write verification SQL (mandatory for user dungeons)
 
-When verifying a dungeon in `dungeons/user/`, also write a standalone DuckDB SQL file at `dungeons/user/<name>-verifications.sql`. Vertical dungeons already have their SQL in `verification/verticals/`. Format: see [report-format.md "Verification SQL file"](references/report-format.md#verification-sql-file-mandatory-for-user-dungeons).
+When verifying a dungeon in `dungeons/user/`, also write a standalone DuckDB SQL file alongside the dungeon in its folder at `dungeons/user/<name>/<name>-verifications.sql`. Vertical dungeons already have their SQL in `verification/verticals/`. Format: see [report-format.md "Verification SQL file"](references/report-format.md#verification-sql-file-mandatory-for-user-dungeons).
 
 ### Step 7: Cleanup
 
@@ -148,9 +168,9 @@ Return-value behavior:
 ## Final output
 
 Tell the user:
-1. Report path: `./research/hook-results.md`
-2. Verification SQL path (for user dungeons): `dungeons/user/<name>-verifications.sql`
-3. Query log path (if written): `./research/hook-query-log.txt`
+1. Report path: `dungeons/user/<name>/hook-results.md` (user dungeon) or `./research/hook-results.md`
+2. Verification SQL path (for user dungeons): `dungeons/user/<name>/<name>-verifications.sql`
+3. Query log path (if written): alongside the report (`dungeons/user/<name>/hook-query-log.txt`, else `./research/hook-query-log.txt`)
 4. Pass/weak/fail counts (per dungeon if batch mode)
 5. One-line summary of the most interesting finding
 

package/.claude/skills/verify-dungeon/references/report-format.md

@@ -1,6 +1,6 @@
 # Report Format
 
-Templates and conventions for writing `./research/hook-results.md` and per-dungeon verification SQL.
+Templates and conventions for writing `hook-results.md` and per-dungeon verification SQL. For user dungeons these live in the dungeon's folder (`dungeons/user/<name>/`); otherwise in `./research/`. See [SKILL.md "Artifact location"](../SKILL.md).
 
 ## Verdict criteria (5-tier)
 
@@ -147,9 +147,7 @@ Each hook's detailed section follows this template (same for single and multi-du
 
 ## Query log format
 
-If `./research/` exists locally, write a plain-text log of every DuckDB query execution to `./research/hook-query-log.txt`. If `./research/` does not exist, skip this step entirely — do not create the directory.
-
-Check with: `ls -d ./research/ 2>/dev/null`
+Write a plain-text log of every DuckDB query execution to `hook-query-log.txt`. For a user dungeon, write it to the dungeon's folder (`dungeons/user/<name>/hook-query-log.txt`). Otherwise, only if `./research/` exists locally write `./research/hook-query-log.txt` — if it doesn't exist, skip this step entirely (don't create the directory; check with `ls -d ./research/ 2>/dev/null`).
 
 Use a consistent delimited format — one block per query, separated by a ruler line. DuckDB table output is preserved verbatim:
 
@@ -191,7 +189,7 @@ grep "^DUNGEON:" research/hook-query-log.txt           # list of dungeons querie
 
 ## Verification SQL file (mandatory for user dungeons)
 
-When verifying a dungeon in `dungeons/user/`, write a standalone DuckDB SQL file alongside the dungeon at `dungeons/user/<name>-verifications.sql`. This file is the reproducible verification artifact — anyone can re-run it against fresh data.
+When verifying a dungeon in `dungeons/user/`, write a standalone DuckDB SQL file alongside the dungeon in its folder at `dungeons/user/<name>/<name>-verifications.sql`. This file is the reproducible verification artifact — anyone can re-run it against fresh data.
 
 Follow the format in `verification/verticals/`:
 
@@ -200,8 +198,8 @@ Follow the format in `verification/verticals/`:
 -- <name>.js — Hook Verification SQL (N hooks)
 -- ============================================================================
 -- USAGE:
---   1. node scripts/verify-runner.mjs dungeons/user/<name>.js verify-<name>
---   2. duckdb < dungeons/user/<name>-verifications.sql
+--   1. node scripts/verify-runner.mjs dungeons/user/<name>/<name>.js verify-<name>
+--   2. duckdb < dungeons/user/<name>/<name>-verifications.sql
 --   3. rm -f verify-<name>-*
 -- ============================================================================
 

package/.claude/skills/write-hooks/SKILL.md

@@ -36,8 +36,8 @@ Out of scope:
 - `lib/hook-patterns/index.js` — high-level recipes (one per Mixpanel
   analysis type).
 - `lib/verify/emulate-breakdown.js` — what `verify-dungeon` will check.
-- `dungeons/user/my-buddy.js` — reference dungeon using a mix of atoms and
-  hand-rolled logic.
+- `dungeons/user/my-buddy/my-buddy.js` — reference dungeon using a mix of atoms
+  and hand-rolled logic.
 - `dungeons/technical/pattern-*.js` — five minimal pattern fixtures, one per
   recipe.
 - `HOOKS.md` — encyclopedia of hook recipes organized by story pattern. Contains

package/CHANGELOG.md

@@ -2,6 +2,85 @@
 
 All notable changes to `@ak--47/dungeon-master`.
 
+## 1.5.4 — 2026-06-04
+
+Patch. Import-phase progress now reaches `onProgress` consumers.
+
+### Changed
+
+- **Bumped `mixpanel-import` to `^3.3.2`.** It now fires `progressCallback`
+  independently of `verbose` / `showProgress`. Previously the import callbacks
+  wired up in `mixpanel-sender.js` never fired in non-verbose runs because the
+  importer only invoked them when its stdout progress bar was enabled.
+
+### Fixed
+
+- **Import progress reaches `onProgress`** (requires `mixpanel-import >= 3.3.2`).
+  Every import call (events, user profiles, ad spend, group profiles, group
+  events, SCD) already passed a `progressCallback`; with the dependency bump
+  those now emit `{ phase: "import", recordType, processed, total, eps,
+  bytesProcessed }` to the consumer's `onProgress` during the import phase.
+  `showProgress: !!verbose` is unchanged — it still gates only the importer's
+  stdout bar, so non-verbose runs stay quiet while the callback fires.
+
+### Why
+
+Consumers (e.g. DM4) already handle `update.phase === 'import'` to render an
+import progress bar; the callbacks simply weren't firing. This is a dependency
+bump plus a regression test — no DM API change. Consumers pick it up via their
+normal upgrade flow with no code change.
+
+## 1.5.3 — 2026-06-04
+
+Adds two JSON/source interop helpers to the public API. No breaking changes —
+existing exports and behavior are untouched.
+
+### Added
+
+- **`dungeonToJSON(input, options?)`** export. The inverse of `parseJSONDungeon`:
+  turns a dungeon into the `{ schema, hooks, timestamp, version }` JSON/UI wrapper
+  format. Accepts the same input flavors as the default export — a config object,
+  a `.js`/`.mjs`/`.json` file path, a raw JS source string, or an array of file
+  paths (returns an array). Output round-trips: `parseJSONDungeon(await
+  dungeonToJSON(x))` yields a runnable config. Best effort — arrow functions and
+  bound `chance.*` methods survive the round trip; detected utility calls
+  (`weighArray`, `weighNumRange`, …) are serialized by name without their
+  arguments and revive to `null` (handled gracefully by the validator). To keep
+  the field's **type** even when the generator can't be revived, every function
+  is sampled at serialization time (closures are still live) and its inferred
+  output type is recorded as `dataType` on the serialized object (e.g.
+  `{ functionName: "weighNumRange", args: [], dataType: "number" }`).
+  **Credentials (`token`, `serviceAccount`, `serviceSecret`, `projectId`,
+  `secret`) are stripped by default** so tokens never leak into JSON — pass
+  `{ includeCredentials: true }` to keep them.
+- **`DungeonJSON`, `DungeonComments`, and `SerializedFunction` types** in
+  `types.d.ts` — the JSON-representation shapes are now formally specced.
+- **`extractComments(input)`** export. Pulls the human-readable doc blocks out of
+  a dungeon's **source** — the `// ── OVERVIEW ──` and `// ── HOOK STORIES ──`
+  blocks plus every other `// ── LABEL ──` header that is immediately followed by
+  a block comment. Returns `{ overview, hookStories, sections }` with the comment
+  scaffolding (`// ──`, `/* */`, leading ` * `) stripped to readable prose.
+  Operates on a file path or raw source string — it never imports the dungeon,
+  since importing discards comments. Best effort: relies on the canonical
+  header + block-comment convention emitted by the `create-dungeon` /
+  `write-hooks` skills.
+
+### Changed
+
+- **`scripts/dungeon-to-json.mjs`** is now a thin CLI wrapper over the exported
+  `dungeonToJSON` (passing `includeCredentials: true` to preserve its legacy
+  full-config UI round-trip output). The inline `convertToJSON` /
+  `convertFunctionToObject` logic moved into `lib/core/dungeon-to-json.js`.
+
+### Why
+
+The package could ingest JSON dungeons (`parseJSONDungeon`, `loadFromFile`,
+`loadFromText`) but had no exported way to go the other direction, and no way to
+programmatically read a dungeon's OVERVIEW / HOOK STORIES documentation. Both
+existed only as un-importable script internals. Exporting them completes
+best-effort JSON interop and lets tools (UIs, LLM pipelines) read dungeon docs
+directly.
+
 ## 1.5.2 — 2026-05-21
 
 Docs-only patch. Aligns the `.claude/skills/` authoring + verification

package/README.md

@@ -155,6 +155,32 @@ import { createTextGenerator, generateBatch } from '@ak--47/dungeon-master/text'
 
 these are the same functions used internally. `pickAWinner` creates weighted distributions, `weighNumRange` generates realistic numeric ranges with configurable skew, and the text generators produce organic-looking strings with sentiment analysis and keyword injection.
 
+### named exports
+
+alongside the default `DUNGEON_MASTER` export, the package root exports loader + interop helpers:
+
+```javascript
+import DUNGEON_MASTER, {
+    loadFromFile,          // (path)            → Promise<Dungeon>   load+validate a .js/.mjs/.json dungeon
+    loadFromText,          // (code)            → Promise<Dungeon>   load+validate a raw JS source string
+    parseJSONDungeon,      // (json)            → Dungeon            revive a JSON dungeon into a runnable config
+    validateDungeonShape,  // (config)          → void               throw if config isn't dungeon-shaped
+    dungeonToJSON,         // (input, options?) → Promise<DungeonJSON>     serialize a dungeon → JSON (inverse of parseJSONDungeon)
+    extractComments,       // (input)           → DungeonComments    pull OVERVIEW / HOOK STORIES doc blocks from source
+} from '@ak--47/dungeon-master';
+```
+
+`dungeonToJSON` accepts a config object, a file path, raw JS source, or an array of paths, and returns the `{ schema, hooks, timestamp, version }` wrapper format. it round-trips with `parseJSONDungeon`:
+
+```javascript
+const json   = await dungeonToJSON('./dungeons/vertical/ecommerce.js');  // creds stripped by default
+const config = parseJSONDungeon(json);                                   // back to a runnable dungeon
+```
+
+it's best effort — arrow functions and `chance.*` methods survive the round trip; detected utility calls (`weighArray`, `weighNumRange`, …) serialize by name without their args. pass `{ includeCredentials: true }` to keep `token` / `serviceAccount` / etc. in the output (stripped by default).
+
+`extractComments` reads a dungeon's **source** (file path or raw text — never the imported module, since importing discards comments) and returns `{ overview, hookStories, sections }` with the comment scaffolding stripped to readable prose.
+
 ## how it works
 
 one call to `DUNGEON_MASTER(config)` runs through these phases in order:

package/index.js

@@ -15,6 +15,8 @@ import { createContext, updateContextWithStorage } from './lib/core/context.js';
 import { validateDungeonConfig } from './lib/core/config-validator.js';
 import { StorageManager } from './lib/core/storage.js';
 import { detectInputType, loadFromFile, loadFromText, parseJSONDungeon, validateDungeonShape } from './lib/core/dungeon-loader.js';
+import { dungeonToJSON } from './lib/core/dungeon-to-json.js';
+import { extractComments } from './lib/core/extract-comments.js';
 
 // Orchestrators
 import { userLoop } from './lib/orchestrators/user-loop.js';
@@ -597,5 +599,5 @@ function extractStorageData(storage) {
 
 // ES Module exports
 export default DUNGEON_MASTER;
-export { parseJSONDungeon, validateDungeonShape, loadFromFile, loadFromText };
+export { parseJSONDungeon, validateDungeonShape, loadFromFile, loadFromText, dungeonToJSON, extractComments };
 

package/lib/core/dungeon-to-json.js

@@ -0,0 +1,220 @@
+/**
+ * dungeon → JSON serialization.
+ *
+ * The inverse of `parseJSONDungeon` (lib/core/dungeon-loader.js): turns a runnable
+ * dungeon into the UI/JSON wrapper format `{ schema, hooks, timestamp, version }`.
+ * Functions in the schema are serialized to `{ functionName, body }` / `{ functionName, args }`
+ * objects that `reviveJSONConfig` knows how to revive — so the output round-trips:
+ *
+ *   parseJSONDungeon(await dungeonToJSON(cfg))  →  runnable config
+ *
+ * This is BEST EFFORT. Arrow functions and bound `chance.*` methods round-trip cleanly;
+ * detected utility calls (weighArray, weighNumRange, …) are serialized without their
+ * arguments and revive to null, which the config validator handles gracefully.
+ *
+ * To preserve the field's TYPE even when the generator can't be revived, every function
+ * is sampled at serialization time (when its closure is still live) and the inferred
+ * output type is recorded as `dataType` (e.g. "number", "string", "boolean", "number[]").
+ * So a field that loses its `weighNumRange(1,10)` generator still records `dataType: "number"`.
+ */
+
+import { detectInputType, loadFromFile, loadFromText } from './dungeon-loader.js';
+
+/** Credential keys stripped from JSON output unless `includeCredentials` is set. */
+const CREDENTIAL_KEYS = ['token', 'serviceAccount', 'serviceSecret', 'projectId', 'secret'];
+
+/**
+ * Convert a dungeon into its JSON representation.
+ *
+ * Accepts the same input flavors as the default export: a config object, a path to a
+ * `.js`/`.mjs`/`.json` dungeon file, a raw JS source string (must `export default`), or
+ * an array of file paths (returns an array of results).
+ *
+ * @param {import('../../types').Dungeon | string | string[]} input
+ * @param {{ includeCredentials?: boolean }} [options]
+ * @returns {Promise<import('../../types').DungeonJSON | import('../../types').DungeonJSON[]>}
+ */
+export async function dungeonToJSON(input, options = {}) {
+	const { includeCredentials = false } = options;
+	const { type, value } = detectInputType(input);
+
+	switch (type) {
+		case 'object':
+			return serializeConfig(value, includeCredentials);
+		case 'file':
+			return serializeConfig(await loadFromFile(value), includeCredentials);
+		case 'text':
+			return serializeConfig(await loadFromText(value), includeCredentials);
+		case 'files':
+			return Promise.all(
+				value.map(async (p) => serializeConfig(await loadFromFile(p), includeCredentials))
+			);
+		default:
+			throw new Error(`dungeon-master: dungeonToJSON cannot handle input type "${type}".`);
+	}
+}
+
+/**
+ * Build the `{ schema, hooks, timestamp, version }` wrapper from a runnable config.
+ * @param {import('../../types').Dungeon} config
+ * @param {boolean} includeCredentials
+ * @returns {import('../../types').DungeonJSON}
+ */
+function serializeConfig(config, includeCredentials) {
+	// Hook may be a live function (from .js/text/object) or already a string (from .json).
+	const hook = config.hook;
+	const hooks = typeof hook === 'function'
+		? hook.toString()
+		: (typeof hook === 'string' ? hook : null);
+
+	// Strip the hook (serialized separately) and, by default, credentials (don't leak tokens).
+	const cleanConfig = { ...config };
+	delete cleanConfig.hook;
+	if (!includeCredentials) {
+		for (const key of CREDENTIAL_KEYS) delete cleanConfig[key];
+	}
+
+	return {
+		schema: convertToJSON(cleanConfig),
+		hooks,
+		timestamp: new Date().toISOString(),
+		version: '4.0'
+	};
+}
+
+/**
+ * Convert a JavaScript value to a JSON-serializable form, turning functions into
+ * `{ functionName, body | args }` objects that `reviveJSONConfig` can revive.
+ * @param {any} value
+ * @returns {any}
+ */
+export function convertToJSON(value) {
+	// Null/undefined
+	if (value === null || value === undefined) {
+		return null;
+	}
+
+	// Primitives
+	if (typeof value === 'boolean' || typeof value === 'number' || typeof value === 'string') {
+		return value;
+	}
+
+	// Functions - convert to object representation
+	if (typeof value === 'function') {
+		return convertFunctionToObject(value);
+	}
+
+	// Arrays
+	if (Array.isArray(value)) {
+		return value.map(item => convertToJSON(item));
+	}
+
+	// Objects
+	if (typeof value === 'object') {
+		const result = {};
+		for (const [key, val] of Object.entries(value)) {
+			result[key] = convertToJSON(val);
+		}
+		return result;
+	}
+
+	// Fallback
+	return null;
+}
+
+/**
+ * Convert a function to its object representation.
+ * Arrow functions and bound `chance.*` methods round-trip cleanly; detected utility
+ * functions are stored by name without args (best effort). Every form also carries a
+ * sampled `dataType` so the field's output type survives even when the generator can't.
+ * @param {Function} func
+ * @returns {import('../../types').SerializedFunction}
+ */
+function convertFunctionToObject(func) {
+	const funcString = func.toString();
+	// Sample now, while the closure is still live — the only reliable time to learn the type.
+	const dataType = inferDataType(func);
+
+	// Arrow function
+	if (funcString.startsWith('(') || funcString.startsWith('_') || funcString.includes('=>')) {
+		return withDataType({ functionName: 'arrow', body: funcString }, dataType);
+	}
+
+	// Bound chance methods (e.g., chance.name.bind(chance))
+	if (funcString.includes('.bind(')) {
+		const match = funcString.match(/chance\.(\w+)\.bind/);
+		if (match) {
+			return withDataType({ functionName: `chance.${match[1]}`, args: [] }, dataType);
+		}
+	}
+
+	// Try to detect common utility functions
+	// This is a best-effort approach - some complex functions might not be detected
+	const commonFunctions = [
+		'weighNumRange',
+		'weighArray',
+		'weighChoices',
+		'pickAWinner',
+		'date',
+		'integer',
+		'uid',
+		'comma'
+	];
+
+	for (const fnName of commonFunctions) {
+		if (funcString.includes(fnName)) {
+			// Args can't be recovered from a stringified function, but dataType is captured.
+			return withDataType({ functionName: fnName, args: [] }, dataType);
+		}
+	}
+
+	// Generic function - just store as arrow function
+	return withDataType({ functionName: 'arrow', body: funcString }, dataType);
+}
+
+/**
+ * Attach a `dataType` field if one was inferred (omitted otherwise).
+ * @param {import('../../types').SerializedFunction} obj
+ * @param {string | undefined} dataType
+ * @returns {import('../../types').SerializedFunction}
+ */
+function withDataType(obj, dataType) {
+	if (dataType) obj.dataType = dataType;
+	return obj;
+}
+
+/**
+ * Sample a function (no args) and classify its return type. Best effort — returns
+ * undefined if the call throws or yields an indeterminate value.
+ * @param {Function} func
+ * @returns {string | undefined}
+ */
+function inferDataType(func) {
+	let value;
+	try {
+		value = func();
+	} catch {
+		return undefined;
+	}
+	return classifyValue(value);
+}
+
+/**
+ * Map a sampled value to a type label: "number" | "string" | "boolean" | "date" |
+ * "object" | "<elementType>[]" | "array". Returns undefined for null/undefined/functions.
+ * @param {any} value
+ * @returns {string | undefined}
+ */
+function classifyValue(value) {
+	if (value === null || value === undefined) return undefined;
+	if (Array.isArray(value)) {
+		const el = value.find((v) => v !== null && v !== undefined);
+		const elType = el === undefined ? undefined : classifyValue(el);
+		return elType ? `${elType}[]` : 'array';
+	}
+	if (value instanceof Date) return 'date';
+	const t = typeof value;
+	if (t === 'number' || t === 'string' || t === 'boolean') return t;
+	if (t === 'object') return 'object';
+	return undefined;
+}

package/lib/core/extract-comments.js

@@ -0,0 +1,120 @@
+/**
+ * Best-effort extraction of the human-readable doc blocks from a dungeon's SOURCE.
+ *
+ * Generated/authored dungeons separate sections with box-drawing headers followed by a
+ * block comment, e.g.:
+ *
+ *   // ── OVERVIEW ──
+ *   /* ... *\/
+ *   // ── HOOK STORIES ──
+ *   /* ... *\/
+ *
+ * This pulls those blocks out as cleaned prose. It operates on RAW SOURCE TEXT — it never
+ * imports the dungeon, because importing a module discards its comments.
+ *
+ * Returns `{ overview, hookStories, sections }`:
+ *   - `overview`    — cleaned text of the OVERVIEW block (or null)
+ *   - `hookStories` — cleaned text of the HOOK STORIES block (or null)
+ *   - `sections`    — every `// ── LABEL ──` header that is immediately followed by a
+ *                     block comment, keyed by the exact label as written.
+ */
+
+import { readFileSync } from 'fs';
+import { detectInputType } from './dungeon-loader.js';
+
+// A `// ── LABEL ──` header line. Anchored to `//` at line start so that the inner
+// ` * ───────` dividers inside a block comment are NOT mistaken for section headers.
+const HEADER_RE = /^[ \t]*\/\/[ \t]*─+[ \t]*(.+?)[ \t]*─+[ \t]*$/gm;
+
+/**
+ * @param {string | string[]} input - A dungeon file path, raw dungeon source, or array of paths.
+ * @returns {import('../../types').DungeonComments | import('../../types').DungeonComments[]}
+ */
+export function extractComments(input) {
+	const { type, value } = detectInputType(input);
+
+	switch (type) {
+		case 'file':
+			return parseSource(readFileSync(value, 'utf-8'));
+		case 'text':
+			return parseSource(value);
+		case 'files':
+			return value.map((p) => parseSource(readFileSync(p, 'utf-8')));
+		case 'object':
+			throw new Error(
+				'dungeon-master: extractComments needs source text or a file path, not a config object (comments are lost once a dungeon is imported).'
+			);
+		default:
+			throw new Error(`dungeon-master: extractComments cannot handle input type "${type}".`);
+	}
+}
+
+/**
+ * Parse a single source string into `{ overview, hookStories, sections }`.
+ * @param {string} source
+ * @returns {import('../../types').DungeonComments}
+ */
+function parseSource(source) {
+	/** @type {Record<string, string>} */
+	const sections = {};
+
+	// Collect every header with its label and the position right after its line.
+	const headers = [];
+	HEADER_RE.lastIndex = 0;
+	let m;
+	while ((m = HEADER_RE.exec(source)) !== null) {
+		headers.push({ label: m[1].trim(), end: HEADER_RE.lastIndex });
+	}
+
+	for (let i = 0; i < headers.length; i++) {
+		const { label, end } = headers[i];
+		// Only look between this header and the next one.
+		const sliceEnd = i + 1 < headers.length ? headers[i + 1].end : source.length;
+		const slice = source.slice(end, sliceEnd);
+
+		// Accept the block only if a `/* ... */` comment is the first non-whitespace content
+		// after the header (so headers followed by code — IMPORTS, SCALE — are skipped).
+		const block = slice.match(/^\s*\/\*([\s\S]*?)\*\//);
+		if (block) {
+			sections[label] = cleanBlock(block[1]);
+		}
+	}
+
+	return {
+		overview: findSection(sections, ['OVERVIEW']),
+		hookStories: findSection(sections, ['HOOK STORIES', 'HOOK STORY']),
+		sections
+	};
+}
+
+/**
+ * Strip block-comment scaffolding (` * `) and trim blank edges, leaving readable prose.
+ * @param {string} inner - The text between `/*` and `*\/`.
+ * @returns {string}
+ */
+function cleanBlock(inner) {
+	const lines = inner
+		.split('\n')
+		// Drop a leading ` * ` (or bare ` *`) from each line; preserve content indentation.
+		.map((line) => line.replace(/^[ \t]*\*[ \t]?/, '').replace(/\s+$/, ''));
+
+	// Trim leading/trailing blank lines.
+	while (lines.length && lines[0] === '') lines.shift();
+	while (lines.length && lines[lines.length - 1] === '') lines.pop();
+
+	return lines.join('\n');
+}
+
+/**
+ * Case-insensitive lookup of the first matching label.
+ * @param {Record<string, string>} sections
+ * @param {string[]} candidates
+ * @returns {string | null}
+ */
+function findSection(sections, candidates) {
+	const wanted = candidates.map((c) => c.toUpperCase());
+	for (const [label, text] of Object.entries(sections)) {
+		if (wanted.includes(label.toUpperCase())) return text;
+	}
+	return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ak--47/dungeon-master",
-	"version": "1.5.2",
+	"version": "1.5.4",
 	"description": "generate fancy datasets",
 	"type": "module",
 	"main": "index.js",
@@ -86,7 +86,7 @@
 		"dotenv": "^16.4.5",
 		"hyparquet-writer": "^0.6.1",
 		"mixpanel": "^0.18.0",
-		"mixpanel-import": "^3.3.1",
+		"mixpanel-import": "^3.3.2",
 		"p-limit": "^3.1.0",
 		"pino": "^9.0.0",
 		"pino-pretty": "^11.0.0",
@@ -107,4 +107,4 @@
 			"tmp/"
 		]
 	}
-}
+}

package/scripts/dungeon-to-json.mjs

@@ -1,15 +1,14 @@
 #!/usr/bin/env node
 
 /**
- * Converts a JavaScript dungeon file to JSON that can be loaded into the UI
+ * Converts a JavaScript dungeon file to JSON that can be loaded into the UI.
+ * Thin CLI wrapper around the exported `dungeonToJSON` (lib/core/dungeon-to-json.js).
  * Usage: node scripts/dungeon-to-json.js <input.js> [output-name]
  */
 
 import { writeFileSync } from 'fs';
 import path from 'path';
-import { fileURLToPath } from 'url';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
+import { dungeonToJSON } from '../lib/core/dungeon-to-json.js';
 
 // Get command line arguments
 const args = process.argv.slice(2);
@@ -25,34 +24,10 @@ const inputPath = path.resolve(args[0]);
 const outputName = args[1] || path.basename(inputPath, '.js');
 
 try {
-    // Import the JavaScript module
     console.log(`📖 Loading ${inputPath}...`);
-    const module = await import(`file://${inputPath}`);
-    const config = module.default;
-
-    if (!config) {
-        throw new Error('No default export found in the module');
-    }
-
-    // Extract hooks if they exist
-    const hooksFunction = config.hook;
-    const hooksString = hooksFunction ? hooksFunction.toString() : null;
-
-    // Create a clean config without the hook function
-    const cleanConfig = { ...config };
-    delete cleanConfig.hook;
-
-    // Convert to JSON-serializable format
     console.log('🔄 Converting to JSON format...');
-    const schema = convertToJSON(cleanConfig);
-
-    // Create the dungeon state object (same format as UI saves)
-    const dungeonState = {
-        schema,
-        hooks: hooksString,
-        timestamp: new Date().toISOString(),
-        version: '4.0'
-    };
+    // includeCredentials: true preserves the legacy UI round-trip behavior (full config).
+    const dungeonState = await dungeonToJSON(inputPath, { includeCredentials: true });
 
     // Write to JSON file
     const outputPath = path.join(path.dirname(inputPath), `${outputName}.json`);
@@ -67,97 +42,3 @@ try {
     console.error(error.stack);
     process.exit(1);
 }
-
-/**
- * Convert JavaScript config to JSON-serializable format
- * Detects functions and converts them to object representation
- */
-function convertToJSON(value) {
-    // Null/undefined
-    if (value === null || value === undefined) {
-        return null;
-    }
-
-    // Primitives
-    if (typeof value === 'boolean' || typeof value === 'number' || typeof value === 'string') {
-        return value;
-    }
-
-    // Functions - convert to object representation
-    if (typeof value === 'function') {
-        return convertFunctionToObject(value);
-    }
-
-    // Arrays
-    if (Array.isArray(value)) {
-        return value.map(item => convertToJSON(item));
-    }
-
-    // Objects
-    if (typeof value === 'object') {
-        const result = {};
-        for (const [key, val] of Object.entries(value)) {
-            result[key] = convertToJSON(val);
-        }
-        return result;
-    }
-
-    // Fallback
-    return null;
-}
-
-/**
- * Convert a function to its object representation
- * Tries to detect the function type and extract parameters
- */
-function convertFunctionToObject(func) {
-    const funcString = func.toString();
-
-    // Arrow function
-    if (funcString.startsWith('(') || funcString.startsWith('_') || funcString.includes('=>')) {
-        return {
-            functionName: 'arrow',
-            body: funcString
-        };
-    }
-
-    // Bound chance methods (e.g., chance.name.bind(chance))
-    if (funcString.includes('.bind(')) {
-        const match = funcString.match(/chance\.(\w+)\.bind/);
-        if (match) {
-            return {
-                functionName: `chance.${match[1]}`,
-                args: []
-            };
-        }
-    }
-
-    // Try to detect common utility functions
-    // This is a best-effort approach - some complex functions might not be detected
-    const commonFunctions = [
-        'weighNumRange',
-        'weighArray',
-        'weighChoices',
-        'pickAWinner',
-        'date',
-        'integer',
-        'uid',
-        'comma'
-    ];
-
-    for (const fnName of commonFunctions) {
-        if (funcString.includes(fnName)) {
-            // Extract args (this is simplified - real parsing would be more complex)
-            return {
-                functionName: fnName,
-                args: [] // Args would need to be extracted, but that's complex
-            };
-        }
-    }
-
-    // Generic function - just store as arrow function
-    return {
-        functionName: 'arrow',
-        body: funcString
-    };
-}

package/types.d.ts

@@ -1508,6 +1508,79 @@ export declare function parseJSONDungeon(json: object): Dungeon;
 /** Validate that an object has the minimum shape of a dungeon config. Throws on shape violations. */
 export declare function validateDungeonShape(config: unknown): void;
 
+/**
+ * The serialized form of a function found in a dungeon schema. Produced by `dungeonToJSON`
+ * and revived by `parseJSONDungeon`.
+ *
+ * - `functionName: "arrow"` with a `body` — an inline/closure function, re-eval'd on revive.
+ * - `functionName: "chance.<method>"` — a bound chance method, e.g. `chance.name.bind(chance)`.
+ * - `functionName: "<utility>"` (weighNumRange, weighArray, …) — a detected utility; args are
+ *   not recoverable from the stringified source, so it revives to null (best effort).
+ *
+ * `dataType` records the function's sampled output type so the field's type is preserved even
+ * when the generator itself can't be revived.
+ */
+export interface SerializedFunction {
+	/** "arrow", "chance.<method>", or a known utility name. */
+	functionName: string;
+	/** Stringified function source (present for arrow/closure forms). */
+	body?: string;
+	/** Captured call arguments (best effort; usually empty for detected utilities). */
+	args?: unknown[];
+	/**
+	 * Inferred output type, sampled at serialization time:
+	 * "number" | "string" | "boolean" | "date" | "object" | "<elementType>[]" | "array".
+	 * Omitted when sampling failed (e.g. the function threw).
+	 */
+	dataType?: string;
+}
+
+/**
+ * The JSON/UI wrapper representation of a dungeon, as produced by `dungeonToJSON` and
+ * consumed by `parseJSONDungeon`. Functions in `schema` are serialized to
+ * {@link SerializedFunction} objects; everything else is plain JSON.
+ */
+export interface DungeonJSON {
+	/** The dungeon config with functions converted to {@link SerializedFunction} objects (hook excluded). */
+	schema: Record<string, unknown>;
+	/** The `hook` function stringified, or null if the dungeon has no hook. */
+	hooks: string | null;
+	/** ISO timestamp of when the JSON was produced. */
+	timestamp: string;
+	/** UI schema format version. */
+	version: string;
+}
+
+/** The doc blocks extracted from a dungeon's source by `extractComments`. */
+export interface DungeonComments {
+	/** Cleaned text of the `// ── OVERVIEW ──` block, or null if absent. */
+	overview: string | null;
+	/** Cleaned text of the `// ── HOOK STORIES ──` block, or null if absent. */
+	hookStories: string | null;
+	/** Every `// ── LABEL ──` header followed by a block comment, keyed by exact label. */
+	sections: Record<string, string>;
+}
+
+/**
+ * Convert a dungeon into its JSON representation (the inverse of `parseJSONDungeon`).
+ * Accepts a config object, a file path, raw JS source, or an array of file paths
+ * (returns an array). Credentials are stripped unless `includeCredentials` is set.
+ * Best effort: arrow functions and `chance.*` methods round-trip; detected utility
+ * calls lose their arguments. Always async.
+ */
+export declare function dungeonToJSON(input: Dungeon, options?: { includeCredentials?: boolean }): Promise<DungeonJSON>;
+export declare function dungeonToJSON(input: string, options?: { includeCredentials?: boolean }): Promise<DungeonJSON>;
+export declare function dungeonToJSON(input: string[], options?: { includeCredentials?: boolean }): Promise<DungeonJSON[]>;
+
+/**
+ * Extract the human-readable doc blocks (OVERVIEW, HOOK STORIES, …) from a dungeon's
+ * SOURCE. Operates on a file path or raw source string — never imports the dungeon
+ * (importing discards comments). Best effort: relies on the canonical `// ── LABEL ──`
+ * header + block-comment convention.
+ */
+export declare function extractComments(input: string): DungeonComments;
+export declare function extractComments(input: string[]): DungeonComments[];
+
 // ============= Text Generator Types =============
 
 /**