Configuration guide

Seagull has separate configuration owners. Backend processes read typed environment variables; the agent reads one strict JSON file; rules, alert tuning, and authorization policy use their own validated documents.

Backend settings

Startup parses and validates configuration at composition boundaries and reports all detected problems before exiting. Empty environment values count as unset. Any supported variable can read from a file using its _FILE variant; do not supply secrets in checked-in examples.

The generated environment index extracts declarations from code, including type, required/default form, and bounds. Defaults written as Go expressions preserve the actual source definition. Duration(name, default, minimum, maximum) and equivalent typed calls show validation limits. Shared settings must be read alongside each executable's declarations.

The maintainer operational reference adds purpose, topology, ACK details, and retention explanations. It is a reviewed snapshot of prose and can lag source; code declarations take precedence where they disagree.

Document configuration

deploy/rules supplies bootstrap detection content. deploy/alerting.yml controls alert-plane tuning. deploy/policy.yml declares operator authorization. Changes to these documents are changes to security decisions, not just presentation settings.

Agent configuration

The agent uses -config FILE and ignores environment configuration. Unknown keys, duplicate keys, null values, oversized input, unsupported formats, and unsafe ownership are refused. See the complete agent reference, including which reserved settings do not yet have active consumers.

Source evidence

Reviewed against the source baseline. Seagull-backend-v2/internal/platform/config/parser.go · Seagull-backend-v2/docs/configuration.md · Seagull-agent-v2/internal/config/config.go.