homegames-common 1.5.2 → 1.5.4

package/docker-helper.js

@@ -101,7 +101,7 @@ const runGameContainer = async ({
     saveDataPath,
     assetCachePath = null,
     imageName = 'homegames-runner',
-    memoryLimit = '128m',
+    memoryLimit = '196m',
     cpuLimit = '1',
     gameEntryRelative = null,
     noFrame = false,
@@ -395,4 +395,5 @@ module.exports = {
     stopContainer,
     isContainerRunning,
     streamContainerLogs,
+    parseMemoryString,
 };

package/docs/ARCHITECTURE.md

@@ -0,0 +1,173 @@
+# Homegames — Architecture
+
+Component-by-component. For where these physically run, see INFRA.md; for traces
+through them, see FLOWS.md.
+
+---
+
+## squish (npm: `squishjs`)
+
+The shared contract between server and client — a compact binary serialization
+of a game's scene graph, plus the node types and base classes games are built
+from.
+
+- **Node types** (`GameNode`): `Shape` (polygons/lines), `Text`, `Asset` (image/audio).
+  Everything is positioned in a virtual **0–100 coordinate plane**.
+- **`squish(node)` / `unsquish(bytes)`** (`src/squish.js`): TLV-style encoder.
+  Each node frame starts with magic byte `3`, a class code, then per-property
+  sub-frames (color, coordinates, text, asset, playerIds, etc.), each with its
+  own type tag + length. Numbers are stored as integer + 2-decimal-fraction byte
+  pairs (~0.01 resolution).
+- **`Game` / `ViewableGame`** base classes: games extend these. `ViewableGame`
+  adds a large world "plane" + `ViewUtils.getView()` for per-player cameras into
+  a world bigger than one screen.
+- **`Squisher`** (`src/Squisher.js`): walks a game's layer tree, squishes every
+  node, builds **per-player frames** (via `playerIds` filtering — this is how
+  hidden info / private UI works and why it's bandwidth-efficient and
+  cheat-resistant), bundles binary assets, and coalesces per-tick mutations into
+  one broadcast.
+- **Versioning:** published as pinned versions; the canonical map is
+  `homegames-common/game-loader.js → squishMap`. A game's `squishVersion` selects
+  which package both server and client use. **Image cropping / spritesheets
+  require `squish-140`+.**
+
+Authoring contract: **squishjs-game-authoring.md** (this folder).
+
+---
+
+## homegames-common
+
+The shared backend library. Notable modules:
+
+- **`game-loader.js`** — `squishMap` (version → npm alias, **single source of
+  truth**), `parseSquishVersion` (AST-reads a game's `squishVersion`),
+  `loadGameClass*`, and `fetchGameFromForgejo` (download a game's repo archive,
+  find `index.js`).
+- **`docker-helper.js`** — the isolation layer. `runGameContainer` (live session:
+  read-only code mount, mem/CPU/PID limits, `CapDrop: ALL`, tmpfs, auto-remove)
+  and `validateGame` (publish gate: `--network=none`, read-only rootfs, noexec
+  tmpfs, timeout). Uses `dockerode`.
+- **`game-session-manager.js`** — starts a session by `versionId` (fetch from
+  Forgejo) or path; **uses Docker when available, falls back to `fork()` when
+  not** (see security_notes.md — fail closed in production).
+- **`index.js`** — config, logging, `getAppDataPath`, and the **authoring-doc
+  accessor** (`authoringDocPath`, `getAuthoringDoc()`) so every consumer reads
+  one doc.
+- **`docs/`** — this documentation.
+
+---
+
+## homegames-core (game-session server)
+
+Runs a single published game and streams it to players.
+
+- Loads the game class for the requested `squishVersion`, instantiates it,
+  constructs a `Squisher`, and on each tick/state-change squishes the scene and
+  **broadcasts frames over WebSocket**. Receives input messages (click/key/etc.)
+  and routes them to the game instance's handlers.
+- **Per-session isolation:** each live game runs in a `homegames-runner` Docker
+  container (built from `homegames-core/docker/`: `Dockerfile`,
+  `container-entry.js`, and `validate.js` used by the publish gate).
+- Session orchestration / port assignment / handing players to the right session
+  is done with the **Homenames** registry and the socket layer (`src/util/socket.js`),
+  which also speaks the binary client protocol (init / asset bundle / state /
+  port-redirect / aspect-ratio messages).
+- Built-in games live in `src/games/` (e.g. `image-test`, `singularity`,
+  `enhanced-view-test`). Published user games are fetched from Forgejo at run time.
+
+---
+
+## homegames-client (browser renderer)
+
+The engine that turns squished frames into pixels.
+
+- `src/index.js` — `HomegamesClient`: WebSocket lifecycle (inline or via a Web
+  Worker, `socket-worker.js`), handles the binary message types, picks the right
+  `unsquish` by version (`squish-map.js`), runs a rAF render loop that only
+  repaints when state actually changed.
+- `src/renderer.js` — draws polygons/text/images/audio + effects; records
+  hit-test data; applies image **crop** (9-arg `drawImage`).
+- `src/input.js` — mouse/touch/keyboard/gamepad → game protocol messages;
+  point-in-polygon hit-testing; held-key repeat throttled to ~30/s; clears stuck
+  mouse state on blur / off-window release.
+- `src/assets.js` — decodes the binary asset bundle (image/audio/font) and caches.
+- Built to `dist/homegames-client.js` (webpack) and served to players.
+
+---
+
+## homegamesio (the website)
+
+Static site on S3+CloudFront; `app.js` is the Node origin that maps URL paths to
+HTML files. Surfaces:
+
+- **Landing / catalog / play / view** pages.
+- **Studio** (`studio.html` + `studio.js`) — the in-browser game editor: code
+  editor + file tree, live **Preview**, **Versions** history, **AI Edit**, a
+  consolidated **Settings** panel (description / thumbnail / clone), one-click
+  **Publish**, and a full **Assets** workspace (Upload / Draw / Record / Keyboard).
+  Top-level UI is two modes: **GAMES** and **ASSETS**. (Redesigned to an
+  "analog dashboard" — big labeled buttons, progressive disclosure.)
+- **Admin** (`admin.html` + `admin.js`) — moderation console at `/admin`,
+  admin-only: inspect/search/delete users, games, assets; publish-request review;
+  support messages; stats. (One-click "delete user + everything they made"
+  cascades Mongo + Forgejo repos + the Forgejo account.)
+- **Reset-password / verify** pages.
+- Talks to `api.homegames.io` for everything dynamic; serves the **authoring
+  guide** at `/authoring-guide.md` (read from `homegames-common`).
+
+---
+
+## api (backend REST + publish worker)
+
+Node HTTP API. Routing in `router.js` (regex → handler, with `requiresAuth` /
+`requiresVerified` gates). Key areas:
+
+- **auth.js** — signup (internal `userId` ≠ immutable `displayName`), login (by
+  display name or email), **email verification by 6-digit code**, **password
+  reset by code** (anti-enumeration). JWT in `crypto.js`.
+- **studio-handlers.js** — the Studio backend: provisions a per-user Forgejo
+  account (password derived via HMAC from a server secret), creates/edits game
+  repos, lists versions, restores, sets thumbnail, submits **publish requests**
+  (rate-limited), receives Forgejo **push webhooks** (HMAC-verified), and queues
+  build/LLM jobs.
+- **handlers.js** — catalog, asset upload (**calls `nsfw.js` `classifyImage`
+  in-process at upload time** — TensorFlow `nsfwjs`), admin endpoints, delete
+  (game/asset/developer with cascade), email-verify/reset handlers.
+- **worker.js** — the **publish-validation worker** (consumes the
+  `publish_requests` RabbitMQ queue): checks `index.js` + GPLv3 LICENSE, size
+  limits, runs **`ast-scanner.js`** over every JS file, then **`validateGame`**
+  (Docker sandbox: loads/instantiates/runs the game ~5s, no network), reads NSFW
+  flags, and on success writes a `gameVersions` record with `published: true`.
+- **forgejo.js** — admin-token client for the Forgejo server (create user/repo,
+  files, webhooks, archives, delete user/repo).
+- **nsfw.js / detect.js / ast-scanner.js / crypto.js / db.js / queue.js / email.js**
+  — moderation model, mime detection, the static-analysis gate, JWT+hashing,
+  Mongo access, RabbitMQ publishing, SES email.
+
+Note the API is a **monolith process** that also embeds the NSFW model — NSFW
+moderation is *not* a separate worker.
+
+---
+
+## worker (LLM "AI edit")
+
+Runs on the Mac Studio (MLX needs Apple Silicon).
+
+- `index.js` (Node) — pulls LLM jobs from the EC2's RabbitMQ, manages a
+  long-lived Python child, posts results back to the API (authenticated with
+  `LLM_WORKER_SECRET`).
+- `llm/model_server.py` (MLX) — holds a warm code model (Qwen2.5-Coder), prefills
+  the **authoring guide** as the system prompt (resolved from `homegames-common`
+  via `AUTHORING_DOC_PATH`), rewrites a game's `index.js` from a natural-language
+  request, with validation-error retry.
+- The result is dropped into the Studio editor as an unsaved change for the user
+  to review and save.
+
+---
+
+## Supporting services (on the EC2 host)
+
+- **MongoDB** — all application data (users, games, versions, assets, etc.). See DATA-MODEL.md.
+- **RabbitMQ** — job queues: `publish_requests` (publish validation) and the
+  unified jobs queue (`homegames-jobs`, incl. `LLM_REQUEST`, `BUILD_GAME`).
+- **Forgejo** — git server; one repo per game; the canonical store of game source.

package/docs/DATA-MODEL.md

@@ -0,0 +1,115 @@
+# Homegames — Data Model
+
+Where state lives: **MongoDB** (app data), **Forgejo** (game source), the **asset
+store** (binaries in Mongo), and the **squish** wire format (transient, on the
+wire). `> TODO: confirm` marks fields inferred from code that should be
+spot-checked against a live DB.
+
+---
+
+## Identity model (important)
+
+- **`userId`** — the canonical internal id (generated, `md5(uuid)`). Never shown.
+  It's what the JWT carries, what `developerId` references, and the **Forgejo
+  account/owner name**.
+- **`displayName`** — chosen at signup, **immutable**, unique (case-insensitive).
+  The only user-facing name.
+- **`email`** — unique (case-insensitive), used for verification + reset.
+
+This split was deliberate so display names can stay stable/independent of identity
+and future-flexible. Anything that shows `developerId` as an author is showing the
+opaque id — map to `displayName` for display. (`> TODO`: a sweep of catalog/profile
+pages to show displayName everywhere.)
+
+---
+
+## MongoDB collections
+
+Connection + helpers: `api/db.js`. DB name default `homegames`.
+
+### `users`
+`userId`, `displayName`, `displayNameLower`, `email`, `emailLower`, `verified`,
+`verificationCodeHash`, `verificationCodeExpires`, `resetCodeHash`,
+`resetCodeExpires`, `passwordHash`, `passwordSalt`, `created`, `isAdmin`,
+`forgejoAccountCreated`, `forgejoPasswordSynced`, plus profile fields
+(`image`, `description`, `btcAddress`). Password = pbkdf2(`crypto.js`). Codes are
+stored **hashed** (`hashValue`/sha256).
+
+### `games`
+`gameId`, `name`, `description`, `developerId` (= `userId`), `created`,
+`forgejoRepo` (`"<userId>/<repoName>"`), `featured`, `thumbnail` (an assetId),
+`nsfw`.
+
+### `gameVersions`
+`versionId`, `gameId`, `commitSha`, `publishedAt`, `publishedBy`, `published`,
+`approved`, `nsfw`. **This is what makes a game launchable** — a session runs the
+`commitSha` of a published version.
+
+### `publishRequests`
+`requestId`, `gameId`, `commitSha`, `userId`, `status`
+(`PENDING` → `PROCESSING` → `PUBLISHED` | `FAILED`; an older manual-approval path
+uses `PENDING_PUBLISH_APPROVAL` → `REJECTED`), `created`, `completedAt`,
+`versionId`, `error`, `adminMessage`. Rate-limited to 1 per 10 min per user.
+
+### `builds`
+`buildId`, `gameId`, `commitSha`, `commitMessage`, `triggeredBy`, `status`,
+`error`, `created`, `completed`. Created on Forgejo push webhooks.
+
+### `assets`
+`assetId`, `developerId`, `name`, `type` (`image`/`audio`/`font`), `fileType`,
+`nsfw`, `created`, `tags`, `description`, public/approval flags. `> TODO: confirm`
+exact public/approval field names. Max 100 assets/user (`MAX_ASSETS_PER_USER`).
+
+### `documents`
+The **binary asset store**: `developerId`, `assetId`, `data` (BSON `Binary`),
+`fileSize`, `fileType`. Served at `GET /assets/:id`.
+
+### `supportMessages`
+`id`, `created`, `ipHash`, `status` (`PENDING` → ack'd), `message`, `email`.
+
+### `blog`
+`id`, `publishedBy`, `created`, `title`, `content`.
+
+`> TODO: confirm` any other collections in the live DB (sessions/homenames state, certs, etc.).
+
+---
+
+## Forgejo (game source of truth)
+
+- A self-hosted Gitea fork. **One repo per game**, at `"<userId>/<repoName>"`,
+  owned by the user's internal id. Created/managed by the API via the **admin
+  token** (`api/forgejo.js`).
+- Each user has a Forgejo account (username = `userId`); its password is **derived
+  on demand** via `HMAC(FORGEJO_USER_SECRET, userId)` — nothing stored. CLI clone
+  URLs embed those derived credentials.
+- A game's `index.js` (and other files) are committed here; the published
+  `commitSha` in `gameVersions` pins exactly what runs.
+- Push webhooks (HMAC `FORGEJO_WEBHOOK_SECRET`) drive the build/publish pipeline.
+
+---
+
+## Asset store / serving
+
+- Binaries live in Mongo `documents`; metadata in `assets`. Served by the API at
+  `/assets/:id`.
+- The squish `Asset` class (client + game code) references assets by **id**, and
+  historically downloads from an asset endpoint (`api.homegames.io/assets`,
+  older `assets.homegames.io`). `> TODO: confirm` whether any assets are also in
+  S3 vs all in Mongo now.
+
+---
+
+## squish wire format (on the wire, not stored)
+
+Transient binary frames between homegames-core and the browser. Full spec +
+authoring rules: **squishjs-game-authoring.md**. In brief:
+
+- A game's scene = a tree of `Shape`/`Text`/`Asset` nodes in 0–100 space.
+- `squish()` encodes each node as `[3, len…, classCode, …sub-frames]`; each
+  property (color, coordinates2d, text, asset, playerIds, …) is a typed,
+  length-prefixed sub-frame. Numbers are integer + 2-decimal-fraction byte pairs.
+- The server sends: **init** (player id, aspect ratio, squishVersion) →
+  **asset bundle** → **state frames**, plus port-redirect / aspect-ratio messages.
+- **Versioned**: `squishVersion` in a game's `metadata()` selects the pinned
+  squish package used to encode (server) and decode (client). Never mutate a
+  published version's format; ship a new version (see `game-loader.js → squishMap`).

package/docs/FLOWS.md

@@ -0,0 +1,125 @@
+# Homegames — End-to-End Flows
+
+Traces through the system for the things that matter. See ARCHITECTURE.md for the
+components named here.
+
+---
+
+## 1. Playing a game (hosted)
+
+1. Player opens `homegames.io` (S3/CloudFront) and picks a game from the catalog,
+   or hits a play link with a `gameId`/`versionId`.
+2. The page asks the **API** to create/find a **session** for that published
+   version. The API (via **Homenames** + homegames-core) ensures a
+   **homegames-core session is running in a Docker container** for that game and
+   returns a WebSocket endpoint/port.
+3. The **homegames-client** (bundled in the page) opens the WebSocket. The server
+   sends an **init** message (player id, aspect ratio, bezel, and the game's
+   **squishVersion**), then the **asset bundle** (type 1), then **state frames**
+   (type 3).
+4. The client picks the matching `unsquish` for that squishVersion, decodes each
+   frame, and **renders** polygons/text/images to the canvas (0–100 space → pixels).
+5. Player input (click/key/touch) is normalized to 0–100 and sent back over the
+   socket; homegames-core routes it to the game instance's handlers
+   (`onClick`, `handleKeyDown`, …), which mutate state; the `Squisher` coalesces
+   and broadcasts the next frame.
+6. Per-player visibility (`playerIds`) means each player can receive a different
+   frame — the server only squishes what that player should see.
+
+Multiple players share **one** game instance (it's authoritative); there is no
+per-player game process.
+
+---
+
+## 2. Authoring + publishing a game
+
+**Author (in the Studio):**
+1. User signs in to the Studio (`homegames.io/studio`). On first studio action the
+   API lazily provisions them a **Forgejo account** (username = their internal
+   `userId`; password derived by HMAC from `FORGEJO_USER_SECRET`).
+2. "New Game" → API creates a **Forgejo repo** (`<userId>/<repo>`), commits a
+   GPLv3 `LICENSE` + a chosen starter template, and a `games` record in Mongo.
+3. Editing in the Studio writes files via the API → Forgejo commits (the **Save
+   Version** path). They can Preview (a real session of the working tree), use
+   **AI Edit**, set Description/Thumbnail in **Settings**, etc.
+4. They can also `git clone` the repo (Settings → Clone) and push from the CLI.
+
+**Publish pipeline:**
+5. **Publish** (or a Forgejo push webhook) → the API enqueues a job on RabbitMQ.
+   Webhooks are HMAC-verified (`FORGEJO_WEBHOOK_SECRET`).
+6. The **API worker** (`api/worker.js`) consumes `publish_requests` and validates
+   the target commit:
+   - `index.js` exists; a **GPLv3 LICENSE** matches; size limits OK.
+   - **AST scan** (`ast-scanner.js`) every `.js`: no banned `require`s (fs, net,
+     child_process, …), no `eval`/`Function`, no dynamic `require`/`import`, etc.
+   - **Docker validation** (`validateGame`): load the class, check `metadata()`
+     + `squishVersion`, instantiate, run ~5s in a **no-network, read-only**
+     container; collect asset ids.
+   - **NSFW**: the game's assets already carry an `nsfw` flag (set at upload —
+     see flow 6); if any are flagged, the version is marked nsfw.
+7. On success it writes a `gameVersions` record with `published: true`
+   (+ `commitSha`). The game is now in the catalog and launchable; sessions run
+   that exact pinned commit.
+
+> Trust boundary: publishing **is** running attacker-controlled code. The AST scan
+> is a filter; the Docker container is the real boundary. See `security_notes.md`.
+
+---
+
+## 3. Developer signup + email verification
+
+1. Studio signup form posts `{ displayName, email, password }` to `/auth/signup`.
+2. API creates a user: generated internal **`userId`** (canonical identity),
+   separate **immutable `displayName`**, `verified: false`, a hashed **6-digit
+   code** (24h expiry). A JWT is returned (they're logged in but unverified).
+3. SES emails the **code** (not a link — avoids email-client prefetch consuming
+   it).
+4. In the Studio, the unverified banner takes the code → `POST /auth/verify`
+   (authenticated, scoped to the user) → `verified: true`.
+5. **Gating:** unverified users can browse/edit but the API blocks the
+   abuse-surface routes (`requiresVerified`): create game, save, publish, AI edit,
+   asset upload, thumbnail. Playing/browsing is fully anonymous and ungated.
+
+Forgot password (`/auth/forgot` → `/auth/reset`) mirrors this: anti-enumeration
+(always 200), 8-char emailed code, 1h expiry, rate-limited; standalone page at
+`/reset-password`.
+
+---
+
+## 4. Asset upload + moderation
+
+1. Studio Assets workspace → Upload/Draw/Record/Keyboard → `POST /asset`.
+2. The API stores asset metadata in `assets` and binary data in `documents`
+   (MongoDB Binary), and **synchronously classifies the image** in-process
+   (`nsfw.js`, TensorFlow `nsfwjs`); the `nsfw` flag is saved on the asset.
+3. Assets are served back at `/assets/:id` and referenced from games by id.
+4. Admins moderate via `/admin` (delete asset, flag/unflag NSFW). Publishing a
+   game inherits its assets' NSFW status.
+
+---
+
+## 5. Moderation / admin
+
+1. Admin (a user with `isAdmin: true` in Mongo — set manually to bootstrap) opens
+   `/admin`.
+2. The console lists/searches **users / games / assets** (paginated), shows
+   **stats**, **publish requests** (approve/reject), and **support messages**
+   (acknowledge) — all gated server-side on `isAdmin`.
+3. **Delete user** (`DELETE /admin/developers/:id`) cascades: their Forgejo
+   repos, the Forgejo account, search index entries, and all Mongo data (games,
+   versions, publishRequests, builds, assets, documents, user). One click removes
+   everything they made.
+
+---
+
+## 6. AI "edit my game" (LLM)
+
+1. Studio → AI Edit → `POST /studio/games/:id/llm-modify` with a prompt; the API
+   enqueues an `LLM_REQUEST` on RabbitMQ.
+2. The **Mac Studio worker** pulls the job, the MLX model server rewrites
+   `index.js` grounded by the **authoring guide** (system prompt), with
+   validation-error retries.
+3. The worker posts the result back to the API (auth'd by `LLM_WORKER_SECRET`);
+   the Studio polls status and drops the rewrite into the editor as an **unsaved
+   change** for the user to review + save.
+4. If the Mac is offline, jobs simply wait — nothing else is affected.

package/docs/INFRA.md

@@ -0,0 +1,111 @@
+# Homegames — Infrastructure
+
+What physically runs where, the domains, ports, and secrets. Design principle:
+**keep it runnable on a single box** so others can self-host the whole thing
+without orchestration. `> TODO: confirm` marks things to verify against the live
+environment.
+
+---
+
+## Hosts
+
+### 1. The single EC2 instance (the backend)
+Everything below runs on **one EC2 host**, on purpose (simplest possible to run):
+
+- **API** (`api.homegames.io`) — the Node monolith (`api/`). Also embeds the
+  **NSFW model** in-process (TensorFlow `nsfwjs`).
+- **API worker** — `api/worker.js`, the publish-validation consumer.
+- **homegames-core** + **Docker** — game sessions, each in a `homegames-runner`
+  container. **Planned split:** move homegames-core (and its Docker host duty)
+  onto its **own instance** for scalability, keeping it separate from the API.
+  This is the one intended departure from single-host.
+- **MongoDB** — all app data.
+- **RabbitMQ** — job queues (port 5672).
+- **Forgejo** — git server (port 3000). `api/config.js` currently hardcodes
+  `FORGEJO_URL = 'http://52.32.110.71:3000'` → that IP is the EC2 host.
+  `> GOTCHA`: this is a hardcoded IP, not config/DNS — update it if the instance
+  IP changes, and ideally move it to an env var.
+
+### 2. Mac Studio (the LLM worker) — Joseph's personal machine, at home
+- Runs `worker/` (Node `index.js` + Python MLX `llm/model_server.py`). MLX
+  requires Apple Silicon, which is why this is not on EC2.
+- **Pulls LLM jobs from the EC2's RabbitMQ** (`amqp://api.homegames.io:5672`) and
+  posts results back to the API. AWS/networking was configured so the Mac can
+  reach the queue. `> TODO: confirm` exactly how (security-group allowance for the
+  Mac's IP to 5672? VPN?).
+- If this machine is off, "AI edit" requests just queue and wait — nothing else
+  is affected.
+
+### 3. homegames.io (the website) — AWS S3 + CloudFront
+- Static hosting for the site, Studio, Admin, client bundle, and assets like the
+  authoring guide. `> TODO: confirm` the exact deploy story (see OPERATIONS.md —
+  `deploy.sh` only pushes `bundle.js`; need to confirm how the HTML pages,
+  `studio.js`, `admin.*`, `reset-password.*`, and `/authoring-guide.md` reach
+  prod, i.e. whether CloudFront's origin is S3 or the EC2 `app.js`).
+
+---
+
+## Domains / DNS
+
+- **`homegames.io`** — the website (S3/CloudFront).
+- **`api.homegames.io`** — the API; also the RabbitMQ host (`:5672`), Homenames,
+  and asset serving (`/assets/...`). `> TODO: confirm` it points at the EC2.
+- **`homegames.link` / `public.homegames.link`** — the **relay** for the old
+  self-hosted model (exposing a home instance to the public internet without
+  port-forwarding). It worked but is **not maintained** now that the hosted
+  service exists. Code references remain (`LINK_PROXY_URL`, port 81/82) but treat
+  it as legacy unless revived.
+- `> TODO: confirm` Route53 zones and the asset/cert domains (`homegames.link`
+  cert domain appears in config).
+
+---
+
+## Ports (on the EC2 host)
+
+| Port | Service | Notes |
+|------|---------|-------|
+| 80 / 443 | API (and/or web) | `> TODO: confirm` TLS termination (in-process? nginx? CloudFront?) |
+| 3000 | Forgejo | hardcoded in `api/config.js` |
+| 5672 | RabbitMQ | the Mac worker connects here |
+| 27017 | MongoDB | `> TODO: confirm` |
+| 7400 | Homenames | session/naming registry (`HOMENAMES_PORT`) |
+| 8300–8400 | game sessions | per-session container ports (`GAME_SERVER_PORT_RANGE`) |
+| 7001 / 9801 | self-host home port | legacy/self-host (`HOME_PORT`) |
+
+---
+
+## Secrets & credentials inventory
+
+All currently provided via environment to the relevant service. **Bus-factor: know
+where these are set** (`> TODO: confirm` — systemd unit `Environment=`/EnvironmentFile,
+a `.env`, AWS SSM, etc.).
+
+- **`JWT_SECRET`** (api) — signs user JWTs. If lost/rotated, everyone is logged out.
+- **`FORGEJO_USER_SECRET`** (api) — HMAC key from which **every user's Forgejo
+  password is derived**. If lost, you can't reproduce users' git credentials;
+  rotating it requires re-syncing all users' Forgejo passwords
+  (`rotate-forgejo-secret.js`).
+- **`FORGEJO_WEBHOOK_SECRET`** (api + Forgejo) — verifies push webhooks.
+- **Forgejo admin token** — the API does all Forgejo ops with an admin token.
+  `> TODO: confirm` where it's stored.
+- **`LLM_WORKER_SECRET`** (api + Mac worker) — authenticates the Mac worker
+  posting results back to the API.
+- **AWS credentials / IAM** — EC2 instance role (Route53, SES, possibly S3); the
+  Mac's AWS config for queue access. `> TODO: confirm` the IAM role's exact
+  permissions (least privilege — see security_notes.md re: IMDS).
+- **SES** — `SES_FROM_ADDRESS` (verified identity), `SES_REGION`; account must be
+  out of the SES sandbox for public email.
+- **Mongo** — `DB_USERNAME` / `DB_PASSWORD` (if auth enabled).
+- **TLS certs** — `> TODO: confirm` (Let's Encrypt? CloudFront-managed? the
+  `acme-client` dep in the worker suggests ACME somewhere).
+
+---
+
+## squish version aliasing (deploy-relevant)
+
+`squishjs` is published under many npm aliases (`squish-135`, `squish-138`,
+`squish-140`, …) so every game keeps running on the exact version it declared.
+The map is `homegames-common/game-loader.js → squishMap`. Adding a squish feature
+= publish a new version + add the alias in **every consumer** (`api`,
+`homegames-core`, `homegames-client`, `homegames-web`, `homegamesio`) and the map.
+The image-crop / `getView` work lives in **`squish-140`**.

package/docs/OPERATIONS.md

@@ -0,0 +1,121 @@
+# Homegames — Operations / Runbook
+
+How to deploy, restart, observe, and recover. `> TODO: confirm` marks gaps to fill
+in with current practice.
+
+---
+
+## The host
+
+The EC2 backend runs its services under **systemd**. Manage with `systemctl`,
+read logs with `journalctl`.
+
+```bash
+# status / restart / logs (service names: > TODO confirm exact unit names)
+systemctl status  homegames-core api homegames-worker
+systemctl restart api
+journalctl -u api -f                # follow API logs
+journalctl -u homegames-core -f
+journalctl -u homegames-worker -f
+```
+
+Services (one host today): **api**, **homegames-core**, **the API worker**, plus
+**mongod**, **rabbitmq-server**, **forgejo**, and **docker**.
+`> TODO: confirm` the exact systemd unit names and whether Mongo/Rabbit/Forgejo are
+distro packages or also custom units.
+
+---
+
+## Deploying / updating
+
+### API, homegames-core, API worker (on the EC2 host)
+Current practice (`> TODO: confirm` precise steps):
+```bash
+cd <repo> && git pull
+npm install            # if deps changed
+systemctl restart <service>
+journalctl -u <service> -n 100 --no-pager   # verify it came up
+```
+- After changing **homegames-common**, dependents that pin it via `file:` link
+  pick it up on `npm install`; restart them.
+- After changing the **Docker runner** (`homegames-core/docker/`), rebuild the
+  `homegames-runner` image (the session manager can build it on boot if
+  `dockerImageDir` is set; otherwise rebuild manually).
+
+### Website (homegames.io — S3/CloudFront)
+- `homegamesio/deploy.sh` currently does:
+  `aws s3 cp bundle.js s3://homegames.io/bundle.js` + a CloudFront invalidation.
+- `> TODO: CONFIRM (important)`: that script only pushes `bundle.js`, but the site
+  also serves `index.html`, `studio.html`/`studio.js`, `admin.html`/`admin.js`,
+  `reset-password.*`, `catalog.html`, etc., and `/authoring-guide.md`. **How do
+  those reach production?** Either CloudFront's origin is the EC2 `app.js`
+  (so HTML routes are dynamic), or all files must be `aws s3 sync`'d and the
+  routing is S3/CloudFront behaviors. **This must be nailed down** — recent
+  studio/admin/reset/authoring-guide changes only go live once this path is
+  correct. (If S3-static, `deploy.sh` needs to sync those files too; if the EC2
+  is the origin, `app.js` routes are what matter and `deploy.sh` is incomplete.)
+
+### LLM worker (Mac Studio)
+- Pull `worker/`, `npm install`, ensure the Python venv (`worker/llm/env`) +
+  model are present, run `worker/index.js` (it spawns the MLX model server).
+  `> TODO: confirm` how it's kept running (launchd? a `run.sh` in tmux? manual?)
+  and how it's updated.
+- It needs `homegames-common` installed (`npm install`) so it can resolve the
+  authoring-guide path it feeds the model.
+
+### Publishing a new squish version
+1. Bump + `npm publish` `squishjs`. 2. Add the alias (`squish-<v>`) to **every**
+consumer's `package.json` and to `homegames-common/game-loader.js → squishMap`.
+3. `npm install` + restart consumers; rebuild the client bundle + the runner image.
+
+---
+
+## Bootstrapping / common tasks
+
+- **Make someone an admin:** set `isAdmin: true` on their `users` doc directly in
+  Mongo (there is intentionally no self-serve admin grant):
+  `db.users.updateOne({ displayName: "X" }, { $set: { isAdmin: true } })`.
+- **Wipe/reset:** the user model changed (internal id + email); a fresh start
+  means clearing `users` (and dependent collections).
+- **SES out of sandbox:** required before verification/reset emails can go to
+  arbitrary addresses; set `SES_FROM_ADDRESS`/`SES_REGION`.
+
+---
+
+## Backups & disaster recovery
+
+`> TODO: CONFIRM` — define and verify these, they're the bus-factor core:
+- **MongoDB** — is there a scheduled `mongodump` / snapshot? Where to?
+- **Forgejo** — game source lives here; is the Forgejo data dir / repos backed up
+  (or the EBS volume snapshotted)?
+- **Assets** — binaries are in Mongo `documents`, so covered by the Mongo backup
+  (confirm).
+- **Secrets** — where is the canonical copy of `JWT_SECRET`,
+  `FORGEJO_USER_SECRET`, etc. so the host can be rebuilt? (Losing
+  `FORGEJO_USER_SECRET` orphans every user's git credentials.)
+- **EBS snapshots** of the single host would capture Mongo + Forgejo + configs in
+  one shot — `> TODO` confirm a snapshot schedule exists.
+
+---
+
+## Failure playbook
+
+| Symptom | Likely cause / check |
+|---------|----------------------|
+| Games won't start / blank | homegames-core or Docker down (`systemctl status docker homegames-core`). **Note:** the session manager falls back to in-process `fork()` if Docker is unavailable — for the public host this is a security risk; prefer fail-closed (see security_notes.md). |
+| Publishes stuck in PENDING | API worker down, or RabbitMQ down (`systemctl status homegames-worker rabbitmq-server`); check `journalctl -u homegames-worker`. |
+| "AI edit" never completes | Mac Studio worker offline or can't reach RabbitMQ. Safe to ignore short-term. |
+| Verification / reset emails not arriving | SES in sandbox, `SES_FROM_ADDRESS` unset, or DKIM/SPF missing. With SES unset, the API logs the code instead of sending. |
+| Site changes not live | the homegames.io deploy path (see TODO above) — invalidate CloudFront / sync S3. |
+| Forgejo errors on publish/clone | Forgejo down or the hardcoded `FORGEJO_URL` IP changed (`api/config.js`). |
+| Login broken for everyone | `JWT_SECRET` changed/lost. |
+
+---
+
+## Security posture (pointer)
+
+The publish pipeline runs untrusted code; containment is the real boundary. Before
+scaling or hardening, read **`homegames-core/../security_notes.md`** (Docker
+fail-closed, IMDS/credential exposure from session containers, network egress,
+least-privilege IAM, validation-vs-runtime parity). The single-host design means a
+container escape reaches everything — weigh that as usage grows.