From d8297cf3bfa36eec8f1e738e645c3616979258cd Mon Sep 17 00:00:00 2001
From: 0xward <0xward.dev@gmail.com>
Date: Mon, 3 Aug 2026 08:53:17 +0000
Subject: [PATCH 1/2] A new contributor could not have known the engine cannot
 import from lib/
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Every convention in this repo that matters is written down somewhere, and no two
of them are in the same place. The engine boundary is explained in the header of
lib/constants/game-config.ts. The invariants are §10 of a 67KB design doc. The
reason CI does not run lint is a comment in a workflow file. The reason wagmi
mounts as a sibling rather than a wrapper is thirty lines of Web3Providers.tsx —
and the note explaining it exists because somebody had already undone it once.

That is fine for the owner, who wrote all of it. It is not fine for an assistant
opening the repo cold, which is exactly who keeps being handed these tasks: it
reads the file it was pointed at, does not read the four other files that
explain why the file is shaped that way, and helpfully simplifies something back
into the bug it was written to fix.

CLAUDE.md collects the parts that are load-bearing and cheap to violate:

  THE BOUNDARY, first, because everything else follows from it. Fourteen plain
  <script> files under public/ that next build never touches, cannot import from
  lib/, and whose syntax errors ship. The duplicated marketplace list is a
  consequence, not an oversight, and the engine's copy wins.

  THE INVARIANTS from GAME-DESIGN.md §10 verbatim, plus the two the tooling
  already enforces but nobody would guess: one owner for the RPC endpoint and
  one for the origin, and an attribution tag that CANNOT be backfilled — an
  untagged transaction is unattributed forever, including the four the backend
  signs.

  WHAT THE CHECK SCRIPTS ARE. They are not a test suite. Each one is a bug that
  already shipped, wearing a filename. check:cssvars exists because a primary
  button rendered as near-black text on a dark modal; check:copy exists because
  "Add Cash" reached four files and a "Connect wallet" line sat permanently on
  /profile. Listing them next to what they guard is what stops the next person
  from deleting the noisy one.

  THE MINIPAY RULES that live in copy and in .npmrc, which look like style
  preferences and are listing-review rejections.

  THE COMMIT STYLE, described from the log rather than prescribed: the subject
  names the problem in the player's words, the body carries symptom, mechanism,
  fix and a Verified: line with real numbers.

Verified against the source, not the README: the env section names
FIREBASE_SERVICE_ACCOUNT, which is what firebase-config.ts actually reads — the
README says FIREBASE_SERVICE_ACCOUNT_JSON, which nothing does. Route count (44),
engine script count and load order, gitignored min/ output, and the audit's
one-place-allowed rules for celoRpc.ts and siteUrl.ts were each read off the
files. npm run audit clean; no source file changed.
---
 CLAUDE.md | 351 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 351 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..2a2efd6
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,351 @@
+# CLAUDE.md
+
+Guidance for Claude Code (and any AI assistant) working in this repository.
+
+NULL_STATE is a real-time, top-down dungeon crawler on Celo, built to run inside
+MiniPay. Playing is free; only Marketplace/Season Pass purchases settle on-chain,
+and USDT rewards are paid out from the Treasure Vault, Leaderboard and Season
+Pass. Next.js 14 App Router + React 18 + TypeScript on the outside, a vanilla
+Canvas2D engine on the inside.
+
+---
+
+## 1. The one thing to understand first: two worlds, one boundary
+
+This repo contains **two codebases that cannot import from each other.**
+
+| | The shell | The engine |
+|---|---|---|
+| Where | `app/`, `components/`, `lib/`, `hooks/` | `public/game-engine/*.js` |
+| What | Next.js App Router, React, TypeScript | 14 plain `<script>` files, vanilla JS + Canvas2D |
+| Built by | `next build` — typechecked, bundled | Nothing. Served byte-for-byte out of `public/` |
+| Entry point | `components/game/DungeonGame.tsx` | `window.NullStateGame.{mount,unmount}` |
+
+**The engine cannot `import` from `lib/`.** It is loaded by `<script>` tag, so
+there are no modules and no bundler. Values cross the boundary only through:
+
+- `window.__NS` (engine-owned state read by the shell — see `game.js`)
+- `mount(opts)` options passed in by `DungeonGame.tsx`
+- an API call to `app/api/**`
+
+Consequences you must respect:
+
+- A constant that must exist on both sides is **duplicated on purpose**, and the
+  engine's copy is authoritative for gameplay. The `lib/` copy must say so in a
+  comment. Today this applies to the marketplace catalogue
+  (`lib/constants/marketplace.ts` ↔ `public/game-engine/marketplace-items.js`),
+  guarded by `npm run check:market`.
+- A syntax error in an engine file **passes the build and ships**. CI runs
+  `node --check` over every engine file for exactly this reason.
+- Engine load order matters (`assets.js` must run before `entities.js`). The list
+  lives in `DungeonGame.tsx:34` (`ENGINE_SCRIPTS`); `lib/engineScript.ts` owns
+  which copy is served and the cache-busting `?v=<build id>`.
+- Production serves the **minified** copies from `public/game-engine/min/`
+  (gitignored build output, regenerated by `npm run build:engine`). Dev serves the
+  readable sources so stack traces point at findable lines.
+
+---
+
+## 2. Commands
+
+```bash
+npm ci            # install exactly what package-lock.json pins
+npm run dev       # dev server on http://localhost:3000
+npm run build     # minifies the engine, then next build
+npm start         # serve the production build
+npm run lint      # ESLint (NOT run during builds — see below)
+npx tsc --noEmit  # type check — this is what CI enforces
+```
+
+### Verification scripts (`scripts/`)
+
+These are not a test framework — they are single-purpose Node scripts, each
+written to catch one class of bug that had already shipped. Read the header
+comment of a script before changing it; it explains the failure it exists for.
+
+**Consistency checks (all gated in CI):**
+
+| Command | Guards |
+|---|---|
+| `npm run check:market` | the two marketplace price lists agreeing |
+| `npm run audit` | every asset/sprite/script path resolving to a real file |
+| `npm run check:copy` | MiniPay's copy rules (banned words, connect prompts, signing) |
+| `npm run check:attribution` | every Celo tx carrying its ERC-8021 tag |
+| `npm run check:cssvars` | no stylesheet using a `var(--x)` another sheet declares |
+| `npm run build:icons` / `build:weapons` | generated art matching its masters |
+
+**Behaviour tests** — `test:season`, `test:seasonxp`, `test:kills`, `test:play`,
+`test:contracts`, `test:streak`, `test:migrate`, `test:vaultwin`, and ~20 more
+(see `package.json` scripts). Some drive a real browser via `playwright-core`
+against engine files loaded directly; those taking `--serve` (`test:privy`,
+`test:season-ui`, `test:campaign-end`, `test:pass-cards`) spawn `next start`
+themselves and therefore need `npm run build` first.
+
+Chromium is preinstalled in the remote environment — never run
+`playwright install`.
+
+`npm run test:play` is the integration test: it actually plays a run (walks the
+map, fights, loots, rides the lift, burns, saves). Run it before anything that
+touches the engine goes out.
+
+### What CI runs
+
+`.github/workflows/checks.yml` on every PR: `npm ci`, the six consistency checks
+above, `node --check` over engine sources and minified output, and `npx tsc
+--noEmit`. It deliberately does **not** run `next build` (Vercel already does)
+and deliberately does **not** run `npm run lint` — the repo carries ~20 files of
+pre-existing stylistic findings, and a permanently-red check trains people to
+ignore CI. `next.config.js` sets `eslint.ignoreDuringBuilds` for the same reason.
+
+---
+
+## 3. Layout
+
+```
+app/
+  layout.tsx            root layout — NO Web3Providers here, and no preconnects
+                        (both have been tried and measured; see the comments)
+  page.tsx              landing
+  game/  profile/       routes that wrap children in Web3Providers via a nested layout
+  stats/ docs/ privacy/ terms/
+  api/                  44 route handlers, one directory per capability
+    marketplace/verify  on-chain purchase verification (the reference route)
+    cron/season         Vercel cron, daily 01:00 UTC — season close/payout
+components/
+  game/                 the shell's screens: GameFlowManager (router), WorldMapHub,
+                        DungeonGame (engine host), MarketplaceScreen, RewardsScreen,
+                        SeasonPassScreen, CraftingScreen, Leaderboard, PrivyGate…
+  ui/  landing/  common/
+lib/
+  constants/            game-config, marketplace, tokens, bunkers, seasonRewards
+  server/               server-only logic: seasonClose, loginStreak, dailyContracts,
+                        energy, vault-fragments, referrals, guestMigrate…
+  WagmiIsland.tsx       wagmi/viem, mounted as a deferred SIBLING (see §5)
+  WalletProvider.tsx    useWallet() — the identity surface
+  celoRpc.ts            the ONLY place a Celo endpoint may be named
+  siteUrl.ts            the ONLY place the canonical origin may be named
+hooks/                  usePassSBT, useReward, useVault (wagmi-backed contract hooks)
+contracts/              PassSBTv3.sol, NullStateRewardV3.sol, TreasureVaultV2.sol
+public/game-engine/     THE GAME (see §1)
+public/sprites/         LPC-derived character/monster/weapon sheets
+styles/                 globals.css (always loaded) + per-route sheets
+scripts/                verification + asset-generation scripts (see §2)
+docs/                   design and operations docs (see §8)
+__tests__/              two legacy unit tests; new coverage goes in scripts/
+```
+
+---
+
+## 4. Invariants (from `docs/GAME-DESIGN.md` §10)
+
+Breaking one of these is how the game drifted the first time.
+
+1. **The engine cannot import from `lib/`.** See §1.
+2. **Config that nothing reads is a lie.** Before adding to
+   `lib/constants/game-config.ts`, confirm a line of source will import it. Nine
+   blocks were deleted in one pass because they were unread *and wrong*, and
+   their wrong numbers had already reached the player-facing docs.
+3. **Money is weekly. Progress is daily.** Do not add USDT payouts to the daily
+   layer.
+4. **Never make a real reward reachable only by luck.** Luck may accelerate it;
+   effort must guarantee it.
+5. **Sessions stay short.** If a change makes the minimum useful session longer
+   than ~5 minutes, it is wrong for MiniPay.
+6. **Content does not fix a missing loop.** More bunkers/monsters/weapons will
+   not answer "why come back tomorrow."
+7. **Update `docs/GAME-DESIGN.md` in the same PR.** Flip `[TARGET]` → `[TODAY]`
+   when you ship it.
+
+Two more that the tooling enforces:
+
+8. **Single-source config.** `lib/celoRpc.ts` owns RPC endpoints, `lib/siteUrl.ts`
+   owns the origin. `npm run audit` fails if any other file names an endpoint —
+   they used to disagree, and the knob only half-worked.
+9. **Every Celo transaction carries its ERC-8021 attribution tag** — via
+   `dataSuffix:` or `withAttribution()` on `data`. This *cannot be backfilled*;
+   an untagged tx is unattributed forever. `npm run check:attribution` gates it,
+   and this includes the four transactions the **backend** signs.
+
+---
+
+## 5. Web3 and wallet conventions
+
+- **Chain:** Celo Mainnet (`42220`). Tokens: Mento USDM, USDC, USDT — mixed 6-
+  and 18-decimal, always go through `parseTokenAmount` in `lib/constants/tokens.ts`.
+- **Connectors:** injected only. MiniPay auto-connects silently; MetaMask
+  extension works. WalletConnect / Coinbase / Rainbow are **not** integrated and
+  the relay was deliberately removed — do not reintroduce them.
+- **No `personal_sign` / `eth_signTypedData`.** MiniPay does not support message
+  signing at all; a call is a hard failure on a real device. `check:copy` enforces it.
+- **wagmi loads late, and as a sibling.** `lib/Web3Providers.tsx` renders children
+  immediately behind a dependency-free bridge, then mounts `WagmiIsland` beside
+  them on idle (1500 ms ceiling). The obvious `ready ? <WagmiProvider>{children}`
+  form would remount the whole tree the moment wagmi arrived. Never "simplify"
+  this into a wrapper.
+- **Three identity tiers**, most-authoritative first (`useWallet()` in
+  `lib/WalletProvider.tsx`):
+  - `realAddress` — a wallet. The only tier that can sign, pay or claim.
+  - `authAddress` — a Firebase account rendered as an address (SHA-256 of the uid,
+    first 20 bytes; `lib/authIdentity.ts`). Stable across devices, cannot sign.
+  - `guestAddress` — random localStorage id. Cannot sign, dies with the browser.
+
+  All three are `/^0x[0-9a-f]{40}$/`, so every Firebase-keyed path works
+  unchanged. **None of them is a credential** — anything that must be protected
+  is protected by Firestore rules keyed on the authenticated uid, never by the
+  unguessability of an address.
+- **Feature flags** live in one file each and are read by every consumer:
+  `lib/worldMapHubFlag.ts` (default **on**; `NEXT_PUBLIC_WORLDMAP_HUB=0` reverts
+  to the classic menu) and `lib/privyGateFlag.ts` (default **off**, never inside
+  MiniPay, requires an app id; temporary scaffolding for talent.app judging).
+
+---
+
+## 6. Server routes and data
+
+- Route handlers live at `app/api/<capability>/<action>/route.ts` and return
+  `NextResponse.json`. Business logic that is worth testing belongs in
+  `lib/server/` so a script can bundle and exercise it (`test:season` does this
+  with esbuild).
+- **Firebase Admin** is initialised in `firebase-config.ts` via `getAdminDb()`.
+  Never import it from client code — client Firebase is `lib/firebase.ts`.
+  `firebase-admin` v14 has no namespaced API; use the subpath modules
+  (`firebase-admin/app`, `/database`, `/auth`). It is also pinned as a
+  `serverComponentsExternalPackages` external in `next.config.js` to avoid
+  `ERR_REQUIRE_ESM` in the serverless bundle.
+- **Storage split:** Realtime DB (asia-southeast1) holds player profiles,
+  marketplace ownership and materials; Firestore holds usernames, bunker saves
+  and the leaderboard.
+- **Every on-chain claim is verified server-side**, and every verification is
+  replay-protected by recording the tx hash before granting anything — see
+  `app/api/marketplace/verify/route.ts`, which is the pattern to copy. Use
+  `waitForTransactionReceipt` (not `getTransactionReceipt`); the frontend calls
+  these routes immediately after broadcasting, so the tx is usually not indexed yet.
+- Firestore transactions must **read before write**. A violation of this rule
+  silently discarded every kill for a month; `test:kills` and `test:seasonxp`
+  assert it for every transaction in their modules.
+- Vercel: API functions get `maxDuration: 30`; `/api/cron/season` runs daily at
+  01:00 UTC (`vercel.json`).
+
+---
+
+## 7. MiniPay listing rules that live in code
+
+These are not style preferences — the listing review rejects the app over them.
+
+- **Banned player-facing words:** "gas" → *network fee*, "onramp"/"offramp" →
+  *deposit*/*withdraw*, "crypto" → *stablecoin*, and no "Add Cash" button label.
+  Code identifiers, comments and `eth_gasPrice` are fine; `check:copy` only reads
+  text a user can see.
+- **No "Connect wallet" copy and no connect button.** Inside MiniPay the address
+  resolves with zero interaction, so a connect prompt is always wrong. No gate
+  screen may appear between a MiniPay player and the game — not even for a frame.
+- **`.npmrc` is a listing requirement:** `minimum-release-age=10080` (reject
+  dependency versions published in the last 7 days) and `ignore-scripts=true`.
+  Do not remove either; install with `npm ci`/`npm install` as-is.
+- Load speed is graded on real-user p75, which is why the code-splitting in §5
+  and the "no preconnects" note in `app/layout.tsx` exist. Both were measured.
+  Read the comments before undoing either.
+
+---
+
+## 8. Documentation map
+
+`docs/GAME-DESIGN.md` is the source of truth for what the game *is* — read it
+before changing any loop or economy value. It carries `[TODAY]`/`[TARGET]`
+status markers, a decision log, and the invariants in §4.
+
+| File | Covers |
+|---|---|
+| `docs/GAME-DESIGN.md` | the loops, the four time layers, why each system exists |
+| `docs/game-mechanics.md`, `docs/faq.md` | player-facing rules |
+| `docs/rewards-system.md`, `docs/leaderboard.md`, `docs/pass-system.md` | economy |
+| `docs/TREASURY-OPS.md`, `docs/OWNER-RUNBOOK.md` | operating the treasury, deposit log |
+| `docs/network-manifest.md` | every external endpoint the app talks to |
+| `ARCHITECTURE_HYBRID.md`, `NULLSTATE_WEB3_ARCHITECTURE.md` | system architecture |
+| `MINIPAY-COMPLIANCE-CHECKLIST.md` | the full listing checklist |
+| `DEPLOYMENT.md`, `FIREBASE_SETUP.md`, `SEASONS_CONFIGURATION.md` | ops setup |
+
+Player-visible numbers appear in `docs/` **and** in the app's How to Play screen.
+If you change an economy value, change both — wrong numbers reaching the docs is
+the specific failure invariant #2 was written for.
+
+---
+
+## 9. House style
+
+**Comments explain the failure, not the code.** This repo's defining convention
+is that non-obvious code carries a header comment naming the bug it exists for,
+what was tried before, and why the obvious alternative is wrong. Read those
+before editing — several of them exist because a previous change was reverted.
+When you fix something subtle, leave the same kind of note; when you change code
+that has one, keep it accurate.
+
+**Commits are narrative.** The subject line is a sentence describing the problem
+in the player's or owner's terms, not a conventional-commits prefix:
+
+```
+The season score punished the players who had been here longest (#233)
+A Google player can pay, and no MiniPay player pays for it (#232)
+The half second of map that should not have been there (#226)
+```
+
+The body states the symptom (often quoting the owner), the mechanism, the fix and
+its shape, migration impact if any, and a **Verified:** line listing what was run
+(`19/19 test:seasonxp, 8/8 test:kills, tsc clean, build 143/242 kB, lint 35`).
+Match this. Run the relevant checks and report the real numbers.
+
+**Other conventions:**
+- Imports use the `@/*` path alias (`tsconfig.json`).
+- `strict: true`. `npx tsc --noEmit` must be clean — it is the check CI enforces.
+- Client components need `'use client'`; the wallet layer depends on precise
+  client/server boundaries.
+- Server-only env vars must never gain a `NEXT_PUBLIC_` prefix
+  (`POSTHOG_PERSONAL_API_KEY`, `CELO_RPC_URL`, `BACKEND_PRIVATE_KEY`,
+  `FIREBASE_SERVICE_ACCOUNT`, `DEV_TEST_WALLETS`).
+
+---
+
+## 10. Environment
+
+Required for a functioning backend (not in `.env.example`, which documents only
+the optional knobs):
+
+```
+FIREBASE_SERVICE_ACCOUNT      # service-account JSON string (never commit)
+FIREBASE_DATABASE_URL         # regional RTDB URL (asia-southeast1)
+BACKEND_PRIVATE_KEY           # backend signer: vault payouts, pass mints
+NEXT_PUBLIC_FIREBASE_*        # client SDK config (lib/firebase.ts)
+```
+
+Note the name is `FIREBASE_SERVICE_ACCOUNT` — `firebase-config.ts` reads exactly
+that, and warns and disables Admin rather than throwing when it is absent.
+
+`.env.example` documents everything else with the reasoning for each, and all of
+it is inert when unset: PostHog (Web Vitals reporting and the `/stats` speed
+card), `NEXT_PUBLIC_CELO_RPC` / `CELO_RPC_URL` (defaults to Forno with a viem
+`fallback()` chain), `NEXT_PUBLIC_SITE_URL`,
+`NEXT_PUBLIC_CELO_ATTRIBUTION_CODE`, the feature flags in §5, and two plain
+random strings that are not keys and cannot spend anything — `CRON_SECRET`
+(authenticates Vercel's call to `/api/cron/season`) and `ADMIN_SECRET` (sent as
+`x-admin-secret` to mark a season paid; it only sets a flag).
+
+`DEV_TEST_WALLETS` is a server-side allowlist that unlocks marketplace items
+without payment for on-device QA — leave it unset in production; grants are
+tagged `devGrant:true` in Firebase so they can be found and wiped.
+
+Contract addresses have hardcoded mainnet fallbacks in `lib/contract-abi.ts` and
+only need overriding for a redeploy.
+
+---
+
+## 11. Session notes
+
+- `.claude/hooks/session-start.sh` runs on session start: sets the repo-local git
+  identity (commits are the owner's; Claude stays on the `Co-Authored-By`
+  trailer), installs `node_modules` if missing, and regenerates
+  `public/game-engine/min/` so anything serving the app without a full build
+  measures the right thing.
+- `node_modules/` and `public/game-engine/min/` are gitignored — never commit them.
+- Before opening a PR, at minimum: `npx tsc --noEmit`, plus the checks relevant to
+  what you touched. Engine changes → `npm run test:play`. Economy or season logic
+  → the matching `test:*` script. Assets → `npm run audit`.

From 125672bcaa48f3597633619b299292a49dc1cf27 Mon Sep 17 00:00:00 2001
From: 0xward <0xward.dev@gmail.com>
Date: Mon, 3 Aug 2026 12:26:37 +0000
Subject: [PATCH 2/2] Update CLAUDE.md for the vault payout work that landed in
 #235
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The branch was cut before #235, so the file described a repo that no longer
exists: 44 routes (now 45), a lib/server/ list with no vaultChain or vaultSweep,
a cron that only closes seasons, and no mention of test:vaultpay.

Three conventions added to §6, because they are exactly the kind this file is
for — each one is a bug that already shipped and would have been avoided by a
sentence:

  - two on-chain writes in one player request is how a solved vault paid
    nothing; the second write was rejected at the RPC boundary before it was a
    transaction, and only the first winner of each week ever took that path
  - anything that can leave a reward unpaid needs a server-side sweep, because
    the vault's only recovery was re-clearing Bunker 5 to reach the door
  - never name a cause you did not check: the payout blamed an empty pool it had
    never read

A documentation branch that is behind main is documentation that is already
wrong, which is the failure invariant #2 in this same file exists to name.
---
 CLAUDE.md | 29 +++++++++++++++++++++++++----
 1 file changed, 25 insertions(+), 4 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 2a2efd6..a35264b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -75,7 +75,8 @@ comment of a script before changing it; it explains the failure it exists for.
 | `npm run build:icons` / `build:weapons` | generated art matching its masters |
 
 **Behaviour tests** — `test:season`, `test:seasonxp`, `test:kills`, `test:play`,
-`test:contracts`, `test:streak`, `test:migrate`, `test:vaultwin`, and ~20 more
+`test:contracts`, `test:streak`, `test:migrate`, `test:vaultwin`,
+`test:vaultpay`, and ~20 more
 (see `package.json` scripts). Some drive a real browser via `playwright-core`
 against engine files loaded directly; those taking `--serve` (`test:privy`,
 `test:season-ui`, `test:campaign-end`, `test:pass-cards`) spawn `next start`
@@ -108,9 +109,11 @@ app/
   page.tsx              landing
   game/  profile/       routes that wrap children in Web3Providers via a nested layout
   stats/ docs/ privacy/ terms/
-  api/                  44 route handlers, one directory per capability
+  api/                  45 route handlers, one directory per capability
     marketplace/verify  on-chain purchase verification (the reference route)
-    cron/season         Vercel cron, daily 01:00 UTC — season close/payout
+    vault/prepare       stores the week's vault code on chain BEFORE anyone wins
+    cron/season         Vercel cron, daily 01:00 UTC — season close/payout, and
+                        the sweep that retries unpaid vault rewards
 components/
   game/                 the shell's screens: GameFlowManager (router), WorldMapHub,
                         DungeonGame (engine host), MarketplaceScreen, RewardsScreen,
@@ -119,7 +122,8 @@ components/
 lib/
   constants/            game-config, marketplace, tokens, bunkers, seasonRewards
   server/               server-only logic: seasonClose, loginStreak, dailyContracts,
-                        energy, vault-fragments, referrals, guestMigrate…
+                        energy, vault-fragments, referrals, guestMigrate,
+                        vaultChain (all on-chain vault work), vaultSweep…
   WagmiIsland.tsx       wagmi/viem, mounted as a deferred SIBLING (see §5)
   WalletProvider.tsx    useWallet() — the identity surface
   celoRpc.ts            the ONLY place a Celo endpoint may be named
@@ -223,6 +227,23 @@ Two more that the tooling enforces:
 - Firestore transactions must **read before write**. A violation of this rule
   silently discarded every kill for a month; `test:kills` and `test:seasonxp`
   assert it for every transaction in their modules.
+- **Never put two on-chain writes in one player request.** A vault payout did —
+  store the week's code, then pay — and only for the *first* winner of each
+  week, so it looked random and survived weeks. Forno is load-balanced, so the
+  node answering the nonce read for the second write need not have seen the
+  first; the transaction was rejected at the RPC boundary before it was ever a
+  transaction, and the player was told the reward pool was empty. Do the
+  prerequisite write on its own schedule (`/api/vault/prepare`, plus the cron),
+  and if two writes genuinely must be sequential, read the nonce **once** and
+  increment locally. `lib/server/vaultChain.ts` carries the chain evidence.
+- **Money that fails must retry without the player.** The vault's only recovery
+  was re-opening the vault door, which means re-clearing Bunker 5 and killing
+  the final boss. Anything that can leave a reward unpaid needs a server-side
+  sweep — `lib/server/vaultSweep.ts`, run from the daily cron.
+- **Never name a cause you did not check.** Every failed vault payout printed
+  "the transfer completes as soon as the reward pool is topped up" and the
+  server had never read the pool; it cost hours of looking in the wrong place.
+  Read the balance before blaming the balance (`VAULT_FAILURE_MESSAGE`).
 - Vercel: API functions get `maxDuration: 30`; `/api/cron/season` runs daily at
   01:00 UTC (`vercel.json`).