# Configuration Resolution Chain

CleverAgents uses a multi-level configuration resolution chain that determines
the effective value for each configuration key. This document describes the
resolution order, all registered configuration keys, their types, defaults,
and environment variable mappings.

## Resolution Order

Values are resolved from **highest to lowest** priority. The first level that
provides a non-`None` value wins:

| Priority | Level            | Description                                          |
|----------|------------------|------------------------------------------------------|
| 1        | **CLI flag**     | Value passed explicitly via `--key=value` on the CLI |
| 2        | **Env var**      | Environment variable (`CLEVERAGENTS_<SECTION>_<KEY>`) |
| 3        | **Project scope**| Per-project override in `[project."<name>"]` TOML table |
| 4        | **Global config**| Value in `~/.cleveragents/config.toml`               |
| 5        | **Default**      | Built-in default from the key registry               |

### Example

```
$ export CLEVERAGENTS_CORE_LOG_LEVEL=WARNING
$ agents config set core.log_level DEBUG      # writes to global config
$ agents config get core.log_level
# -> WARNING (env var wins over global config)
```

## Environment Variable Convention

All registered keys map to environment variables following the pattern:

```
CLEVERAGENTS_<SECTION>_<KEY>
```

Where `<SECTION>` and `<KEY>` are uppercased. For example:

- `core.log_level` -> `CLEVERAGENTS_CORE_LOG_LEVEL`
- `plan.max_retries` -> `CLEVERAGENTS_PLAN_MAX_RETRIES`
- `provider.temperature` -> `CLEVERAGENTS_PROVIDER_TEMPERATURE`

## Configuration Keys

### `core.*` — Core Runtime

| Key                  | Type   | Default                      | Env Var                            | Project-Scopable | Description                    |
|----------------------|--------|------------------------------|------------------------------------|-------------------|-------------------------------|
| `core.log_level`     | `str`  | `INFO`                       | `CLEVERAGENTS_CORE_LOG_LEVEL`      | Yes               | Logging verbosity level       |
| `core.debug_enabled` | `bool` | `false`                      | `CLEVERAGENTS_CORE_DEBUG_ENABLED`  | Yes               | Enable debug mode             |
| `core.env`           | `str`  | `development`                | `CLEVERAGENTS_CORE_ENV`            | Yes               | Runtime environment name      |
| `core.data_dir`      | `str`  | `data`                       | `CLEVERAGENTS_CORE_DATA_DIR`       | Yes               | Base data directory path      |
| `core.database_url`  | `str`  | `sqlite:///cleveragents.db`  | `CLEVERAGENTS_CORE_DATABASE_URL`   | No                | Primary database URL          |
| `core.server_host`   | `str`  | `0.0.0.0`                   | `CLEVERAGENTS_CORE_SERVER_HOST`    | No                | Server bind host              |
| `core.server_port`   | `int`  | `8080`                       | `CLEVERAGENTS_CORE_SERVER_PORT`    | No                | Server bind port              |

### `plan.*` — Plan Execution

| Key                    | Type   | Default | Env Var                              | Project-Scopable | Description                           |
|------------------------|--------|---------|--------------------------------------|-------------------|---------------------------------------|
| `plan.auto_apply`      | `bool` | `false` | `CLEVERAGENTS_PLAN_AUTO_APPLY`       | Yes               | Auto-apply plans on completion        |
| `plan.max_retries`     | `int`  | `3`     | `CLEVERAGENTS_PLAN_MAX_RETRIES`      | Yes               | Maximum plan retry count              |
| `plan.timeout_seconds` | `int`  | `300`   | `CLEVERAGENTS_PLAN_TIMEOUT_SECONDS`  | Yes               | Plan execution timeout in seconds     |

### `provider.*` — LLM Provider

| Key                      | Type    | Default | Env Var                                | Project-Scopable | Description                    |
|--------------------------|---------|---------|----------------------------------------|-------------------|-------------------------------|
| `provider.default_provider` | `str` | `""`  | `CLEVERAGENTS_PROVIDER_DEFAULT_PROVIDER` | No              | Default LLM provider name     |
| `provider.default_model`   | `str` | `""`  | `CLEVERAGENTS_PROVIDER_DEFAULT_MODEL`    | No              | Default LLM model name        |
| `provider.temperature`     | `float` | `0.7` | `CLEVERAGENTS_PROVIDER_TEMPERATURE`    | Yes               | LLM sampling temperature      |
| `provider.max_tokens`      | `int` | `4096` | `CLEVERAGENTS_PROVIDER_MAX_TOKENS`      | Yes               | Max tokens per LLM response   |

### `sandbox.*` — Sandbox Isolation

| Key                    | Type   | Default        | Env Var                              | Project-Scopable | Description                           |
|------------------------|--------|----------------|--------------------------------------|-------------------|---------------------------------------|
| `sandbox.strategy`     | `str`  | `git_worktree` | `CLEVERAGENTS_SANDBOX_STRATEGY`      | Yes               | Default sandbox strategy              |
| `sandbox.auto_cleanup` | `bool` | `true`         | `CLEVERAGENTS_SANDBOX_AUTO_CLEANUP`  | Yes               | Auto-clean sandbox after use          |
| `sandbox.max_age_hours`| `int`  | `48`           | `CLEVERAGENTS_SANDBOX_MAX_AGE_HOURS` | Yes               | Max sandbox age before cleanup        |

### `context.*` — Context Management

| Key                            | Type   | Default  | Env Var                                        | Project-Scopable | Description                                |
|--------------------------------|--------|----------|-------------------------------------------------|-------------------|--------------------------------------------|
| `context.max_files`            | `int`  | `100`    | `CLEVERAGENTS_CONTEXT_MAX_FILES`               | Yes               | Maximum context files per session          |
| `context.max_tokens`           | `int`  | `128000` | `CLEVERAGENTS_CONTEXT_MAX_TOKENS`              | Yes               | Maximum context token window               |
| `context.auto_include_gitignore` | `bool` | `true` | `CLEVERAGENTS_CONTEXT_AUTO_INCLUDE_GITIGNORE` | Yes               | Auto-include gitignore in context filtering |

### `index.*` — Vector Store Indexing

| Key                      | Type   | Default | Env Var                                  | Project-Scopable | Description                     |
|--------------------------|--------|---------|------------------------------------------|-------------------|---------------------------------|
| `index.enabled`          | `bool` | `false` | `CLEVERAGENTS_INDEX_ENABLED`             | Yes               | Enable vector-store indexing    |
| `index.backend`          | `str`  | `faiss` | `CLEVERAGENTS_INDEX_BACKEND`             | Yes               | Vector store backend name       |
| `index.embedding_model`  | `str`  | `fake`  | `CLEVERAGENTS_INDEX_EMBEDDING_MODEL`     | Yes               | Embedding model for indexing    |
| `index.embedding_dimension` | `int` | `1536` | `CLEVERAGENTS_INDEX_EMBEDDING_DIMENSION` | Yes               | Embedding vector dimension      |

## Validation Rules

### Unknown Keys

Attempting to get or set an unregistered key will produce an actionable error:

```
ValueError: Unknown configuration key: 'bogus.key'.
Valid keys include: context.auto_include_gitignore, context.max_files, ...
```

### Type Mismatches

Values are coerced to the registered type. If coercion fails, an actionable
error is raised:

```
TypeError: Type mismatch for key 'core.server_port': expected int,
got str with value 'not_a_number'.
```

Boolean coercion accepts: `true`/`false`, `1`/`0`, `yes`/`no` (case-insensitive).

## TOML File Location

The global configuration file is stored at:

```
~/.cleveragents/config.toml
```

Parent directories are created automatically on first write. Project-scoped
overrides live under `[project."<name>"]` tables within the same file.

## Verbose Mode

When `--verbose` is passed to `config get`, the full resolution chain is
displayed, showing which level provided (or could provide) the value:

```
$ agents config get core.log_level --verbose
Key:    core.log_level
Value:  INFO
Source: default

Resolution chain (highest -> lowest priority):
  cli_flag       -> (not set)
  env_var        -> (not set)  [CLEVERAGENTS_CORE_LOG_LEVEL]
  project        -> (not set)
  global         -> (not set)  [~/.cleveragents/config.toml]
  default        -> INFO       <-- active
```