# Codex CLI — KIS-TOiR workspace supplement

This file supplements the repository root `AGENTS.md` with Codex-specific
operational notes. The root `AGENTS.md` is the authoritative contract —
if anything here contradicts root, root wins.

---

## Agent role summary

| Role | Config file | Sandbox | Write boundary |
|------|-------------|---------|----------------|
| `generator` | `agents/generator.toml` | workspace-write | Tier 3 generation zones |
| `explorer` | `agents/explorer.toml` | read-only | None |
| `reviewer` | `agents/reviewer.toml` | read-only | Proposes patches only |
| `docs_researcher` | `agents/docs-researcher.toml` | read-only | None |

Use `/agent generator` for implementation work. Use `/agent explorer` first for
discovery, `/agent docs_researcher` when framework or prompt patterns need
verification, and `/agent reviewer` before claiming a generation run is complete.

---

## Mutation boundary map

```
Tier 1 — Source of truth (NEVER written by any agent)
  domain/*.api.dsl              — single source of truth for all generation
  prompts/*.md                  — generation spec / rules
  AGENTS.md                     — agent operating rules
  .codex/AGENTS.md (this file)  — Codex-specific supplement

Tier 2 — Deterministic derivatives (written only by npm scripts, not by agents)
  api-summary.json              ← npm run generate:api-summary
  openapi.json                  ← npm run generate:openapi  (auxiliary)

Tier 3 — LLM-generated artifacts (written ONLY by generator agent)
  server/src/modules/<entity>/
  client/src/resources/<entity>/
  server/src/app.module.ts
  client/src/App.tsx
  server/prisma/schema.prisma   ← LLM-generated per prompts/prisma-rules.md
  server/src/auth/
  client/src/auth/
  client/src/dataProvider.ts
  toir-realm.json
  docker-compose.yml
  server/.env.example
  client/.env.example

Tier 4 — Handwritten / framework-managed support files
  framework scaffold and other manual support files outside prompt-governed outputs
```

---

## Standard generation invocation

```bash
# 1. Read AGENTS.md + prompts/general-prompt.md
# 2. Read the entity-scoped DSL block from domain/toir.api.dsl
# 3. Load only the stage-specific companion rules you need
# 4. Run generation or repair with the appropriate agent
# 5. Refresh api-summary.json only if validator/tooling expects the auxiliary freshness artifact
# 6. Verify (both stages must pass)
node tools/validate-generation.mjs --artifacts-only
npm run eval:generation
```

---

## MCP servers (project-local)

Defined in `.codex/config.toml`:

- **github** — repository access
- **context7** — library documentation lookup (use for framework questions)
- **exa** — web search
- **memory** — persistent cross-session context
- **playwright** — browser automation for smoke tests
- **sequential-thinking** — structured multi-step reasoning

Add heavier or credential-backed servers in `~/.codex/config.toml`.

---

## Validation gate

Run before every commit and after every generation:

```bash
# Stage 1 — structural gate
node tools/validate-generation.mjs --artifacts-only

# Stage 2 — eval harness
npm run eval:generation
```

The pre-commit hook (`tools/hooks/pre-commit`) runs both stages automatically
after `npm run install-hooks`.

---

## Security notes

- Never commit secrets. Use environment variables from `.env.example` templates.
- Run `npm audit` when adding new dependencies to `server/` or `client/`.
- Auth contracts live in `prompts/auth-rules.md`. Do not deviate from them.