# {{ .project_name }} — Instructions for Claude

## Shared Engineering Rules
Read `bible/` — shared rules for all projects (CSV, logging, DB, tables, background tasks, code style).
Start with `bible/rules/patterns/` for specific contracts.

## Project Architecture
Read `bible-local/` — project-specific architecture.
Every architectural decision specific to this project must be recorded in `bible-local/`.

---

## Quick Reference (full contracts in `bible/rules/patterns/`)

### Go Code Style (`go-code-style/contract.md`)
- Handler → Service → Repository. No SQL in handlers, no HTTP writes in services.
- Errors: `fmt.Errorf("context: %w", err)`. Never discard with `_`.
- `gofmt` before every commit.
- Thresholds and status logic on the server — UI only reflects what server returns.

### Logging (`go-logging/contract.md`)
- `slog`, stdout/stderr only. Never `console.log` as substitute for server logging.
- Always log: startup, task start/finish/error, export row counts, ingest results, any 500.

### Database (`go-database/contract.md`)
- **CRITICAL**: never run SQL on the same tx while iterating a cursor. Two-phase: read all → close → write.
- Soft delete via `is_active = false`.
- Fail-fast DB ping before starting HTTP server.
- No N+1: use JOINs or batch `WHERE id IN (...)`.
- GORM: `gorm:"-"` = fully ignored; `gorm:"-:migration"` = skip migration only.

### REST API (`go-api/contract.md`)
- Plural nouns: `/api/assets`, `/api/components`.
- Never `200 OK` for errors — use `422` for validation, `404`, `500`.
- Error body: `{"error": "message", "fields": {"field": "reason"}}`.
- List response always includes `total_count`, `page`, `per_page`, `total_pages`.
- `/health` and `/api/db-status` required in every app.

### Background Tasks (`go-background-tasks/contract.md`)
- Slow ops (>300ms): POST → `{task_id}` → client polls `/api/tasks/:id`.
- No SSE. Polling only. Return `202 Accepted`.

### Tables, Filtering, Pagination (`table-management/contract.md`)
- Server-side only. Filter state in URL params. Filter resets to page 1.
- Display: "51–100 из 342".

### Modals (`modal-workflows/contract.md`)
- States: open → submitting → success | error.
- Destructive actions require confirmation modal naming the target.
- Never close on error. Use `422` for validation errors in htmx flows.

### CSV Export (`import-export/contract.md`)
- BOM: `\xEF\xBB\xBF`. Delimiter: `;`. Decimal: `,` (`1 234,56`). Dates: `DD.MM.YYYY`.
- Stream via callback — never load all rows into memory.
- Always call `w.Flush()` after the loop.