@ak--47/dungeon-master 1.5.3 → 1.6.0

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

@@ -1,7 +1,7 @@
 ---
 name: analyze-soup
 description: Use when investigating TimeSoup parameters, diagnosing event-distribution shape, or comparing soup configs — runs a dungeon locally and analyzes time distribution at week/day/hour/minute granularities, producing a soup-analysis.md diagnostic report.
-argument-hint: [dungeon path, e.g. dungeons/soup-test.js]
+argument-hint: [dungeon path, e.g. dungeons/technical/simplest.js]
 model: claude-opus-4-6
 effort: max
 ---
@@ -10,7 +10,7 @@ effort: max
 
 Run a dungeon and analyze the time distribution of generated events to evaluate TimeSoup parameters.
 
-**Dungeon file:** `$ARGUMENTS` (default: `dungeons/soup-test.js`)
+**Dungeon file:** `$ARGUMENTS` (default: `dungeons/technical/simplest.js`)
 
 ## Step 1: Run the Dungeon
 
@@ -32,10 +32,19 @@ Wait for generation to complete. Note the event count and EPS.
 
 Run these DuckDB queries against the generated JSONL file. Use `duckdb` CLI.
 
+**All bucketing is UTC — do not convert timezones.** TimeSoup applies its
+day-of-week / hour-of-day weights in UTC, the engine's calendar-day logic
+(`avgActiveDaysPerUser`, lifecycle periods, session midnight splits) is UTC,
+and `/create-project` pins Mixpanel projects to UTC. Casting `time::timestamp`
+on the ISO strings keeps the UTC wall time. Converting to a local zone (e.g.
+`America/Los_Angeles`, −8h) shifts late-evening UTC events onto the previous
+calendar day — the DOW histogram you'd analyze would not be the one the soup
+generated or the one Mixpanel reports.
+
 ### 2a. Week over Week
 ```bash
 duckdb -c "
-SELECT date_trunc('week', (time::timestamp AT TIME ZONE 'UTC' AT TIME ZONE 'America/Los_Angeles')) as week,
+SELECT date_trunc('week', time::timestamp) as week,
        count(*) as events
 FROM read_json_auto('./data/soup-analysis-EVENTS.json')
 GROUP BY 1 ORDER BY 1;
@@ -45,7 +54,7 @@ GROUP BY 1 ORDER BY 1;
 ### 2b. Day over Day
 ```bash
 duckdb -c "
-SELECT date_trunc('day', (time::timestamp AT TIME ZONE 'UTC' AT TIME ZONE 'America/Los_Angeles')) as day,
+SELECT date_trunc('day', time::timestamp) as day,
        count(*) as events
 FROM read_json_auto('./data/soup-analysis-EVENTS.json')
 GROUP BY 1 ORDER BY 1;
@@ -55,10 +64,10 @@ GROUP BY 1 ORDER BY 1;
 ### 2c. Hour over Hour (last 7 days only)
 ```bash
 duckdb -c "
-SELECT date_trunc('hour', (time::timestamp AT TIME ZONE 'UTC' AT TIME ZONE 'America/Los_Angeles')) as hour,
+SELECT date_trunc('hour', time::timestamp) as hour,
        count(*) as events
 FROM read_json_auto('./data/soup-analysis-EVENTS.json')
-WHERE (time::timestamp AT TIME ZONE 'UTC' AT TIME ZONE 'America/Los_Angeles') > (SELECT max((time::timestamp AT TIME ZONE 'UTC' AT TIME ZONE 'America/Los_Angeles')) - interval '7 days' FROM read_json_auto('./data/soup-analysis-EVENTS.json'))
+WHERE time::timestamp > (SELECT max(time::timestamp) - interval '7 days' FROM read_json_auto('./data/soup-analysis-EVENTS.json'))
 GROUP BY 1 ORDER BY 1;
 "
 ```
@@ -66,10 +75,10 @@ GROUP BY 1 ORDER BY 1;
 ### 2d. Minute over Minute (last 24 hours only)
 ```bash
 duckdb -c "
-SELECT date_trunc('minute', (time::timestamp AT TIME ZONE 'UTC' AT TIME ZONE 'America/Los_Angeles')) as minute,
+SELECT date_trunc('minute', time::timestamp) as minute,
        count(*) as events
 FROM read_json_auto('./data/soup-analysis-EVENTS.json')
-WHERE (time::timestamp AT TIME ZONE 'UTC' AT TIME ZONE 'America/Los_Angeles') > (SELECT max((time::timestamp AT TIME ZONE 'UTC' AT TIME ZONE 'America/Los_Angeles')) - interval '1 day' FROM read_json_auto('./data/soup-analysis-EVENTS.json'))
+WHERE time::timestamp > (SELECT max(time::timestamp) - interval '1 day' FROM read_json_auto('./data/soup-analysis-EVENTS.json'))
 GROUP BY 1 ORDER BY 1;
 "
 ```
@@ -78,14 +87,14 @@ GROUP BY 1 ORDER BY 1;
 ```bash
 duckdb -c "
 WITH daily AS (
-  SELECT date_trunc('day', (time::timestamp AT TIME ZONE 'UTC' AT TIME ZONE 'America/Los_Angeles')) as day, count(*) as events
+  SELECT date_trunc('day', time::timestamp) as day, count(*) as events
   FROM read_json_auto('./data/soup-analysis-EVENTS.json')
   GROUP BY 1
 ),
 hourly AS (
-  SELECT date_trunc('hour', (time::timestamp AT TIME ZONE 'UTC' AT TIME ZONE 'America/Los_Angeles')) as hour, count(*) as events
+  SELECT date_trunc('hour', time::timestamp) as hour, count(*) as events
   FROM read_json_auto('./data/soup-analysis-EVENTS.json')
-  WHERE (time::timestamp AT TIME ZONE 'UTC' AT TIME ZONE 'America/Los_Angeles') > (SELECT max((time::timestamp AT TIME ZONE 'UTC' AT TIME ZONE 'America/Los_Angeles')) - interval '7 days' FROM read_json_auto('./data/soup-analysis-EVENTS.json'))
+  WHERE time::timestamp > (SELECT max(time::timestamp) - interval '7 days' FROM read_json_auto('./data/soup-analysis-EVENTS.json'))
   GROUP BY 1
 )
 SELECT 'daily' as granularity,
@@ -112,7 +121,7 @@ FROM hourly;
 ```bash
 duckdb -c "
 WITH daily AS (
-  SELECT date_trunc('day', (time::timestamp AT TIME ZONE 'UTC' AT TIME ZONE 'America/Los_Angeles')) as day, count(*) as events
+  SELECT date_trunc('day', time::timestamp) as day, count(*) as events
   FROM read_json_auto('./data/soup-analysis-EVENTS.json')
   GROUP BY 1
 )

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

@@ -51,7 +51,14 @@ Out of scope (hand off to `write-hooks`):
 For an encyclopedia of hook patterns, recipes, and real-world examples:
 see `HOOKS.md` at the project root.
 
-These config keys are silently ignored — DO NOT use them: `subscription`, `attribution`, `geo`, `features`, `anomalies`. Recreate with hooks via `write-hooks`.
+> ⚠️ **Silently-ignored config keys — do not use.** The validator STRIPS these
+> five keys before generation: `subscription`, `attribution`, `geo`,
+> `features`, `anomalies`. They produce **zero data** — only a verbose-mode
+> warning. A dungeon that "configures" churn via `subscription:` or campaign
+> lift via `attribution:` is configuring nothing, and the omission is
+> invisible at smoke-test scale. Recreate those behaviors with hooks via
+> `/write-hooks` (churn cohorts, UTM biasing, geo weighting, feature-flag
+> cohorts, anomaly windows all have recipes in `HOOKS.md`).
 
 ## Reference reading
 
@@ -62,8 +69,10 @@ Before writing any code, scan:
   with full JSDoc. **Treat this as the source of truth.**
 - `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/my-buddy.js` — consumer-app reference (gitignored)
+- `dungeons/vertical/sass/sass.js` — B2B reference dungeon with full identity model
+- `dungeons/vertical/ecommerce/ecommerce.js` — canonical consumer exemplar:
+  schema, funnels, stories export, and full hook layout (what your schema
+  becomes after `/write-hooks`)
 - `dungeons/technical/identity-model-verify.js` — minimal identity-model fixture
 
 ## File structure
@@ -88,6 +97,7 @@ import * as v from "ak-tools";
  * APP:        <2-4 line description: what users do, core flow, monetization>
  * SCALE:      <numUsers> users, ~<numEvents> events, <numDays> days (<start> → <end>)
  * CORE LOOP:  <event1> → <event2> → <event3> → ...
+ * VALUE MOMENT: <the one event representing realized value — lifecycle hooks anchor here>
  *
  * EVENTS (N):
  *   <event name (weight)> > ...   (sorted by weight desc)
@@ -160,7 +170,7 @@ KNOBS (extracted tunable constants — timing, thresholds, multipliers),
 HOOK STATE (module-level Maps/Sets used across users), and HELPER FUNCTIONS
 (per-type handlers like `handleEventHooks`, `handleEverythingHooks`).
 `config.hook` becomes a thin dispatcher delegating to the helpers. See
-`dungeons/vertical/ecommerce.js` as the canonical exemplar.
+`dungeons/vertical/ecommerce/ecommerce.js` as the canonical exemplar.
 
 ## Required components
 
@@ -196,6 +206,30 @@ When using experiments, include `$experiment_started` in the events array with
 }}
 ```
 
+**Design the vocabulary for the analyses hooks will target (v1.6):**
+
+- **Session-friendly next-events.** Flows (Sankey) reads collapse when an
+  anchor event can plausibly be followed by 15 different event types — every
+  branch gets a sliver and no engineered path clears the top level. For each
+  high-traffic anchor (post-login, post-search, post-add-to-cart), keep the
+  realistic next-event vocabulary to **≤5–6 event types**; if the app
+  genuinely has more surfaces, give the rare ones weight 1 so the top paths
+  stay legible. A path-share hook needs ~20–25% share to survive a Sankey's
+  top-3 — impossible against a 15-way fan-out.
+- **Designate a value moment.** Pick ONE event that represents realized value
+  (first workout logged, order delivered, report generated) and record it in
+  the OVERVIEW block as `VALUE MOMENT: <event>`. Lifecycle stories
+  (dormancy → resurrection waves) anchor on the value moment — hooks gate or
+  inject THAT event, not generic page views. A schema with no obvious value
+  moment forces `write-hooks` to invent one badly.
+- **Hidden-event hygiene.** Heartbeat/telemetry events (`ping`,
+  `app foregrounded`, `position updated`) at weight ≥5 drown every Sankey
+  level — every top path becomes anchor → heartbeat → heartbeat. Mixpanel
+  Flows (and the emulator's `topPaths` via `hiddenEvents`) can hide them at
+  query time, but the default view is what demos show. If realism demands
+  heartbeats, keep them at weight 1–2 and list them in the OVERVIEW so
+  `write-hooks` knows to pass `hiddenEvents` in flows stories.
+
 ### 2. Funnels (3–6)
 
 - First funnel: includes `isFirstEvent` AND has `isAuthEvent: true` on the
@@ -237,6 +271,32 @@ event.
 
 **Funnels representing loops need `reentry: true`.** Any funnel named "X loop" / "X cycle" / "session" / per-instance recurring behavior must declare `reentry: true`. Without it, the engine emits one sequence per user and downstream "power user" / "daily active" cohorts have no behavioral signal to bin on.
 
+**Structural trend engineering — duplicate funnels instead of reaching for
+hooks.** Not every trend needs a hook: initial conditions can raise or lower
+a metric by themselves. The funnel array is a set of knobs — duplicate a
+funnel and swap steps, props, `conversionRate`, `timeToConvert`, or `weight`
+to architect a comparison directly into the schema:
+
+- **Exclusion-step story**: Mixpanel funnels can exclude users who did
+  `foo` between A and B. There's no `excludeSteps` config — model it with
+  two funnels, `[A, B, C]` and `[A, B, foo, C]`, giving the second a lower
+  `conversionRate`. The report shows the conversion dip for the
+  detour-takers with zero hook code.
+- **Segment-split story**: two copies of the same sequence with different
+  `props` (`{ checkout_version: "v1" }` vs `"v2"`) and different
+  `conversionRate` — an A/B story without the experiment machinery (use
+  `experiment` when you want `$experiment_started` + variant reports).
+- **Speed story**: same sequence, different `timeToConvert`, split by a
+  funnel-level prop — time-to-convert deltas appear structurally.
+- **Mix-shift story**: `weight` controls how often each variant funnel is
+  chosen; a heavy-weighted low-converting path drags the blended rate.
+
+Prefer structure when the story is a *between-path comparison* (this path
+converts worse / slower than that one). Reach for hooks when the story is a
+*within-cohort behavior* (these users do more of X over time, this segment's
+values differ). Structural trends are cheaper to verify — the knob IS the
+expected value.
+
 ### 3. SuperProps (2–3)
 
 Properties present on EVERY event. Common picks: `Plan`, `Region`, `Platform`,
@@ -554,7 +614,7 @@ When designing event properties, always consider which Mixpanel type best repres
 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`.
+file share the name, matching the vertical layout (`ecommerce/ecommerce.js`).
 
 This keeps `dungeons/user/` organized — EVERYTHING about this dungeon lives in
 the same folder: `hook-results.md` + `hook-query-log.txt` +

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` comment block plus the `stories` named export (per story: `narrative` + `mixpanelReport` + intentional deviations); dungeons without stories fall back to the `HOOK STORIES` comment scrape (via the package's `extractComments`). Plus an events/funnels/props/group-keys summary, capped at 50k chars. The dry-run plan prints which source was used.
+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,336 @@
+#!/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 + the dungeon's `stories` export
+ *      (narrative + mixpanelReport per story) — falls back to the HOOK
+ *      STORIES comment scrape when the dungeon has no 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, pathToFileURL } 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);
+
+// stories is a NAMED export of JS dungeons (v1.6 story-spec) — the verified
+// behavior contract. Preferred over the comment scrape for business context.
+let stories = null;
+if (/\.(js|mjs)$/i.test(dungeonPath)) {
+	try {
+		const mod = await import(pathToFileURL(dungeonPath).href);
+		if (Array.isArray(mod.stories) && mod.stories.length) stories = mod.stories;
+	} catch {
+		// loadFromFile above already imported the module; an error here would
+		// have surfaced there. Fall back to the comment scrape regardless.
+	}
+}
+
+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 ctxSource = stories ? `stories export (${stories.length} stories)` : 'comment scrape';
+const content = buildContext(name, config, comments, groupKeys, stories);
+
+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;
+	// Mixpanel's createServiceAccount requires %Y-%m-%dT%H:%M:%SZ — seconds
+	// precision, NO milliseconds. toISOString() emits ".sssZ", which the API
+	// rejects ("Expiration date … does not match %Y-%m-%dT%H:%M:%SZ").
+	return new Date(ms).toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+
+function buildContext(name, config, comments, groupKeys, stories) {
+	const parts = [`# ${name}`, ''];
+	if (comments.overview) parts.push(comments.overview, '');
+
+	// Preferred source: the stories export — each story's narrative is the
+	// human-readable behavior and mixpanelReport (free-form object) points at
+	// the report where it shows. Comment scrape is the fallback for dungeons
+	// without stories (schema-only or pre-1.6).
+	if (stories?.length) {
+		parts.push('## Engineered Behaviors', '');
+		parts.push(`${stories.length} machine-verified story patterns (from the dungeon's \`stories\` export):`, '');
+		for (const s of stories) {
+			const arch = s.archetype ? ` — ${s.archetype}` : '';
+			parts.push(`### ${s.id}${arch}`, '');
+			if (s.narrative) parts.push(String(s.narrative).trim(), '');
+			if (s.mixpanelReport && typeof s.mixpanelReport === 'object') {
+				parts.push('How to see it in Mixpanel:');
+				for (const [k, v] of Object.entries(s.mixpanelReport)) {
+					parts.push(`- **${k}**: ${typeof v === 'string' ? v : JSON.stringify(v)}`);
+				}
+				parts.push('');
+			}
+			if (Array.isArray(s.intentionalDeviations) && s.intentionalDeviations.length) {
+				parts.push('Notes:', ...s.intentionalDeviations.map((d) => `- ${d}`), '');
+			}
+		}
+	} else 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 (source: ${ctxSource})`);
+	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) {
+		// Defensive: the API's `added`/`skipped` entries may be objects, strings, or
+		// null. Never let summary formatting throw — it would swallow real warnings.
+		const fmt = (g) => (g == null ? null : typeof g === 'string' ? g : (g.property_name || g.name || null));
+		const added = (groupKeyResult?.added || []).map(fmt).filter(Boolean).join(', ') || '(none)';
+		const skipped = (groupKeyResult?.skipped || []).map(fmt).filter(Boolean).join(', ') || '(none)';
+		console.log(`group keys:     added [${added}]  skipped [${skipped}]`);
+	}
+	console.log(`business ctx:   ${content.length} chars uploaded (source: ${ctxSource})`);
+	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);
+}