Prepare public repo docs and browser checks

Author: Hartwich

AGENTS.md

@@ -21,6 +21,7 @@ This file is for AI coding agents and humans using them.
 - Optional game list: `config/known-games.json`
 - Local game generator: `scripts/local-games.mjs`
 - Virtual controller helper for AI browser checks: `scripts/virtual-controllers.mjs`
+- Host DEV automation bridge for browser checks: `apps/host/src/app/appBootstrap.ts`
 - Catalog: `packages/game-core/src/catalog/gameCatalog.ts`
 - Shared protocol exports: `packages/protocol/src/index.ts`
 - Room lifecycle: `apps/server/src/rooms/roomLifecycle.ts`

CONTRIBUTING.md

@@ -27,16 +27,9 @@ If those terms do not work for you, please discuss before contributing.
 
 All games are currently alpha. Balance, pacing, scoring, and content may change substantially, and contributions that make the games easier to understand, fairer, or more fun are welcome.
 
-New or changed games usually need updates in all of these places:
-
-- `packages/game-core/src/catalog/gameCatalog.ts`
-- `packages/game-core/src/catalog/i18n/gameTexts.ts`
-- `packages/protocol/src/games/*`
-- `apps/server/src/game-engine/gameRegistry.ts`
-- `apps/server/src/games/*`
-- `apps/host/src/games/*`
-- `apps/controller/src/controller-ui/games/*`
-- docs
+Games live in optional repos under `local-games/` during local development. A game repo owns its server logic, protocol types, host scene, controller model, assets, manifest, README, and package entrypoints.
+
+The Platform owns common room lifecycle, generated optional game registries, reusable controller layouts, generic setup rendering, and shared DTO/socket contracts. Add a game to `config/known-games.json`, then run `npm run games:sync-local` so the generated registries import only locally available games.
 
 The server must remain authoritative. Controllers should send input, not decide winners. Before adding a controller layout, check whether an existing layout can be reused or extended.
 

apps/host/src/app/appBootstrap.ts

@@ -6,7 +6,7 @@ import { mountFullscreenOverlay } from "./fullscreenOverlay.js";
 import { mountScreenWakeLock } from "./screenWakeLock.js";
 import { mountBackgroundMusic } from "./backgroundMusic.js";
 import { createHostRouter } from "./router.js";
-import { HostSocketClient } from "./hostSocketClient.js";
+import { HostSocketClient, type HostAppState } from "./hostSocketClient.js";
 import { mountJoinOverlay } from "./joinOverlay.js";
 import {
   applyHostFps,
@@ -21,6 +21,36 @@ import { RoundIntroScene } from "../scenes/RoundIntroScene.js";
 import { ScoreboardScene } from "../scenes/ScoreboardScene.js";
 import { externalHostScenes } from "../games/.generated/externalGames.js";
 
+interface HostAutomationBridge {
+  getState: () => HostAppState;
+  kickPlayer: (playerId: string) => void;
+  returnToGameSelection: () => void;
+  selectGame: (gameId: string) => void;
+  sendGameHostAction: (gameId: string, action: unknown) => void;
+  startRound: () => void;
+}
+
+declare global {
+  interface Window {
+    __openPartyLabHost?: HostAutomationBridge;
+  }
+}
+
+function exposeHostAutomationBridge(hostClient: HostSocketClient): void {
+  if (!import.meta.env.DEV) {
+    return;
+  }
+
+  window.__openPartyLabHost = {
+    getState: () => hostClient.getState(),
+    kickPlayer: (playerId) => hostClient.kickPlayer(playerId),
+    returnToGameSelection: () => hostClient.returnToGameSelection(),
+    selectGame: (gameId) => hostClient.selectGame(gameId),
+    sendGameHostAction: (gameId, action) => hostClient.sendGameHostAction(gameId, action),
+    startRound: () => hostClient.startRound()
+  };
+}
+
 export function bootstrapHostApp(): Phaser.Game {
   const serverUrl = import.meta.env.VITE_SERVER_URL ?? "http://localhost:3000";
   const hostClient = new HostSocketClient(serverUrl);
@@ -58,6 +88,7 @@ export function bootstrapHostApp(): Phaser.Game {
   mountFullscreenOverlay(hostClient);
   mountScreenWakeLock();
   mountBackgroundMusic(hostClient);
+  exposeHostAutomationBridge(hostClient);
   hostClient.connect();
 
   return game;

docs/architecture.md

@@ -10,8 +10,8 @@ Open Party Lab is a TypeScript npm-workspace monorepo for local browser party ga
 
 ## Shared Packages
 
-- `packages/protocol`: event names, client/server event payloads, DTOs, game-specific payloads
-- `packages/game-core`: game manifests, catalog, localization hooks, round phase helpers, shared gameplay contracts
+- `packages/protocol`: event names, client/server event payloads, and shared DTOs
+- `packages/game-core`: game manifests, layout keys, round phase helpers, and shared gameplay contracts
 - `packages/ui-kit`: shared UI tokens
 - `packages/utils`: generic utilities
 
@@ -21,7 +21,7 @@ Open Party Lab is a TypeScript npm-workspace monorepo for local browser party ga
 2. Controllers send intent; they do not decide outcomes.
 3. Host scenes render state; they do not own game rules.
 4. Protocol types are the contract between all apps.
-5. New games should be additive: manifest, server implementation, host scene, controller model, registry entries, docs.
+5. New games should live in optional game repos and expose only the documented package entrypoints.
 
 ## Runtime Flow
 
@@ -56,9 +56,10 @@ Game-specific state should fit inside this lifecycle unless there is a strong re
 
 Main registry files:
 
-- `packages/game-core/src/catalog/gameCatalog.ts`
+- `config/known-games.json`
+- `scripts/local-games.mjs`
 - `apps/server/src/game-engine/gameRegistry.ts`
 - `apps/host/src/games/registry.ts`
 - `apps/controller/src/controller-ui/games/registry.tsx`
 
-If a game is added or removed, check all of them.
+`npm run games:sync-local` generates optional registry imports from the local repos it finds. Missing optional game repos are normal and must not break `dev`, `typecheck`, or `build`.

docs/project-status.md

@@ -17,6 +17,7 @@ Platform:
 - host controls for language, FPS, and player moderation outside active rounds
 - optional local game-repo discovery through `npm run games:list` and `npm run games:sync-local`
 - virtual controller helper for AI browser checks through `npm run ai:controllers`
+- host DEV automation bridge for browser checks exposed only by the Vite dev host
 
 Optional local game repos:
 

docs/protocol.md

@@ -40,4 +40,6 @@ The shared protocol lives in `packages/protocol`.
 
 ## Game Payloads
 
-Game-specific types live in `packages/protocol/src/games/*`. When a game adds public state, controller state, host actions, or inputs, define those contracts there and export them from `packages/protocol/src/index.ts`.
+Game-specific types belong in each optional game repo under its `./protocol` package entrypoint. The Platform should import only public game package entrypoints generated by `npm run games:sync-local`, not private files from a game repo.
+
+Some legacy shared layout models still reference older protocol types while the Platform keeps those reusable controller layouts. Do not add new game-specific protocol files to `packages/protocol` without maintainer approval.

docs/repository-descriptions.md

@@ -0,0 +1,55 @@
+# Repository Descriptions
+
+Short descriptions and topics for GitHub repository metadata.
+
+## Tap Race
+Description: Fast tap-mash race for Open Party Lab where players sprint by tapping their phone controller.
+Topics: open-party-lab party-game browser-game phaser typescript local-multiplayer tap-race
+
+## Pantomime
+Description: Charades-style Open Party Lab game where one player performs prompts while the others guess.
+Topics: open-party-lab party-game browser-game phaser typescript local-multiplayer charades
+
+## Air Hockey
+Description: Two-player arcade air hockey for Open Party Lab with phone joystick controls.
+Topics: open-party-lab party-game browser-game phaser typescript local-multiplayer air-hockey
+
+## Tabu
+Description: Taboo-inspired word explanation game for Open Party Lab with team and party flow.
+Topics: open-party-lab party-game browser-game phaser typescript local-multiplayer word-game
+
+## Imposter
+Description: Social deduction prompt game for Open Party Lab where players identify the bluffing player.
+Topics: open-party-lab party-game browser-game phaser typescript local-multiplayer social-deduction
+
+## Schaetzorama
+Description: Colorful estimation quiz for Open Party Lab with numeric, ranking, and assignment questions.
+Topics: open-party-lab party-game browser-game phaser typescript local-multiplayer quiz-game
+
+## Light Trails
+Description: Realtime trail-survival arena game for Open Party Lab with compact phone steering.
+Topics: open-party-lab party-game browser-game phaser typescript local-multiplayer arcade
+
+## Drift Racer
+Description: Arcade drift racing game for Open Party Lab with phone racing controls and shared host action.
+Topics: open-party-lab party-game browser-game phaser typescript local-multiplayer racing-game
+
+## Word Tiles
+Description: Shared word-board tile game for Open Party Lab with phone rack controls and premium fields.
+Topics: open-party-lab party-game browser-game phaser typescript local-multiplayer word-game
+
+## Zeichnen & Erraten
+Description: Drawing and guessing party game for Open Party Lab with phone drawing controls and word categories.
+Topics: open-party-lab party-game browser-game phaser typescript local-multiplayer drawing-game
+
+## Arena Survivor
+Description: Co-op arena survival game for Open Party Lab with character choices, waves, and difficulty setup.
+Topics: open-party-lab party-game browser-game phaser typescript local-multiplayer arena-survival
+
+## MinionsTD
+Description: Competitive tower-defense game for Open Party Lab where players build towers and send minions.
+Topics: open-party-lab party-game browser-game phaser typescript local-multiplayer tower-defense
+
+## Chaos-Kommando
+Description: Turn-based cartoon artillery game for Open Party Lab with mercenaries, wild weapons, and destructible terrain.
+Topics: open-party-lab party-game browser-game phaser typescript local-multiplayer artillery-game