hanna/fabrica

feat(config): load, validate, and show TOML+env configuration

d1a7fc7 · hanna committed on 2026-07-25

Implement phase 2. The config crate loads a TOML file layered over
built-in defaults and FABRICA__* env overrides via figment (defaults ->
/etc -> XDG -> --config -> env, later wins), then validates strictly and
fails fast: unknown keys are an error, instance.url must parse without a
trailing slash, storage dirs must be creatable, smtp needs host/from;
cookie-secure-over-http is a warning.

Secrets (auth.secret, mail.password) are a redact-by-default Secret
newtype — Debug and Serialize always emit <redacted>, the real value is
reachable only via expose() — and their *_file siblings are read from
disk and take precedence. This keeps secrets out of logs, errors, and
`config show`.

Wire `fabrica config check` and `fabrica config show [--json]` into a
minimal clap tree with global --config/--log-level/--json. Ship a
fully-commented fabrica.example.toml and docs/configuration.md, and log
the Secret and strict-loading decisions.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Signed by hannaSSH key fingerprint: SHA256:4g9cWhkAAw8gwqhJUcVbSnGEvdGwklW+1Aa/fMUu59k

Cargo.lock +875 −0

Cargo.toml +11 −0

crates/cli/Cargo.toml +4 −0

crates/cli/src/config_cmd.rs +62 −0

crates/cli/src/lib.rs +57 −4

crates/config/Cargo.toml +8 −0

crates/config/src/lib.rs +420 −0

crates/config/src/secret.rs +101 −0

crates/config/src/types.rs +384 −0

docs/configuration.md +92 −0

docs/decisions.md +33 −0

fabrica.example.toml +89 −0

 api = { path = "crates/api" }
 cli = { path = "crates/cli" }
+# External dependencies. Versions are centralised here; crates opt in with
+# `<dep> = { workspace = true }` so the whole workspace stays on one version.
+figment = { version = "0.10", features = ["toml", "env"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+toml = "0.8"
+thiserror = "2"
+url = "2"
+clap = { version = "4", features = ["derive"] }
+anyhow = "1"
 [workspace.lints.rust]
 unsafe_code = "forbid"
 missing_docs = "warn"

 publish.workspace = true
 [dependencies]
+config = { workspace = true }
+anyhow = { workspace = true }
+clap = { workspace = true }
+serde_json = { workspace = true }
 [lints]
 workspace = true

+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+//! `fabrica config check` and `fabrica config show`.
+use std::path::Path;
+use std::process::ExitCode;
+use clap::Subcommand;
+/// Actions under `fabrica config`.
+#[derive(Debug, Subcommand)]
+pub(crate) enum ConfigCommand {
+    /// Validate the effective configuration and exit non-zero on any error.
+    Check,
+    /// Print the effective, merged configuration with secrets redacted.
+    Show,
+}
+/// Dispatch a `config` subcommand.
+///
+/// Warnings are always written to stderr; on `check` they do not affect the exit
+/// status. A validation failure is reported to stderr and yields
+/// [`ExitCode::FAILURE`] without returning an `Err`, so no backtrace-style
+/// wrapper is printed for the expected "your config is wrong" case.
+pub(crate) fn run(
+    command: &ConfigCommand,
+    config_path: Option<&Path>,
+    json: bool,
+) -> anyhow::Result<ExitCode> {
+    match command {
+        ConfigCommand::Check => match config::load(config_path) {
+            Ok(loaded) => {
+                warn(&loaded.warnings);
+                println!("configuration ok");
+                Ok(ExitCode::SUCCESS)
+            }
+            Err(err) => {
+                eprintln!("error: {err}");
+                Ok(ExitCode::FAILURE)
+            }
+        },
+        ConfigCommand::Show => {
+            let loaded = config::load(config_path)?;
+            warn(&loaded.warnings);
+            if json {
+                println!("{}", serde_json::to_string_pretty(&loaded.config)?);
+            } else {
+                print!("{}", loaded.config.to_toml_string()?);
+            }
+            Ok(ExitCode::SUCCESS)
+        }
+    }
+}
+/// Write each warning to stderr, prefixed, leaving stdout for real output.
+fn warn(warnings: &[String]) {
+    for warning in warnings {
+        eprintln!("warning: {warning}");
+    }
+}

 //!
 //! Every subcommand operates directly on the store and filesystem; there is no
 //! IPC with a running `serve`. [`run`] is the single entry point invoked by the
-//! `fabrica` binary.
+//! `fabrica` binary. The command tree is built out over the implementation
+//! phases; today it covers only `config check` and `config show`.
+mod config_cmd;
+use std::path::PathBuf;
 use std::process::ExitCode;
+use clap::{Parser, Subcommand};
+/// Top-level argument parser for the `fabrica` binary.
+#[derive(Debug, Parser)]
+#[command(name = "fabrica", version, about = "A self-hosted git server.")]
+struct Cli {
+    /// Path to a configuration file, merged last after the standard locations.
+    #[arg(long, global = true, value_name = "PATH")]
+    config: Option<PathBuf>,
+    /// Override the configured log level (`trace|debug|info|warn|error`).
+    #[arg(long, global = true, value_name = "LEVEL")]
+    log_level: Option<String>,
+    /// Emit machine-readable JSON instead of human-formatted output.
+    #[arg(long, global = true)]
+    json: bool,
+    /// The subcommand to run.
+    #[command(subcommand)]
+    command: Command,
+}
+/// The fabrica subcommand tree.
+#[derive(Debug, Subcommand)]
+enum Command {
+    /// Inspect and validate configuration.
+    Config {
+        /// The configuration action to perform.
+        #[command(subcommand)]
+        command: config_cmd::ConfigCommand,
+    },
+}
 /// Parse arguments and dispatch to the requested subcommand.
 ///
-/// Returns the process exit code. The command tree is built out over the
+/// Returns the process exit code. Argument-parse failures are handled by clap
-/// implementation phases; today this is a placeholder that exits successfully.
+/// (which prints usage and exits); any other error is printed to stderr and
+/// mapped to [`ExitCode::FAILURE`].
 #[must_use]
 pub fn run() -> ExitCode {
-    ExitCode::SUCCESS
+    let cli = Cli::parse();
+    match dispatch(&cli) {
+        Ok(code) => code,
+        Err(err) => {
+            eprintln!("error: {err:#}");
+            ExitCode::FAILURE
+        }
+    }
+}
+/// Route a parsed [`Cli`] to its handler.
+fn dispatch(cli: &Cli) -> anyhow::Result<ExitCode> {
+    match &cli.command {
+        Command::Config { command } => config_cmd::run(command, cli.config.as_deref(), cli.json),
+    }
+}

 publish.workspace = true
 [dependencies]
+figment = { workspace = true }
+serde = { workspace = true }
+thiserror = { workspace = true }
+toml = { workspace = true }
+url = { workspace = true }
+[dev-dependencies]
+figment = { workspace = true, features = ["test"] }
 [lints]
 workspace = true

 version = 4
 [[package]]
+name = "anstream"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "824a212faf96e9acacdbd09febd34438f8f711fb84e09a8916013cd7815ca28d"
+dependencies = [
+ "anstyle",
+ "anstyle-parse",
+ "anstyle-query",
+ "anstyle-wincon",
+ "colorchoice",
+ "is_terminal_polyfill",
+ "utf8parse",
+]
+[[package]]
+name = "anstyle"
+version = "1.0.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "940b3a0ca603d1eade50a4846a2afffd5ef57a9feac2c0e2ec2e14f9ead76000"
+[[package]]
+name = "anstyle-parse"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52ce7f38b242319f7cabaa6813055467063ecdc9d355bbb4ce0c68908cd8130e"
+dependencies = [
+ "utf8parse",
+]
+[[package]]
+name = "anstyle-query"
+version = "1.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc"
+dependencies = [
+ "windows-sys",
+]
+[[package]]
+name = "anstyle-wincon"
+version = "3.0.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d"
+dependencies = [
+ "anstyle",
+ "once_cell_polyfill",
+ "windows-sys",
+]
+[[package]]
+name = "anyhow"
+version = "1.0.104"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "330a5ed07fa54e4702c9d6c4174f74427fc0ef6e214bbd677ae50a5099946470"
+[[package]]
 name = "api"
 version = "0.1.0"
 [[package]]
+name = "atomic"
+version = "0.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a89cbf775b137e9b968e67227ef7f775587cde3fd31b0d8599dbd0f598a48340"
+dependencies = [
+ "bytemuck",
+]
+[[package]]
 name = "auth"
 version = "0.1.0"
 [[package]]
+name = "bitflags"
+version = "2.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b588b76d00fde79687d7646a9b5bdf3cc0f655e0bbd080335a95d7e96f3587da"
+[[package]]
+name = "bytemuck"
+version = "1.25.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "95832e849adfb21180ccb6826a99da14e5d266ae5c2e668e1602cf234f153797"
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+[[package]]
+name = "clap"
+version = "4.6.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d91e0c145792ef73a6ad36d27c75ac09f1832222a3c209689d90f534685ee5b7"
+dependencies = [
+ "clap_builder",
+ "clap_derive",
+]
+[[package]]
+name = "clap_builder"
+version = "4.6.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f09628afdcc538b57f3c6341e9c8e9970f18e4a481690a64974d7023bd33548b"
+dependencies = [
+ "anstream",
+ "anstyle",
+ "clap_lex",
+ "strsim",
+]
+[[package]]
+name = "clap_derive"
+version = "4.6.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d012d2b9d65aca7f18f4d9878a045bc17899bba951561ba5ec3c2ba1eed9a061"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "syn 3.0.3",
+]
+[[package]]
+name = "clap_lex"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c8d4a3bb8b1e0c1050499d1815f5ab16d04f0959b233085fb31653fbfc9d98f9"
+[[package]]
 name = "cli"
 version = "0.1.0"
+dependencies = [
+ "anyhow",
+ "clap",
+ "config",
+ "serde_json",
+]
+[[package]]
+name = "colorchoice"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570"
 [[package]]
 name = "config"
 version = "0.1.0"
+dependencies = [
+ "figment",
+ "serde",
+ "thiserror",
+ "toml",
+ "url",
+]
+[[package]]
+name = "displaydoc"
+version = "0.2.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ac70aa55017e108007fbaf5aa0f54b021c98f92ff8af59d42eda9da96e3dd4f"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+[[package]]
+name = "equivalent"
+version = "1.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
+[[package]]
+name = "errno"
+version = "0.3.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
+dependencies = [
+ "libc",
+ "windows-sys",
+]
 [[package]]
 name = "fabrica"
+]
 [[package]]
+name = "fastrand"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "da7c62ceae207dd37ea5b845da6a0696c799f85e97da1ab5b7910be3c1c80223"
+[[package]]
+name = "figment"
+version = "0.10.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8cb01cd46b0cf372153850f4c6c272d9cbea2da513e07538405148f95bd789f3"
+dependencies = [
+ "atomic",
+ "parking_lot",
+ "pear",
+ "serde",
+ "tempfile",
+ "toml",
+ "uncased",
+ "version_check",
+]
+[[package]]
+name = "form_urlencoded"
+version = "1.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cb4cb245038516f5f85277875cdaa4f7d2c9a0fa0468de06ed190163b1581fcf"
+dependencies = [
+ "percent-encoding",
+]
+[[package]]
+name = "getrandom"
+version = "0.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "300e883d756b2e4ec94e02791f39b04b522276138852cfc41d9fb7e904106099"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "r-efi",
+]
+[[package]]
 name = "git"
 version = "0.1.0"
 [[package]]
+name = "hashbrown"
+version = "0.17.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+[[package]]
 name = "highlight"
 version = "0.1.0"
 [[package]]
+name = "icu_collections"
+version = "2.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4c6b649701667bbe825c3b7e6388cb521c23d88644678e83c0c4d0a621a34b43"
+dependencies = [
+ "displaydoc",
+ "potential_utf",
+ "yoke",
+ "zerofrom",
+ "zerovec",
+]
+[[package]]
+name = "icu_locale_core"
+version = "2.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "edba7861004dd3714265b4db54a3c390e880ab658fec5f7db895fae2046b5bb6"
+dependencies = [
+ "displaydoc",
+ "litemap",
+ "tinystr",
+ "writeable",
+ "zerovec",
+]
+[[package]]
+name = "icu_normalizer"
+version = "2.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5f6c8828b67bf8908d82127b2054ea1b4427ff0230ee9141c54251934ab1b599"
+dependencies = [
+ "icu_collections",
+ "icu_normalizer_data",
+ "icu_properties",
+ "icu_provider",
+ "smallvec",
+ "zerovec",
+]
+[[package]]
+name = "icu_normalizer_data"
+version = "2.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7aedcccd01fc5fe81e6b489c15b247b8b0690feb23304303a9e560f37efc560a"
+[[package]]
+name = "icu_properties"
+version = "2.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "020bfc02fe870ec3a66d93e677ccca0562506e5872c650f893269e08615d74ec"
+dependencies = [
+ "icu_collections",
+ "icu_locale_core",
+ "icu_properties_data",
+ "icu_provider",
+ "zerotrie",
+ "zerovec",
+]
+[[package]]
+name = "icu_properties_data"
+version = "2.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "616c294cf8d725c6afcd8f55abc17c56464ef6211f9ed59cccffe534129c77af"
+[[package]]
+name = "icu_provider"
+version = "2.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85962cf0ce02e1e0a629cc34e7ca3e373ce20dda4c4d7294bbd0bf1fdb59e614"
+dependencies = [
+ "displaydoc",
+ "icu_locale_core",
+ "writeable",
+ "yoke",
+ "zerofrom",
+ "zerotrie",
+ "zerovec",
+]
+[[package]]
+name = "idna"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3b0875f23caa03898994f6ddc501886a45c7d3d62d04d2d90788d47be1b1e4de"
+dependencies = [
+ "idna_adapter",
+ "smallvec",
+ "utf8_iter",
+]
+[[package]]
+name = "idna_adapter"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3acae9609540aa318d1bc588455225fb2085b9ed0c4f6bd0d9d5bcd86f1a0344"
+dependencies = [
+ "icu_normalizer",
+ "icu_properties",
+]
+[[package]]
+name = "indexmap"
+version = "2.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d466e9454f08e4a911e14806c24e16fba1b4c121d1ea474396f396069cf949d9"
+dependencies = [
+ "equivalent",
+ "hashbrown",
+]
+[[package]]
+name = "inlinable_string"
+version = "0.1.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c8fae54786f62fb2918dcfae3d568594e50eb9b5c25bf04371af6fe7516452fb"
+[[package]]
+name = "is_terminal_polyfill"
+version = "1.70.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695"
+[[package]]
+name = "itoa"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+[[package]]
+name = "libc"
+version = "0.2.189"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
+[[package]]
+name = "linux-raw-sys"
+version = "0.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53"
+[[package]]
+name = "litemap"
+version = "0.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92daf443525c4cce67b150400bc2316076100ce0b3686209eb8cf3c31612e6f0"
+[[package]]
+name = "lock_api"
+version = "0.4.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "224399e74b87b5f3557511d98dff8b14089b3dadafcab6bb93eab67d3aace965"
+dependencies = [
+ "scopeguard",
+]
+[[package]]
 name = "mail"
 version = "0.1.0"
 [[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+[[package]]
 name = "model"
 version = "0.1.0"
 [[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+[[package]]
+name = "once_cell_polyfill"
+version = "1.70.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
+[[package]]
+name = "parking_lot"
+version = "0.12.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "93857453250e3077bd71ff98b6a65ea6621a19bb0f559a85248955ac12c45a1a"
+dependencies = [
+ "lock_api",
+ "parking_lot_core",
+]
+[[package]]
+name = "parking_lot_core"
+version = "0.9.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2621685985a2ebf1c516881c026032ac7deafcda1a2c9b7850dc81e3dfcb64c1"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "redox_syscall",
+ "smallvec",
+ "windows-link",
+]
+[[package]]
+name = "pear"
+version = "0.2.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bdeeaa00ce488657faba8ebf44ab9361f9365a97bd39ffb8a60663f57ff4b467"
+dependencies = [
+ "inlinable_string",
+ "pear_codegen",
+ "yansi",
+]
+[[package]]
+name = "pear_codegen"
+version = "0.2.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4bab5b985dc082b345f812b7df84e1bef27e7207b39e448439ba8bd69c93f147"
+dependencies = [
+ "proc-macro2",
+ "proc-macro2-diagnostics",
+ "quote",
+ "syn 2.0.119",
+]
+[[package]]
+name = "percent-encoding"
+version = "2.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
+[[package]]
+name = "potential_utf"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0103b1cef7ec0cf76490e969665504990193874ea05c85ff9bab8b911d0a0564"
+dependencies = [
+ "zerovec",
+]
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+[[package]]
+name = "proc-macro2-diagnostics"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "af066a9c399a26e020ada66a034357a868728e72cd426f3adcd35f80d88d88c8"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+ "version_check",
+ "yansi",
+]
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+[[package]]
+name = "r-efi"
+version = "6.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf"
+[[package]]
+name = "redox_syscall"
+version = "0.5.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed2bf2547551a7053d6fdfafda3f938979645c44812fbfcda098faae3f1a362d"
+dependencies = [
+ "bitflags",
+]
+[[package]]
+name = "rustix"
+version = "1.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6fe4565b9518b83ef4f91bb47ce29620ca828bd32cb7e408f0062e9930ba190"
+dependencies = [
+ "bitflags",
+ "errno",
+ "libc",
+ "linux-raw-sys",
+ "windows-sys",
+]
+[[package]]
+name = "scopeguard"
+version = "1.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
+[[package]]
+name = "serde"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+[[package]]
+name = "serde_core"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
+dependencies = [
+ "serde_derive",
+]
+[[package]]
+name = "serde_derive"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.3",
+]
+[[package]]
+name = "serde_json"
+version = "1.0.151"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14"
+dependencies = [
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+[[package]]
+name = "serde_spanned"
+version = "0.6.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bf41e0cfaf7226dca15e8197172c295a782857fcb97fad1808a166870dee75a3"
+dependencies = [
+ "serde",
+]
+[[package]]
+name = "smallvec"
+version = "1.15.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ed6a63f02c8539c91a8685a86f4099661ba3da017932f6ebbea6de3f0fa7c90"
+[[package]]
 name = "ssh"
 version = "0.1.0"
 [[package]]
+name = "stable_deref_trait"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596"
+[[package]]
 name = "store"
 version = "0.1.0"
 [[package]]
+name = "strsim"
+version = "0.11.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"
+[[package]]
+name = "syn"
+version = "2.0.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+[[package]]
+name = "syn"
+version = "3.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "53e9bae58849f64dfa4f5d5ae372c8341f7305f82a3868709269343628b659a3"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+[[package]]
+name = "synstructure"
+version = "0.13.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "728a70f3dbaf5bab7f0c4b1ac8d7ae5ea60a4b5549c8a5914361c99147a709d2"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+[[package]]
+name = "tempfile"
+version = "3.27.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd"
+dependencies = [
+ "fastrand",
+ "getrandom",
+ "once_cell",
+ "rustix",
+ "windows-sys",
+]
+[[package]]
+name = "thiserror"
+version = "2.0.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09a43598840e33d5b0331f38c5e30d13bb11c11210a4b58f0d9b18a5a5eefcd9"
+dependencies = [
+ "thiserror-impl",
+]
+[[package]]
+name = "thiserror-impl"
+version = "2.0.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "43cbfe0cf76104d42a574802844187e84a305e531ed54455f11fbde0f10541cd"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.3",
+]
+[[package]]
+name = "tinystr"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c8323304221c2a851516f22236c5722a72eaa19749016521d6dff0824447d96d"
+dependencies = [
+ "displaydoc",
+ "zerovec",
+]
+[[package]]
+name = "toml"
+version = "0.8.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc1beb996b9d83529a9e75c17a1686767d148d70663143c7854d8b4a09ced362"
+dependencies = [
+ "serde",
+ "serde_spanned",
+ "toml_datetime",
+ "toml_edit",
+]
+[[package]]
+name = "toml_datetime"
+version = "0.6.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "22cddaf88f4fbc13c51aebbf5f8eceb5c7c5a9da2ac40a13519eb5b0a0e8f11c"
+dependencies = [
+ "serde",
+]
+[[package]]
+name = "toml_edit"
+version = "0.22.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41fe8c660ae4257887cf66394862d21dbca4a6ddd26f04a3560410406a2f819a"
+dependencies = [
+ "indexmap",
+ "serde",
+ "serde_spanned",
+ "toml_datetime",
+ "toml_write",
+ "winnow",
+]
+[[package]]
+name = "toml_write"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5d99f8c9a7727884afe522e9bd5edbfc91a3312b36a77b5fb8926e4c31a41801"
+[[package]]
+name = "uncased"
+version = "0.9.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e1b88fcfe09e89d3866a5c11019378088af2d24c3fbd4f0543f96b479ec90697"
+dependencies = [
+ "version_check",
+]
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+[[package]]
+name = "url"
+version = "2.5.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ff67a8a4397373c3ef660812acab3268222035010ab8680ec4215f38ba3d0eed"
+dependencies = [
+ "form_urlencoded",
+ "idna",
+ "percent-encoding",
+ "serde",
+]
+[[package]]
+name = "utf8_iter"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
+[[package]]
+name = "utf8parse"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
+[[package]]
+name = "version_check"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
+[[package]]
 name = "web"
 version = "0.1.0"
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+[[package]]
+name = "windows-sys"
+version = "0.61.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
+dependencies = [
+ "windows-link",
+]
+[[package]]
+name = "winnow"
+version = "0.7.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df79d97927682d2fd8adb29682d1140b343be4ac0f08fd68b7765d9c059d3945"
+dependencies = [
+ "memchr",
+]
+[[package]]
+name = "writeable"
+version = "0.6.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ffae5123b2d3fc086436f8834ae3ab053a283cfac8fe0a0b8eaae044768a4c4"
+[[package]]
+name = "yansi"
+version = "1.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cfe53a6657fd280eaa890a3bc59152892ffa3e30101319d168b781ed6529b049"
+[[package]]
+name = "yoke"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "709fe23a0424b6a435d82152b1bd3fdfb0833487d5fa90d05d42762a9891fef5"
+dependencies = [
+ "stable_deref_trait",
+ "yoke-derive",
+ "zerofrom",
+]
+[[package]]
+name = "yoke-derive"
+version = "0.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "de844c262c8848816172cef550288e7dc6c7b7814b4ee56b3e1553f275f1858e"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+ "synstructure",
+]
+[[package]]
+name = "zerofrom"
+version = "0.1.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ec05a11813ea801ff6d75110ad09cd0824ddba17dfe17128ea0d5f68e6c5272"
+dependencies = [
+ "zerofrom-derive",
+]
+[[package]]
+name = "zerofrom-derive"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "11532158c46691caf0f2593ea8358fed6bbf68a0315e80aae9bd41fbade684a1"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+ "synstructure",
+]
+[[package]]
+name = "zerotrie"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0f9152d31db0792fa83f70fb2f83148effb5c1f5b8c7686c3459e361d9bc20bf"
+dependencies = [
+ "displaydoc",
+ "yoke",
+ "zerofrom",
+]
+[[package]]
+name = "zerovec"
+version = "0.11.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "90f911cbc359ab6af17377d242225f4d75119aec87ea711a880987b18cd7b239"
+dependencies = [
+ "yoke",
+ "zerofrom",
+ "zerovec-derive",
+]
+[[package]]
+name = "zerovec-derive"
+version = "0.11.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "625dc425cab0dca6dc3c3319506e6593dcb08a9f387ea3b284dbd52a92c40555"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+[[package]]
+name = "zmij"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"

 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 //! Configuration loading, validation, and path resolution.
+//!
+//! Configuration is a TOML file plus environment overrides, merged with
+//! [`figment`]. The resolution order (later wins) is:
+//!
+//! 1. built-in defaults ([`Config::default`]);
+//! 2. `/etc/fabrica/fabrica.toml`;
+//! 3. `$XDG_CONFIG_HOME/fabrica/fabrica.toml`;
+//! 4. an explicit `--config <path>`;
+//! 5. `FABRICA__*` environment variables (nested keys use `__`, e.g.
+//!    `FABRICA__SERVER__PORT=8080`).
+//!
+//! Missing files at the fixed locations are skipped; a missing `--config` path
+//! is likewise tolerated so the same code path serves first-run.
+//!
+//! Any `*_file` key (`auth.secret_file`, `mail.password_file`) is read from disk
+//! after merging and supersedes its inline sibling. Secrets are wrapped in
+//! [`Secret`], which redacts itself in every `Debug`/`Serialize` context, so
+//! neither logging nor `fabrica config show` can leak them.
+mod secret;
+mod types;
+use std::path::{Path, PathBuf};
+use figment::Figment;
+use figment::providers::{Env, Format, Serialized, Toml};
+pub use crate::secret::{REDACTED, Secret};
+pub use crate::types::{
+    Auth, Config, Database, Git, Instance, Log, LogFormat, LogLevel, Mail, MailBackend,
+    MailEncryption, Server, Ssh, Storage, Ui,
+};
+/// System-wide configuration path, the lowest-priority file source.
+const ETC_PATH: &str = "/etc/fabrica/fabrica.toml";
+/// Prefix and nesting separator for environment overrides.
+const ENV_PREFIX: &str = "FABRICA__";
+/// Errors produced while loading or validating configuration.
+#[derive(Debug, thiserror::Error)]
+pub enum ConfigError {
+    /// A file could not be parsed, a value had the wrong type, or an unknown key
+    /// was present. Boxed because `figment::Error` is large relative to the
+    /// other variants.
+    #[error("failed to load configuration: {0}")]
+    Load(Box<figment::Error>),
+    /// A `*_file` secret could not be read. The path is included; the file's
+    /// contents never are.
+    #[error("failed to read secret file {path}: {source}")]
+    SecretFile {
+        /// The path that could not be read.
+        path: PathBuf,
+        /// The underlying I/O error.
+        source: std::io::Error,
+    },
+    /// Validation failed. Each line is a distinct, actionable problem.
+    #[error("invalid configuration:\n{0}")]
+    Invalid(String),
+    /// The effective configuration could not be serialized for display.
+    #[error("failed to render configuration: {0}")]
+    Render(#[from] toml::ser::Error),
+}
+/// A successfully loaded configuration together with any non-fatal warnings.
+#[derive(Debug, Clone)]
+pub struct Loaded {
+    /// The validated, effective configuration.
+    pub config: Config,
+    /// Non-fatal advisories (e.g. an insecure cookie setting). The caller is
+    /// expected to surface these to the operator.
+    pub warnings: Vec<String>,
+}
+/// Load configuration from all standard sources, applying the `--config`
+/// override when supplied.
+///
+/// # Errors
+///
+/// Returns [`ConfigError`] if a source fails to parse, an unknown key is
+/// present, a `*_file` secret cannot be read, or validation fails.
+pub fn load(explicit: Option<&Path>) -> Result<Loaded, ConfigError> {
+    load_from(&base_figment(explicit))
+}
+/// Load configuration from an already-assembled [`Figment`].
+///
+/// This is the seam used by [`load`] and by tests that need to bypass the fixed
+/// filesystem locations. The provided figment is expected to include the
+/// [`Config::default`] layer as its base.
+///
+/// # Errors
+///
+/// Returns [`ConfigError`] under the same conditions as [`load`].
+pub fn load_from(figment: &Figment) -> Result<Loaded, ConfigError> {
+    let mut config: Config = figment
+        .extract()
+        .map_err(|e| ConfigError::Load(Box::new(e)))?;
+    resolve_secret_files(&mut config)?;
+    let warnings = validate(&config)?;
+    Ok(Loaded { config, warnings })
+}
+/// Assemble the layered figment for the standard load path.
+fn base_figment(explicit: Option<&Path>) -> Figment {
+    let mut figment =
+        Figment::from(Serialized::defaults(Config::default())).merge(Toml::file(ETC_PATH));
+    if let Some(path) = xdg_config_path() {
+        figment = figment.merge(Toml::file(path));
+    }
+    if let Some(path) = explicit {
+        figment = figment.merge(Toml::file(path));
+    }
+    figment.merge(Env::prefixed(ENV_PREFIX).split("__"))
+}
+/// Resolve `$XDG_CONFIG_HOME/fabrica/fabrica.toml`, falling back to
+/// `$HOME/.config`.
+fn xdg_config_path() -> Option<PathBuf> {
+    let base = match std::env::var_os("XDG_CONFIG_HOME") {
+        Some(dir) if !dir.is_empty() => PathBuf::from(dir),
+        _ => {
+            let home = std::env::var_os("HOME").filter(|h| !h.is_empty())?;
+            PathBuf::from(home).join(".config")
+        }
+    };
+    Some(base.join("fabrica").join("fabrica.toml"))
+}
+/// Read any `*_file` secrets and fold them onto their inline siblings.
+fn resolve_secret_files(config: &mut Config) -> Result<(), ConfigError> {
+    if let Some(path) = &config.auth.secret_file {
+        config.auth.secret = Some(read_secret(path)?);
+    }
+    if let Some(path) = &config.mail.password_file {
+        config.mail.password = Some(read_secret(path)?);
+    }
+    Ok(())
+}
+/// Read a secret from a file, trimming a single trailing newline.
+fn read_secret(path: &Path) -> Result<Secret, ConfigError> {
+    let raw = std::fs::read_to_string(path).map_err(|source| ConfigError::SecretFile {
+        path: path.to_path_buf(),
+        source,
+    })?;
+    Ok(Secret::new(raw.trim_end_matches(['\r', '\n']).to_string()))
+}
+/// Validate the effective configuration, failing fast with actionable messages.
+///
+/// Returns the list of non-fatal warnings on success; returns
+/// [`ConfigError::Invalid`] with every hard error joined by newlines otherwise.
+fn validate(config: &Config) -> Result<Vec<String>, ConfigError> {
+    let mut errors: Vec<String> = Vec::new();
+    let mut warnings: Vec<String> = Vec::new();
+    // instance.url must parse and must not carry a trailing slash.
+    if let Err(e) = url::Url::parse(&config.instance.url) {
+        errors.push(format!(
+            "instance.url ({}) is not a valid URL: {e}",
+            config.instance.url
+        ));
+    } else if config.instance.url.ends_with('/') {
+        errors.push(format!(
+            "instance.url ({}) must not have a trailing slash",
+            config.instance.url
+        ));
+    }
+    if config.instance.default_branch.trim().is_empty() {
+        errors.push("instance.default_branch must not be empty".to_string());
+    }
+    // Storage directories must exist or be creatable.
+    check_dir_creatable("storage.data_dir", &config.storage.data_dir, &mut errors);
+    check_dir_creatable("storage.repo_dir", &config.storage.repo_dir, &mut errors);
+    // SMTP delivery needs a host and a from address.
+    if config.mail.backend == MailBackend::Smtp {
+        if config.mail.host.trim().is_empty() {
+            errors.push("mail.backend is \"smtp\" but mail.host is empty".to_string());
+        }
+        if config.mail.from.trim().is_empty() {
+            errors.push("mail.backend is \"smtp\" but mail.from is empty".to_string());
+        }
+    }
+    // A secure cookie over plain HTTP will be dropped by browsers.
+    if config.auth.cookie_secure && !config.instance.url.starts_with("https://") {
+        warnings.push(
+            "auth.cookie_secure is true but instance.url is not https; browsers will drop the \
+             session cookie"
+                .to_string(),
+        );
+    }
+    if errors.is_empty() {
+        Ok(warnings)
+    } else {
+        Err(ConfigError::Invalid(
+            errors
+                .iter()
+                .map(|e| format!("  - {e}"))
+                .collect::<Vec<_>>()
+                .join("\n"),
+        ))
+    }
+}
+/// Push an error unless `path` is an existing directory or has an existing
+/// directory ancestor (i.e. it could be created). Performs no filesystem
+/// mutation, so it is safe to call from `fabrica config check`.
+fn check_dir_creatable(label: &str, path: &Path, errors: &mut Vec<String>) {
+    match path.metadata() {
+        Ok(meta) if meta.is_dir() => {}
+        Ok(_) => errors.push(format!(
+            "{label} ({}) exists but is not a directory",
+            path.display()
+        )),
+        Err(_) => {
+            let mut ancestor = path.parent();
+            while let Some(dir) = ancestor {
+                if dir.as_os_str().is_empty() {
+                    break;
+                }
+                match dir.metadata() {
+                    Ok(meta) if meta.is_dir() => return,
+                    Ok(_) => {
+                        errors.push(format!(
+                            "{label} ({}) is not creatable: {} is not a directory",
+                            path.display(),
+                            dir.display()
+                        ));
+                        return;
+                    }
+                    Err(_) => ancestor = dir.parent(),
+                }
+            }
+            errors.push(format!(
+                "{label} ({}) does not exist and has no existing parent directory to create it in",
+                path.display()
+            ));
+        }
+    }
+}
+impl Config {
+    /// Render the effective configuration as TOML, with secrets redacted.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`ConfigError::Render`] if serialization fails.
+    pub fn to_toml_string(&self) -> Result<String, ConfigError> {
+        Ok(toml::to_string_pretty(self)?)
+    }
+}
+#[cfg(test)]
+mod tests {
+    #![allow(
+        clippy::unwrap_used,
+        clippy::expect_used,
+        clippy::panic,
+        clippy::result_large_err
+    )]
+    use figment::Jail;
+    use figment::providers::{Format, Serialized, Toml};
+    use super::*;
+    /// Build a figment from defaults plus an inline TOML fragment — no
+    /// filesystem or environment sources, so tests stay hermetic.
+    fn from_toml(fragment: &str) -> Result<Loaded, ConfigError> {
+        load_from(
+            &Figment::from(Serialized::defaults(Config::default())).merge(Toml::string(fragment)),
+        )
+    }
+    #[test]
+    fn defaults_load_and_match() {
+        // A bare config validates; the only advisory is the cookie-over-http
+        // warning, since the default url is http and cookie_secure is true.
+        let loaded = from_toml("").unwrap();
+        assert_eq!(loaded.config, Config::default());
+    }
+    #[test]
+    fn later_sources_win() {
+        let loaded = from_toml("[server]\nport = 9000\n").unwrap();
+        assert_eq!(loaded.config.server.port, 9000);
+        // Untouched keys keep their defaults.
+        assert_eq!(loaded.config.server.address, "0.0.0.0");
+    }
+    #[test]
+    fn unknown_key_is_rejected() {
+        let err = from_toml("[server]\nprot = 9000\n").unwrap_err();
+        assert!(matches!(err, ConfigError::Load(_)), "got {err:?}");
+        assert!(format!("{err}").contains("prot"));
+    }
+    #[test]
+    fn unknown_section_is_rejected() {
+        let err = from_toml("[nope]\nx = 1\n").unwrap_err();
+        assert!(matches!(err, ConfigError::Load(_)), "got {err:?}");
+    }
+    #[test]
+    fn enum_values_are_validated() {
+        let err = from_toml("[mail]\nbackend = \"carrier-pigeon\"\n").unwrap_err();
+        assert!(matches!(err, ConfigError::Load(_)), "got {err:?}");
+    }
+    #[test]
+    fn trailing_slash_url_is_rejected() {
+        let err = from_toml("[instance]\nurl = \"https://git.example.com/\"\n").unwrap_err();
+        match err {
+            ConfigError::Invalid(msg) => assert!(msg.contains("trailing slash"), "{msg}"),
+            other => panic!("expected Invalid, got {other:?}"),
+        }
+    }
+    #[test]
+    fn unparseable_url_is_rejected() {
+        let err = from_toml("[instance]\nurl = \"not a url\"\n").unwrap_err();
+        assert!(matches!(err, ConfigError::Invalid(_)), "got {err:?}");
+    }
+    #[test]
+    fn smtp_without_host_is_rejected() {
+        let err = from_toml("[mail]\nbackend = \"smtp\"\n").unwrap_err();
+        match err {
+            ConfigError::Invalid(msg) => assert!(msg.contains("mail.host"), "{msg}"),
+            other => panic!("expected Invalid, got {other:?}"),
+        }
+    }
+    #[test]
+    fn insecure_cookie_over_http_warns_but_loads() {
+        // Default url is http and cookie_secure defaults to true.
+        let loaded = from_toml("").unwrap();
+        assert!(
+            loaded.warnings.iter().any(|w| w.contains("cookie_secure")),
+            "expected a cookie warning, got {:?}",
+            loaded.warnings
+        );
+    }
+    #[test]
+    fn https_url_produces_no_cookie_warning() {
+        let loaded = from_toml("[instance]\nurl = \"https://git.example.com\"\n").unwrap();
+        assert!(!loaded.warnings.iter().any(|w| w.contains("cookie_secure")));
+    }
+    #[test]
+    fn secrets_are_redacted_in_rendered_toml() {
+        let loaded = from_toml("[auth]\nsecret = \"super-secret-key\"\n").unwrap();
+        assert_eq!(
+            loaded.config.auth.secret.as_ref().unwrap().expose(),
+            "super-secret-key"
+        );
+        let rendered = loaded.config.to_toml_string().unwrap();
+        assert!(rendered.contains(REDACTED));
+        assert!(!rendered.contains("super-secret-key"));
+    }
+    #[test]
+    fn secret_file_supersedes_inline_and_reads_from_disk() {
+        Jail::expect_with(|jail| {
+            let path = jail.directory().join("secret.key");
+            std::fs::write(&path, "from-file\n").unwrap();
+            let fragment = format!(
+                "[auth]\nsecret = \"inline\"\nsecret_file = \"{}\"\n",
+                path.display()
+            );
+            let loaded = from_toml(&fragment).map_err(|e| e.to_string())?;
+            assert_eq!(loaded.config.auth.secret.unwrap().expose(), "from-file");
+            Ok(())
+        });
+    }
+    #[test]
+    fn missing_secret_file_errors() {
+        let err = from_toml("[auth]\nsecret_file = \"/no/such/fabrica/secret\"\n").unwrap_err();
+        match err {
+            ConfigError::SecretFile { path, .. } => {
+                assert!(path.ends_with("secret"));
+            }
+            other => panic!("expected SecretFile, got {other:?}"),
+        }
+    }
+    #[test]
+    fn env_overrides_apply_with_double_underscore_nesting() {
+        Jail::expect_with(|jail| {
+            jail.set_env("FABRICA__SERVER__PORT", "7000");
+            jail.set_env("FABRICA__INSTANCE__DEFAULT_BRANCH", "trunk");
+            let loaded = load_from(&base_figment(None)).map_err(|e| e.to_string())?;
+            assert_eq!(loaded.config.server.port, 7000);
+            assert_eq!(loaded.config.instance.default_branch, "trunk");
+            Ok(())
+        });
+    }
+    #[test]
+    fn explicit_config_path_is_merged() {
+        Jail::expect_with(|jail| {
+            let path = jail.directory().join("fabrica.toml");
+            std::fs::write(&path, "[instance]\nname = \"from-explicit\"\n").unwrap();
+            let loaded = load_from(&base_figment(Some(&path))).map_err(|e| e.to_string())?;
+            assert_eq!(loaded.config.instance.name, "from-explicit");
+            Ok(())
+        });
+    }
+}

+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+//! A string wrapper that never reveals itself when logged or serialized.
+use std::fmt;
+use serde::{Deserialize, Deserializer, Serialize, Serializer};
+/// The placeholder rendered in every non-authorised view of a secret.
+pub const REDACTED: &str = "<redacted>";
+/// A secret string (signing key, SMTP password, …).
+///
+/// The inner value is only reachable through [`Secret::expose`]. Both the
+/// [`fmt::Debug`] and [`Serialize`] implementations emit [`REDACTED`] instead of
+/// the real value, so a `Secret` can never leak through `tracing` output, a
+/// `Debug`-formatted [`crate::Config`], or `fabrica config show`.
+#[derive(Clone, PartialEq, Eq)]
+pub struct Secret(String);
+impl Secret {
+    /// Wrap a value as a secret.
+    #[must_use]
+    pub fn new(value: String) -> Self {
+        Self(value)
+    }
+    /// Borrow the underlying secret value.
+    ///
+    /// This is the single deliberate escape hatch; call it only where the raw
+    /// value is genuinely needed (e.g. signing a token or authenticating to an
+    /// SMTP server), never for display or logging.
+    #[must_use]
+    pub fn expose(&self) -> &str {
+        &self.0
+    }
+}
+impl fmt::Debug for Secret {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(REDACTED)
+    }
+}
+impl Serialize for Secret {
+    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        serializer.serialize_str(REDACTED)
+    }
+}
+impl<'de> Deserialize<'de> for Secret {
+    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+        String::deserialize(deserializer).map(Self)
+    }
+}
+impl From<String> for Secret {
+    fn from(value: String) -> Self {
+        Self(value)
+    }
+}
+#[cfg(test)]
+mod tests {
+    #![allow(clippy::unwrap_used, clippy::expect_used)]
+    use serde::{Deserialize, Serialize};
+    use super::*;
+    #[test]
+    fn debug_is_redacted() {
+        let s = Secret::new("hunter2".to_string());
+        assert_eq!(format!("{s:?}"), REDACTED);
+        assert!(!format!("{s:?}").contains("hunter2"));
+    }
+    #[derive(Serialize, Deserialize)]
+    struct Holder {
+        s: Secret,
+    }
+    #[test]
+    fn serialize_is_redacted_but_expose_is_not() {
+        let holder = Holder {
+            s: Secret::new("hunter2".to_string()),
+        };
+        let rendered = toml::to_string(&holder).unwrap();
+        assert!(rendered.contains(REDACTED));
+        assert!(!rendered.contains("hunter2"));
+        assert_eq!(holder.s.expose(), "hunter2");
+    }
+    #[test]
+    fn deserialize_reads_the_real_value() {
+        let holder: Holder = toml::from_str("s = \"real\"").unwrap();
+        assert_eq!(holder.s.expose(), "real");
+    }
+}

+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+//! The strongly-typed configuration tree.
+//!
+//! Field names and section layout mirror `fabrica.example.toml` exactly. Every
+//! struct is `deny_unknown_fields` so a typo in the TOML (or a stray
+//! `FABRICA__*` variable) is a load error rather than a silently ignored key.
+use std::path::PathBuf;
+use serde::{Deserialize, Serialize};
+use crate::secret::Secret;
+/// The complete, merged configuration.
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Config {
+    /// Instance identity and global policy.
+    pub instance: Instance,
+    /// HTTP server binding and limits.
+    pub server: Server,
+    /// SSH server binding and advertised clone endpoint.
+    pub ssh: Ssh,
+    /// On-disk storage locations.
+    pub storage: Storage,
+    /// Database connection.
+    pub database: Database,
+    /// Authentication parameters and secrets.
+    pub auth: Auth,
+    /// Outbound mail.
+    pub mail: Mail,
+    /// Web UI presentation.
+    pub ui: Ui,
+    /// Git binary and pack-transport limits.
+    pub git: Git,
+    /// Logging.
+    pub log: Log,
+}
+/// `[instance]` — identity and global policy.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Instance {
+    /// Display name shown in the header and page titles.
+    pub name: String,
+    /// Canonical external URL, with no trailing slash.
+    pub url: String,
+    /// One-line description shown on the landing page.
+    pub description: String,
+    /// Default branch for newly created repositories.
+    pub default_branch: String,
+    /// Allow anonymous browse and clone of public repositories.
+    pub allow_anonymous: bool,
+}
+impl Default for Instance {
+    fn default() -> Self {
+        Self {
+            name: "fabrica".to_string(),
+            url: "http://localhost:8080".to_string(),
+            description: String::new(),
+            default_branch: "main".to_string(),
+            allow_anonymous: true,
+        }
+    }
+}
+/// `[server]` — HTTP binding and limits.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Server {
+    /// Bind address for the HTTP listener.
+    pub address: String,
+    /// Bind port for the HTTP listener.
+    pub port: u16,
+    /// Trust `X-Forwarded-For` / `X-Forwarded-Proto` from a fronting proxy.
+    pub behind_proxy: bool,
+    /// Seconds to wait for in-flight requests to drain on shutdown.
+    pub graceful_shutdown_secs: u64,
+    /// Maximum request body size for non-pack routes, in bytes.
+    pub max_body_bytes: u64,
+}
+impl Default for Server {
+    fn default() -> Self {
+        Self {
+            address: "0.0.0.0".to_string(),
+            port: 8080,
+            behind_proxy: false,
+            graceful_shutdown_secs: 20,
+            max_body_bytes: 1_048_576,
+        }
+    }
+}
+/// `[ssh]` — SSH binding and advertised clone endpoint.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Ssh {
+    /// Whether the SSH server is started at all.
+    pub enabled: bool,
+    /// Bind address for the SSH listener.
+    pub address: String,
+    /// Bind port for the SSH listener.
+    pub port: u16,
+    /// Path to the Ed25519 host key (generated on first run if absent).
+    pub host_key_path: PathBuf,
+    /// Hostname shown in clone URLs (may differ from the bind address).
+    pub clone_host: String,
+    /// Port shown in clone URLs (may differ from the bind port).
+    pub clone_port: u16,
+}
+impl Default for Ssh {
+    fn default() -> Self {
+        Self {
+            enabled: true,
+            address: "0.0.0.0".to_string(),
+            port: 2222,
+            host_key_path: PathBuf::from("/var/lib/fabrica/ssh/host_ed25519"),
+            clone_host: "localhost".to_string(),
+            clone_port: 22,
+        }
+    }
+}
+/// `[storage]` — on-disk locations.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Storage {
+    /// Base data directory (secrets, host key, SQLite database, tmp).
+    pub data_dir: PathBuf,
+    /// Directory holding the bare repositories, sharded by id prefix.
+    pub repo_dir: PathBuf,
+}
+impl Default for Storage {
+    fn default() -> Self {
+        Self {
+            data_dir: PathBuf::from("/var/lib/fabrica"),
+            repo_dir: PathBuf::from("/var/lib/fabrica/repos"),
+        }
+    }
+}
+/// `[database]` — connection settings.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Database {
+    /// Connection URL; `sqlite:` and `postgres:` schemes are detected at runtime.
+    pub url: String,
+    /// Maximum number of pooled connections.
+    pub max_connections: u32,
+}
+impl Default for Database {
+    fn default() -> Self {
+        Self {
+            url: "sqlite:///var/lib/fabrica/fabrica.db".to_string(),
+            max_connections: 16,
+        }
+    }
+}
+/// `[auth]` — authentication parameters and secrets.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Auth {
+    /// HS256 signing key. Generated on first run if neither this nor
+    /// [`Auth::secret_file`] is set. Superseded by `secret_file` when present.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub secret: Option<Secret>,
+    /// Path to a file holding the HS256 signing key; takes precedence over
+    /// [`Auth::secret`].
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub secret_file: Option<PathBuf>,
+    /// Session lifetime, in days.
+    pub session_ttl_days: u32,
+    /// API token lifetime, in days.
+    pub token_ttl_days: u32,
+    /// Name of the session cookie.
+    pub cookie_name: String,
+    /// Set the `Secure` attribute on the session cookie.
+    pub cookie_secure: bool,
+    /// Argon2id memory cost, in KiB.
+    pub argon2_m_cost: u32,
+    /// Argon2id time cost (iterations).
+    pub argon2_t_cost: u32,
+    /// Argon2id parallelism (lanes).
+    pub argon2_p_cost: u32,
+}
+impl Default for Auth {
+    fn default() -> Self {
+        Self {
+            secret: None,
+            secret_file: None,
+            session_ttl_days: 30,
+            token_ttl_days: 90,
+            cookie_name: "fabrica_session".to_string(),
+            cookie_secure: true,
+            argon2_m_cost: 19456,
+            argon2_t_cost: 2,
+            argon2_p_cost: 1,
+        }
+    }
+}
+/// Outbound mail backend.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum MailBackend {
+    /// Deliver via SMTP (requires host and from).
+    Smtp,
+    /// Print messages to standard output (useful for development).
+    Stdout,
+    /// Discard messages; mail-dependent features are disabled.
+    None,
+}
+/// Transport encryption for the SMTP backend.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum MailEncryption {
+    /// Upgrade a plaintext connection with `STARTTLS`.
+    Starttls,
+    /// Connect with implicit TLS (SMTPS).
+    Tls,
+    /// No transport encryption.
+    None,
+}
+/// `[mail]` — outbound mail.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Mail {
+    /// Which delivery backend to use.
+    pub backend: MailBackend,
+    /// Envelope and header `From` address.
+    pub from: String,
+    /// SMTP server hostname.
+    pub host: String,
+    /// SMTP server port.
+    pub port: u16,
+    /// SMTP username.
+    pub username: String,
+    /// SMTP password. Superseded by [`Mail::password_file`] when present.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub password: Option<Secret>,
+    /// Path to a file holding the SMTP password; takes precedence over
+    /// [`Mail::password`].
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub password_file: Option<PathBuf>,
+    /// Transport encryption.
+    pub encryption: MailEncryption,
+    /// Connection/handshake timeout, in seconds.
+    pub timeout_secs: u64,
+}
+impl Default for Mail {
+    fn default() -> Self {
+        Self {
+            backend: MailBackend::Stdout,
+            from: "fabrica@localhost".to_string(),
+            host: String::new(),
+            port: 587,
+            username: String::new(),
+            password: None,
+            password_file: None,
+            encryption: MailEncryption::Starttls,
+            timeout_secs: 15,
+        }
+    }
+}
+/// `[ui]` — web UI presentation.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Ui {
+    /// Active theme: a file stem in [`Ui::themes_dir`] or an embedded theme name.
+    pub theme: String,
+    /// Directory scanned for additional `*.css` themes.
+    pub themes_dir: PathBuf,
+    /// Directory for asset overrides; embedded assets are used as a fallback.
+    pub assets_dir: PathBuf,
+    /// Show the theme picker and honour the per-visitor theme cookie.
+    pub allow_theme_choice: bool,
+    /// Show the (CI) runs navigation slot. Inert until CI ships.
+    pub show_runs: bool,
+    /// Lines of context shown around each diff hunk.
+    pub diff_context_lines: u32,
+    /// Skip syntax highlighting for blobs larger than this many bytes.
+    pub max_highlight_bytes: u64,
+    /// Refuse to render diffs larger than this many bytes.
+    pub max_diff_bytes: u64,
+    /// Maximum number of commits walked when annotating a tree listing.
+    pub tree_history_limit: u32,
+}
+impl Default for Ui {
+    fn default() -> Self {
+        Self {
+            theme: "dark".to_string(),
+            themes_dir: PathBuf::from("/var/lib/fabrica/themes"),
+            assets_dir: PathBuf::from("/var/lib/fabrica/assets"),
+            allow_theme_choice: true,
+            show_runs: false,
+            diff_context_lines: 3,
+            max_highlight_bytes: 1_048_576,
+            max_diff_bytes: 5_242_880,
+            tree_history_limit: 1000,
+        }
+    }
+}
+/// `[git]` — git binary and pack-transport limits.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Git {
+    /// The `git` binary to spawn for pack transport and maintenance.
+    pub binary: String,
+    /// Maximum wall-clock time for a single pack transfer, in seconds.
+    pub transport_timeout_secs: u64,
+    /// Reject pushes whose received pack exceeds this many bytes.
+    pub max_pack_size_bytes: u64,
+}
+impl Default for Git {
+    fn default() -> Self {
+        Self {
+            binary: "git".to_string(),
+            transport_timeout_secs: 3600,
+            max_pack_size_bytes: 536_870_912,
+        }
+    }
+}
+/// Log output format.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum LogFormat {
+    /// Human-readable, colourised when attached to a terminal.
+    Pretty,
+    /// One JSON object per line.
+    Json,
+}
+/// Minimum log level. `RUST_LOG` is also honoured at runtime.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum LogLevel {
+    /// Verbose tracing.
+    Trace,
+    /// Debugging detail.
+    Debug,
+    /// Normal operational messages.
+    Info,
+    /// Warnings only.
+    Warn,
+    /// Errors only.
+    Error,
+}
+/// `[log]` — logging.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Log {
+    /// Minimum level emitted.
+    pub level: LogLevel,
+    /// Output format.
+    pub format: LogFormat,
+}
+impl Default for Log {
+    fn default() -> Self {
+        Self {
+            level: LogLevel::Info,
+            format: LogFormat::Pretty,
+        }
+    }
+}

+# Configuration
+fabrica reads a single TOML file, layered over built-in defaults and overridable
+by the environment. A fully-commented starting point ships as
+[`fabrica.example.toml`](../fabrica.example.toml); copy it, keep only the keys
+you change, and validate with `fabrica config check`.
+## Resolution order
+Sources are merged in the following order; a later source overrides an earlier
+one key-by-key:
+. Built-in defaults (every key has one — a bare config is valid).
+. `/etc/fabrica/fabrica.toml`
+. `$XDG_CONFIG_HOME/fabrica/fabrica.toml` (falls back to
+   `$HOME/.config/fabrica/fabrica.toml`)
+. `--config <path>` passed on the command line
+. `FABRICA__*` environment variables
+Missing files are skipped silently, so the same binary serves a first-run
+machine and a fully-configured one.
+### Environment overrides
+Environment variables are prefixed `FABRICA__` and nest with double
+underscores; single underscores inside a key are preserved:
+```
+FABRICA__SERVER__PORT=8080              # -> server.port
+FABRICA__INSTANCE__DEFAULT_BRANCH=trunk # -> instance.default_branch
+FABRICA__LOG__LEVEL=debug               # -> log.level
+```
+### Secret files (`*_file`)
+Any key ending in `_file` reads its value from that file and takes precedence
+over its inline sibling. This keeps secrets out of the config file for
+agenix / systemd-creds / Docker secrets:
+| Inline key      | File key           | Contents                     |
+| --------------- | ------------------ | ---------------------------- |
+| `auth.secret`   | `auth.secret_file` | HS256 session-signing key    |
+| `mail.password` | `mail.password_file` | SMTP password              |
+A single trailing newline is trimmed from the file. Secrets are never logged,
+never appear in error messages, and render as `<redacted>` in
+`fabrica config show`.
+## Validation
+Validation is strict and fails fast with actionable messages:
+- **Unknown keys are an error.** A typo (`prot` for `port`, a misplaced section)
+  aborts the load rather than being ignored.
+- `instance.url` must be a valid URL and must not have a trailing slash.
+- `instance.default_branch` must not be empty.
+- `storage.data_dir` and `storage.repo_dir` must exist or be creatable (they may
+  be created on first run).
+- `mail.backend = "smtp"` requires `mail.host` and `mail.from`.
+Some conditions are **warnings** — printed to stderr but non-fatal:
+- `auth.cookie_secure = true` with a non-`https` `instance.url`: browsers will
+  drop the session cookie. Use this only for local development.
+## Sections
+Each section maps one-to-one to a `[table]` in the TOML file. See
+`fabrica.example.toml` for the default value and a comment on every key.
+| Section      | Purpose                                                        |
+| ------------ | ------------------------------------------------------------- |
+| `[instance]` | Identity, canonical URL, default branch, anonymous access.    |
+| `[server]`   | HTTP bind address/port, proxy trust, body-size and drain limits. |
+| `[ssh]`      | SSH bind address/port, host key path, advertised clone endpoint. |
+| `[storage]`  | Data and repository directories on disk.                      |
+| `[database]` | Connection URL (`sqlite:`/`postgres:`) and pool size.         |
+| `[auth]`     | Session/token lifetimes, cookie settings, Argon2id cost, signing key. |
+| `[mail]`     | Backend (`smtp`/`stdout`/`none`), sender, SMTP endpoint and encryption. |
+| `[ui]`       | Theme, asset/theme directories, diff/highlight limits.        |
+| `[git]`      | `git` binary path and pack-transport limits.                  |
+| `[log]`      | Level and format (`pretty`/`json`).                           |
+## Commands
+- `fabrica config check` — validate the effective configuration and exit. Prints
+  `configuration ok` and exits `0` on success; prints the problems and exits `1`
+  otherwise. Warnings are printed but do not change the exit status.
+- `fabrica config show` — print the effective, merged configuration with secrets
+  redacted. Add `--json` for machine-readable output.
+Both honour the global `--config <path>` flag.

 **Rationale:** flake-parts scales better as the flake grows (NixOS module,
 container image, multiple checks) and gives a cleaner multi-output structure. The
 spec permits either; picked one and stay consistent.
+## 2026-07-24 — Secrets are a redact-by-default `Secret` newtype
+**Decision:** Secret configuration values (`auth.secret`, `mail.password`) are
+wrapped in a `config::Secret` newtype whose `Debug` and `Serialize` impls always
+emit `<redacted>`. The real value is reachable only through `Secret::expose`.
+**Alternatives:** Store secrets as plain `String` and redact them at each output
+site (`config show`, error messages, logs).
+**Rationale:** Redaction is the default and cannot be forgotten — a `Secret`
+cannot leak through `tracing`, a `Debug`-formatted `Config`, `fabrica config
+show`, or the JSON API, satisfying the spec's "secrets MUST NOT be logged,
+echoed, or included in error messages". Site-by-site redaction is one missed
+call away from a leak. Trade-off: serialization is lossy, so `Secret` is never
+round-tripped through our own `Serialize` (figment reads the raw value into the
+figment `Value` before deserialization, and `*_file` resolution reads from disk).
+## 2026-07-24 — Strict config: unknown keys are errors, missing files are not
+**Decision:** Every config struct is `#[serde(deny_unknown_fields)]`, so an
+unknown key (typo, stale key, stray `FABRICA__*`) aborts the load. Missing files
+at the fixed locations (`/etc`, XDG) and a missing `--config` path are tolerated
+silently. Directory validation checks creatability without side effects (an
+existing directory ancestor), never creating anything during `config check`.
+**Alternatives:** Ignore unknown keys (serde default); require every file to
+exist; create directories during validation.
+**Rationale:** Failing fast on typos is worth more than forward-compatibility for
+a single-operator forge. Tolerating missing files lets one binary serve both a
+bare first-run machine and a fully-configured one. Side-effect-free validation
+keeps `config check` safe to run anywhere.

+# fabrica configuration — copy to /etc/fabrica/fabrica.toml (or point at it with
+# `fabrica --config <path>`) and edit. Every value shown below is the built-in
+# default, so you only need to keep the keys you actually change.
+#
+# Resolution order, later wins: built-in defaults -> /etc/fabrica/fabrica.toml
+# -> $XDG_CONFIG_HOME/fabrica/fabrica.toml -> --config <path> -> FABRICA__* env.
+# Environment overrides nest with double underscores, e.g.
+#   FABRICA__SERVER__PORT=8080
+#
+# Any *_file key reads its value from that file and wins over its inline sibling
+# (use it for agenix / systemd-creds / Docker secrets). Unknown keys are a hard
+# error, so a typo fails fast rather than being silently ignored.
+#
+# Validate with `fabrica config check`; print the effective config (secrets
+# redacted) with `fabrica config show`.
+[instance]
+name            = "fabrica"                 # shown in the header and page titles
+url             = "https://git.example.com" # canonical external URL, no trailing slash
+description     = "A small, private forge." # one line, shown on the landing page
+default_branch  = "main"                    # default branch for new repositories
+allow_anonymous = true                      # anonymous browse + clone of public repos
+[server]
+address                = "0.0.0.0"
+port                   = 8080
+behind_proxy           = false     # trust X-Forwarded-For / X-Forwarded-Proto
+graceful_shutdown_secs = 20        # drain in-flight requests for this long on shutdown
+max_body_bytes         = 1048576   # non-pack routes only
+[ssh]
+enabled       = true
+address       = "0.0.0.0"
+port          = 2222
+host_key_path = "/var/lib/fabrica/ssh/host_ed25519"  # generated on first run if absent
+clone_host    = "git.example.com"  # what the UI shows in clone URLs, may differ from bind
+clone_port    = 22
+[storage]
+data_dir = "/var/lib/fabrica"        # secrets, host key, SQLite db, scratch
+repo_dir = "/var/lib/fabrica/repos"  # bare repos, sharded by id prefix
+[database]
+url             = "sqlite:///var/lib/fabrica/fabrica.db"
+max_connections = 16
+# SQLite is opened with journal_mode=WAL, synchronous=NORMAL, foreign_keys=ON,
+# busy_timeout=5000. Postgres URLs (postgres://…) are detected automatically.
+[auth]
+# secret          = "…"                        # HS256 key; prefer secret_file below
+secret_file       = "/var/lib/fabrica/secret"  # generated on first run, mode 0600
+session_ttl_days  = 30
+token_ttl_days    = 90
+cookie_name       = "fabrica_session"
+cookie_secure     = true    # set false only if instance.url is plain http (dev)
+argon2_m_cost     = 19456   # KiB
+argon2_t_cost     = 2       # iterations
+argon2_p_cost     = 1       # lanes
+[mail]
+backend       = "smtp"                    # smtp | stdout | none
+from          = "fabrica@example.com"
+host          = "smtp.example.com"        # required when backend = "smtp"
+port          = 587
+username      = "fabrica"
+# password    = "…"                       # prefer password_file below
+password_file = "/run/secrets/fabrica-smtp"
+encryption    = "starttls"                # starttls | tls | none
+timeout_secs  = 15
+[ui]
+theme                = "dark"    # file stem in themes_dir, or an embedded theme name
+themes_dir           = "/var/lib/fabrica/themes"
+assets_dir           = "/var/lib/fabrica/assets"
+allow_theme_choice   = true      # show the theme picker; choice persists in a cookie
+show_runs            = false     # CI nav slot, inert until CI ships
+diff_context_lines   = 3
+max_highlight_bytes  = 1048576   # skip highlighting blobs larger than this
+max_diff_bytes       = 5242880   # refuse to render diffs larger than this
+tree_history_limit   = 1000      # commits walked when annotating a tree listing
+[git]
+binary                 = "git"       # must be >= 2.41 and on PATH
+transport_timeout_secs = 3600
+max_pack_size_bytes    = 536870912   # reject pushes with a larger received pack
+[log]
+level  = "info"     # trace | debug | info | warn | error (RUST_LOG also honoured)
+format = "pretty"   # pretty | json