feat(cli)!: unify config env to FIRMA_CONFIG (#627)

## Why

`firma sidecar` bound `--config` to `FIRMA_SIDECAR_CONFIG_FILE`,
`authority` bound no env, and the stack-inspection commands bound
`FIRMA_CONFIG` — all selecting the same unified `firma.toml`. The
`FIRMA_SIDECAR_CONFIG_FILE` name was also overloaded as a `firma run`
autostart sidecar-template source, so setting it for one purpose
silently affected the other. This unifies unified-config selection under
one canonical flag and env.

## What Changed

- Add a global `-c` / `--config` bound to `FIRMA_CONFIG` on the
top-level `firma` command (accepted before or after any subcommand);
`main.rs` threads the resolved path into each consumer.
- Remove the per-command unified-config `--config` from `control`,
`doctor`, `monitor`, `sidecar` (serve/start/stop), and `authority`.
`firma run --config` keeps working via the global (it was already the
unified-config selector).
- Fully retire `FIRMA_SIDECAR_CONFIG_FILE`, including the `firma run`
autostart template fallback (`TemplateSource::Env` removed; selection is
now `--sidecar-config` → `./firma_sidecar.toml` → synthesized minimal).
- Update docs (cli.md, README, manage-the-stack, firma-run, examples)
and extend the `--help` contract test to sidecar/authority.

## Risks / Notes

- **Breaking (`feat!`)**: `FIRMA_SIDECAR_CONFIG_FILE` is removed.
Migration: export `FIRMA_CONFIG` to select the unified `firma.toml`; use
`--sidecar-config <path>` (or `./firma_sidecar.toml`) for a `firma run`
autostart template.
- Config resolution precedence and fail-closed behavior are unchanged
(still owned by `firma-config-loader` `ConfigResolver`); the path — not
a pre-resolved config — is threaded because `doctor` reports resolution,
`run` may scaffold, and `sidecar start` uses a different resolver.
- As a clap global, `--config` is also accepted (and ignored) by
commands that do not consume the unified config (`token`, `policy`,
internal `__*`).
- Design/rationale: `docs/architecture/config-env-unification-plan.md`.
- Stacked on top of #619 (`amp/canonical-config-discovery`); base
retargets to `main` once that merges.

## AI Assistance

Claude Opus 4.8 (claude-opus-4-8).

Author: luca-iachini

crates/firma-run/src/routing.rs

@@ -901,10 +901,6 @@ fn prepare_run_components(
             })?;
         let firma_exe = std::env::current_exe()
             .map_err(|error| RunError::Internal(format!("resolve current executable: {error}")))?;
-        let env_template = std::env::var("FIRMA_SIDECAR_CONFIG_FILE")
-            .ok()
-            .filter(|value| !value.trim().is_empty())
-            .map(PathBuf::from);
         let cwd_template = std::env::current_dir()
             .ok()
             .map(|cwd| cwd.join("firma_sidecar.toml"));
@@ -1006,7 +1002,6 @@ fn prepare_run_components(
                             session_id: &identity.session_id,
                             marker_dir: marker_dir.clone(),
                             template_path: component_flags.template_path.as_deref(),
-                            env_template: env_template.clone(),
                             cwd_template: cwd_template.clone(),
                             firma_exe: firma_exe.clone(),
                             authority_url: component_flags.authority_url.as_deref(),

crates/firma-run/src/sidecar/config.rs

@@ -303,8 +303,6 @@ pub struct SynthesizeRequest<'a> {
     pub session_id: &'a str,
     /// Highest-priority template path (typically `--sidecar-config`).
     pub explicit_template: Option<&'a Path>,
-    /// Fallback template path from `FIRMA_SIDECAR_CONFIG_FILE`.
-    pub env_template: Option<PathBuf>,
     /// Fallback template path from the current working directory.
     pub cwd_template: Option<PathBuf>,
     /// UDS path the spawned sidecar must bind.
@@ -352,7 +350,6 @@ pub struct SynthesizeRequest<'a> {
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum TemplateSource {
     Explicit(PathBuf),
-    Env(PathBuf),
     Cwd(PathBuf),
     Minimal,
 }
@@ -372,7 +369,7 @@ pub enum TemplateSource {
 pub fn synthesize(req: SynthesizeRequest<'_>) -> Result<TemplateSource, RunError> {
     let source = select_template(&req);
     let (mut value, template_dir) = match &source {
-        TemplateSource::Explicit(path) | TemplateSource::Env(path) | TemplateSource::Cwd(path) => {
+        TemplateSource::Explicit(path) | TemplateSource::Cwd(path) => {
             let abs = std::path::absolute(path).unwrap_or_else(|_| path.clone());
             (parse_template(path)?, abs.parent().map(Path::to_path_buf))
         }
@@ -489,11 +486,6 @@ fn select_template(req: &SynthesizeRequest<'_>) -> TemplateSource {
     {
         return TemplateSource::Explicit(path.to_path_buf());
     }
-    if let Some(path) = req.env_template.as_deref()
-        && path.is_file()
-    {
-        return TemplateSource::Env(path.to_path_buf());
-    }
     if let Some(path) = req.cwd_template.as_deref()
         && path.is_file()
     {
@@ -1058,7 +1050,6 @@ mod tests {
             execution_profile: firma_config_loader::AgentProfile::Vscode,
             session_id: "sess_001",
             explicit_template: None,
-            env_template: None,
             cwd_template: None,
             socket_path: &tmp.path().join("sidecar.sock"),
             listen_addr: Some(

crates/firma-run/src/sidecar/prepare.rs

@@ -61,7 +61,6 @@ pub struct PrepareRequest<'a> {
     pub session_id: &'a str,
     pub marker_dir: PathBuf,
     pub template_path: Option<&'a Path>,
-    pub env_template: Option<PathBuf>,
     pub cwd_template: Option<PathBuf>,
     pub firma_exe: PathBuf,
     pub authority_url: Option<&'a str>,
@@ -104,7 +103,6 @@ pub fn prepare(req: PrepareRequest<'_>) -> Result<PreparedSidecarLaunch, RunErro
         execution_profile: req.execution_profile,
         session_id: req.session_id,
         explicit_template: req.template_path,
-        env_template: req.env_template,
         cwd_template: req.cwd_template,
         socket_path: &socket_path,
         listen_addr,

crates/firma-run/tests/integration/sidecar_config_merge.rs

@@ -51,7 +51,6 @@ fn req<'a>(sock: &'a Path, out: &'a Path) -> SynthesizeRequest<'a> {
         execution_profile: AgentProfile::Generic,
         session_id: "sess",
         explicit_template: None,
-        env_template: None,
         cwd_template: None,
         socket_path: sock,
         listen_addr: None,
@@ -269,13 +268,12 @@ paths = ["/etc/firma/cap.toml"]
 }
 
 #[test]
-fn priority_order_explicit_over_env_over_cwd() {
+fn priority_order_explicit_over_cwd() {
     let tmp = TempDir::new().expect("tmp");
 
     let explicit = tmp.path().join("explicit.toml");
-    let env = tmp.path().join("env.toml");
     let cwd = tmp.path().join("cwd.toml");
-    for path in [&explicit, &env, &cwd] {
+    for path in [&explicit, &cwd] {
         fs::write(path, "[interceptor]\nmode = \"http_proxy\"\n").expect("write");
     }
 
@@ -284,21 +282,12 @@ fn priority_order_explicit_over_env_over_cwd() {
 
     let source = synthesize(SynthesizeRequest {
         explicit_template: Some(&explicit),
-        env_template: Some(env.clone()),
         cwd_template: Some(cwd.clone()),
         ..req(&sock, &out)
     })
     .expect("synthesize");
     assert_eq!(source, TemplateSource::Explicit(explicit));
 
-    let source = synthesize(SynthesizeRequest {
-        env_template: Some(env.clone()),
-        cwd_template: Some(cwd.clone()),
-        ..req(&sock, &out)
-    })
-    .expect("synthesize");
-    assert_eq!(source, TemplateSource::Env(env));
-
     let source = synthesize(SynthesizeRequest {
         cwd_template: Some(cwd.clone()),
         ..req(&sock, &out)
@@ -477,7 +466,6 @@ fn nonexistent_template_paths_fall_through_to_minimal() {
     let explicit = PathBuf::from("/does/not/exist/explicit.toml");
     let source = synthesize(SynthesizeRequest {
         explicit_template: Some(&explicit),
-        env_template: Some(PathBuf::from("/does/not/exist/env.toml")),
         cwd_template: Some(PathBuf::from("/does/not/exist/cwd.toml")),
         ..req(&sock, &out)
     })

crates/firma-run/tests/integration/sidecar_prepare.rs

@@ -21,7 +21,6 @@ fn request(
         session_id: "prepared-session",
         marker_dir,
         template_path: None,
-        env_template: None,
         cwd_template: None,
         firma_exe: "/bin/false".into(),
         authority_url: Some("http://127.0.0.1:50051"),

crates/firma/README.md

@@ -51,7 +51,7 @@ firma sidecar --config /etc/firma/firma.toml
 
 | Flag                 | Env                              | Default          |
 | -------------------- | -------------------------------- | ---------------- |
-| `-c, --config`       | `FIRMA_SIDECAR_CONFIG_FILE`      | discovered       |
+| `-c, --config`       | `FIRMA_CONFIG`                   | discovered       |
 | `--health-bind-addr` | `FIRMA_SIDECAR_HEALTH_BIND_ADDR` | `127.0.0.1:9000` |
 
 When `--config` is omitted, a shared `firma.toml` is discovered from
@@ -222,12 +222,12 @@ Subcommands:
 
 `start` / `stop` flags:
 
-| Flag          | Env                         | Default                                      |
-| ------------- | --------------------------- | -------------------------------------------- |
-| `--config`    | `FIRMA_SIDECAR_CONFIG_FILE` | discovered `firma.toml` (`start` only)       |
-| `--state-dir` | `FIRMA_STATE_DIR`           | `$XDG_RUNTIME_DIR/firma` → `/tmp/firma-$UID` |
-| `--detach`    | —                           | _off_ (`start` only)                         |
-| `--timeout`   | —                           | `2` seconds (`stop` only)                    |
+| Flag          | Env               | Default                                        |
+| ------------- | ----------------- | ---------------------------------------------- |
+| `--config`    | `FIRMA_CONFIG`    | discovered `firma.toml` (`start` only, global) |
+| `--state-dir` | `FIRMA_STATE_DIR` | `$XDG_RUNTIME_DIR/firma` → `/tmp/firma-$UID`   |
+| `--detach`    | —                 | _off_ (`start` only)                           |
+| `--timeout`   | —                 | `2` seconds (`stop` only)                      |
 
 State-dir resolution order: `--state-dir` flag → `FIRMA_STATE_DIR` env →
 `$XDG_RUNTIME_DIR/firma` → `/tmp/firma-$UID` on Unix;

crates/firma/src/args/authority.rs

@@ -7,11 +7,6 @@ use firma_identifiers::TokenId;
 
 #[derive(Debug, clap::Args)]
 pub struct Args {
-    /// Path to the Authority TOML config (issuer identity, key paths, bundle dir,
-    /// listen address). When unset, falls back to platform discovery.
-    #[arg(short, long)]
-    pub config: Option<PathBuf>,
-
     /// Internal path for writing the one-shot startup report.
     #[arg(long, hide = true)]
     pub startup_report: Option<PathBuf>,

crates/firma/src/args/control.rs

@@ -7,10 +7,6 @@ use clap::Args as ClapArgs;
 /// Parsed `firma control` command-line arguments.
 #[derive(Debug, ClapArgs)]
 pub struct Args {
-    /// Stack config used to discover the sidecar audit log and Authority
-    /// policy directory.
-    #[arg(long, env = "FIRMA_CONFIG")]
-    pub config: Option<PathBuf>,
     /// Override the runtime state directory containing the audit log.
     #[arg(long, env = "FIRMA_STATE_DIR")]
     pub state_dir: Option<PathBuf>,

crates/firma/src/args/doctor.rs

@@ -6,8 +6,7 @@ use clap::Args as ClapArgs;
 
 /// Parsed `firma doctor` arguments.
 ///
-/// `--config` is the unified `firma.toml`. It's optional; when unset,
-/// `doctor` resolves it via the standard config discovery precedence.
+/// The unified `firma.toml` is selected by the global `--config` / `FIRMA_CONFIG`.
 ///
 /// `--state-dir` overrides the resolved state directory.
 ///
@@ -18,10 +17,6 @@ use clap::Args as ClapArgs;
 /// already report unreachable as a structured `FAIL`, not a hang.
 #[derive(Debug, ClapArgs)]
 pub struct Args {
-    /// Path to the unified `firma.toml`. When unset, resolved via standard
-    /// config discovery (`FIRMA_CONFIG` / nearest `.firma/firma.toml`).
-    #[arg(long, env = "FIRMA_CONFIG")]
-    pub config: Option<PathBuf>,
     /// Override the runtime state directory inspected for pid files, sockets,
     /// and component logs.
     #[arg(long, env = "FIRMA_STATE_DIR")]
@@ -55,7 +50,6 @@ mod tests {
     #[test]
     fn defaults_parse() {
         let args = try_parse(&["firma-doctor"]).expect("parse default");
-        assert!(args.config.is_none());
         assert!(args.state_dir.is_none());
         assert!(!args.json);
         assert_eq!(args.timeout_ms, 500);

crates/firma/src/args/mod.rs

@@ -71,6 +71,11 @@ fn configure_help(command: &mut ClapCommand) {
                   firma doctor        — diagnose setup issues"
 )]
 pub struct Cli {
+    /// Unified `firma.toml` selecting stack configuration. When unset, resolved
+    /// via `FIRMA_CONFIG`, then the nearest `.firma/firma.toml`. Ignored by
+    /// subcommands that do not consume the unified config.
+    #[arg(long, short = 'c', global = true, env = "FIRMA_CONFIG")]
+    pub config: Option<PathBuf>,
     /// Write logs to this file instead of stderr.
     #[arg(long, global = true, env = "FIRMA_LOG_FILE")]
     pub log_file: Option<PathBuf>,