config-loading-precedence

Configuration Loading & Precedence

CLI Mode Precedence (highest to lowest)

1. Individual CLI flags (--ocr, --output-format, --chunk)
2. Inline JSON config (--config-json or --config-json-base64)
3. Config file (--config path.toml)
4. Auto-discovered config (xberg.{toml,yaml,yml,json} in cwd/parents, then the user config dir)
5. Default values

Server/MCP Mode Precedence

1. CLI arguments (--host, --port)
2. Environment variables (XBERG_HOST, XBERG_PORT)
3. Config file [server] section
4. Defaults (127.0.0.1:8000)

Config File Discovery

ExtractionConfig::discover() (core/config/extraction/loaders.rs) uses the same deterministic format precedence at every level:

1. Walks the current directory and its parents, probing xberg.toml, xberg.yaml, xberg.yml, then xberg.json in each directory. The first hit wins.
2. If that finds nothing, falls back to the per-user global config directory (dirs::config_dir()/xberg) and probes four basenames in a fixed order: xberg.toml, xberg.yaml, xberg.yml, xberg.json.

Inline JSON Config

Field-level merge (not whole-object replacement):

fn merge_json_into_config(base: &ExtractionConfig, json: Value) -> Result<ExtractionConfig> {
    let mut config_json = serde_json::to_value(base)?;
    // Merge fields from json into config_json
    serde_json::from_value(merged)?
}

Use --config-json-base64 for shell escaping.

Config File Formats

TOML (xberg.toml):

use_cache = true
[ocr]
backend = "tesseract"
languages = ["eng", "deu"]
[security_limits]
max_archive_size = 524288000

YAML and JSON follow equivalent structure.

CLI Flag Overrides

crates/xberg-cli/src/commands/overrides/mod.rs: the ExtractionOverrides struct's validate() runs first, then apply(self, config: &mut ExtractionConfig) lays individual CLI flags over the merged config. There is no apply_extraction_overrides() and no commands.rs — commands/ is a directory.