# AGENTS.md — DivaCode

## Quick start

```bash
# build
make build                    # go build -o build/divad ./cmd/divad

# run (llama.cpp server must be on :8080)
make run                      # build + run

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

## Architecture

```
cmd/divad/main.go            # entrypoint: wires agent, llama, companion, TUI, API, scheduler
internal/agent/              # core loop: message → memory search → prompt → llama.cpp → save → respond
internal/agent/scheduler.go  # autonomous tick: mood check, diary write, proactive message
internal/companion/          # orchestrates personality, relationship, reflection, mood, prompt builder
  engine.go                  # BuildPrompt: assembles dynamic prompt from all sub-engines
  personality.go             # 5 bounded traits in SQLite (humor, curiosity, playfulness, formality, affection)
  relationship.go            # familiarity, trust, shared topics, inside jokes
  reflection.go              # diary entries, observations
  promptbuilder.go           # generates dynamic system prompt section
  mood.go                    # mood derivation from recent interaction + energy level
internal/memory/             # RAG store + self-memory (promises, strategies, mistakes)
internal/llama/client.go     # llama.cpp HTTP client (POST /completion, POST /embedding, GET /health)
internal/storage/            # SQLite wrapper, auto-creates data/ directory, auto-migrates on startup
internal/log/handler.go      # custom slog: [LEVEL] [TIME] [FILE:LINE] message key=val
internal/tools/              # MCP tool registry + builtins (web_fetch, web_search stub)
internal/channel/            # Bubble Tea TUI + Matrix adapter (stub)
  tui.go                     # chat UI: viewport + input bar, Ctrl+C/Ctrl+Q to quit
internal/config/config.go    # std lib os.Getenv only (no third-party config libs)
pkg/types/types.go            # Message, Role, Mood, ToolCall types
pkg/personality/traits.go     # TraitValue, RelationshipMetrics, DiaryEntry, Observation types
```

## Key constraints

- **Module path**: `git.db123.ir/db123/divacode` — private Gitea. Set `GOPRIV=git.db123.ir GONOSUMDB=git.db123.ir GONOSUMCHECK=git.db123.ir GODIRECT=git.db123.ir GOPROXY=https://proxy.golang.org,direct` for `go mod tidy` and `go build`.
- **Database**: modernc.org/sqlite (pure Go, no CGO). Schema in `internal/storage/migrations.go` — 15 tables across two schema groups. `data/` dir auto-created on startup.
- **llama.cpp**: required at runtime, connected via HTTP. 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**: std lib `net/http`, enabled via `API_ENABLED=true`. Endpoints: `POST /v1/chat`, `POST /v1/conversations`, `GET /health`.
- **TUI quirks**: Bubble Tea with `tea.WithAltScreen()`. Keys: enter to send, backspace to edit, Ctrl+C/Ctrl+Q to quit.
- **OpenCode permissions**: `bash` commands need approval (ask mode), `git push*` and `rm -rf*` are denied.

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

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

## Project files layout

```
cmd/divad/main.go          # single entrypoint
internal/                   # all app logic (unexported)
  agent/                    # two files: agent.go, scheduler.go
  channel/                  # two files: tui.go, matrix.go
  companion/                # six files: engine.go + five sub-engines
  config/                   # one file
  llama/                    # one file
  log/                      # one file
  memory/                   # two files
  storage/                  # two files: sqlite.go, migrations.go
  tools/                    # two files: registry.go, builtin.go
pkg/                        # shared types (exported if needed elsewhere)
```

## Docker

```bash
docker compose up -d        # starts divacode agent only (llama.cpp runs externally)
```

Override variables via `.env` or environment:

```bash
LLAMACPP_URL=http://host.docker.internal:8080 docker compose up
```