initial commit

backend/AGENTS.md

@@ -0,0 +1,53 @@
+# Backend Agent Instructions
+
+## Stack
+
+- **Go 1.25.5**
+- **cobra** (CLI framework)
+- **logrus** (structured logging)
+- **openai-go/v3** (OpenAI API client)
+- **golangci-lint** (linting)
+
+## Commands
+
+```bash
+go build -o ./dist/aethera ./cmd
+golangci-lint run
+go test ./...
+```
+
+## Non-Negotiables
+
+- ❌ No unhandled errors - always check `err`
+- ❌ No ignored linter warnings
+- ❌ No sensitive data in logs
+- ❌ No hardcoded paths - use `path.Join`
+- ❌ No unsafe file access - use `filepath.Base`
+- ❌ Don't skip tests or linting
+
+## Code Style
+
+- tab indentation, PascalCase exports, camelCase internal
+- Error wrapping with context: `fmt.Errorf("...: %w", err)`
+- Custom error types for domain errors (e.g., `ChatNotFoundError`)
+- Struct tags for JSON with `omitempty`
+- Log with context: `log.WithField("key", val)`
+- Clean up resources with `defer`
+
+## Key Patterns
+
+- **Interfaces**: `Store` interface for swappable backends
+- **DI**: Dependencies through constructors (`New*` functions)
+- **HTTP**: Handlers receive `store.Store`, validate inputs, return proper status codes
+- **Streaming**: Use `FlushWriter` for SSE/text streams
+- **Storage**: JSON file-based (`FileStore` implementation)
+
+## What Goes Where
+
+- CLI entry: `cmd/` (main.go, config.go)
+- HTTP handlers: `internal/api/`
+- OpenAI client: `internal/client/`
+- Server setup: `internal/server/`
+- Storage interface & impl: `internal/store/`
+- Storage utilities: `internal/storage/`
+- Utilities: `pkg/` (ptr, slices)