docs: add CLI TUI compatibility contract

Author: yacosta738

src/commands/skill.rs

@@ -1917,6 +1917,13 @@ mod tests {
         ));
     }
 
+    #[test]
+    fn detect_suggest_install_output_mode_json_stays_json_without_tty() {
+        let mode =
+            detect_suggest_install_output_mode(true, false, Some("1"), Some("0"), Some("dumb"));
+        assert!(matches!(mode, SuggestInstallOutputMode::Json));
+    }
+
     // Tests for skill_id validation
     #[test]
     fn validate_skill_id_rejects_dotdot() {

src/output.rs

@@ -411,6 +411,30 @@ mod tests {
         );
     }
 
+    #[test]
+    fn detect_output_mode_non_tty_human_output_is_plain_even_without_term() {
+        assert_eq!(
+            detect_output_mode(false, false, None, None, None),
+            OutputMode::Human { use_color: false }
+        );
+    }
+
+    #[test]
+    fn detect_output_mode_no_color_value_disables_color_regardless_of_value() {
+        assert_eq!(
+            detect_output_mode(false, true, Some("false"), None, Some("xterm")),
+            OutputMode::Human { use_color: false }
+        );
+    }
+
+    #[test]
+    fn detect_output_mode_clicolor_zero_disables_color_even_with_no_color_empty() {
+        assert_eq!(
+            detect_output_mode(false, true, Some(""), Some("0"), Some("xterm")),
+            OutputMode::Human { use_color: false }
+        );
+    }
+
     #[test]
     fn detect_output_mode_term_dumb_case_insensitive() {
         assert_eq!(

tests/test_cli_tui_compatibility_contract.rs

@@ -0,0 +1,25 @@
+use std::fs;
+
+#[test]
+fn cli_tui_compatibility_contract_documents_required_topics() {
+    let contract = fs::read_to_string("website/docs/src/content/docs/cli-tui-compatibility.md")
+        .expect("CLI/TUI compatibility contract should be documented");
+
+    for required_topic in [
+        "--json",
+        "TTY",
+        "NO_COLOR",
+        "CLICOLOR=0",
+        "TERM=dumb",
+        "CI and piped output",
+        "exit codes",
+        "non-interactive fallbacks",
+        "full-screen TUI",
+        "opt-in",
+    ] {
+        assert!(
+            contract.contains(required_topic),
+            "compatibility contract should mention {required_topic}"
+        );
+    }
+}

website/docs/src/content/docs/cli-tui-compatibility.md

@@ -0,0 +1,62 @@
+# CLI and TUI compatibility contract
+
+AgentSync can improve its human interface without breaking existing CLI users when every output change follows this contract.
+
+## Stable machine output
+
+Commands that support `--json` must treat `--json` as the highest-priority output mode. When `--json` is set:
+
+- stdout must contain machine-readable JSON only.
+- Human headings, colors, spinners, progress frames, and hints must not be mixed into stdout.
+- Existing JSON field names and meanings should remain stable unless a schema migration is explicitly documented.
+- Error exits should preserve the command's existing exit-code behavior and return structured JSON whenever the command already supports JSON errors.
+
+## Human output mode
+
+Human output is optimized for people and may use headings, labels, Unicode status symbols, hints, and summaries. Human output must remain readable when copied from logs or piped into another command.
+
+Use the shared formatter and output-mode detection rules instead of ad hoc color or TTY checks.
+
+## TTY and color rules
+
+Color is enabled only when stdout is a TTY and no supported color-disabling override is active.
+
+The current color-disabling overrides are:
+
+- `NO_COLOR` with any non-empty value.
+- `CLICOLOR=0`.
+- `TERM=dumb`, matched case-insensitively.
+
+When stdout is not a TTY, AgentSync should continue in plain human output unless the user requested `--json`.
+
+## CI and piped output
+
+CI and piped output should be line-oriented and deterministic. Commands must not require cursor control, alternate-screen mode, or carriage-return animation when stdout is not an interactive TTY.
+
+Progress-heavy flows may keep a live renderer for safe TTY contexts, but they must provide a plain line renderer for non-TTY contexts.
+
+## Exit codes
+
+Output rendering must not change command success or failure semantics. A formatting-only change should preserve existing exit codes for success, validation failures, partial failures, and unsupported terminal states.
+
+## Non-interactive fallbacks
+
+AgentSync supports non-interactive fallbacks for interactive flows. Interactive flows must detect unsupported non-interactive contexts before prompting. In non-interactive contexts, a command should either:
+
+- use an explicit non-interactive path, such as an `--all` or dry-run mode;
+- fall back to the existing safe renderer; or
+- exit with a clear diagnostic and remediation.
+
+A command must not hang waiting for input that cannot arrive.
+
+## Full-screen TUI compatibility
+
+A full-screen TUI is allowed only when it is explicitly opt-in or when AgentSync can prove the terminal context is safe and interactive. Until a future release changes this contract deliberately, full-screen TUI behavior must not replace the existing default wizard behavior.
+
+Any full-screen TUI must:
+
+- initialize only after confirming the required TTY capabilities;
+- clean up terminal state on success, error, and cancellation;
+- provide cancellation semantics that preserve existing generated files unless the user confirms changes;
+- fall back to the existing wizard or exit with a clear message when initialization fails; and
+- keep `--json` and non-interactive command paths free from full-screen rendering.