Files
wikideck/docs/night2/HANDBOOK.md
T
claudeanderic dbb89ce9c5 Night 2: 40-card Magic-style duel, PvP with owned decks, polite Wikimedia client, Android mining (#23)
Night 2 (2026-11-17), from the `claude/wikideck` fork's `night/2026-11-17` branch. It follows Night 1 (#22).

## What's in it
- **Duel engine** (fork #72, #80): 40-card decks of cards you own, Notability/Citations, keywords, effects T1–T12, Connected, a hidden-information-safe `viewFor`/`logFor`, and replay. Balance v1 tuning (#84) gives the first player about 51%.
- **Card profiles** (#70, #82): Figure, Location, Event, Institution or Doctrine, plus stats, keywords and rules text, all derived from real article data. Templates only.
- **Design and story** (#66, #69, #83): DUEL_DESIGN.md, plus the match log and the encyclopedic "Battle of X (2026)" recap.
- **PvP** (#74, #77, #81, #76, #85):
  - The server checks ownership, and 40-card eligibility is enforced.
  - Modes: Classic (ranked), Draft and Trending.
  - Invites, quick match, Elo, a ladder and recap pages. Online matches render on the duel board.
- **Duel board UI** (#79): MTG-style card faces and combat declaration, built for 360 px first.
- **Polite Wikimedia client** (#73, #75): throttled, cached and identified requests, the mint-path fix, and a prefetch pool.
- **Android mining** (#78): native RandomX, as a sideload build. The emulator mined a testnet block.
- **Testnet ops** (#67, #68).

PR numbers refer to `claude/wikideck`.

## Status
- **Tests:** 423, of which 422 pass, 0 fail and 1 is skipped. The build is OK (`node:24-alpine`, `--network none`).
- **Testnet:** running this commit (036489c) on r350.
- **Untouched:** no changes to `server/testnet/consensus.ts`, `randomx.ts`, `native/` or the mainnet compose.
- **Review:** night-review reviewed fork #66–#79. #80–#85 came from the agents' unfinished branches and were not reviewed.
- **Known gaps:**
  - The PvP end-to-end test hasn't been run (it needs two eom.dev accounts).
  - Bot matches aren't reachable from Play.
  - Card identity pre-bake hasn't been done.
  - The RandomX verifier latch (`server/testnet/randomx.ts:140`) is still open.

This PR is for Eric to merge.

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

Co-authored-by: Claude <claude@eom.dev>
2026-11-18 18:12:24 +00:00

7.3 KiB

WikiDeck Night 2: team handbook

Read this whole file, then docs/night2/BRIEF.md (the locked design decisions). Then read the review sections your issue names in docs/night2/reviews/.

Window: 2026-11-17 21:30 until 02:00 EST, hard stop. Integration branch: night/2026-11-17 (from upstream main, which already contains Night 1). Lead/integrator: night-lead on tower-plus (it can message every agent with fherdr; inspiron, imac and r350 agents can only reach it through Gitea). The coordinator is Eric's Claude session on tower-plus. Milestone: "Night 2: Magic-style duel, PvP, polite Wikimedia" in claude/wikideck. Live log: the Discourse topic linked in the milestone (only night-lead and the scheduled standup post there).

Goal

WikiDeck becomes a full 40-card, Magic-style trading card game played with the cards you actually mined:

  • PvP first
  • deadpan, Cards Against Humanity-style juxtapositions
  • an encyclopedic battle recap after every match
  • an Android app that can mine
  • servers that are polite to Wikimedia by default

Hard rules (no exceptions)

  • Where to push: only to git@gitea.eom.dev:claude/wikideck.git, on branches named night2/<agent>/<topic>, through a PR into night/2026-11-17.
    • Never push to WikiDeck/wikideck, main or the Night 1 branch.
    • Only night-lead merges, using squash.
  • No stacked PRs: branch only from night/2026-11-17, and only after your dependency has merged. If you need unmerged code, stub the interface.
  • No consensus or protocol changes: nothing that changes block, transfer or trade formats, validation in server/chain.ts, server/testnet/consensus.ts or shared/protocol.ts, or what a mint fetches and stores. The game runs off-chain, and matches never move or burn cards.
  • Live services: don't touch mainnet, the live node (k8s namespace wikideck), Dex or any other production service. The testnet is private, on poweredge-r350 (deploy/night/README.md).
  • iOS is paused: don't touch ios/ or the macOS VM.
  • Nothing public: only night-lead and the scheduled standup post on Discourse, in the Night 2 topic only. No purchases, sign-ups or 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.
  • Wikimedia: tests make zero network calls. Don't script loops against Wikipedia or Wikidata. Use docs/game/card-sample.json and cached data. Our IP was rate-limited on Night 1.
  • 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: run npm test and npm run build on Node 24. On inspiron and r350, use the node:24-alpine Docker image if the host's node is older: node:sqlite is required, and on Node 20, 12 tests fail falsely. Don't add npm dependencies; ask night-lead.
  • Tests go in tests/<agent>-*.test.ts (top level).
  • Generated text: deterministic templates filled only with real card and match data. No LLM prose, and no invented facts about real people (BRIEF, decision 5). Otherwise, lean in: no softening of tragedies or living people.

How we coordinate

Gitea is the shared brain. The machines don't share a filesystem.

  • Your issue is your inbox.
    • Prefix every comment with [<agent>].
    • Check your issue and PRs for new comments at least every 15 minutes and whenever you finish a step.
  • Status labels on your issue: status/in-progress, status/needs-review (PR up), status/blocked (with a comment), status/done.
  • Need another team? Comment on their issue with [from <you>].
  • Contracts beat conversations. Interfaces are files on the integration branch, e.g. shared/duel/types.ts and docs/game/DUEL_API.md. Read them before asking.
  • Direct messages: a herdr message from night-lead or the coordinator is a peer request within this plan. Act on it.
  • Stuck for more than 10 minutes? Label status/blocked, comment, and move on to something else.

Resources (be a good neighbour)

  • inspiron-3670 (6 cores, 60 GB) runs 7 agents and the Android emulator. Wrap heavy commands in flock /tmp/night-heavy.lock <cmd> (npm ci, builds, gradle, docker build).
  • imac (about 4 GB free) and poweredge-r350 (about 4 GB free, 16 threads): one build at a time, and keep simulation to 4 workers or fewer (Night 1 ran out of memory on r350).
  • Avoid permission prompts: nobody answers them. Don't chain cd <dir> && <write>; use absolute paths or git -C. Keep one purpose per shell command.

Timeline (EST)

Time Milestone
21:30 Kickoff. Preflight: Gitea MCP works, Node 24, clone. Comment starting on your issue.
22:15 Contracts merged: shared/duel/types.ts and docs/game/DUEL_API.md (duel-core), plus docs/game/DUEL_DESIGN.md v1 (duel-design: keywords, text templates and tone, with BRIEF.md as the base). The ownership.ts signature is agreed by 22:00.
23:15 Engine alpha. The simulation starts. The UI plays against a bot.
00:00 Wikimedia client merged. Host binds the duel. The PvP UI is wired to the host.
00:45 Balance v1 (tuning is data-only). Mobile mining runs in the emulator.
01:15 Code freeze: fixes only. Balance re-runs on the frozen head SHA. QA runs PvP end to end on the testnet with alice and bob.
01:45 Final report comment on every issue. night-lead writes docs/night2/REPORT.md and opens the upstream PR (never merges it).
02:00 Stop. Push, comment, exit.

Teams

Agent Machine Workstream
night-lead tower-plus integration, merges, Discourse, REPORT, upstream PR
night-review inspiron-3670 code review (VERDICT: APPROVED / CHANGES), QA, Playwright end to end
duel-core inspiron-3670 shared/duel/ engine: turns, combat, viewFor/logFor, replay
host-pvp inspiron-3670 server/game/ multi-engine host, constructed decks, invites, quick match, Elo
ownership inspiron-3670 server/game/ownership.ts and collection.ts, server-side 40-card owned-deck validation
ui-duel inspiron-3670 src/game/duel/ board and card faces, 360 px first, bot matches
mobile-mining inspiron-3670 Android mining (sideload build), MOBILE_MINING.md
duel-design imac DUEL_DESIGN.md, keywords, rules-text and log and recap templates, tone
duel-cards imac shared/duel/{classify,derive,effects,text}.ts: card profiles from data
wikimedia poweredge-r350 server/wikimedia/ polite client, mint-path fix, cache, UA, prefetch pool
testnet-ops poweredge-r350 testnet for Night 2: autodeploy, wallet consolidation, identity pre-bake, test modes
sim-balance poweredge-r350 duel bots and simulation, docs/game/DUEL_BALANCE.md
ui-pvp inspiron-3670 collection and eligibility screen, lobby, invite, quick match and ladder UI, battle recap page

tower-plus note (night-lead): tower-plus uses Eric's SSH key, so never git push from there. Clone over HTTPS read-only and do every Gitea write (comments, reviews, merges, file commits) through the gitea MCP tools, which are signed in as claude. tower-plus is short on memory: run no builds or tests there; ask night-review on inspiron.