@ak--47/dungeon-master 1.4.5 → 1.5.1

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

@@ -0,0 +1,158 @@
+---
+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]
+model: claude-opus-4-6
+effort: max
+---
+
+# Analyze TimeSoup Distribution
+
+Run a dungeon and analyze the time distribution of generated events to evaluate TimeSoup parameters.
+
+**Dungeon file:** `$ARGUMENTS` (default: `dungeons/soup-test.js`)
+
+## Step 1: Run the Dungeon
+
+Run the dungeon with forced local-only settings:
+
+```bash
+npm run prune
+node -e "
+import generate from './index.js';
+import config from './$ARGUMENTS';
+const result = await generate({ ...config, writeToDisk: true, format: 'json', token: '', verbose: true, name: 'soup-analysis' });
+console.log('Events:', result.eventCount, 'Users:', result.userCount);
+"
+```
+
+Wait for generation to complete. Note the event count and EPS.
+
+## Step 2: Query with DuckDB
+
+Run these DuckDB queries against the generated JSONL file. Use `duckdb` CLI.
+
+### 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,
+       count(*) as events
+FROM read_json_auto('./data/soup-analysis-EVENTS.json')
+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,
+       count(*) as events
+FROM read_json_auto('./data/soup-analysis-EVENTS.json')
+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,
+       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'))
+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,
+       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'))
+GROUP BY 1 ORDER BY 1;
+"
+```
+
+### 2e. Distribution Statistics
+```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
+  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
+  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'))
+  GROUP BY 1
+)
+SELECT 'daily' as granularity,
+       count(*) as buckets,
+       round(avg(events), 1) as avg_events,
+       min(events) as min_events,
+       max(events) as max_events,
+       round(max(events)::float / nullif(avg(events), 0), 2) as max_to_avg_ratio,
+       round(stddev(events) / nullif(avg(events), 0), 3) as cv
+FROM daily
+UNION ALL
+SELECT 'hourly',
+       count(*),
+       round(avg(events), 1),
+       min(events),
+       max(events),
+       round(max(events)::float / nullif(avg(events), 0), 2),
+       round(stddev(events) / nullif(avg(events), 0), 3)
+FROM hourly;
+"
+```
+
+### 2f. Spike Detection
+```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
+  FROM read_json_auto('./data/soup-analysis-EVENTS.json')
+  GROUP BY 1
+)
+SELECT
+  'last_day_vs_avg' as check,
+  CASE WHEN last_events > avg_events * 2.0 THEN '❌ FAIL (>2x avg)'
+       WHEN last_events > avg_events * 1.5 THEN '⚠️ WARN (>1.5x avg)'
+       ELSE '✅ PASS' END as result,
+  last_events,
+  round(avg_events, 0) as avg_events,
+  round(last_events::float / avg_events, 2) as ratio
+FROM (
+  SELECT
+    (SELECT events FROM daily ORDER BY day DESC LIMIT 1) as last_events,
+    (SELECT avg(events) FROM daily) as avg_events
+);
+"
+```
+
+## Step 3: Write Report
+
+Create `soup-analysis.md` in the project root with:
+
+1. **Config**: The soup parameters used (peaks, deviation, mean, numDays)
+2. **Summary stats**: Total events, event count, avg EPS
+3. **Distribution tables**: Week/Day/Hour/Minute tables from Step 2
+4. **Statistics**: CV, max-to-avg ratio at each granularity
+5. **Spike detection**: Pass/fail for last day and last hour
+6. **Assessment**: Overall quality judgment and recommendations
+
+### Quality Criteria
+- **Daily CV**: 0.2-0.6 is ideal (some variation, not flat or spiky)
+- **Max-to-avg ratio**: < 2.0 at daily level, < 3.0 at hourly level
+- **Last day spike**: < 1.5x average = PASS, < 2x = WARN, > 2x = FAIL
+- **Hourly pattern**: Should show visible peaks but no single hour > 5x average
+
+## Step 4: Cleanup
+
+```bash
+npm run prune
+```
+
+Remove `soup-analysis.md` only if the user asks. It's meant to persist for comparison across runs.

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

@@ -0,0 +1,464 @@
+---
+name: create-dungeon
+description: Use when authoring a new dungeon-master config from an app description — designs events, funnels, properties, identity model, and macro/soup. SCHEMA ONLY; engineered story trends + hooks are added separately by write-hooks.
+argument-hint: [free-text app description, e.g. "AI meeting assistant" or "B2B logistics platform"]
+model: claude-opus-4-6
+effort: max
+---
+
+# Create a Dungeon (schema only)
+
+Design and write a complete dungeon-master dungeon for: **$ARGUMENTS**
+
+## Scope
+
+This skill produces a **realistic baseline schema** that runs cleanly out of the
+box. It does **NOT** engineer story trends or magic numbers — those are the
+`write-hooks` skill's job. After this skill produces a dungeon, the next call
+should be:
+
+```
+/write-hooks dungeons/user/<your-dungeon>.js "describe the trends to engineer"
+```
+
+In scope here:
+- Event names, weights, properties (with realistic value distributions)
+- `superProps` and `userProps` (consistent across users)
+- Funnels with `sequence`, `conversionRate`, `timeToConvert`, `weight`,
+  `isFirstFunnel`, `attempts`
+- Event flags: `isAuthEvent`, `isAttributionEvent`, `isFirstEvent`,
+  `isStrictEvent`, `isChurnEvent`, `isSessionStartEvent`
+- Top-level: `datasetStart`, `datasetEnd`, `numUsers`, `avgEventsPerUserPerDay`,
+  `seed`, `format`, device flags, `avgDevicePerUser`, `hasLocation`,
+  `hasCampaigns`, `hasSessionIds`, `hasAvatar`, `macro`, `soup`
+- Surviving advanced entities: `personas`, `worldEvents`, `engagementDecay`,
+  `dataQuality` — use sparingly
+
+Out of scope (hand off to `write-hooks`):
+- The `hook` function (default to no hook OR a tiny stub that stamps superProps
+  on injected events)
+- Engineered patterns (magic numbers, A/B effects, time-bomb regressions, etc.)
+
+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`.
+
+## Reference reading
+
+Before writing any code, scan:
+
+- `types.d.ts` — the complete API reference. Every Dungeon field, EventConfig
+  flag, Funnel option, AttemptsConfig, and Hook meta interface is documented
+  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.js` — consumer-app reference (gitignored)
+- `dungeons/technical/identity-model-verify.js` — minimal identity-model fixture
+
+## File structure
+
+```javascript
+// ── TWEAK THESE ──
+const SEED = "dm4-VERTICAL";
+const num_days = 120;
+const num_users = 5_000;
+const avg_events_per_user_per_day = 1.2;
+let token = "your-mixpanel-token";
+if (process.env.MP_TOKEN) token = process.env.MP_TOKEN;
+
+import dayjs from "dayjs";
+import "dotenv/config";
+import * as u from "../../lib/utils/utils.js";
+import * as v from "ak-tools";
+
+const chance = u.initChance(SEED);
+
+/** @typedef  {import("../../types").Dungeon} Config */
+
+// Generate consistent IDs at module level
+const productIds = v.range(1, 200).map(n => `prod_${v.uid(8)}`);
+
+/**
+ * ═══════════════════════════════════════════════════════════════
+ * DATASET OVERVIEW
+ * ═══════════════════════════════════════════════════════════════
+ *
+ * App Name — what it models, the core user loop, monetization.
+ * - N users over M days, ~X events
+ * - Key entities and relationships
+ * - Why these events/properties were chosen
+ *
+ * NO STORY TRENDS YET — schema only. Pass to /write-hooks for engineering.
+ */
+
+/** @type {Config} */
+const config = {
+  token, seed: SEED,
+  numDays: num_days,
+  avgEventsPerUserPerDay: avg_events_per_user_per_day,
+  numUsers: num_users,
+
+  // Identity model — see "Identity guidelines" below
+  hasAnonIds: true,
+  avgDevicePerUser: 2,
+  hasSessionIds: true,
+
+  // I/O
+  format: "json", gzip: true, writeToDisk: false, concurrency: 1,
+
+  // Realistic platform
+  hasLocation: true, hasAndroidDevices: false, hasIOSDevices: false,
+  hasDesktopDevices: true, hasBrowser: true, hasAvatar: true,
+
+  funnels: [ /* see "Funnels" below */ ],
+  events: [ /* see "Events" below */ ],
+  superProps: { /* see "SuperProps" below */ },
+  userProps: { /* see "UserProps" below */ },
+  scdProps: { /* see "SCDs" below */ },
+  groupKeys: [ /* see "Groups" below */ ],
+
+  // No hook — schema only.
+};
+
+export default config;
+```
+
+## Required components
+
+### 1. Events (~15–20)
+
+15–20 distinct event types covering the app's core loop. Each event:
+
+- `event` — name in **lowercase with spaces** (Mixpanel convention)
+- `weight` — relative frequency 1–10 (clamped)
+- `properties` — flat property map. Values can be arrays (random pick) or
+  utility calls like `u.weighNumRange(1, 100, 0.5, 20)`
+
+**Event flags** (see `types.d.ts` `EventConfig`):
+
+- `isFirstEvent: true` — the user's first-ever event (e.g., "sign up")
+- `isAuthEvent: true` — marks the identity stitch moment. See "Identity
+  guidelines" below. Multiple events may carry it; the engine looks at the
+  first occurrence in the user's stream when stamping inside an `isFirstFunnel`.
+- `isAttributionEvent: true` — when `hasCampaigns: true`, only flagged events
+  get UTMs (~25% of them). Without flags, ~25% of all events get UTMs (legacy).
+- `isStrictEvent: true` — exclude from auto-generated catch-all funnels. Use
+  for funnel-only events (Sign Up, Onboarding Question) so they don't bleed
+  into the standalone weighted picker.
+- `isChurnEvent: true` + `returnLikelihood` — fire-and-stop semantics
+- `isSessionStartEvent: true` — auto-prepended 15s before each funnel sequence
+
+When using experiments, include `$experiment_started` in the events array with
+`isStrictEvent: true` so the engine schema includes its properties:
+```js
+{ event: "$experiment_started", weight: 1, isStrictEvent: true, properties: {
+    "Experiment name": ["My Experiment"],
+    "Variant name": ["Control", "Variant A", "Variant B"],
+}}
+```
+
+### 2. Funnels (3–6)
+
+- First funnel: includes `isFirstEvent` AND has `isAuthEvent: true` on the
+  identity-transition step.
+- Usage funnels: ordinary sequences without `isFirstFunnel`. Optionally use
+  `attempts` for repeat-usage modeling (abandon-cart pattern).
+- Pick `conversionRate` between 30 and 80; `timeToConvert` in hours.
+
+Funnel `props` stamp constant properties on all events in that funnel run.
+Use for funnel-level context (checkout flow variant, onboarding version):
+
+```js
+{
+  sequence: ["View Item", "Add to Cart", "Checkout"],
+  conversionRate: 40,
+  timeToConvert: 2,
+  conversionWindowDays: 7,             // cap how late "Checkout" can fire
+  props: {
+    checkout_version: ["v1", "v2"],      // random per funnel run
+    payment_method: ["card", "paypal"],
+  },
+}
+```
+
+**`conversionWindowDays`:** explicit Mixpanel-style conversion window
+cap, in days. Default 30 (Mixpanel UI default). Hard cap 180 (Mixpanel max).
+The validator auto-bumps to `min(180, ceil(timeToConvert/24 * 1.5))` if your
+`timeToConvert` exceeds 30 days. Set explicitly to silence the warning. The
+verifier (`verifyDungeon`) reads this field automatically.
+
+**`isStrictEvent` auto-promote:** if you list a funnel-step event in
+`events[]`, the validator auto-sets `isStrictEvent: true` for you and warns.
+This heals the silent-corruption footgun where the greedy funnel engine
+consumed standalone instances as funnel matches. Set `isStrictEvent: false`
+explicitly only when you intend mixed funnel/standalone semantics for that
+event.
+
+**Mark hook-readable funnel-step events with `isStrictEvent: false`.** When a hook reads `event === 'X'` and `X` is also a funnel step, the validator's auto-promote turns it into `isStrictEvent: true` and the engine stops emitting standalone occurrences — cohort goes empty. Identify these candidates at schema time so `write-hooks` doesn't have to re-thread the schema. Common candidates: login, page view, search, add to cart, swap, deposit — anything that's both a funnel step AND a recurring user behavior hooks will likely cohort on.
+
+**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.
+
+### 3. SuperProps (2–3)
+
+Properties present on EVERY event. Common picks: `Plan`, `Region`, `Platform`,
+`App Version`. Values must come from same enumerations used in `userProps` for
+consistency.
+
+### 4. UserProps (4–8)
+
+User profile properties. Set once per user. Use enumerations whose values
+match `superProps` for any overlapping keys (so per-event Region matches per-user
+Region).
+
+### 5. Groups (0–2)
+
+Use `groupKeys: [["company_id", 250]]` for B2B SaaS. Add `groupProps` for
+group attributes. Skip for B2C apps.
+
+### 6. SCDs (0–2)
+
+Slowly-changing dimensions for plan tier, role, etc. JSDoc on `SCDProp` covers
+type/frequency/timing/values/max.
+
+### 7. Hook function — DO NOT WRITE
+
+Skip the `hook:` field entirely (engine defaults to pass-through). The
+`write-hooks` skill picks this up and engineers the trends.
+
+If you absolutely need a stub for downstream stamping consistency, leave a
+1-liner that returns the record unchanged.
+
+## Identity guidelines
+
+The identity model has three knobs:
+
+### `avgDevicePerUser` (whole number, default 0)
+
+| App type | Recommended | Why |
+|----------|-------------|-----|
+| B2C consumer app, web/mobile single device | 1 | Sticky single device; ratio of user_id to device_id is 1:1 |
+| B2B SaaS engineer / knowledge worker | 2 | Laptop + work-from-home laptop; per-session sticky pick |
+| Multi-device-heavy product (streaming, fitness) | 2–3 | TV + phone + tablet sessions distinguishable |
+| Server / API-only product | 0 | No client device concept |
+
+`hasAnonIds: true` aliases to `avgDevicePerUser: 1`. Set both for clarity.
+
+### `isAuthEvent` placement
+
+Flag the event that represents "user becomes identified". Put it in the
+`isFirstFunnel` sequence. Common picks:
+
+- Consumer apps: `Sign Up`, `Login`
+- B2B SaaS: `workspace created`, `account created`
+- Marketplaces: `Account Activated`
+
+The engine stamps user_id+device_id on this event; pre-auth funnel steps get
+device_id only; post-auth funnel steps get user_id only.
+
+### `attempts` (per-funnel, optional)
+
+```js
+{
+  sequence: ["Land", "Onboarding Question", "Sign Up"],
+  isFirstFunnel: true,
+  conversionRate: 70,
+  attempts: { min: 0, max: 2 },         // 0–2 failed priors → 1–3 total passes
+}
+```
+
+Typical ranges:
+
+- Direct-acquisition first funnels: `{ min: 0, max: 0 }` (single attempt) or omit
+- Shared-link / friction-heavy onboarding: `{ min: 0, max: 2 }` (some retry)
+- Re-engagement / abandon-cart usage funnels: `{ min: 0, max: 3 }`
+
+When set, `attempts.conversionRate` (optional) overrides `funnel.conversionRate`
+on the FINAL attempt. Failed prior attempts truncate before the first
+`isAuthEvent` step (no stitch fires for those attempts).
+
+### Experiments (per-funnel, optional)
+
+Funnels can run A/B/C experiments with `experiment: true` (3 default variants) or
+a rich `ExperimentConfig`:
+
+```js
+{
+  sequence: ["Create Agenda", "Agenda Generated"],
+  conversionRate: 60,
+  timeToConvert: 0.5,
+  name: "Collaborative Agenda",
+  experiment: {
+    name: "Collaborative Agenda",
+    variants: [
+      { name: "Control (No Collab)" },
+      { name: "Variant A (Ask User)", conversionMultiplier: 1.15, ttcMultiplier: 0.9 },
+      { name: "Variant B (Assume + Confirm)", conversionMultiplier: 1.35, ttcMultiplier: 0.7 },
+    ],
+    startDaysBeforeEnd: 30,
+  },
+}
+```
+
+Key fields (see `ExperimentConfig` in `types.d.ts`):
+- `variants[]` — custom names, conversion/TTC multipliers, distribution weights
+- `startDaysBeforeEnd` — temporal gating (experiment activates N days before dataset end)
+- Variant assignment is **deterministic per user** (hash-based, not random per run)
+- Engine injects `$experiment_started` with "Experiment name" and "Variant name" properties
+- Add `$experiment_started` to the events array with `isStrictEvent: true` so the schema includes it
+
+Variant-specific downstream effects (e.g., "Variant B boosts downstream event X") go in the `write-hooks` skill via `funnel-post` hooks that check `meta.experiment.variantName`.
+
+### World Events (optional)
+
+Shared temporal events affecting all users. Good for modeling outages, campaigns,
+or launches that create visible inflection points:
+
+```js
+worldEvents: [
+  {
+    name: "Black Friday Sale",
+    startDay: 55,
+    duration: 3,
+    affectsEvents: ["Purchase", "Add to Cart"],
+    volumeMultiplier: 2.5,
+    conversionModifier: 1.3,
+    injectProps: { promo_active: true },
+  },
+  {
+    name: "API Outage",
+    startDay: 30,
+    duration: 1,
+    affectsEvents: "*",
+    volumeMultiplier: 0.3,
+  },
+]
+```
+
+World events stamp `injectProps` on matching events and modulate volume via
+accept/reject sampling. `conversionModifier` affects funnel conversion rates.
+See `types.d.ts` `ResolvedWorldEvent` for the full interface.
+
+## Trend shape — `macro` and `soup`
+
+Default to NOT setting either. Defaults: `macro: "flat"` (preset born=12,
+bias=0, uniform pre-existing spread) + `soup: "growth"` (standard intra-week /
+intra-day rhythm). Only override when you have a specific reason:
+
+- Use `macro: "growth"` if you want a mild acquisition trend (visible births
+  over the window, 30% born-in-dataset).
+- Use `macro: "viral"` only if the app has a hockey-stick acquisition story.
+  Pair with `personas` so the late entrants behave differently.
+- Use `macro: "decline"` for sunsetting products. Pair with `engagementDecay`
+  or a churn cohort to get a real downtrend (the macro alone produces a flat
+  shape — see `lib/templates/macro-presets.js` decline JSDoc).
+- Use `soup: "spiky"` for products with dramatic peaks / valleys (gaming
+  weekends, financial market hours).
+- Use `soup: "global"` to flatten all DOW/HOD weights (24/7 server-side products).
+
+### Macro × born% / bias compatibility (strict clamps)
+
+When you set `macro` AND `percentUsersBornInDataset` explicitly, the validator
+clamps born% to the macro's preset value: flat=12, steady=12, growth=30,
+viral=55, decline=5. Same for `bornRecentBias` outside `[-0.5, 0.5]`. If you
+need higher born% (e.g., "this app launched mid-window — every user is in the
+dataset"), switch macros first (flat → growth → viral) instead of pushing the
+preset's value. Setting born% without a macro keeps legacy behavior (no clamp).
+
+The clamp warning explains why and points to safe alternatives — read it.
+
+⚠️ **Don't set `percentUsersBornInDataset > 60`** with macro=flat / steady /
+decline. Cumulative-acquisition right-edge explosion is the inevitable result
+on a no-hook dungeon. The strict clamps will rescue the run, but the chart
+won't look like what you asked for.
+
+See [CLAUDE.md "Engine guarantees"](../../../CLAUDE.md#engine-guarantees) for the full safe-range table.
+
+### `avgActiveDaysPerUser` (concentrator)
+
+Top-level optional knob. Sets the mean number of distinct UTC days each user
+fires events on. Total event count is preserved (still `rate × numDays`),
+but events cluster onto fewer days. Per-user count drawn from
+`normal(mean=N, sd=N/3)`, clamped to `[1, userActiveDays]`.
+
+Default: undefined (legacy — events spread across the whole window via TimeSoup).
+
+**Concentrator semantic — per-active-day rate inflates.** Example:
+
+```
+avgEventsPerUserPerDay: 4
+avgActiveDaysPerUser: 2
+numDays: 30
+→ 120 events per user, concentrated onto 2 days = 60 events/active day
+```
+
+The validator warns when the implied per-active-day rate > 50. To reduce
+total events, lower `avgEventsPerUserPerDay`, NOT this knob.
+
+**Incompatibility with `engagementDecay`:** these two erosive primitives
+combine destructively — decay drops events from late picked days, eroding
+the effective active-day count below the configured target. Use one or the
+other in a dungeon. If you need both, set `avgActiveDaysPerUser` and write
+the decay as an `everything` hook scoped to specific cohorts (the `write-hooks`
+skill handles this).
+
+### `maxTouchpointsPerUser` (attribution cap)
+
+Top-level optional knob. Caps UTM stamping at this many events per user
+(default 10, matching Mixpanel `TOUCHPOINTS_LIMIT`). When `hasCampaigns: true`
+and a user has more eligible events than the cap, the engine takes a
+uniform-random sample across the user's lifetime and stamps UTMs on the
+sampled events only. Sampling across lifetime (NOT first-N) preserves
+realistic touch shape — Mixpanel's last-10-window then gives meaningful
+first/last-touch attribution. Set to `Infinity` to disable the cap.
+
+## SuperProp consistency rule
+
+If `superProps` and `userProps` both define a property like `Plan`, the
+enumeration must match exactly. Otherwise users with `userProps.Plan = 'pro'`
+will fire events with `superProps.Plan = 'free'` — Mixpanel will see broken
+breakdowns.
+
+```js
+const PLANS = ["Free", "Free", "Free", "Pro", "Pro", "Enterprise"];
+// ...
+superProps: { Plan: PLANS, Region: REGIONS },
+userProps:  { Plan: PLANS, Region: REGIONS, Role: ROLES, ... },
+```
+
+## Verification
+
+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`.
+
+## Property Type Reference
+
+Use the correct helper for each Mixpanel property data type. All helpers are imported from `@ak--47/dungeon-master/utils` (already available as `u` in dungeon files).
+
+| Mixpanel Type | Helper | Example |
+|---|---|---|
+| **String** | Array of options | `["Basic", "Pro", "Enterprise"]` |
+| **Numeric** | `weighNumRange()` or array | `u.weighNumRange(1, 100)` or `[10, 20, 50, 100]` |
+| **Boolean** | Boolean array | `[true, false, false]` (weighted 33/67) |
+| **Date** | `dateRange()` | `dateRange()` (dataset window) or `dateRange('2023-01-01', '2024-01-01')` |
+| **List** | `listOf()` | `listOf(["tag1", "tag2", "tag3"], {min: 1, max: 3})` |
+| **Object** | Plain object | `{tier: "premium", seats: 5}` |
+| **List of Objects** | `objectList()` | `objectList({sku: u.weighNumRange(1000,9999), qty: [1,2,3]}, {min:1, max:4})` |
+
+When designing event properties, always consider which Mixpanel type best represents the data:
+- Tags, genres, interests → `listOf()`
+- Cart items, line items, participants → `objectList()`
+- Subscription start, trial end, next billing → `dateRange()`
+- Status, tier, category → string array
+
+## 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).
+
+When done, tell the user the next skill to run.