# AGENTS.md — DivaCode

## Commands

```bash
make all         # lint → vet → build
make build       # go build -o build/divad ./cmd/divad
make run         # build + run (needs llama.cpp on :8080)
make test        # go test -race -count=1 ./...
make lint        # golangci-lint run ./...
make vet         # go vet ./...
make tidy        # go mod tidy
make clean       # rm -rf build/
```

Private proxy for deps:

```bash
GONOSUMDB=git.db123.ir GONOSUMCHECK=git.db123.ir GOPRIV=git.db123.ir \
GOPROXY=https://proxy.golang.org,direct go vet ./...
```

## Architecture

| Layer      | Dir                              | Role                                                                         |
| ---------- | -------------------------------- | ---------------------------------------------------------------------------- |
| Entrypoint | `cmd/divad/main.go`              | Wires agent, llama, companion, TUI, API, scheduler                           |
| Agent      | `internal/agent/`                | Message loop: receive → memory search → prompt → llama → save → respond      |
| Companion  | `internal/companion/`            | Personality (5 traits), relationship, reflection, mood, prompt builder       |
| Memory     | `internal/memory/`               | RAG store + self-memory (promises, strategies)                               |
| Inference  | `internal/llama/`                | llama.cpp HTTP client (`POST /completion`, `POST /embedding`, `GET /health`) |
| Storage    | `internal/storage/`              | SQLite wrapper, auto-creates `data/`, auto-migrates on startup               |
| Channel    | `internal/channel/`              | Bubble Tea TUI + Matrix stub                                                 |
| Tools      | `internal/tools/`                | MCP tool registry + builtins (`web_fetch`, `web_search` stub)                |
| Config     | `internal/config/`               | All env vars via std lib `os.Getenv` only                                    |
| Types      | `pkg/types/`, `pkg/personality/` | Shared data types                                                            |

## Key constraints

- **Module**: `git.db123.ir/db123/divacode` — private Gitea. Set `GOPRIV`, `GONOSUMDB`, `GONOSUMCHECK` for `go mod tidy`/`go build`.
- **Database**: `modernc.org/sqlite` (pure Go, no CGO). **12 tables** across two schema groups in `internal/storage/migrations.go`. Two DB files: `divacode.db` (conversations, messages, context_state, memories) and `companion.db` (personality, relationship, reflection, self-memory). `data/` dir auto-created on startup.
- **Migrations** are code-internal constants; the `migrations/` directory is empty.
- **llama.cpp** required at runtime. Default `http://localhost:8080`. Agent exits if health check fails.
- **Logging**: `[LEVEL] [TIME] [FILE:LINE] message key=val`. Set `LOG_LEVEL=DEBUG` for verbose output.
- **HTTP API** (enabled via `API_ENABLED=true`): std lib `net/http` only. Endpoints: `GET /health`, `POST /v1/chat`, `POST /v1/conversations`.
- **TUI**: Bubble Tea with `tea.WithAltScreen()`. Enter to send, backspace to edit, Ctrl+C/Ctrl+Q to quit.
- **Formatters** in `opencode.json`: `gofmt` for `.go`, `prettier` for everything else. LSP enabled.
- **Config**: all via env vars, never third-party config libs. See `.env.example` for all knobs.

## Conventions (from "The Holy Code Bible")

| Context                   | Rule                                            |
| ------------------------- | ----------------------------------------------- |
| Exported Go identifiers   | PascalCase                                      |
| Unexported Go identifiers | camelCase                                       |
| Go file names             | `snake_case.go`                                 |
| Error wrapping            | `fmt.Errorf("context: %w", err)`                |
| Error checking            | always check, no silent discards                |
| Config                    | env vars only via `os.Getenv`                   |
| HTTP API                  | std lib `net/http` only, no third-party routers |