# KIS-TOiR — Agent Operating Rules

Read this file at the start of every session before reading any other file.

---

## What this repository is

KIS-TOiR is a fullstack CRUD application (NestJS backend + React Admin frontend)
for equipment maintenance management (Техническое обслуживание и ремонт).

Generation is driven by a single authoritative source file:

- `domain/toir.api.dsl` — the complete API contract: enums, DTOs, endpoints, HTTP methods, pagination

---

## Source-of-truth hierarchy

### Tier 1 — authoritative (hand-authored; never overwritten by generation)

| File                    | Authoritative for                                                                                                                                                                                        |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `domain/*.api.dsl`      | Enums, DTO shapes per operation, nullability, HTTP verb+path per endpoint, endpoint names, pagination contracts. Single source of truth. Drives: NestJS modules + React Admin resources + Prisma schema. |
| `prompts/*.md`          | Auth rules, runtime rules, framework scaffold rules, Prisma rules, validation rules, generation policy, naming conventions.                                                                              |
| `AGENTS.md` (this file) | Agent workflow, mutation boundaries, verification contract.                                                                                                                                              |

### Tier 2 — deterministic derivative (generated by script; never edited manually)

| File               | Generated from     | Command                        |
| ------------------ | ------------------ | ------------------------------ |
| `api-summary.json` | `domain/*.api.dsl` | `npm run generate:api-summary` |

### Tier 3 — LLM-generated artifacts (never edit manually after generation)

| Zone                             | Generated from                                         |
| -------------------------------- | ------------------------------------------------------ |
| `server/src/modules/<entity>/`   | `domain/*.api.dsl` + `prompts/backend-rules.md`        |
| `client/src/resources/<entity>/` | `domain/*.api.dsl` + `prompts/frontend-rules.md`       |
| `server/src/app.module.ts`       | Module registrations derived from api.dsl api blocks   |
| `client/src/App.tsx`             | Resource registrations derived from api.dsl api blocks |
| `server/prisma/schema.prisma`    | `domain/*.api.dsl` + `prompts/prisma-rules.md`         |
| `server/src/auth/`               | `prompts/auth-rules.md`                                |
| `client/src/auth/`               | `prompts/auth-rules.md`                                |
| `client/src/dataProvider.ts`     | `prompts/auth-rules.md`                                |
| `toir-realm.json`                | `prompts/auth-rules.md`                                |
| `docker-compose.yml`             | `prompts/runtime-rules.md`                             |
| `server/.env.example`            | `prompts/runtime-rules.md`                             |
| `client/.env.example`            | `prompts/runtime-rules.md`                             |

### Tier 4 — handwritten / framework-managed support files

- Framework scaffold: `server/nest-cli.json`, `server/tsconfig*.json`, `client/vite.config.*`, etc.

---

## Forbidden mutations during any generation run

**NEVER write to `*.dsl` files.**
They are read-only inputs. To change the API contract or domain model, edit `domain/*.api.dsl`
as a separate explicit task.

**NEVER manually edit files under `server/src/modules/` or `client/src/resources/`.**
To change generated code: update `domain/*.api.dsl` and regenerate.

**NEVER edit `server/prisma/schema.prisma` directly.**
It is LLM-generated from `domain/*.api.dsl` following `prompts/prisma-rules.md`.

---

## Generation workflow (required sequence)

1. Read `AGENTS.md` and `prompts/general-prompt.md`.
2. Read the active `api API.<EntityName>` block + its DTOs + its enums from `domain/toir.api.dsl` (entity-scoped — do not inject the full DSL as a blob).
3. Load the companion rule files required for the active stage:
   - `prompts/prisma-rules.md`
   - `prompts/backend-rules.md`
   - `prompts/frontend-rules.md`
   - `prompts/auth-rules.md`
   - `prompts/runtime-rules.md`
   - `prompts/validation-rules.md`
4. Verify or repair framework scaffolds before domain generation:
   - official Nest CLI for backend workspace creation/repair
   - official Vite React TypeScript CLI for frontend workspace creation/repair
   - official Prisma CLI when Prisma initialization or repair is required
5. Generate `server/prisma/schema.prisma` per `prompts/prisma-rules.md`.
6. Generate backend modules and registrations per `prompts/backend-rules.md`.
7. Generate frontend resources and registrations per `prompts/frontend-rules.md`.
8. Generate auth/runtime/realm artifacts per `prompts/auth-rules.md` and `prompts/runtime-rules.md`.
9. Refresh `api-summary.json` only when validation/tooling requires the auxiliary freshness artifact: `npm run generate:api-summary`.
10. Run: `node tools/validate-generation.mjs --artifacts-only`
11. Run: `npm run eval:generation`
12. Fix all failures before considering the task complete.

**Context budget rule:** Before generating any DTO or component, quote the field
definitions from the DSL api block verbatim, then generate from those quotes. This
prevents training-data contamination. See `prompts/general-prompt.md`.

---

## Type mappings

| DSL type  | Prisma type                   | TS DTO type | React Admin component         |
| --------- | ----------------------------- | ----------- | ----------------------------- |
| `uuid`    | `String @id @default(uuid())` | `string`    | `TextInput` / `TextField`     |
| `string`  | `String`                      | `string`    | `TextInput` / `TextField`     |
| `text`    | `String`                      | `string`    | `TextInput` / `TextField`     |
| `integer` | `Int`                         | `number`    | `NumberInput` / `NumberField` |
| `number`  | `Float`                       | `number`    | `NumberInput` / `NumberField` |
| `decimal` | `Decimal`                     | `string`    | `NumberInput` / `NumberField` |
| `date`    | `DateTime`                    | `string`    | `DateInput` / `DateField`     |
| `boolean` | `Boolean`                     | `boolean`   | (appropriate boolean input)   |
| enum name | enum name                     | `string`    | `SelectInput` / `SelectField` |

---

## Naming conventions

Resource name (plural, kebab-case):

- `Equipment` → `equipment` (irregular — stays as-is)
- `EquipmentType` → `equipment-types`
- `RepairOrder` → `repair-orders`
- General: PascalCase → kebab-case → append `s` (or `es` if ends in `s`; irregular cases explicit)

Default sort field (when not declared in api.dsl):
Priority: `inventoryNumber` > `number` > `code` > `name` > primary key

---

## Verification gate (two-stage)

### Stage 1 — Structural gate

```
node tools/validate-generation.mjs --artifacts-only
```

Checks: file existence, api-summary freshness, auth seam contracts, natural-key handling, realm structure, runtime contract, api.dsl coverage (backend + frontend files per entity), DTO field name coverage, **DTO class-validator decorator coverage**, **@UseGuards presence on controllers**, **frontend component type correctness**.

Full structural verification (requires installed `node_modules`):

```
node tools/validate-generation.mjs
```

### Stage 2 — Eval harness (Rule 6)

```
npm run eval:generation
```

Fixture-based semantic checks from `tools/eval/fixtures/`. Checks: correct HTTP method decorators, Content-Range header, enum filter patterns, FK reference wiring, component type correctness, class-validator decorator patterns.

See `tools/eval/README.md` for fixture authoring and eval-driven development workflow.

**Generation is incomplete unless both stages pass.**

## Pre-commit hook

Install with `npm run install-hooks`. The hook runs **both** the structural gate and
the eval harness before every commit. Commits are blocked when either fails.

---

## Auth and runtime defaults

Full auth contract: `prompts/auth-rules.md`

Working defaults (do not regress to localhost):

- Keycloak base: `https://sso.greact.ru`
- Realm/client: `toir` / `toir-frontend` / `toir-backend`
- Production frontend: `https://toir-frontend.greact.ru`
- CORS: `http://localhost:5173,https://toir-frontend.greact.ru`

---

## OpenRouter configuration

```
OPENAI_API_KEY=<openrouter-key>
OPENAI_BASE_URL=https://openrouter.ai/api/v1
OPENAI_MODEL=<model-id>
```

These variables are used by `tools/api-format-to-openapi/convert.mjs --mode llm`.

---

## Reading order for generation tasks

**Critical zone (load first, never drop):**

1. `AGENTS.md` (this file) — project governance, mutation boundaries, tier hierarchy
2. `prompts/general-prompt.md` — master orchestration prompt: mission, stage ownership, delegation model, completion criteria
3. `domain/toir.api.dsl §API.<EntityName>` — active api block only, plus its referenced DTOs and enums

**Companion zone (load when the matching stage is active):**

4. `prompts/prisma-rules.md` — Prisma schema generation details
5. `prompts/backend-rules.md` — NestJS generation details
6. `prompts/frontend-rules.md` — React Admin generation details
7. `prompts/auth-rules.md` — auth seam and realm requirements
8. `prompts/runtime-rules.md` — scaffold, env, and bootstrap requirements
9. `prompts/validation-rules.md` — success gate requirements

**Auxiliary zone (never authoritative):**

10. `api-summary.json` — optional inventory/freshness artifact for validators and supporting tooling; do not use it instead of the DSL

**Reference only (do not load proactively):**

- `domain/dsl-spec.md` — DSL syntax reference; load only if DSL is ambiguous
- `docs/generation-playbook.md` — step-by-step workflow reference
- `docs/future-work.md` — deferred items (Rules 7 and 8)