git init

prompts/runtime-rules.md

@@ -0,0 +1,86 @@
+# Runtime Rules
+
+<!-- prompt-version: 2.0 -->
+<!-- applies-to: docker-compose.yml, server/.env.example, client/.env.example -->
+<!-- validated-by: tools/validate-generation.mjs §validateRuntimeContractChecks -->
+
+Use this document during the **Preparation / Discovery** and **Auth / Runtime / Realm** stages defined in `prompts/general-prompt.md`.
+
+## Purpose
+
+Define the runtime topology, environment defaults, scaffold expectations, and bootstrap sequence for a buildable generated workspace.
+
+## Mandatory Inputs
+
+- `prompts/general-prompt.md`
+- `prompts/auth-rules.md` when runtime changes affect auth defaults or seams
+- current repository runtime/auth defaults
+
+`api-summary.json` is an auxiliary artifact only. Refresh it when validator/tooling requires freshness checks or when a compact inventory helps discovery. Do not treat it as the runtime source of truth.
+
+## Expected Outputs
+
+- `docker-compose.yml`
+- `server/.env.example`
+- `client/.env.example`
+- a buildable NestJS workspace under `server/`
+- a buildable Vite React TypeScript workspace under `client/`
+- any validator-required auxiliary artifacts such as `api-summary.json`
+
+## Baseline Runtime Topology
+
+- `server/` is the backend output path
+- `client/` is the frontend output path
+- Docker scope stays PostgreSQL-only
+- Keycloak remains external to repository runtime
+- the project remains LLM-first and prompt-driven
+
+## Concrete Runtime Defaults
+
+Backend:
+
+- `PORT=3000`
+- `DATABASE_URL="postgresql://postgres:postgres@localhost:5432/toir"`
+- `CORS_ALLOWED_ORIGINS="http://localhost:5173,https://toir-frontend.greact.ru"`
+- `KEYCLOAK_ISSUER_URL="https://sso.greact.ru/realms/toir"`
+- `KEYCLOAK_AUDIENCE="toir-backend"`
+
+Frontend:
+
+- `VITE_API_URL=http://localhost:3000`
+- `VITE_KEYCLOAK_URL=https://sso.greact.ru`
+- `VITE_KEYCLOAK_REALM=toir`
+- `VITE_KEYCLOAK_CLIENT_ID=toir-frontend`
+
+## Scaffold Expectations
+
+- new or repaired backend workspaces start from the official Nest CLI
+- new or repaired frontend workspaces start from the official Vite React TypeScript CLI
+- Prisma initialization uses the official Prisma CLI when relevant
+- the LLM may customize generated code after scaffold creation, but must not replace official initialization with ad hoc file creation
+
+## Runtime Bootstrap
+
+1. import `toir-realm.json` into Keycloak
+2. start PostgreSQL with `docker compose up -d`
+3. from `server/`:
+   - repair or create the workspace with official Nest CLI if needed
+   - install dependencies
+   - run Prisma commands required by the schema stage
+   - run `npm run build`
+   - run `npm run start`
+4. from `client/`:
+   - repair or create the workspace with official Vite CLI if needed
+   - install dependencies
+   - run `npm run build`
+   - run `npm run dev`
+
+## Completion Expectations
+
+Runtime preparation is incomplete if any of the following is true:
+
+- `server/` is missing or not buildable as a NestJS workspace
+- `client/` is missing or not buildable as a Vite React TypeScript workspace
+- framework scaffolding was hand-built instead of created or repaired from official CLIs
+- shared env defaults drift from the repository auth/runtime contract
+- runtime success is claimed without actual build verification