cli: Add shared styling service with slim help surface and trimmed validate output

Add comprehensive styling infrastructure with stderr, help-text, and prompt
support through the shared style service

Co-authored-by: SCE <sce@crocoder.dev>

Author: davidabram

.opencode/package.json

@@ -1,5 +1,5 @@
 {
   "dependencies": {
-    "@opencode-ai/plugin": "1.3.9"
+    "@opencode-ai/plugin": "1.3.10"
   }
 }

cli/src/app.rs

@@ -127,13 +127,11 @@ where
     };
 
     let styled_code = services::style::error_code(error.code());
+    let styled_heading = services::style::heading_stderr("Error");
+    let styled_message =
+        services::style::error_text(&services::security::redact_sensitive_text(&rendered));
 
-    let _ = writeln!(
-        writer,
-        "Error [{}]: {}",
-        styled_code,
-        services::security::redact_sensitive_text(&rendered)
-    );
+    let _ = writeln!(writer, "{styled_heading} [{styled_code}]: {styled_message}");
 }
 
 #[allow(clippy::too_many_lines)]
@@ -310,11 +308,8 @@ where
                 return Ok(Command::Help);
             }
             if error.kind() == clap::error::ErrorKind::DisplayHelpOnMissingArgumentOrSubcommand {
-                if args_vec.get(1).map(String::as_str) == Some(services::auth_command::NAME) {
-                    return Ok(Command::HelpText {
-                        name: services::auth_command::NAME.to_string(),
-                        text: cli_schema::auth_help_text(),
-                    });
+                if let Some(help_text) = render_missing_subcommand_help(&args_vec) {
+                    return Ok(help_text);
                 }
 
                 return Err(ClassifiedError::parse(
@@ -377,6 +372,22 @@ fn render_subcommand_help_from_args(args: &[String]) -> Option<(String, String)>
     cli_schema::render_help_for_path(&command_path).map(|text| (command_name, text))
 }
 
+fn render_missing_subcommand_help(args: &[String]) -> Option<Command> {
+    let command_name = args.get(1)?.as_str();
+
+    match command_name {
+        services::auth_command::NAME => Some(Command::HelpText {
+            name: services::auth_command::NAME.to_string(),
+            text: cli_schema::auth_help_text(),
+        }),
+        services::config::NAME => Some(Command::HelpText {
+            name: services::config::NAME.to_string(),
+            text: cli_schema::render_help_for_path(&[services::config::NAME])?,
+        }),
+        _ => None,
+    }
+}
+
 fn clean_clap_error_message(message: &str, kind: clap::error::ErrorKind) -> String {
     use clap::error::ErrorKind;
 
@@ -730,12 +741,13 @@ fn dispatch(
 mod tests {
     use std::process::ExitCode;
 
+    use crate::services::error::ClassifiedError;
     use crate::services::setup::{SetupMode, SetupRequest, SetupTarget};
 
     use super::{
         parse_command, run, run_with_dependency_check, run_with_dependency_check_and_streams,
-        Command, EXIT_CODE_DEPENDENCY_FAILURE, EXIT_CODE_PARSE_FAILURE, EXIT_CODE_RUNTIME_FAILURE,
-        EXIT_CODE_VALIDATION_FAILURE,
+        write_error_diagnostic, Command, EXIT_CODE_DEPENDENCY_FAILURE, EXIT_CODE_PARSE_FAILURE,
+        EXIT_CODE_RUNTIME_FAILURE, EXIT_CODE_VALIDATION_FAILURE,
     };
 
     #[test]
@@ -836,6 +848,21 @@ mod tests {
         assert!(stderr.contains("Try:"));
     }
 
+    #[test]
+    fn write_error_diagnostic_preserves_plain_text_contract_without_color() {
+        let mut stderr = Vec::new();
+
+        write_error_diagnostic(
+            &mut stderr,
+            &ClassifiedError::parse("Unknown command 'nope'. Try: run 'sce --help'."),
+        );
+
+        assert_eq!(
+            String::from_utf8(stderr).expect("stderr should be utf-8"),
+            "Error [SCE-ERR-PARSE]: Unknown command 'nope'. Try: run 'sce --help'.\n"
+        );
+    }
+
     #[test]
     fn empty_payload_does_not_write_stdout() {
         let mut stdout = Vec::new();
@@ -1543,6 +1570,38 @@ mod tests {
         );
     }
 
+    #[test]
+    fn parser_routes_bare_config_to_help_text() {
+        let command = parse_command(vec!["sce".to_string(), "config".to_string()], None)
+            .expect("bare config should route to help");
+
+        assert_eq!(
+            command,
+            Command::HelpText {
+                name: crate::services::config::NAME.to_string(),
+                text: crate::cli_schema::render_help_for_path(&[crate::services::config::NAME])
+                    .expect("config help should render"),
+            }
+        );
+    }
+
+    #[test]
+    fn parser_routes_bare_config_to_same_help_as_config_help_flag() {
+        let bare_config = parse_command(vec!["sce".to_string(), "config".to_string()], None)
+            .expect("bare config should route to help");
+        let config_help = parse_command(
+            vec![
+                "sce".to_string(),
+                "config".to_string(),
+                "--help".to_string(),
+            ],
+            None,
+        )
+        .expect("config --help should route to help");
+
+        assert_eq!(bare_config, config_help);
+    }
+
     #[test]
     fn parser_routes_completion_bash_shell() {
         let command = parse_command(

cli/src/cli_schema.rs

@@ -1,6 +1,8 @@
 use clap::{CommandFactory, Parser, Subcommand, ValueEnum};
 use std::path::PathBuf;
 
+use crate::services::style;
+
 #[derive(Parser, Debug)]
 #[command(name = "sce", version, about, long_about = None)]
 pub struct Cli {
@@ -39,7 +41,9 @@ pub fn render_help_for_path(path: &[&str]) -> Option<String> {
         .write_long_help(&mut buffer)
         .expect("help rendering should write to memory");
 
-    Some(String::from_utf8(buffer).expect("help output should be valid UTF-8"))
+    let help = String::from_utf8(buffer).expect("help output should be valid UTF-8");
+
+    Some(style::clap_help(&help))
 }
 
 pub fn auth_help_text() -> String {
@@ -183,7 +187,7 @@ pub enum ConfigSubcommand {
         timeout_ms: Option<u64>,
     },
 
-    #[command(about = "Validate config files and report resolved observability values")]
+    #[command(about = "Validate config files and report pass/fail with errors or warnings")]
     Validate {
         #[arg(long, value_enum, default_value_t = OutputFormat::Text)]
         format: OutputFormat,
@@ -504,11 +508,11 @@ mod tests {
     }
 
     #[test]
-    fn render_help_for_config_validate_mentions_observability() {
+    fn render_help_for_config_validate_mentions_pass_fail_output() {
         let help = render_help_for_path(&["config", "validate"])
             .expect("config validate help should render");
 
-        assert!(help.contains("Validate config files and report resolved observability values"));
+        assert!(help.contains("Validate config files and report pass/fail with errors or warnings"));
         assert!(help.contains("--config <CONFIG>"));
         assert!(help.contains("--format <FORMAT>"));
     }

cli/src/command_surface.rs

@@ -1,7 +1,7 @@
 use std::fmt::Write;
 
 use crate::services;
-use services::style::{command_name, heading, status_implemented, status_placeholder};
+use services::style::{command_name, example_command, heading};
 
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 pub enum ImplementationStatus {
@@ -14,58 +14,69 @@ pub struct CommandContract {
     pub name: &'static str,
     pub status: ImplementationStatus,
     pub purpose: &'static str,
+    pub show_in_top_level_help: bool,
 }
 
 pub const COMMANDS: &[CommandContract] = &[
     CommandContract {
         name: "help",
         status: ImplementationStatus::Implemented,
-        purpose: "Print the current placeholder command surface",
+        purpose: "Show help for the current CLI surface",
+        show_in_top_level_help: true,
     },
     CommandContract {
         name: services::config::NAME,
         status: ImplementationStatus::Implemented,
         purpose: "Inspect and validate resolved CLI configuration",
+        show_in_top_level_help: true,
     },
     CommandContract {
         name: services::setup::NAME,
         status: ImplementationStatus::Implemented,
         purpose: "Prepare local repository/workspace prerequisites",
+        show_in_top_level_help: true,
     },
     CommandContract {
         name: services::doctor::NAME,
         status: ImplementationStatus::Implemented,
         purpose: "Inspect SCE operator health and explicit repair readiness",
+        show_in_top_level_help: true,
     },
     CommandContract {
         name: services::auth_command::NAME,
         status: ImplementationStatus::Implemented,
         purpose: "Authenticate with WorkOS and inspect local auth state",
+        show_in_top_level_help: false,
     },
     CommandContract {
         name: services::hooks::NAME,
         status: ImplementationStatus::Implemented,
         purpose: "Run git-hook runtime entrypoints for local Agent Trace flows",
+        show_in_top_level_help: false,
     },
     CommandContract {
         name: services::trace::NAME,
         status: ImplementationStatus::Implemented,
         purpose: "Inspect persisted Agent Trace records and captured prompts",
+        show_in_top_level_help: false,
     },
     CommandContract {
         name: services::sync::NAME,
         status: ImplementationStatus::Placeholder,
         purpose: "Coordinate future cloud sync workflows",
+        show_in_top_level_help: false,
     },
     CommandContract {
         name: services::version::NAME,
         status: ImplementationStatus::Implemented,
         purpose: "Print deterministic runtime version metadata",
+        show_in_top_level_help: true,
     },
     CommandContract {
         name: services::completion::NAME,
         status: ImplementationStatus::Implemented,
         purpose: "Generate deterministic shell completion scripts",
+        show_in_top_level_help: true,
     },
 ];
 
@@ -76,20 +87,14 @@ pub fn is_known_command(name: &str) -> bool {
 pub fn help_text() -> String {
     let mut command_rows = String::new();
     for command in COMMANDS {
-        let status_text = match command.status {
-            ImplementationStatus::Implemented => "implemented",
-            ImplementationStatus::Placeholder => "placeholder",
-        };
-        let styled_status = match command.status {
-            ImplementationStatus::Implemented => status_implemented(status_text),
-            ImplementationStatus::Placeholder => status_placeholder(status_text),
-        };
+        if !command.show_in_top_level_help {
+            continue;
+        }
 
         writeln!(
             command_rows,
-            "  {:<10} {:<12} {}",
+            "  {:<10} {}",
             command_name(command.name),
-            styled_status,
             command.purpose
         )
         .unwrap();
@@ -101,31 +106,29 @@ pub fn help_text() -> String {
 {}:\n  {} <show|validate> [--format <text|json>] [options]\n\n\
 {}:\n  {} [--opencode|--claude|--both] [--non-interactive] [--hooks] [--repo <path>]\n\n\
 {}:\n  {} [--fix] [--all-databases] [--format <text|json>]\n\n\
-{}:\n  {} <login|logout|status> [--format <text|json>]\n\n\
 {}:\n  {} --shell <bash|zsh|fish>\n\n\
-{}:\n  {} prompts <commit-sha> [--format <text|json>|--json]\n\n\
 {}:\n  Supported commands accept --format <text|json>\n\n\
-{}:\n  sce setup\n  sce setup --opencode --non-interactive --hooks\n  sce setup --hooks --repo ../demo-repo\n  sce auth status\n  sce auth login --format json\n  sce trace prompts abc1234\n  sce trace prompts abc1234 --json\n  sce doctor --format json\n  sce doctor --all-databases --format json\n  sce doctor --fix\n  sce version --format json\n\n\
-{}:\n{command_rows}\n\
-Setup defaults to interactive target selection when no setup target flag is passed, and installs hooks in the same run.\n\
-Use '--hooks' to install required git hooks for the current repository or '--repo <path>' for a specific repository.\n\
-`setup`, `doctor`, `auth`, `hooks`, `trace`, `version`, and `completion` are implemented; `sync` remains placeholder-oriented.\n",
-        heading("sce - Shared Context Engineering CLI (placeholder foundation)"),
+{}:\n  {}\n  {}\n  {}\n  {}\n  {}\n  {}\n  {}\n\n\
+{}:\n{command_rows}",
+        heading("sce - Shared Context Engineering CLI"),
         heading("Usage"),
         heading("Config usage"),
         command_name("sce config"),
         heading("Setup usage"),
         command_name("sce setup"),
         heading("Doctor usage"),
         command_name("sce doctor"),
-        heading("Auth usage"),
-        command_name("sce auth"),
         heading("Completion usage"),
         command_name("sce completion"),
-        heading("Trace usage"),
-        command_name("sce trace"),
         heading("Output format contract"),
         heading("Examples"),
+        example_command("sce setup"),
+        example_command("sce setup --opencode --non-interactive --hooks"),
+        example_command("sce setup --hooks --repo ../demo-repo"),
+        example_command("sce doctor --format json"),
+        example_command("sce doctor --all-databases --format json"),
+        example_command("sce doctor --fix"),
+        example_command("sce version --format json"),
         heading("Commands"),
     )
 }
@@ -151,7 +154,6 @@ mod tests {
         assert!(help.contains(
             "sce setup [--opencode|--claude|--both] [--non-interactive] [--hooks] [--repo <path>]"
         ));
-        assert!(help.contains("installs hooks in the same run"));
         assert!(help.contains("sce setup --opencode --non-interactive --hooks"));
     }
 
@@ -173,11 +175,25 @@ mod tests {
     }
 
     #[test]
-    fn help_text_mentions_auth_usage_examples() {
+    fn hidden_commands_remain_known_even_when_not_shown_in_top_level_help() {
+        for hidden_command in [
+            crate::services::auth_command::NAME,
+            crate::services::hooks::NAME,
+            crate::services::trace::NAME,
+            crate::services::sync::NAME,
+        ] {
+            assert!(crate::command_surface::is_known_command(hidden_command));
+        }
+    }
+
+    #[test]
+    fn help_text_hides_selected_commands_from_top_level_help() {
         let help = help_text();
-        assert!(help.contains("sce auth <login|logout|status> [--format <text|json>]"));
-        assert!(help.contains("sce auth status"));
-        assert!(help.contains("sce auth login --format json"));
+
+        assert!(!help.contains("auth"));
+        assert!(!help.contains("hooks"));
+        assert!(!help.contains("trace"));
+        assert!(!help.contains("sync"));
     }
 
     #[test]
@@ -188,11 +204,14 @@ mod tests {
     }
 
     #[test]
-    fn help_text_mentions_trace_command() {
+    fn help_text_drops_placeholder_and_status_copy() {
         let help = help_text();
-        assert!(help.contains("trace"));
-        assert!(help.contains("sce trace prompts <commit-sha>"));
-        assert!(help.contains("sce trace prompts abc1234 --json"));
+
+        assert!(!help.contains("placeholder foundation"));
+        assert!(!help.contains("implemented"));
+        assert!(!help.contains("placeholder-oriented"));
+        assert!(!help.contains("Setup defaults to interactive target selection"));
+        assert!(!help.contains("Use '--hooks' to install required git hooks"));
     }
 
     #[test]