feat(cli): the operator config surface — identity and output defaults (RFC-007 PR 1)

~/.omnigraph/config.yaml joins the resolution chains as the operator
surface: operator.actor becomes the last hop of THE actor chain (--as >
legacy cli.actor during the RFC-008 window > operator.actor > none, one
implementation for direct-engine and cluster commands alike) and
defaults.output joins the read-format cascade below every more-specific
source. Discovery honors $OMNIGRAPH_HOME (tilde-expanded, #139 finding 9);
an absent file is an empty layer; unknown keys WARN and load (a file
written for later slices must not break this CLI); malformed YAML is a
loud error. The module is CLI-only — the server never reads operator
config (invariant 11 by construction).

$OMNIGRAPH_CONFIG becomes a first-class stand-in for --config in
load_config (flag > env > ./omnigraph.yaml), one meaning in both binaries.

The test harness pins hermeticity: spawned binaries get a nonexistent
OMNIGRAPH_HOME by default so no test ever reads the developer's real
operator config. New coverage: loader unit tests, the env-precedence
matrix on load_config_in, and spawned-binary e2es for the actor chain
(operator wins with no flag/legacy key; legacy outranks it; --as wins) and
the format cascade.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

crates/omnigraph-cli/src/operator.rs

@@ -0,0 +1,212 @@
+//! The operator config surface (RFC-007): `~/.omnigraph/config.yaml` — who
+//! the operator IS (identity, ergonomics), never what the system is (that's
+//! cluster config) and never a project file (nothing here arrives with a
+//! repo checkout).
+//!
+//! PR-1 scope: `operator.actor` + `defaults.output`. Unknown keys WARN and
+//! are preserved-by-ignoring — a file written for a newer CLI (servers,
+//! aliases, credentials keys from later slices) must load cleanly on this
+//! one. Contrast with `cluster.yaml`, where unknown keys are fatal because
+//! they change what a plan means.
+//!
+//! This module is CLI-only by design: the server never reads operator
+//! config (server-side identity comes from bearer auth — invariant 11
+//! holds by construction).
+
+use std::env;
+use std::path::{Path, PathBuf};
+
+use color_eyre::Result;
+use color_eyre::eyre::eyre;
+use serde::Deserialize;
+
+use omnigraph_server::config::ReadOutputFormat;
+
+pub(crate) const OPERATOR_HOME_ENV: &str = "OMNIGRAPH_HOME";
+pub(crate) const OPERATOR_DIR: &str = ".omnigraph";
+pub(crate) const OPERATOR_CONFIG_FILE: &str = "config.yaml";
+
+#[derive(Debug, Default, Deserialize)]
+pub(crate) struct OperatorConfig {
+    #[serde(default)]
+    pub(crate) operator: OperatorIdentity,
+    #[serde(default)]
+    pub(crate) defaults: OperatorDefaults,
+    /// Everything this CLI version doesn't know. Warned once at load,
+    /// otherwise ignored (forward compatibility within the operator layer).
+    #[serde(flatten)]
+    unknown: serde_yaml::Mapping,
+}
+
+#[derive(Debug, Default, Deserialize)]
+pub(crate) struct OperatorIdentity {
+    /// Default actor for every `--as` cascade (CLI direct-engine writes and
+    /// cluster commands alike): `--as` > legacy config actor (RFC-008
+    /// window) > this > none.
+    pub(crate) actor: Option<String>,
+    #[serde(flatten)]
+    unknown: serde_yaml::Mapping,
+}
+
+#[derive(Debug, Default, Deserialize)]
+pub(crate) struct OperatorDefaults {
+    /// Default read output format, below every more-specific source.
+    pub(crate) output: Option<ReadOutputFormat>,
+    #[serde(flatten)]
+    unknown: serde_yaml::Mapping,
+}
+
+impl OperatorConfig {
+    pub(crate) fn actor(&self) -> Option<&str> {
+        self.operator.actor.as_deref()
+    }
+
+    pub(crate) fn output(&self) -> Option<ReadOutputFormat> {
+        self.defaults.output
+    }
+}
+
+/// The operator dir: `$OMNIGRAPH_HOME` if set (tilde-expanded), else
+/// `~/.omnigraph`. Returns None when no home directory is resolvable
+/// (degenerate environments — the layer is simply absent).
+pub(crate) fn operator_dir() -> Option<PathBuf> {
+    if let Some(home_override) = env::var_os(OPERATOR_HOME_ENV) {
+        let raw = home_override.to_string_lossy().into_owned();
+        return Some(expand_tilde(&raw));
+    }
+    env::home_dir().map(|home| home.join(OPERATOR_DIR))
+}
+
+/// Load the operator layer. Absent file (or unresolvable home) is an empty
+/// layer, never an error; a present-but-malformed file is a loud error (the
+/// operator owns it and can fix it); unknown keys warn to stderr once.
+pub(crate) fn load_operator_config() -> Result<OperatorConfig> {
+    let Some(dir) = operator_dir() else {
+        return Ok(OperatorConfig::default());
+    };
+    load_operator_config_at(&dir.join(OPERATOR_CONFIG_FILE))
+}
+
+pub(crate) fn load_operator_config_at(path: &Path) -> Result<OperatorConfig> {
+    let text = match std::fs::read_to_string(path) {
+        Ok(text) => text,
+        Err(err) if err.kind() == std::io::ErrorKind::NotFound => {
+            return Ok(OperatorConfig::default());
+        }
+        Err(err) => {
+            return Err(eyre!(
+                "could not read operator config '{}': {err}",
+                path.display()
+            ));
+        }
+    };
+    let config: OperatorConfig = serde_yaml::from_str(&text).map_err(|err| {
+        eyre!(
+            "could not parse operator config '{}': {err}",
+            path.display()
+        )
+    })?;
+    for warning in config.unknown_key_warnings() {
+        eprintln!("warning: {warning} in operator config '{}'", path.display());
+    }
+    Ok(config)
+}
+
+impl OperatorConfig {
+    fn unknown_key_warnings(&self) -> Vec<String> {
+        let mut warnings = Vec::new();
+        let mut collect = |mapping: &serde_yaml::Mapping, prefix: &str| {
+            for key in mapping.keys() {
+                if let Some(name) = key.as_str() {
+                    warnings.push(format!(
+                        "unknown key `{prefix}{name}` (newer CLI feature or typo); ignored"
+                    ));
+                }
+            }
+        };
+        collect(&self.unknown, "");
+        collect(&self.operator.unknown, "operator.");
+        collect(&self.defaults.unknown, "defaults.");
+        warnings
+    }
+}
+
+/// Expand a leading `~` / `~/` to the home directory (PR #139 finding 9:
+/// a literal `./~/…` path silently created a directory named `~`).
+pub(crate) fn expand_tilde(raw: &str) -> PathBuf {
+    if raw == "~" {
+        return env::home_dir().unwrap_or_else(|| PathBuf::from(raw));
+    }
+    if let Some(rest) = raw.strip_prefix("~/") {
+        if let Some(home) = env::home_dir() {
+            return home.join(rest);
+        }
+    }
+    PathBuf::from(raw)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::fs;
+
+    #[test]
+    fn absent_file_is_an_empty_layer() {
+        let dir = tempfile::tempdir().unwrap();
+        let config = load_operator_config_at(&dir.path().join("config.yaml")).unwrap();
+        assert!(config.actor().is_none());
+        assert!(config.output().is_none());
+    }
+
+    #[test]
+    fn parses_identity_and_defaults() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("config.yaml");
+        fs::write(
+            &path,
+            "operator:\n  actor: act-andrew\ndefaults:\n  output: json\n",
+        )
+        .unwrap();
+        let config = load_operator_config_at(&path).unwrap();
+        assert_eq!(config.actor(), Some("act-andrew"));
+        assert_eq!(config.output(), Some(ReadOutputFormat::Json));
+    }
+
+    #[test]
+    fn unknown_keys_warn_but_load() {
+        // A file written for a later slice (servers/aliases) must load
+        // cleanly today — warn-only forward compatibility.
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("config.yaml");
+        fs::write(
+            &path,
+            "operator:\n  actor: act-a\n  color: green\nservers:\n  prod:\n    url: https://example.com\naliases: {}\n",
+        )
+        .unwrap();
+        let config = load_operator_config_at(&path).unwrap();
+        assert_eq!(config.actor(), Some("act-a"));
+        let warnings = config.unknown_key_warnings();
+        assert_eq!(warnings.len(), 3, "{warnings:?}");
+        assert!(warnings.iter().any(|w| w.contains("`servers`")));
+        assert!(warnings.iter().any(|w| w.contains("`aliases`")));
+        assert!(warnings.iter().any(|w| w.contains("`operator.color`")));
+    }
+
+    #[test]
+    fn malformed_yaml_is_a_loud_error() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("config.yaml");
+        fs::write(&path, "operator: [not, a, mapping\n").unwrap();
+        let err = load_operator_config_at(&path).unwrap_err();
+        assert!(err.to_string().contains("could not parse operator config"));
+    }
+
+    #[test]
+    fn expand_tilde_resolves_home_prefix() {
+        let home = env::home_dir().unwrap();
+        assert_eq!(expand_tilde("~"), home);
+        assert_eq!(expand_tilde("~/x/y"), home.join("x/y"));
+        assert_eq!(expand_tilde("/abs/path"), PathBuf::from("/abs/path"));
+        assert_eq!(expand_tilde("rel/path"), PathBuf::from("rel/path"));
+    }
+}