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

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

@@ -25,7 +25,7 @@ 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.
+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

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

@@ -10,7 +10,9 @@
  *   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)
+ *   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)
  *
@@ -27,7 +29,7 @@
 
 import { readFileSync, writeFileSync, existsSync } from 'fs';
 import path, { dirname, resolve } from 'path';
-import { fileURLToPath } from 'url';
+import { fileURLToPath, pathToFileURL } from 'url';
 import dotenv from 'dotenv';
 import { loadFromFile, extractComments } from '../../../index.js';
 
@@ -57,12 +59,26 @@ if (!existsSync(dungeonPath)) fail(`dungeon file not found: ${dungeonPath}`);
 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 content = buildContext(name, config, comments, groupKeys);
+const ctxSource = stories ? `stories export (${stories.length} stories)` : 'comment scrape';
+const content = buildContext(name, config, comments, groupKeys, stories);
 
 if (dryRun) {
 	printPlan();
@@ -182,13 +198,41 @@ function slug(s) {
 
 function isoInDays(days) {
 	const ms = Date.now() + days * 24 * 60 * 60 * 1000;
-	return new Date(ms).toISOString();
+	// 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) {
+function buildContext(name, config, comments, groupKeys, stories) {
 	const parts = [`# ${name}`, ''];
 	if (comments.overview) parts.push(comments.overview, '');
-	if (comments.hookStories) parts.push('## Engineered Behaviors', '', comments.hookStories, '');
+
+	// 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 || [];
@@ -252,7 +296,7 @@ function printPlan() {
 	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(`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.');
@@ -268,11 +312,14 @@ function printSummary() {
 	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)';
+		// 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`);
+	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('');

package/.claude/skills/powertools/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: powertools
+description: Use when any task needs the Mixpanel Power Tools API ("use powertools") — schema export (get-schema), event volumes, project CRUD, query methods, macros, or snapshotting a prod project's schema to copy it into a dungeon. Companion to create-project (which handles provisioning specifically).
+argument-hint: [what to do, e.g. "get schema for project 12345" or "copy project 12345 into a dungeon"]
+---
+
+# Power Tools API
+
+Base URL: `https://mixpanel-power-tools-api-lmozz6xkha-uc.a.run.app`
+
+## Auth model — read this first
+
+- **GET any endpoint path = documentation, no auth.** Always `curl -s GET <base><path>` before first use of an unfamiliar endpoint — docs include exact body params and response shapes.
+- **POST = execute.** `Authorization: Bearer <oauth-token>` (employee OAuth from repo `.env` `BEARER_TOKEN`, or a customer's OAuth token) or `Basic base64(service_acct:secret)`.
+- **Customer OAuth tokens are accepted** (verified 2026-07-06): `/auth` and `/macro/get-schema` work with a customer token on projects that token can access. `ai_endpoints_allowed: false` for non-employees — the `ai-*` family stays employee-only.
+- **Every POST body** should include `client_id: "dungeon-master"` and `region` (`US` default).
+- **`/auth` accessibility ≠ data access.** `/auth {project_id}` can report `accessible: true` while `get-schema`/`query/*` on the same project return `HTTP 403: Forbidden` (token lacks data-level access, e.g. an employee token on a customer project). Diagnose with `/auth`, but don't trust it for data endpoints. Prefer the token of an actual project member.
+
+## Tools in this skill
+
+### `pt.mjs` — ad-hoc client
+
+```bash
+node .claude/skills/powertools/pt.mjs <path> ['<json-body>'] [--bearer <token>] [--get] [--region US]
+# examples
+node .claude/skills/powertools/pt.mjs /auth '{}'
+node .claude/skills/powertools/pt.mjs /macro/get-schema '{"project_id":"123","include_metadata":true,"verbose":true}'
+node .claude/skills/powertools/pt.mjs /query/getTopEvents --get          # docs, no auth
+```
+
+Bearer defaults to `.env` `BEARER_TOKEN`. Merges `client_id`/`region` into the body. Prints pretty JSON to stdout.
+
+### `snapshot-project.mjs` — schema + relative-volume snapshot
+
+```bash
+node .claude/skills/powertools/snapshot-project.mjs <project_id> --bearer <token> \
+  [--region US] [--out snapshot.json]
+```
+
+- Uses `/macro/get-schema` (`include_metadata` + `verbose`) + `/query/getTopEvents`. Token (customer or employee) needs data access to the project.
+- Output shape: `{ projectId, projectName, fetchedAt, totalCount, events: [{ name, count, pct, properties: [{name, type, description}] }], userProps: [{name, type, description}], groups: {} }`, events sorted by count desc.
+- **Never captures property values** — schema + volumes only. Snapshots stay privacy-safe by construction.
+
+## Endpoint catalog (the useful subset)
+
+GET the path for full docs. Full list: GET `/` and GET `/macro`.
+
+**crud** — `/crud/createProject`, `/crud/deleteProject`, `/crud/getProjects`, `/crud/mintServiceAccount`, `/crud/addGroupKey`, `/crud/setBusinessContext` (all used by the create-project skill's `provision.mjs`).
+
+**query** — `/query/getTopEvents` (per-event counts, limit≤100 default), `/query/getEventNames`, `/query/getPropertyValues`, `/query/getTopProperties`, `/query/getSegmentation`, `/query/getFunnel`, `/query/listFunnels`, `/query/listCohorts`, `/query/runJQL`. Rate limits: 5 concurrent / 60 per hour; 1h response cache.
+
+**macros** — `/macro/get-schema` (always pass `include_metadata: true, verbose: true`; also `include_density: true` for per-(event,property) coverage % and `include_sdk_defaults: true` to keep `$browser`/`$os`-style SDK props — needed for carbon copies), `/macro/analyze-project` (volumes + cardinality + activity), `/macro/enumerate-project`, `/macro/clone-project`, `/macro/clone-boards`, `/macro/delete-entities`, `/macro/dungeon-master` (runs a dungeon config server-side and ingests), `/macro/ai-e2e-dm4` (demo build from a supplied schema, designed for dungeon-master), plus the `ai-*` family (dashboards, cohorts, metrics, schema naming).
+
+### get-schema field notes (verified on a 2,410-event project, 2026-07-06)
+
+- Response nests under `json`: `{ json: { events, properties, users, groups, dependencies }, duration_ms }`. Large projects are slow — 2,410 events took ~13 min; run it in the background.
+- Event counts include custom events (`customEventId > 0`) and merged events. Filter `!merged && !(customEventId > 0)` to match the Lexicon UI event count.
+- `properties` includes `mp_*` internals and `$custom_property:<id>` computed-prop references — exclude both when authoring a dungeon (ingestion stamps `mp_*` itself; computed props can't be tracked).
+- `exampleValue` fields contain REAL customer values — never copy them into a dungeon.
+- **Known issue**: `dependencies` can come back empty (`{events:{},properties:{}}`) on large projects even with `verbose: true` + `include_density: true` — the bulk dependency call silently fails. Retry the call; per-event property mapping is unavailable until it succeeds.
+
+## Recipe: copy a prod project into a dungeon
+
+Goal: a purely synthetic dungeon with the same events/props/user-props and matching **relative** event volumes. Safe to share — no customer data.
+
+1. **Snapshot** the source project (`snapshot-project.mjs`, customer token unless the employee token has data access). Sanity-check event count + that counts are non-zero.
+2. **Author the dungeon** from the snapshot (schema-first, per repo hook rules):
+   - Take the top-N events covering ≥95% of total volume (`pct` cumsum); note dropped tail in the OVERVIEW comment.
+   - `weight` per event ∝ snapshot `count` (normalize so max ≈ 100, min ≥ 1).
+   - Properties per event from snapshot; **invent all values** from name/type/description — never copy real values.
+   - `userProps` from snapshot; shared high-frequency props → `superProps`.
+   - Funnels: best-effort from event-name semantics (or `/query/listFunnels` + `/query/getFunnel` on the source if accessible).
+3. **Provision** into our org via the create-project skill: `node .claude/skills/create-project/provision.mjs <dungeon> --dry-run` → confirm → live. Uses `.env` `BEARER_TOKEN` + `ORG_ID`, writes `credentials` back into the dungeon.
+4. **Run**: `node scripts/run-dungeon.mjs <dungeon>`.
+5. **Verify** relative volumes: top-10 generated events should rank in the same order as the snapshot's top-10.

package/.claude/skills/powertools/pt.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+
+/**
+ * pt.mjs — thin ad-hoc client for the Mixpanel Power Tools API.
+ *
+ * Usage:
+ *   node .claude/skills/powertools/pt.mjs <path> ['<json-body>'] [--bearer <token>] [--get] [--region US]
+ *
+ * Examples:
+ *   node .claude/skills/powertools/pt.mjs /auth '{}'
+ *   node .claude/skills/powertools/pt.mjs /macro/get-schema '{"project_id":"123","include_metadata":true,"verbose":true}'
+ *   node .claude/skills/powertools/pt.mjs /query/getTopEvents --get     # endpoint docs, no auth
+ *
+ * POST bodies are merged with { client_id: "dungeon-master", region }.
+ * Bearer defaults to BEARER_TOKEN in the repo .env (employee OAuth). Customer
+ * OAuth tokens are accepted on non-ai endpoints; the ai-* family is
+ * employee-only (see SKILL.md).
+ */
+
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import dotenv from 'dotenv';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+dotenv.config({ path: resolve(__dirname, '../../../.env') });
+
+const BASE = 'https://mixpanel-power-tools-api-lmozz6xkha-uc.a.run.app';
+const CLIENT_ID = 'dungeon-master';
+
+const args = process.argv.slice(2);
+const getMode = popFlag('--get');
+const bearer = popOpt('--bearer') ?? process.env.BEARER_TOKEN;
+const region = popOpt('--region') ?? 'US';
+const [pathArg, bodyArg] = args;
+
+if (!pathArg || !pathArg.startsWith('/')) {
+	console.error('Usage: node pt.mjs <path starting with /> [\'<json-body>\'] [--bearer <token>] [--get] [--region US]');
+	process.exit(1);
+}
+
+if (getMode) {
+	const res = await fetch(BASE + pathArg);
+	console.log(JSON.stringify(await res.json(), null, 2));
+	process.exit(res.ok ? 0 : 1);
+}
+
+if (!bearer) {
+	console.error('No bearer token: pass --bearer or set BEARER_TOKEN in .env');
+	process.exit(1);
+}
+
+let body = {};
+if (bodyArg) {
+	try {
+		body = JSON.parse(bodyArg);
+	} catch (err) {
+		console.error(`Body is not valid JSON: ${err.message}`);
+		process.exit(1);
+	}
+}
+
+const res = await fetch(BASE + pathArg, {
+	method: 'POST',
+	headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${bearer}` },
+	body: JSON.stringify({ client_id: CLIENT_ID, region, ...body }),
+});
+
+const text = await res.text();
+try {
+	console.log(JSON.stringify(JSON.parse(text), null, 2));
+} catch {
+	console.log(text);
+}
+if (!res.ok) {
+	console.error(`\nHTTP ${res.status} ${res.statusText}`);
+	process.exit(1);
+}
+
+function popFlag(name) {
+	const i = args.indexOf(name);
+	if (i === -1) return false;
+	args.splice(i, 1);
+	return true;
+}
+
+function popOpt(name) {
+	const i = args.indexOf(name);
+	if (i === -1) return undefined;
+	const [, value] = args.splice(i, 2);
+	return value;
+}

package/.claude/skills/powertools/snapshot-project.mjs

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+
+/**
+ * snapshot-project.mjs — export a Mixpanel project's schema + relative event
+ * volumes into one normalized JSON snapshot, for authoring a synthetic
+ * dungeon-master "copy" of the project.
+ *
+ * Usage:
+ *   node .claude/skills/powertools/snapshot-project.mjs <project_id> --bearer <token> \
+ *     [--region US|EU|IN] [--out <file>]
+ *
+ * Uses the Power Tools API: /macro/get-schema (include_metadata + verbose) +
+ * /query/getTopEvents. The bearer token (customer or employee OAuth) needs
+ * data access to the project — /auth reporting accessible: true is not enough.
+ *
+ * Output shape (events sorted by count desc):
+ *   {
+ *     projectId, projectName, fetchedAt, region, totalCount,
+ *     events:    [{ name, count, pct, properties: [{ name, type, description }] }],
+ *     userProps: [{ name, type, description }],
+ *     groups:    {}
+ *   }
+ *
+ * Privacy: captures schema + volumes ONLY — never property values.
+ */
+
+import { writeFileSync } from 'fs';
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import dotenv from 'dotenv';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+dotenv.config({ path: resolve(__dirname, '../../../.env') });
+
+const PT_BASE = 'https://mixpanel-power-tools-api-lmozz6xkha-uc.a.run.app';
+const CLIENT_ID = 'dungeon-master';
+const REGIONS = ['US', 'EU', 'IN'];
+
+const args = process.argv.slice(2);
+const bearer = popOpt('--bearer') ?? process.env.BEARER_TOKEN;
+const region = (popOpt('--region') ?? 'US').toUpperCase();
+const outArg = popOpt('--out');
+const projectId = args.find((a) => !a.startsWith('--'));
+
+if (!projectId || !/^\d+$/.test(projectId)) fail('Usage: snapshot-project.mjs <project_id> --bearer <token> [--region US] [--out file]');
+if (!bearer) fail('No bearer token: pass --bearer or set BEARER_TOKEN in .env');
+if (!REGIONS.includes(region)) fail(`Unknown --region "${region}"`);
+
+const outPath = resolve(process.cwd(), outArg ?? `snapshot-${projectId}.json`);
+
+const snapshot = await snapshotViaPowertools();
+
+snapshot.events.sort((a, b) => b.count - a.count);
+snapshot.totalCount = snapshot.events.reduce((s, e) => s + e.count, 0);
+for (const e of snapshot.events) e.pct = snapshot.totalCount ? +(e.count / snapshot.totalCount * 100).toFixed(4) : 0;
+
+writeFileSync(outPath, JSON.stringify(snapshot, null, 2));
+
+const zeros = snapshot.events.filter((e) => e.count === 0).length;
+console.log(`✓ snapshot → ${outPath}`);
+console.log(`  project:    ${snapshot.projectName ?? '(name unknown)'} (${snapshot.projectId})`);
+console.log(`  events:     ${snapshot.events.length} (${zeros} with zero volume)`);
+console.log(`  userProps:  ${snapshot.userProps.length}`);
+console.log(`  total vol:  ${snapshot.totalCount.toLocaleString()} events`);
+console.log('  top 10:');
+for (const e of snapshot.events.slice(0, 10)) console.log(`    ${e.pct.toFixed(2).padStart(6)}%  ${e.count.toLocaleString().padStart(12)}  ${e.name}`);
+
+async function snapshotViaPowertools() {
+	const schema = await ptPost('/macro/get-schema', { project_id: projectId, include_metadata: true, verbose: true });
+	const top = await ptPost('/query/getTopEvents', { project_id: projectId, limit: 500 });
+
+	const counts = {};
+	for (const r of top.results ?? []) counts[r.event] = r.count;
+
+	// dependencies.events maps eventName → [propertyNames]; property defs live in schema.properties
+	const propDefs = new Map();
+	for (const p of schema.properties ?? []) propDefs.set(p.name, p);
+	const deps = schema.dependencies?.events ?? {};
+
+	const events = (schema.events ?? []).map((ev) => {
+		const name = ev.name ?? ev;
+		const propNames = deps[name] ?? [];
+		return {
+			name,
+			count: counts[name] ?? 0,
+			pct: 0,
+			properties: propNames.map((pn) => {
+				const def = propDefs.get(pn) ?? {};
+				return { name: pn, type: def.type ?? 'string', description: def.description ?? '' };
+			}),
+		};
+	});
+
+	const userProps = (schema.users ?? []).map((p) => ({
+		name: p.name ?? p,
+		type: p.type ?? 'string',
+		description: p.description ?? '',
+	}));
+
+	return { projectId, projectName: null, fetchedAt: new Date().toISOString(), region, totalCount: 0, events, userProps, groups: schema.groups ?? {} };
+}
+
+async function ptPost(pathname, body) {
+	const res = await fetch(PT_BASE + pathname, {
+		method: 'POST',
+		headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${bearer}` },
+		body: JSON.stringify({ client_id: CLIENT_ID, region, ...body }),
+	});
+	const json = await res.json().catch(() => ({}));
+	if (!res.ok) throw new Error(`POST ${pathname} → HTTP ${res.status}: ${json.error ?? JSON.stringify(json).slice(0, 300)}`);
+	return json;
+}
+
+function popOpt(name) {
+	const i = args.indexOf(name);
+	if (i === -1) return undefined;
+	const [, value] = args.splice(i, 2);
+	return value;
+}
+
+function fail(msg) {
+	console.error(`✖ ${msg}`);
+	process.exit(1);
+}