# 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)