feat: add integration tests for initialization flow

- Implemented end-to-end integration tests covering database reset, bootstrap admin creation, demo user provisioning, scenario installation, and general creation.
- Added support for deterministic seeding and auto admin general creation.
- Created a new package for integration tests with necessary configurations and scripts.
- Updated various modules to support new features, including admin user handling and scenario seeding.
- Enhanced error handling and validation in the join and orchestrator modules.

docs/integration-tests.md

@@ -0,0 +1,72 @@
+# Integration Tests (Initialization Flow)
+
+This document describes the end-to-end integration test that exercises the
+gateway, game-api, and game-engine initialization flow.
+
+## Scope
+
+The initialization integration test validates:
+
+- database reset and schema readiness
+- bootstrap admin creation
+- demo user provisioning (10 accounts)
+- scenario install for `che` with `scenario_2` and 1-minute ticks
+- deterministic seeding (via env)
+- auto admin general creation
+- general creation for demo users with constrained city selection
+- reserved turn submission (uprising, founding, appointment)
+- running three turns and validating founding outcomes
+
+The test runs real Postgres and Redis, and talks to the API servers via tRPC.
+
+## Files
+
+- `tools/integration-tests/test/initialization.test.ts`
+- `tools/integration-tests/vitest.config.ts`
+
+## Prerequisites
+
+- Postgres and Redis are running and reachable.
+- `.env.ci` is present at the repo root and contains:
+    - Postgres and Redis connection settings.
+    - `GAME_TOKEN_SECRET`, `KAKAO_REST_KEY`, `KAKAO_REDIRECT_URI`
+    - `GATEWAY_BOOTSTRAP_TOKEN`
+    - `GATEWAY_API_HOST`, `GATEWAY_API_PORT`, `GAME_API_HOST`, `GAME_API_PORT`
+    - `PROFILE=che`, `SCENARIO=2`
+- `pnpm install` and `pnpm build` have already completed.
+
+## Safety
+
+The test truncates the `public` and `che` schemas and flushes Redis. Use a
+dedicated CI/local database and Redis instance.
+
+## Running
+
+Use the root helper script:
+
+```sh
+pnpm test:integration
+```
+
+Or run the package script directly:
+
+```sh
+pnpm --filter @sammo-ts/integration-tests test:integration
+```
+
+## Environment Flags
+
+- `INTEGRATION_WORLD_SEED`: injected into world meta as `hiddenSeed` for
+  deterministic RNG.
+- `INTEGRATION_JOIN_ALLOW_CITY=true`: allows test-only city selection when
+  creating generals (still restricted to level 5/6 cities).
+
+These are loaded from `.env.ci` and can be overridden per run.
+
+## Notes
+
+- `auth.bootstrapLocal` only works when no users exist; the test resets the DB
+  to satisfy this precondition.
+- `profiles.installNow` seeds the scenario and auto-creates the admin general.
+- The test runs turn processing via `turnDaemon.run` and validates founding
+  rules at the third turn.