Configuration layering

Configuration is layered using ortho-config with the following precedence order:

1. built-in defaults,
2. configuration files discovered via --config-path and the XDG search path,
3. environment variables, and
4. CLI flags.

Each successive layer overrides earlier sources. This guarantees that a parameter passed through the CLI is honoured even when a configuration file or environment variable also supplies the same field.

The CLI exposes the following configuration flags today:

• --config-path <PATH> — reads an explicit configuration file.
• --daemon-socket <ENDPOINT> — overrides the daemon transport. Accepts values such as unix:///run/user/1000/weaver.sock or tcp://127.0.0.1:9779.
• --log-filter <FILTER> — sets the tracing filter (defaults to info).
• --log-format <FORMAT> — selects the log output format (json or compact only).
• --capability-overrides <DIRECTIVE> — appends a directive of the form language:capability=directive. Directives may be repeated to accumulate overrides. Duplicate entries are resolved by keeping the last directive for each language and capability pair, and lookups ignore case and surrounding whitespace.
• --locale <LOCALE> — selects the operator-facing locale (defaults to en-US). Locale values must be valid BCP 47 language identifiers.

weaver --help and weaver daemon start --help both list these flags in their Options: section. The runtime behaviour remains strict, however: for a configuration flag to take effect, it must appear before the command domain or structured subcommand.

Most options are available through environment variables. They follow the WEAVER_* naming convention:

• WEAVER_CONFIG_PATH
• WEAVER_DAEMON_SOCKET
• WEAVER_LOG_FILTER
• WEAVER_LOG_FORMAT
• WEAVER_LOCALE

Environment variables override files, but remain lower priority than CLI flags.

Configuration files are written in TOML. The following snippet demonstrates how to pin the daemon socket, switch to a compact log format, and force the call hierarchy capability for Python:

daemon_socket = { transport = "tcp", host = "127.0.0.1", port = 9779 }
log_filter = "info"
log_format = "compact"
locale = "en-GB"

[[capability_overrides]]
language = "python"
capability = "observe.call-hierarchy"
directive = "force"

Invalid configuration files are treated as fatal. When --config-path points at a broken file, or when discovery finds a malformed weaver.toml/ .weaver.toml, both the CLI and daemon abort with a LoadConfiguration error that lists every offending path. Remove or fix the reported files before retrying. If no configuration files exist at all, the loader still falls back to the built-in defaults described below. See the developer's guide for toolchain baseline and configuration framework internals.

Operators will see aggregated errors enumerated in the order discovery encounters them. For example:

failed to load configuration: multiple configuration errors:
1: Configuration file error in '/etc/weaver/weaver.toml': expected `}`
2: Configuration file error in '/home/alex/.weaver.toml': invalid type:
string "yes", expected a boolean