AGENTS.md

1# Config Guidelines
2 
3**Last Updated:** April 9, 2026
4 
5## Option Precedence & Wiring
6 
7- Respect config precedence: `options.yml` overrides CLI and environment values, which override defaults.
8- When adding a new option, update `internal/config/options.go` for YAML and flag tags, register the flag in `internal/config/flags.go`, expose a getter, surface it in `*config.Report()`, and persist generated values by setting `c.options.OptionsYaml` before writing `options.yml`.
9- Exercise new flags with `CliTestContext` from `internal/config/test.go`.
10 
11## Config Persistence
12 
13- For `options.yml` writes, use config-owned helpers instead of ad-hoc YAML handling: `Config.SaveOptionsPatch(...)` for generic merges and `Config.SaveClusterOptionsUpdate(...)` for cluster-managed updates.
14- Use `pkg/fs.ConfigFilePath` when you need a config filename so existing `.yml` files stay valid while new installs may adopt `.yaml`.
15- In Go code, use public `*config.Config` accessors such as `Config.JWKSUrl()`, `Config.SetJWKSUrl()`, and `Config.ClusterUUID()` instead of mutating `Config.Options()` directly; reserve raw option mutation for test fixtures.
16 
17## CLI Override Rules & DB Helpers
18 
19- Favor explicit CLI flags: check `c.cliCtx.IsSet("<flag>")` before overriding user-supplied values.
20- Follow the `ClusterUUID` pattern for generated values: `options.yml`, then CLI or environment overrides, then a generated value persisted back to disk.
21- Reuse `conf.Db()` and `conf.Database*()` helpers, avoid GORM `WithContext`, quote MySQL identifiers, and reject unsupported drivers early.
22 
23