(** The config file: what the user wants by default, and where each value came
    from.

    Owns precedence and provenance and nothing else. Never reads the filesystem
    -- callers hand it text -- so it is as testable as the language table.

    A config file is OPTIONAL. With none, colitur behaves exactly as it does
    without this feature, except that names resolve through the default
    language. *)

type t

val empty : t
val of_string : string -> (t, string) result

(** [lang], [template] and [format] are each set from a single field. A
    repeated key is LAST-WINS -- the opposite direction from
    {!Colitur_kernel.Overlay_ini.get}'s first-wins over the same [section]
    type -- because the natural reading of a config file a user edited by
    hand and appended to is "the bottom line is the one that took effect".
    This holds whether the repeat is within one [\[defaults\]] block or
    across two of them: every section named [defaults] is merged, not only
    the first, the same duplicate-section policy {!Lang.of_string} documents
    for its own sections -- the two modules read the same underlying format
    and must not disagree about what a repeated header means. *)
val lang : t -> string option

val overlays : t -> string list
val template : t -> string option
val format : t -> string option

(** The template ESCAPING flavour ([latex] | [typst] | [groff] | [html] |
    [xml] | [ics] | [none]).

    Only consulted when the flavour cannot be inferred from the template's
    own extension, which is the usual case -- a template named [.tex] needs
    no setting. It exists for the template whose extension says nothing,
    and getting it wrong produces output that is malformed rather than
    merely ugly, so there is deliberately no silent fallback. *)
val flavour : t -> string option

(** Which citation style to render a reference in: a language CODE, looked
    up the same way {!lang} is, or a path -- but a DIFFERENT axis from
    {!lang}: a language file's own [\[sigla\]] section IS a style
    ({!Colitur_citation.Render.style_of_fields}), and this key SELECTS
    which file's [\[sigla\]] section supplies it, independently of which
    file's other sections supply names elsewhere (a booklet may want
    Polish names but Latin-convention citations). Same last-wins duplicate
    policy as {!lang}. *)
val sigla_style : t -> string option

(** [full] or [abbr] -- overrides the style's own [book] setting rather than
    replacing the style outright, so a chosen style's punctuation survives
    even when the book form is overridden ({!Colitur_citation.Render.with_book}).
    Same last-wins duplicate policy as {!lang}. *)
val sigla_book : t -> string option

(** The name of a section in [lang/traditions.ini] -- which BOOK a reference
    DENOTES (Vulgate numbering by default), a different question again from
    both {!sigla_style} (how a reference is WRITTEN) and {!lang} (what
    everything else is CALLED): naming and numbering both vary by
    convention, but not together. Same last-wins duplicate policy as
    {!lang}. *)
val sigla_tradition : t -> string option

(** Keys present in the [\[defaults\]] section that this build does not
    understand. Reported, never fatal: a config written for a newer colitur
    must still work on an older one, but silently ignoring a line the user
    wrote is how a typo becomes invisible. *)
val unknown_keys : t -> string list

(** Section names other than [\[defaults\]], reported separately from
    {!unknown_keys} so the CLI can word the two warnings differently (a
    misspelled section, e.g. [\[deafults\]], versus a misspelled key inside a
    recognised one). Also never fatal, and never silent: a section this build
    does not recognise is exactly the highest-value typo this feature exists
    to catch, because it silently discards the whole section -- [lang] and
    everything else in it -- with no other way for the user to notice. *)
val unknown_sections : t -> string list

(** [resolve ~flag ~config ~default] returns [(value, source)] with source one of
    ["flag"], ["config"], ["default"]. Precedence is flag > config > default. *)
val resolve : flag:string option -> config:string option -> default:string -> string * string