= core-config

== purpose

Loads and represents the Correx application configuration from a TOML file. Provides a single entry point (`ConfigLoader`) that reads `~/.config/correx/config.toml` (or a path from `CORREX_CONFIG`) and returns a `CorrexConfig` data class with validated defaults.

== responsibilities

* Read configuration file from well-known filesystem path
* Parse TOML-format configuration with minimal manual parser
* Provide type-safe config objects with sensible defaults for all subsystems
* Silently fall back to defaults when config file is missing or unparseable

== non-responsibilities

* Does not validate configuration values semantically (beyond type coercion)
* Does not watch for file changes at runtime
* Does not manage environment variables beyond `CORREX_CONFIG`
* Does not expose configuration to remote clients

== key types

=== CorrexConfig
* **kind**: data class
* **purpose**: Root configuration object, aggregating all subsystem configs.
* **fields**: `server`, `tui`, `cli`, `approval`, `tools`

=== ServerConfig
* **kind**: data class
* **purpose**: Ktor HTTP server binding configuration.
* **fields**: `host` (default `"localhost"`), `port` (default `8080`)

=== TuiConfig
* **kind**: data class
* **purpose**: Terminal UI preferences.
* **fields**: `theme` (default `"dark"`), `sessionListLimit` (default `5`)

=== CliConfig
* **kind**: data class
* **purpose**: CLI output formatting preferences.
* **fields**: `defaultOutput` (default `"human"`)

=== ApprovalConfig
* **kind**: data class
* **purpose**: Approval gate timeouts.
* **fields**: `timeoutMs` (default `300_000L`)

=== ToolsConfig
* **kind**: data class
* **purpose**: Tool sandbox and execution configuration.
* **fields**: `sandboxRoot`, `workingDir`, `shellAllowedExecutables`, `defaultSystemPromptPath`

=== ConfigLoader
* **kind**: object
* **purpose**: Stateless loader that reads and parses the TOML config file.
* **fields**: none (singleton)

== event flow

*None.* Config is read eagerly at startup and does not participate in event sourcing.

== integration points

* `core:events` — `@Serializable` annotations on all config types
* `apps:cli`, `apps:server`, `core:approvals`, `core:tools` — consume `CorrexConfig` fields

== invariants

* ConfigLoader must never throw on missing or unparseable files — always returns `CorrexConfig()` with defaults
* All config types are `@Serializable` for potential persistence

== PlantUML diagram

[plantuml, core-config, "png"]
----
include::../../diagrams/core-config.puml[]
----




== known issues

* TOML parser is hand-written and only supports sections with simple `key = value` pairs. Arrays, inline tables, and multi-line strings are not supported.

== open questions

* Will config be migrated to a proper TOML library (e.g., `ktoml`)?
* Should config support hot-reload or remain load-once?