# AGENTS.md

This document defines the laws, principles, and rule sets that govern this codebase. Any agent or developer making changes has to adhere to these rules.

**Before starting off** — Read the README.md file to understand the project's goals and objectives.

---

## Agent Rules (Override Everything)

1. **No testing by yourself** — All testing is done by the team.
2. **No assumptions about code or domain logic** — Always confirm and be sure before making changes.
3. **No running scripts** — Do not run build, dev, test, or migrate scripts unless explicitly approved.
4. **No touching migration files** — Do not mess with the `migrations` sql dir, as those are generated manually via drizzle orm

5. **Log meaningful changes** — After completing any meaningful change or activity, append a numbered entry to `memory.log.md` summarizing what was done. This keeps context across sessions.

More rules are only to be added by the human, in case such a suggestion becomes viable.

---

## 1. Stack

- **Monorepo**: Turborepo + pnpm
- **Language**: TypeScript everywhere, Node >= 24
- **Apps**: `@apps/main` (SvelteKit), `@apps/frontend` (Hono), `@apps/orchestrator` (Hono)
- **Packages**: `@pkg/logic`, `@pkg/db`, `@pkg/logger`, `@pkg/result`, `@pkg/keystore`, `@pkg/settings`
- **DB**: PostgreSQL via Drizzle ORM; Redis (Valkey) via `@pkg/keystore`

---

## 2. Logic Package Conventions

All domain logic lives in `@pkg/logic` under `packages/logic/domains/<domain>/` with four files: `data.ts`, `repository.ts`, `controller.ts`, `errors.ts`. Mirror this exactly when adding a domain.

**Path aliases** (logic package only):

- `@/*` → `./*` · `@domains/*` → `./domains/*` · `@core/*` → `./core/*`

**FlowExecCtx** (`fctx`) — passed into every domain operation for tracing:

```ts
type FlowExecCtx = { flowId: string; userId?: string; sessionId?: string };
```

---

## 3. Error Handling

- Use `neverthrow` (`ResultAsync`, `okAsync`, `errAsync`) for all fallible async logic.
- `@pkg/result`'s `Result` type is **legacy** — do not reach for it primarily.
- Use `ERROR_CODES` from `@pkg/result` for all error codes.
- Use `getError()` from `@pkg/logger` when converting thrown errors into `Err` objects at boundaries.
- Use domain-specific error constructors from `errors.ts` — never ad-hoc error objects.
- Always check `result.isOk()` / `result.isErr()` before accessing `result.value`.

---

## 4. Main App Conventions (`apps/main`)

- Feature code lives in `src/lib/domains/<domain>/` — view model, components, remote functions.
- **VM pattern**: `*.vm.svelte.ts` classes own all reactive state and async flows for a screen. Pages are thin — they just mount the VM.
- **Remote functions**: `*.remote.ts` per domain. Naming: `*SQ` for queries, `*SC` for commands.
- Auth context and `fctx` are built inside remote functions from `event.locals` via `$lib/core/server.utils`.

---

## 5. Observability Convention

When adding any new operation in a repository or controller, wrap it with `traceResultAsync` from `@pkg/logic/core/observability.ts`. Keep span names descriptive and consistent (e.g. `"user.getUserInfo"`). Do not add ad-hoc spans.

---

## 6. Validation

- **Valibot** for all schemas. Types via `v.InferOutput<typeof Schema>`.
- Domain data types defined in `data.ts`. Remote function inputs validated via Valibot schemas passed to `query()` / `command()`.