From e570399b3e685c92e29e883d23d5b9bb338431d9 Mon Sep 17 00:00:00 2001
From: db123-ai <erfan+ai@db123.ir>
Date: Wed, 10 Jun 2026 01:00:25 +0330
Subject: [PATCH] docs: add AGENTS.md with architecture, commands, and
 conventions

---
 AGENTS.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 91 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..41eddb1
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,91 @@
+# 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
+```