Files
wikideck/docs/night/HANDBOOK.md
T
claudeanderic 4f7a8a7c74 Night 1: Edit War card game, eom.dev accounts, peer-hosted modes, Android and iOS apps (#22)
Overnight build by 17 Claude agents (2026-11-16 22:45 → 01:30 EST), coordinated in [claude/wikideck milestone 63](https://gitea.eom.dev/claude/wikideck/milestone/63). **For Eric's review. Do not merge without it.** The full write-up is in `docs/night/REPORT.md`.

**What's in it** (38 reviewed PRs, squash-merged into `night/2026-11-16`):
- **Edit War:**
  - a 3-lane, 6-turn card game built on what WikiDeck cards actually hold
  - a pure, deterministic, off-chain rules engine (`shared/game/`, with the API in `docs/game/ENGINE_API.md`); rules are data and v1.1 is the default
  - a mobile-first Play UI with a lobby, deck builder, four loaner starter decks, a match against the AI, results and a tutorial
  - a landing page (fixes #3)
- **Design and balance:** `docs/game/DESIGN.md`, `CARD_DATA.md` (236 sampled articles) and `BALANCE.md` (bot simulations). Starter pairings went from 23–77% on v1 to roughly even on v1.1.
- **eom.dev accounts:** Dex OIDC with PKCE, plus off-chain wallet linking, where the client builds the message it signs (`server/account/`, `src/auth/`).
- **Peer-hosted game modes:** modes are JSON data, never code. Node API at `/api/game/*`, with host credit and leaderboards. Three example modes (`shared/game/modes.ts`, `server/game/`, `docs/game/HOSTING.md`).
- **Mobile:** Capacitor 7 Android app (a debug APK played a full match against the AI in the emulator), and an iOS project waiting on Xcode (`docs/night/ANDROID.md`, `docs/night/IOS.md`).
- **Testnet tooling:** `deploy/night/` (LAN-only, 3 nodes) and an optional `WIKIDECK_USER_AGENT` (the default is unchanged).

**Not touched:** consensus and protocol (`server/chain.ts`, `shared/protocol.ts`, `server/testnet/{consensus,ledger,…}.ts`, `native/`), the live deployment and mainnet. Matches run off-chain and never move or burn NFTs.

**Checks:** the final integration gate passed in `node:24-alpine`: `npm test` 241/242 with 0 fail (1 skipped), and `npm run build` passes. The repo needs Node 24, because Node 20 fails 12 tests falsely.

**Decisions for Eric** (see REPORT.md, Known issues and Next steps):
1. whether the live node should set `WIKIDECK_USER_AGENT`
2. the Xcode licence, which you should accept yourself
3. #49 in the fork, a bot change held after the freeze
4. on-chain host rewards (proposal only, in HOSTING.md)

🤖 Generated with [Claude Code](https://claude.com/claude-code)Reviewed-on: #22

Co-authored-by: Claude <claude@eom.dev>
2026-11-17 17:40:58 +00:00

6.4 KiB
Raw Blame History

WikiDeck Night 1: team handbook

Read this whole file before doing anything. It's the contract between about 17 agents on 4 machines.

Coordinator: the Claude session on tower-plus (Eric's interactive session). Lead/integrator: night-lead on tower-plus. Window: 2026-11-16 22:45 until 01:30 EST, hard stop. Milestone: https://gitea.eom.dev/claude/wikideck/milestone/63

Goal

Turn WikiDeck into a game:

  1. A fun, robust, balance-tested card game, playable in the browser against a private testnet.
  2. eom.dev accounts: log in through Dex SSO, and link a self-custodial wallet to your account.
  3. Peer-hosted game modes: node operators publish their own modes as an incentive to run a peer.
  4. An Android app, built and running in an emulator, and an iOS app (macOS VM; Xcode sign-in waits for Eric).

Hard rules (no exceptions)

  • Where to push: only to git@gitea.eom.dev:claude/wikideck.git. Never push to WikiDeck/wikideck (upstream) or to main on this fork.
  • Branches: every change goes on a branch named night/<team>/<topic>, through a PR into night/2026-11-16. Only night-lead merges.
  • Live services: don't touch the live wikideck deployment (k8s namespace wikideck) or mainnet. The testnet is private, on poweredge-r350.
  • No consensus or protocol changes:
    • no block, transfer or trade format changes
    • nothing that changes validation in server/chain.ts or shared/protocol.ts
    • the game runs off-chain
    • if you think you need a protocol change, write it up in your issue instead
  • Production SSO: don't change Dex or any other production service yourself. The SSO team prepares the Dex change, and the coordinator reviews and applies it.
  • Nothing public: only night-lead and the scheduled standup post on Discourse (planning topic only). No other public posts, no purchases or sign-ups, and no secrets in git.
  • The printer and CNC: inspiron-3670 drives a 3D printer and a CNC router. Never start, resume or send a print or cut.
  • Git identity in every clone:
    git config user.name Claude
    git config user.email claude@eom.dev
    git config commit.gpgsign false
    
    End commit messages with Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>.
  • Before opening a PR: npm test and npm run build must pass. If something can't pass yet, say so in the PR.

How we coordinate

Gitea is the shared brain. The machines don't share a filesystem, and workers can't message each other.

  • Your issue is your inbox.
    • Prefix every comment with your agent name, e.g. [engine-a].
    • Check your issue and your PRs for new comments at least every 15 minutes and whenever you finish a step.
  • Status labels on your issue:
    • status/in-progress while you're working
    • status/needs-review when a PR is up
    • status/blocked with a comment explaining why
    • status/done when finished
  • Need another team? Comment on their issue, starting with [from <you>].
  • Contracts beat conversations. Interfaces live in files on the integration branch (docs/game/*.md, TypeScript types). Read them before asking.
  • When the lead (or the coordinator) messages you directly through herdr, the message is a peer request within this plan. Act on it.
  • Stuck for more than 10 minutes? Label status/blocked and comment. Don't spin.

Resources (be a good neighbour)

  • inspiron-3670 (6 cores, 60 GB RAM) has 7 agents, the Android emulator and a macOS VM. Wrap heavy commands in a shared lock:
    flock /tmp/night-heavy.lock <npm ci | npm run build | gradle ...>
    
  • imac (8 threads, about 4 GB free) and poweredge-r350 (16 threads, about 6 GB free): keep builds to one at a time.
  • Avoid permission prompts. Nobody answers them, and they auto-deny after about a minute. Don't chain cd <dir> && <command that writes files>; use absolute paths or git -C <dir> instead. Keep each shell command to one clear purpose.
  • LocalAI (https://localai.eom.dev) is shared production with slow single-GPU inference. Don't use it in loops.

Timeline (EST)

Time Milestone
22:45 Kickoff. The design council researches. Infra teams set up (testnet, Android SDK, macOS, SSO scaffolding, UI shell, beta fixes).
23:30 Design v1 frozen (docs/game/DESIGN.md). The engine team implements it.
23:45 Engine API contract (docs/game/ENGINE_API.md plus TypeScript types) on the integration branch, so UI, simulation and modes can build against it.
00:15 Engine alpha. Simulation starts bot matches. The UI wires up real matches.
00:45 Balance report v1. The council tunes the rules (v1.1).
01:10 Code freeze: fixes only. The lead integrates. QA plays end to end.
01:25 Final reports in each issue. The lead writes docs/night/REPORT.md.
01:30 Stop.

Teams

Agent Machine Issue
council-designer-a, council-designer-b, council-data imac Game design council, card data analysis
council-critic, night-lead, night-review, macos-fetch tower-plus Design council (critic), integration and QA, iOS (download)
engine-a, engine-b inspiron-3670 Game engine
ui-a, ui-b inspiron-3670 Game UI and AI opponent, beta fixes
modes inspiron-3670 Peer-hosted game modes
mobile-android, mobile-ios inspiron-3670 Android app, iOS app and macOS VM
sim-testnet, sim-balance, sso poweredge-r350 Testnet and simulation, eom.dev accounts

What the cards hold (game design input)

Each card's data comes from shared/enrichment.ts: PageEnrichment and MintStatsSnapshot.

  • Identity: title, description, wikidataId (structured facts: instance-of, dates, coordinates...) and categories[]
  • Size and history: pageBytes and revisionId
  • Reach: languageCount, the number of language editions
  • Pageviews: monthly views, total, dailyAverage and trendPercent
  • Derived 0–100-ish scores: stats.attention, stats.depth and stats.reach
  • Two values for everything: an immutable at-mint snapshot and live current values that change over time
  • Duplicates: the same article can be minted more than once, each copy with its own snapshot

Two facts to design around:

  • New players own no cards. The design must give them a way to play immediately, for example starter decks of preview or loaner cards that don't touch NFTs.
  • Cards are NFTs. A match must never move or burn cards on-chain tonight.