The game kit: the shared infrastructure of Wiz-War and Waving Hands as a template

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0141G6xqLeNRYEtviLWSB5Up
2026-09-23 11:00:05 -04:00
commit 1cd24e3ddd
59 changed files with 7420 additions and 0 deletions
@@ -0,0 +1,52 @@
+# game-kit
+
+The shared infrastructure of Wiz-War and Waving Hands, extracted so the next
+game starts with all of it in place: the hall, room codes and tables, the
+Peanut Gallery, table talk, append-only ledgers replayed through a
+deterministic engine, the rules revision, the reports desk, the deploy
+script with its determinism gate, nightly rollup and backup, Sentry with
+Slack alerts, and the visitors, pulse and reports skills for Claude.
+
+The game itself is one file. `src/lib/game/index.ts` implements `GameSpec`
+(see `src/lib/game/spec.ts`); the server, the client store, the hall and
+the ops tools never look past it. The template ships with a demo game,
+High Card, so everything runs before you have written a line.
+
+## Start a game
+
+    ./new-game.sh <slug> "<Name>" [port] [domain]
+
+That copies `template/` to `~/projects/<slug>`, fills the name, port and
+domain in, initialises git, installs dependencies, and prints the steps
+that remain: write the game, fill in the hall and rules and guide, create
+the droplet and the Sentry project, deploy. `CONVENTIONS.md` is copied to
+the new project as `docs/conventions.md`; it is the house style.
+
+Run the demo locally from a new project:
+
+    npm run server      # the game server on its port
+    npm run dev -- --host
+
+## What is where
+
+    template/
+      src/lib/game/spec.ts        the contract a game implements
+      src/lib/game/index.ts       the demo game; replace it
+      src/lib/net/                client.ts (calls, held seats, socket), room.svelte.ts (the room store), talk.ts, view.ts
+      src/lib/components/         Hall, Lobby, TableTalk, ReportSlip, Board (demo; replace it)
+      src/routes/                 the hall, /join/[code], /rules, /guide
+      server/src/                 index (routes), rooms (game-agnostic), store (ledger), reports (the desk), ratelimit
+      deploy/                     deploy, setup, Caddy, systemd, cron, gate + replay, backup, rollup, pulse, visitors, Slack alert, reports tools
+      .claude/skills/             <slug>-visitors, <slug>-pulse, <slug>-reports
+
+Placeholders: `__SLUG__`, `__NAME__`, `__PORT__`, `__DOMAIN__` are filled by
+`new-game.sh`; `__IP__`, `__SENTRY_DSN__`, `__SENTRY_PROJECT_ID__`,
+`__SENTRY_SLACK_INTEGRATION__` and `__SLACK_CHANNEL_ID__` wait until those
+things exist.
+
+## Keeping the kit current
+
+When a game grows something every game should have (the gallery and the
+reports desk were both born in one game and ported to the other), bring it
+back here, with placeholders, so the next game inherits it. The kit is the
+canonical copy of the shared parts; the games are its instances.