config-loading-precedence

name	config-loading-precedence
description	How Xberg resolves configuration — CLI-mode and server/MCP-mode precedence orders, config file auto-discovery (xberg.{toml,yaml,json}), field-level inline JSON merge (merge_json_into_config), config file formats, and apply_extraction_overrides. Load when adding a config flag or env var, changing config precedence, or debugging why a setting is or isn't taking effect.

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,json} in cwd/parents)
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

Searches current directory and parents for xberg.toml, xberg.yaml, or xberg.json. Stops at first match.

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

In commands.rs: apply_extraction_overrides() applies individual flags on top of merged config.

Critical Rules

1. CLI flags always win over config file
2. JSON merge is field-level, not whole-object
3. Auto-discovery stops at first config file found
4. --config-json-base64 for shell-safe JSON passing
5. Server config uses [server] section + extraction config