ultimate-dominion · mokn · Apr 3, 2026 · Apr 3, 2026 · Apr 4, 2026 · Apr 4, 2026
diff --git a/.claude/commands/handoff.md b/.claude/commands/handoff.md
@@ -0,0 +1,12 @@
+Delegate to the `handoff` agent to execute the full handoff protocol. Pass it all context about what was accomplished this session, what's in progress, and any blockers.
+
+The handoff agent will:
+1. Gather git state (status, diff, recent log)
+2. Write HANDOFF_[task-slug].md to repo root
+3. Archive to ~/Documents/ultimate-dominion/docs/handoffs/YYYY-MM-DD_[task-slug].md
+4. Update SESSION.md (remove completed tasks, keep active ones)
+5. Update today's Obsidian daily note via MCP
+6. Delete the handoff file from repo root
+7. Output the summary
+
+After it completes, tell Michael to `/clear`.
diff --git a/.claude/commands/kaplan.md b/.claude/commands/kaplan.md
@@ -0,0 +1,25 @@
+Put on your Jeff Kaplan hat for game design work.
+
+Before responding, read these two docs:
+1. `~/Documents/ultimate-dominion/docs/JEFF_KAPLAN_DESIGN_PHILOSOPHY.md` — Kaplan's career-spanning design principles, GDC talks, quotes, and lessons learned
+2. `docs/DESIGN_PHILOSOPHY.md` — UD's design philosophy (built on Kaplan's principles + our own identity)
+
+Then apply that lens to whatever Michael is asking about. Think like a principal game designer who:
+
+- Led WoW quest/zone/raid design for 5 years
+- Built Overwatch from the ashes of a failed project
+- Believes in "concentrated coolness" over diluted content
+- Insists on clarity of action (mystery in the world, never in what to do)
+- Demands systems that create player stories, not scripted narratives
+- Ships and iterates rather than polishing forever
+- Respects player time above all else
+- Knows that perception > reality for balance
+- Celebrates moments — every milestone needs weight
+- Hates exposition dumps, fetch quests, and gimmick systems
+
+When designing features, quests, zones, or systems, always run through:
+1. Does it pass the filter? (permanent, player-driven, worth it in a year)
+2. Where's the moment? (concentrated coolness)
+3. Does it create stories? (emergent > scripted)
+4. Is the fun path the efficient path? (don't let them optimize the fun out)
+5. Can a player explain why this is cool in one sentence?
diff --git a/.claude/rules/api.md b/.claude/rules/api.md
@@ -0,0 +1,16 @@
+---
+paths:
+  - packages/api/**
+  - packages/relayer/**
+---
+
+# API & Relayer Rules
+
+## Security
+- All endpoints must have rate limiting, CORS restrictions, and input validation.
+- Never leak secrets or stack traces in responses.
+- Never hardcode private keys or secrets. Always use environment variables.
+
+## Dependencies
+- Pin versions. Run `pnpm audit` before adding new packages.
+- Prefer well-maintained packages with small surface area.
diff --git a/.claude/rules/client.md b/.claude/rules/client.md
@@ -0,0 +1,36 @@
+---
+paths:
+  - packages/client/**/*.ts
+  - packages/client/**/*.tsx
+  - packages/client/**/*.css
+---
+
+# Client / Frontend Rules
+
+## Performance
+- This is a browser game — speed is a feature. Every interaction should feel instant.
+- Never add blocking operations to the UI thread. All chain reads/writes must be async with loading states.
+- Be mindful of bundle size. Lazy-load routes. Don't add heavy dependencies without justification.
+- Test that any UI change remains responsive on mobile browsers.
+
+## Usability & Crypto Abstraction
+- All UI must work without crypto knowledge. Follow `docs/architecture/frontend_guidelines.md`.
+- Never expose wallet addresses, transaction hashes, gas fees, or chain IDs to the player.
+- Every action needs clear feedback: loading states, success confirmations, error messages with recovery steps.
+- Mobile-first — if it doesn't work on a phone browser, it doesn't ship.
+
+## Security
+- No `dangerouslySetInnerHTML`, no `eval`, no user-controlled URLs without validation.
+- Validate `chainId` against `supportedChains`.
+
+## Player-Facing Copy
+Any text that appears in the game — item descriptions, system messages, patch notes, NPC dialogue, UI labels — must sound like a specific person wrote it. No generic AI language. If a player can tell AI wrote it, it failed.
+
+## SEO (Public Pages Only)
+When adding a new page:
+1. Import `{ Helmet } from 'react-helmet-async'`
+2. Add `<Helmet><title>Page Name | Ultimate Dominion</title></Helmet>`
+3. If public (no auth): add to `sitemap.xml`
+4. If authenticated/private: add to `Disallow` in `robots.txt`
+
+Canonical domain: `https://ultimatedominion.com`. No SEO needed for beta.
diff --git a/.claude/rules/deploy.md b/.claude/rules/deploy.md
@@ -0,0 +1,170 @@
+---
+paths:
+  - packages/contracts/script/**
+  - packages/contracts/.env*
+  - packages/contracts/mud.config.*
+  - packages/contracts/worlds.json
+  - packages/indexer/**
+  - "**/deploy*"
+  - "**/PostDeploy*"
+  - "**/EnsureAccess*"
+  - "**/zone-loader*"
+---
+
+# Deploy & Environment Rules
+
+## Environment Separation (CRITICAL — incident 2026-03-30)
+- `beta.ultimatedominion.com` = Base Mainnet (beta world address)
+- `ultimatedominion.com` = Base Mainnet (production world address)
+- Both on chain 8453, distinguished ONLY by WORLD_ADDRESS.
+- **`.env` MUST default to beta.** Production requires explicit `.env.mainnet`.
+- **Bare commands are blocked.** `zone:load`, `item:sync`, `item:verify` require `:testnet` or `:mainnet` suffix.
+- NEVER add the production world address to `.env`. If you see it there, fix it immediately.
+
+## Script Execution Safety (CRITICAL — incident 2026-03-30)
+- **NEVER** run `source .env.testnet && npx tsx ...` — `source` does NOT export vars to subprocesses.
+- **ALWAYS** use pnpm scripts (`pnpm zone:load:testnet`) or `bash -c 'set -a && source .env.testnet && set +a && npx tsx ...'`
+- **ALWAYS** verify the world address in the first lines of script output before continuing.
+- Production world: `0x99d01939F58B965E6E84a1D167E710Abdf5764b0` — all TS scripts now require `--confirm-production` flag.
+- Beta world: `0xDc34AC3b06fa0ed899696A72B7706369864E5678`
+
+## Branch Convention
+| Branch | Target | Confirm? |
+|---|---|---|
+| `dev` | Beta | No |
+| `main` | Production | **Always** |
+| Feature branch | Ask user | Yes |
+
+## MUD Deploy Safety
+- **Always use `--worldAddress`** when deploying to existing chains. Without it, compiler changes can trigger a fresh world deploy.
+- `mud deploy` with nonce errors can silently skip transactions — verify function selectors after every deploy.
+- System upgrades create NEW contract addresses — re-run `EnsureAccess.s.sol` after every deploy.
+- Always run PostDeploy seed/config scripts after a fresh deploy.
+- Backup world state before mainnet upgrades.
+
+## PostDeploy Is All-or-Nothing
+PostDeploy.s.sol runs as a single transaction. If ANY line reverts, ALL access grants are lost. This is why `deploy:testnet` and `deploy:mainnet` auto-chain `ensure-access` after `mud deploy`.
+
+When adding a new system that writes cross-namespace: update `EnsureAccess.s.sol` `ensureAll()`.
+
+## worlds.json blockNumber
+- Must be the ACTUAL world deployment block. If set too high, new clients miss seed data.
+- Use binary search on `cast code` to find the exact deployment block.
+
+## RPC for Deploys
+- Base mainnet: use `base-rpc.publicnode.com` (supports 16K+ block ranges).
+- dRPC free tier limits to 10K blocks — `mud deploy` will fail once gap exceeds 10K.
+
+## Verification
+- Run `pnpm build` in packages/client before pushing.
+- Verify function selectors after any `mud deploy`.
+- Never deploy to mainnet without testnet verification first.
+
+## Pre-Deploy Required Reading
+**BEFORE any `mud deploy` or `pnpm deploy:*`**, read these files for known failure patterns:
+1. `~/.claude/projects/-Users-michaelorourke-ultimate-dominion/memory/game/mud-gotchas.md` — table name collisions, schema immutability, access control traps, bytecode issues
+2. `~/.claude/projects/-Users-michaelorourke-ultimate-dominion/memory/infra/deploy-guide.md` → "Known Failure Patterns" table — EnsureAccess cache, CreateCollision, etc.
+
+## Railway Service Deployment (CRITICAL — know your target)
+
+Railway has SEPARATE beta and prod services. The naming is misleading.
+
+| Service | Railway name | Service ID | Domain (current) |
+|---|---|---|---|
+| **Indexer (prod)** | `indexer` | `61172447-73de-410a-943e-49ed3cc20d10` | `indexer-production-d6df.up.railway.app` |
+| **Indexer (beta)** | `indexer-beta-us` | `390336a9-3856-4ace-9949-f28fa1c4aa3d` | `indexer-beta-us-production.up.railway.app` |
+| **Indexer (legacy)** | `indexer-beta` | `de09dafa-a4c1-4ad8-8873-67a7ae885b90` | `indexer-prod-production-45cf.up.railway.app` (NOT used by beta client) |
+| **Relayer (prod)** | `relayer` | `dd62995a-cab5-4a98-b217-0c7bf111364e` | `8453.relay.ultimatedominion.com` |
+| **Relayer (beta)** | `relayer-beta` | `c7a2c1e4-4bb8-4ce3-aa54-9a38b1a3d067` | `relayer-beta-us-production.up.railway.app` |
+
+### How `railway up` actually works (read this before debugging a failed deploy — confirmed 2026-04-13)
+
+- `railway up` uploads the files from the **main checkout working tree**, not the current worktree you run it from. Verified empirically: running from `.claude/worktrees/movement-monster-display` (pkg version 0.3.1) produced a build that logged `@ud/[email protected]` — the version sitting on disk in the main checkout. The worktree's files were completely ignored by the upload.
+- Practical consequence: **to deploy a commit that's on a feature branch, the main checkout must have that commit's files on disk.** Either merge to the main checkout's current branch, or check out the target branch/SHA in the main checkout before running `railway up` (detached HEAD is fine if another worktree holds the branch).
+- Railway builds using the service's configured **root directory** and Dockerfile. For `indexer-beta-us` / `indexer`, the service has `rootDirectory = packages/indexer` and uses `packages/indexer/Dockerfile`. **Do not pass `--path-as-root`** — it bypasses the service config and makes Railway fall back to RAILPACK, which fails.
+- The upload context size limit is ~100 MB. Anything close to that will 413. The relevant ignore list is the main checkout's `.railwayignore` + `.gitignore`.
+
+### Pre-deploy sequence (exact steps — follow in order)
+
+```bash
+# 1. Make sure the commit you want is reachable on origin/dev (or wherever)
+cd ~/ultimate-dominion/.claude/worktrees/<your-worktree>
+git push origin <branch>              # get the fix onto the remote
+
+# 2. Switch to the main checkout
+cd ~/ultimate-dominion
+git fetch origin
+
+# 3. Stash any uncommitted work (leave untracked files alone)
+git stash push -m "pre-deploy $(date +%F)" -- <modified-tracked-files>
+
+# 4. Check out the target SHA. If dev is locked by another worktree,
+#    use a detached HEAD at the remote SHA.
+git checkout <sha-or-branch>           # or: git checkout origin/dev
+
+# 5. Preflight
+bash scripts/railway-preflight.sh      # must print < 50 MB and exit 0
+railway status                         # must show the expected service
+
+# 6. Deploy
+railway up --detach
+
+# 7. Verify (see "Verify after deploy" below). If the build log shows
+#    the wrong @ud/indexer version, the upload came from a stale main
+#    checkout — fix that before anything else.
+
+# 8. Restore main checkout
+git checkout <original-branch>
+git stash pop
+```
+
+### Deploy commands (the only commands you should run)
+- Beta: `railway service indexer-beta-us && railway up --detach`  (service ID: `390336a9`)
+- Prod: `railway service indexer && railway up --detach`  (**MUST ASK MICHAEL FIRST**)
+
+### Required rules
+- NEVER use `railway redeploy` — it reuses cached images and doesn't pull fresh code.
+- ALWAYS bump `packages/indexer/package.json` version before deploying (Docker cache busting). Note: `health.ts` hardcodes a separate version string that does NOT auto-update; don't use the `/api/health` `version` field as proof of fresh code. Verify via the Railway **build logs** instead (they print `> @ud/[email protected] build`).
+- ALWAYS run `scripts/railway-preflight.sh` before `railway up` to catch `.railwayignore` rot.
+- ALWAYS verify with `railway status` that the linked service is correct before `railway up`.
+- ALWAYS verify with the Railway GraphQL **build logs** (not the live `/api/health`) that the right version was built.
+
+### If a deploy fails: the debugging order
+1. **413 / "Payload Too Large"** → run `scripts/railway-preflight.sh` from the **main checkout**. Find the bloat, add it to `.railwayignore`. Do not try `--path-as-root`, `/tmp/` sub-packages, or any upload-root workaround — those trigger RAILPACK fallback.
+2. **Railway used `RAILPACK` instead of the Dockerfile** → you passed `--path-as-root` or pointed at `packages/indexer` as the upload root. Go back to running `railway up --detach` from the repo root of the main checkout.
+3. **Build log shows the wrong version / old code** → the main checkout's working tree is on the wrong branch/SHA. `railway up` uploads files from the main checkout, not from your worktree. Checkout the target SHA in the main checkout (detached HEAD is fine) and redeploy.
+4. **Build failed inside the Dockerfile** → read the build logs, do not bump versions blindly.
+5. **Deployment succeeds but clients don't see changes** → wrong domain. `indexer-beta-us-production.up.railway.app` is the beta client's URL; other indexer services exist but are not wired up. See the service table above.
+
+**Verify after deploy:**
+```bash
+# Check build status
+RAILWAY_TOKEN=$(python3 -c "import json; print(json.load(open('$HOME/.railway/config.json'))['user']['token'])")
+# Beta:
+curl -s -H "Authorization: Bearer $RAILWAY_TOKEN" -H "Content-Type: application/json" \
+  -d '{"query":"query { deployments(input: { serviceId: \"390336a9-3856-4ace-9949-f28fa1c4aa3d\" }) { edges { node { id status createdAt } } } }"}' \
+  https://backboard.railway.com/graphql/v2 | python3 -c "import sys,json; [print(f'{e[\"node\"][\"id\"][:8]} {e[\"node\"][\"status\"]}') for e in json.load(sys.stdin)['data']['deployments']['edges'][:3]]"
+# Verify code is live:
+curl -s https://indexer-beta-us-production.up.railway.app/api/health
+# Prod: swap service ID to 61172447-73de-410a-943e-49ed3cc20d10
+```
+
+## Smart Contract Upgrade Checklist (ALWAYS follow)
+
+Full playbook with failure patterns: `~/.claude/projects/-Users-michaelorourke-ultimate-dominion/memory/infra/deploy-guide.md` → "Complete Upgrade Deploy Playbook"
+
+**Before deploy:**
+1. Commit all changes — NEVER deploy from dirty tree
+2. Run `verify-onchain.ts` — sim vs on-chain must be 0 mismatches
+3. Check no players in active combat (schema changes break mid-fight encoding)
+4. If schema changed: expect ALL systems to redeploy (new addresses, grants refresh)
+5. If new cross-namespace access needed: update EnsureAccess.s.sol FIRST
+6. If effect types changed (e.g. MagicDamage→StatusEffect): deploy when no one is using that effect
+
+**After deploy:**
+7. `pnpm deploy:mainnet` auto-chains EnsureAccess — verify it ran
+8. Run any data scripts (DeployClassSpellsV2, item-sync, effect-sync, etc.)
+9. Test incrementally: basic combat → spells → shop → marketplace
+10. Check indexer health — reindex if schema changed
+11. Monitor relayer logs for `Access_Denied` errors for 5 min
+12. Commit deploy artifacts
diff --git a/.claude/rules/game.md b/.claude/rules/game.md
@@ -0,0 +1,41 @@
+---
+paths:
+  - packages/contracts/src/systems/**
+  - packages/contracts/zones/**
+  - packages/contracts/test/**
+  - "**/items.json"
+  - "**/effects.json"
+  - "**/monsters.json"
+  - "**/balance*"
+  - "**/combat*"
+  - "**/sim*"
+---
+
+# Game Systems Rules
+
+@./docs/combat-stats/BALANCE_GOALS.md
+@./docs/combat-stats/BALANCE_STATE.md
+
+## Memory Pointers (read on demand, not all at once)
+When working on game systems, check these memory files for relevant context:
+- `game/game-balance.md` — Item IDs, combat triangle, monster roster, drop rates, class spells
+- `game/launch-values.md` — Production constants (XP, gold, combat)
+- `game/economic-design.md` — Hearthstone model, F2P vs marketplace drivers
+- `game/design_principles_kaplan.md` — **READ BEFORE BALANCE WORK**
+- `game/gotcha_*.md` — Grep when touching a specific system
+
+## ID Lookups
+- Basilisk boss: mob ID `12`
+- Item IDs: see `items.json` (single source of truth)
+- Effect IDs: see `effects.json` (single source of truth)
+- Drop rates: ONLY changeable via items.json → item-sync flow
+
+## Balance Changes
+- items.json is the SINGLE SOURCE OF TRUTH. Never bypass with cast/scripts.
+- Flow: edit JSON → commit → `item-sync dark_cave --update` → verify (0 mismatches) → stop if verify fails.
+- After any `mud deploy`: run item-sync + effect-sync to verify, tag the deploy, run drop-sim.
+- Don't over-optimize balance. Set floors and ceilings, not parity. The game is infinite at L20.
+
+## Testing
+- Tests run against forked beta world, never local anvil.
+- Every code change MUST have tests — happy paths, unhappy paths, edge cases.
diff --git a/.claude/rules/indexer.md b/.claude/rules/indexer.md
@@ -0,0 +1,35 @@
+---
+paths:
+  - packages/indexer/**
+---
+
+# Indexer Rules
+
+## Memory Pointers (read on demand)
+- `infra/tools.md` — Railway service IDs, URLs, CLI commands, SSH targets
+- `infra/deploy-guide.md` — Deploy commands, failure patterns
+- `infra/recovery-runbook.md` — Service failure diagnosis
+- `infra/gotcha_*.md` — Grep when touching indexer infra
+
+## Architecture
+Custom MUD indexer (replaces RECS). Syncs Store events → PostgreSQL, REST API + WebSocket.
+- Database: PostgreSQL via `postgres` library, off-chain tables in `queue.` schema
+- WS protocol: typed discriminated unions in `ws/protocol.ts`
+- Game events: `queue/eventFeed.ts` scans MUD tables every 10s
+- Chat: `ws/chatHandler.ts` — rate limiting, shadow mute, guild auth
+
+## Railway Deploy (CRITICAL)
+- Beta: `railway service indexer-beta-us && railway up --detach` (service ID: `390336a9`)
+- Prod: `railway service indexer && railway up --detach` (**ASK MICHAEL FIRST**, service ID: `61172447`)
+- NEVER use `railway redeploy` — reuses cached images
+- ALWAYS bump `packages/indexer/package.json` version before deploying
+- ALWAYS run from repo root, not from `packages/indexer/`
+- ALWAYS verify `railway status` shows the correct service before deploying
+- `railway up` from worktrees uploads main checkout files — deploy from main checkout only
+- Full service ID table in `.claude/rules/deploy.md`
+
+## Patterns
+- Table init: `async function initXxxTables()` with `CREATE TABLE IF NOT EXISTS` in `queue.` schema
+- Broadcast: `broadcaster.broadcastToAll(msg)` or `broadcastToChannel(channel, msg)`
+- Dedup: `ON CONFLICT ... DO NOTHING`
+- WS message handling: `switch (msg.type)` in broadcaster's `addClient()`