inboxer/AGENTS.md

inBOXER Agent Guidance

Reference Documents

• Master specification: PROJECT_PLAN.md (phases, architecture, guardrails)
• Live secrets: .env contains API keys & Git credentials – never commit

Repository Setup

• Use Git credentials from .env (GIT_* variables) to create remote repository
• Create exact directory hierarchy per PROJECT_PLAN.md section 2
• Binary builds to bin/inboxer, config to bin/config.yaml, prompt to bin/prompt.txt (or bin/classify_prompt.txt – see PROJECT_PLAN.md for clarification)
• Prompt file loaded at runtime – users can modify without recompiling

Development Phases

• Follow phased plan (Phase 1–4) with version tags 2026-04.1 etc.
• After each phase: update docs/CHANGELOG.md, commit, push
• Version increment pattern: 2026-04.{phase}

Dependencies & Commands

go mod init
# Key dependencies: go-imap, gorm, sqlite, slog
go test ./...          # Each function has its own *_test.go

Build & Run

• Create Makefile with targets: build, run, test (Phase 4.3)
• Final binary placed in bin/ for distribution

Architecture Notes

• Modular packages: auth, imap, ai, db, worker with focused interfaces
• Main package: orchestrator only (reads config, starts server/worker)
• Frontend: mobile‑first responsive design (Go templates + CSS)
• Database: SQLite single file with GORM
• Authentication: Email + OTP (6-digit, 10-min expiry, bcrypt storage)

Operational Guardrails

• Never delete emails – only move between IMAP folders
• AI failures: keep email in INBOX, log error, retry later
• OTP security: TLS SMTP, bcrypt storage, 10-minute expiry
• Session cookies: HttpOnly, Secure, appropriate expiry
• Test mode: Frontend toggle logs AI decisions without moving emails

Testing & Quality

• Each modular function has its own *_test.go file
• Tests can target any package in isolation
• Frontend must be usable on mobile devices

What's Not Here

• Generic Go advice, exhaustive file trees, speculative claims
• Content already covered by PROJECT_PLAN.md