# Configuration

This document describes how Geneva loads configuration values and how to override them.

## Resolution Order
Configuration is resolved in the following order. Earlier sources override later ones.

1. Overrides added with `override_config` or `override_config_kv`
2. Environment variables
3. `pyproject.toml` under the `[geneva]` table
4. Files in `./.config` or `GENEVA_CONFIG_DIR`, sorted alphabetically
5. Defaults added with `default_config`

## Sources

### Environment Variables
- Keys use double underscores to represent nesting.
- Keys are uppercased.

Example for `[geneva.test.nested_config] config.value = "42"`:

```bash
export GENEVA__TEST__NESTED_CONFIG__CONFIG__VALUE=42
```

### pyproject.toml
Geneva reads configuration from the nearest `pyproject.toml` (walking up from the
current working directory) and uses the `[geneva]` table.

Example:

```toml
[geneva]
log_level = "INFO"

[geneva.storage]
region = "us-east-1"
```

### Config Directory
By default Geneva reads config files from `./.config` and supports `json`, `yaml`,
`yml`, and `toml` files. The directory can be overridden with `GENEVA_CONFIG_DIR`.

Example:

```bash
export GENEVA_CONFIG_DIR=/path/to/config
```

### Programmatic Overrides
Use `override_config` or `override_config_kv` to inject overrides at runtime, and
`default_config` to provide a fallback.

```python
from geneva.config import default_config, override_config_kv

override_config_kv({"geneva.log_level": "DEBUG"})
```

## Value Types
All configuration values are treated as strings. Nested keys are represented as
nested dictionaries in file-based configs.

Example TOML file:

```toml
[storage]
region = "us-east-1"

[admission]
check = "true"
```

## Troubleshooting
- Confirm `GENEVA_CONFIG_DIR` points to the intended directory.
- Ensure file names sort in the desired precedence order.
- Verify environment variables are uppercased and use `__` for nesting.
