AGENTS.md

1# Repository Guidelines
2 
3## Project Structure & Module Organization
4- Entry point lives in `cmd/hovimestari`, wiring the CLI with Kong.
5- Domain logic sits under `internal/*`: `brief` assembles daily briefs, `importer` handles calendar/weather ingestion, `store` wraps SQLite access, and `output` manages delivery channels.
6- Shared prompt artifacts reside in `llm-shared/`; background documentation sits in `docs/`.
7- Tests stay alongside sources as `_test.go` files; builds land in `build/`, and `config.example.json` documents configurable fields.
8 
9## Build, Test, and Development Commands
10- `task build` runs lint and tests before emitting `build/hovimestari`.
11- `task run -- generate-brief` rebuilds then invokes the binary; append any CLI subcommand after `--`.
12- `task test` wraps `go test ./...`; add flags like `-race` or `-run` when needed.
13- `task lint` requires `golangci-lint` in `PATH`; install via `brew install golangci-lint` or the official script.
14- For quick iteration use `go build ./cmd/hovimestari` or `go test ./internal/...` directly.
15 
16## Coding Style & Naming Conventions
17- Always format with `gofmt` (or `goimports`); Task targets assume formatted code.
18- Keep package names aligned with directory names (e.g., `internal/weather`, `internal/output`).
19- Exported symbols use CamelCase plus short doc comments; file-level helpers stay lowerCamelCase.
20- Configuration structs belong in `internal/config`; JSON keys mirror `config.example.json` using lower_case.
21 
22## Testing Guidelines
23- Use Go's `testing` package with table-driven cases and `_test.go` suffixes.
24- Stub external services by faking interfaces in `internal/llm` or `internal/importer`; avoid live API calls.
25- Run `task test` (or `go test ./...`) before pushing; for coverage snapshots, run `go test -cover ./...`.
26 
27## Commit & Pull Request Guidelines
28- Follow Conventional Commits (`feat:`, `fix:`, `chore:`) as in `git log`; keep subjects imperative under ~72 chars.
29- Group related changes per commit and document breaking changes in the body if applicable.
30- PRs should summarize behavior changes, list validation commands, and link issues (`Fixes #12`).
31- Attach CLI transcripts or config snippets when altering user workflows or outputs.
32 
33## Configuration & Secrets
34- Use `config.example.json` as the starting point; do not commit populated `config.json`, `.env`, or `memories.db`.
35- Secrets load from `.env`, `$HOME/.hovimestari.env`, or environment variables before running `task` targets.
36- Document new configuration flags in `docs/04_configuration.md` and update sample values in `config.example.json`.
37