diff --git a/docs/night/HANDBOOK.md b/docs/night/HANDBOOK.md new file mode 100644 index 0000000..7d2bf85 --- /dev/null +++ b/docs/night/HANDBOOK.md @@ -0,0 +1,98 @@ +# 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//`, 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 `. +- **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 ]`. +- **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 + ``` +- **imac** (8 threads, about 4 GB free) and **poweredge-r350** (16 threads, about 6 GB free): keep builds to one at a time. +- **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.