rony-llm-agent/pkg/config/README.md

# pkg/config

> YAML configuration loading with hierarchical precedence.

## Responsibility

Resolve the agent's final configuration by combining multiple sources with a precedence order:

1. **CLI flags** (highest)
2. **Environment variables**
3. **Project config** (`./.rony.yaml`)
4. **Global config** (`~/.config/rony/config.yaml`)
5. **Embedded defaults** (lowest)

## Public API

```go
type Config struct {
    Model       string
    Persona     string
    Provider    ProviderConfig
    Tools       ToolPolicy
    Logging     LoggingConfig
    Sandbox     SandboxConfig
}

type Loader interface {
    Load(ctx context.Context, workdir string) (Config, error)
    LoadFromBytes(data []byte, source string) (Config, error)
}

type ProviderConfig struct {
    Type   string  // "openai" | "anthropic" | "ollama" | "llamacpp"
    Model  string
    APIKey string  // resolved from env if it's a reference
    Endpoint string
}

type ToolPolicy map[string]tools.Permission
```

## YAML format

```yaml
# ~/.config/rony/config.yaml
model: claude-sonnet-4.5
persona: pragmatist
provider:
  type: anthropic
  api_key_env: ANTHROPIC_API_KEY
tools:
  bash: ask
  read: allow
  write: ask
logging:
  level: info
  format: json
sandbox:
  workspace: .
  timeout_ms: 30000
```

## Environment override

```bash
RONY_MODEL=gpt-4o rony chat      # override model
RONY_LOG_LEVEL=debug rony chat   # override log level
```

## Precedence

The loader resolves in this order (highest priority first):

```
flag > RONY_* env > ./.rony.yaml > ~/.config/rony/config.yaml > defaults
```

## See also

- [pkg/agent](../agent/README.md) — Uses Config
- [pkg/llm](../llm/README.md) — ProviderConfig maps to LLMClient