feat(cli)!: unify graph selection under --graph; --cluster is a global scope; remove --cluster-graph (#241)

RFC-011: --graph is the single graph selector across server and cluster scopes; --cluster becomes a global scope primitive; --cluster-graph removed. Maintenance dispatch unified through resolve_scope. Wrong-address guard validates each scope flag against the verb it can consume.

crates/omnigraph-cli/tests/cli_cluster.rs

@@ -975,7 +975,7 @@ fn optimize_resolves_a_cluster_graph_by_id() {
             .arg("optimize")
             .arg("--cluster")
             .arg(temp.path())
-            .arg("--cluster-graph")
+            .arg("--graph")
             .arg("knowledge")
             .arg("--json"),
     );
@@ -994,7 +994,7 @@ fn optimize_unknown_cluster_graph_id_errors() {
             .arg("optimize")
             .arg("--cluster")
             .arg(temp.path())
-            .arg("--cluster-graph")
+            .arg("--graph")
             .arg("does-not-exist")
             .arg("--json"),
     );
@@ -1006,8 +1006,10 @@ fn optimize_unknown_cluster_graph_id_errors() {
 }
 
 #[test]
-fn cluster_flag_requires_cluster_graph() {
-    // clap enforces both-or-neither.
+fn cluster_without_graph_demands_a_graph_selector() {
+    // A cluster holds many graphs; `--cluster` alone can't pick one. The scope
+    // resolver demands `--graph <id>` (replacing the old `--cluster-graph`
+    // requirement) before it ever touches cluster state.
     let out = output_failure(
         cli()
             .arg("optimize")
@@ -1017,8 +1019,8 @@ fn cluster_flag_requires_cluster_graph() {
     );
     let stderr = String::from_utf8_lossy(&out.stderr);
     assert!(
-        stderr.contains("cluster-graph") || stderr.contains("required"),
-        "expected --cluster to require --cluster-graph; got: {stderr}"
+        stderr.contains("--graph <id>"),
+        "expected --cluster to demand --graph; got: {stderr}"
     );
 }
 
@@ -1076,7 +1078,7 @@ fn optimize_by_cluster_works_when_catalog_payloads_are_degraded() {
             .arg("optimize")
             .arg("--cluster")
             .arg(temp.path())
-            .arg("--cluster-graph")
+            .arg("--graph")
             .arg("knowledge")
             .arg("--json"),
     );

crates/omnigraph-cli/tests/cli_data.rs

@@ -165,12 +165,63 @@ fn optimize_with_server_flag_errors_wrong_plane() {
     let stderr = String::from_utf8_lossy(&output.stderr);
     assert!(
         stderr.contains("`optimize` is a direct (storage-native) command")
-            && stderr.contains("--server/--graph address a served graph and do not apply")
-            && stderr.contains("Pass a storage URI, or --cluster <dir> --cluster-graph <id>."),
+            && stderr.contains("--server addresses a served graph and does not apply")
+            && stderr.contains("Pass a storage URI, or --cluster <dir> --graph <id>."),
         "wrong-capability guard message not found; got: {stderr}"
     );
 }
 
+#[test]
+fn wrong_address_guard_message_has_no_trailing_space() {
+    // The remediation tail is empty for served-addressing capabilities, so a
+    // misplaced --cluster on a data verb must not leave "… does not apply. "
+    // with a dangling space (error text is observable contract). NO_COLOR keeps
+    // the assertion off ANSI styling.
+    let output = output_failure(
+        cli()
+            .env("NO_COLOR", "1")
+            .arg("query")
+            .arg("--cluster")
+            .arg("./brain")
+            .arg("-e")
+            .arg("query q { Person { id } }"),
+    );
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert!(
+        stderr.contains("and does not apply."),
+        "expected the wrong-address message; got: {stderr}"
+    );
+    assert!(
+        !stderr.contains("and does not apply. "),
+        "trailing space after the message; got: {stderr}"
+    );
+}
+
+#[test]
+fn graph_flag_on_a_positional_uri_errors() {
+    // RFC-011: `--graph` selects within a multi-graph scope (a server or
+    // cluster). A bare positional URI is already a single graph, so pairing it
+    // with `--graph` is a loud error, not a silently-dropped flag. (The guard
+    // lets `--graph` reach a data verb; the scope resolver is what rejects it.)
+    let temp = tempdir().unwrap();
+    let graph = graph_path(temp.path());
+    init_graph(&graph);
+    let output = output_failure(
+        cli()
+            .arg("query")
+            .arg(&graph)
+            .arg("--graph")
+            .arg("knowledge")
+            .arg("-e")
+            .arg("query q { Person { id } }"),
+    );
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert!(
+        stderr.contains("already a single graph"),
+        "expected --graph-on-positional-URI rejection; got: {stderr}"
+    );
+}
+
 #[test]
 fn optimize_with_remote_target_errors_storage_plane() {
     // RFC-010 Slice 1: a maintenance verb pointed at a remote URI fails loudly

crates/omnigraph-cli/tests/cli_schema_config.rs

@@ -121,7 +121,7 @@ fn schema_plan_with_server_flag_errors_wrong_plane() {
     let stderr = String::from_utf8_lossy(&output.stderr);
     assert!(
         stderr.contains("`schema plan` is a direct (storage-native) command")
-            && stderr.contains("Pass a storage URI, or --cluster <dir> --cluster-graph <id>."),
+            && stderr.contains("Pass a storage URI."),
         "schema plan wrong-capability message not found; got: {stderr}"
     );
 }