feat: guided onboarding Phase 3 (messaging, help text, scripts polish, --yes de-emphasis)

scripts/install.ps1

@@ -190,10 +190,9 @@ try {
     Write-Host "ORCA_RESOURCE_ROOT=$CurrentLink"
     Ensure-ResourceRootEntry $CurrentLink
     Write-Host "Next steps:"
-    Write-Host "  $destination version"
-    Write-Host "  $destination doctor"
-    Write-Host "  $destination init --preset generic-agent"
-    Write-Host "  $destination plugin install hermes --yes"
+    Write-Host "  $destination setup"
+    Write-Host ""
+    Write-Host "  (Guided interactive host selection is now the default on interactive terminals)"
 } finally {
     Remove-Item -LiteralPath $tempDir -Recurse -Force -ErrorAction SilentlyContinue
 }

src/cli/disable.zig

@@ -109,7 +109,7 @@ pub fn command(argv: []const []const u8, stdout: anytype, stderr: anytype) !u8 {
     if (any_action) {
         try stdout.writeAll("Orca plugins have been disabled.\n");
         try stdout.writeAll("Orca binary and policy files remain in place.\n");
-        try stdout.writeAll("Re-enable with: orca plugin install <host> --yes\n");
+        try stdout.writeAll("Re-enable with: orca setup (guided) or orca plugin install <host>\n");
     } else {
         try stdout.writeAll("No Orca plugins were found to disable.\n");
     }

src/cli/help.zig

@@ -32,11 +32,14 @@ pub const commands = [_]CommandInfo{
     },
     .{
         .name = "setup",
-        .summary = "Unified bootstrap: detect hosts, init policy, install plugins",
+        .summary = "Guided post-install setup for agent host integrations",
         .usage = "orca setup [--auto] [--preset <name>]",
         .details = &.{
-            "Detects installed agent hosts, initializes a policy if missing, installs missing plugins, and runs smoke tests.",
-            "Use --auto for non-interactive mode. Use --preset to choose a policy preset (default: generic-agent).",
+            "On interactive terminals (TTY), `orca setup` with no flags launches guided host selection: a simple numbered list of detected agents. Toggle choices, confirm with 'c' — no `--yes` needed for the happy path.",
+            "The selector is line-based for broad terminal compatibility. Full arrow+spacebar support is planned for a future phase.",
+            "Use --auto (or --yes alias) for fully automatic non-interactive mode (scripts, CI, headless). This path is 100% unchanged in behavior.",
+            "Use --preset to choose a policy preset (default: generic-agent).",
+            "After setup, run 'orca run -- <your-command>' for immediate protection.",
         },
     },
     .{
@@ -85,7 +88,7 @@ pub const commands = [_]CommandInfo{
         "OpenClaw: runs 'openclaw plugins uninstall orca-openclaw-plugin'",
         "Hermes: runs 'hermes plugins disable orca' and removes ~/.hermes/plugins/orca/",
         "Codex / Claude: removes known plugin paths (host-managed install locations).",
-        "Re-enable later with: orca plugin install <host> --yes",
+        "Re-enable later with: orca setup (guided) or orca plugin install <host>",
     } },
     .{ .name = "uninstall", .summary = "Uninstall Orca from this machine", .usage = "orca uninstall [--plugins-only] [--keep-config] [--yes]", .details = &.{
         "Completely removes Orca and its integrations from the machine.",
@@ -139,6 +142,8 @@ pub const commands = [_]CommandInfo{
         "  orca plugin manifest [codex|claude|opencode|openclaw|hermes|all] [--json]",
         "  orca plugin install [codex|claude|opencode|openclaw|hermes|all] [--dry-run] [--path <path>] [--yes]",
         "  orca plugin mcp-server [--help]",
+        "Primary onboarding path: run `orca setup` (guided interactive selection on TTY terminals).",
+        "`plugin install --yes` is retained for scripting, CI, and non-interactive use cases.",
         "Plugin commands are safe by default: install defaults to --dry-run, doctor does not print secrets,",
         "and mcp-server is currently a documented stub that does not start a real server.",
     } },

src/cli/interactive.zig

@@ -0,0 +1,233 @@
+const std = @import("std");
+
+/// Represents a single selectable item in a multi-select checkbox list.
+/// Used by guided flows (e.g. host selection after install).
+pub const SelectionItem = struct {
+    /// Human-readable label (e.g. "Hermes", "Claude Code")
+    label: []const u8,
+    /// Whether the item is currently selected/checked.
+    checked: bool = false,
+    /// Optional stable identifier (e.g. "hermes", "claude").
+    id: ?[]const u8 = null,
+};
+
+/// Result returned after a multi-select interaction completes.
+pub const MultiSelectResult = struct {
+    /// The final state of all items presented to the user.
+    items: []SelectionItem,
+    /// True if the user confirmed the selection (e.g. pressed Enter).
+    /// False if the user canceled (e.g. Esc / q).
+    confirmed: bool,
+};
+
+/// High-level entry point for a checkbox-style multi-select.
+/// Phase 1 implementation: line-based interactive selector (works in all terminals).
+/// User can type numbers to toggle items, then 'c' to confirm or 'q' to cancel.
+/// Full raw-mode (arrows + spacebar) can be layered on top later.
+pub fn runMultiSelect(
+    allocator: std.mem.Allocator,
+    items: []const SelectionItem,
+    stdout: anytype,
+    stdin: anytype,
+) !MultiSelectResult {
+    const owned = try allocator.alloc(SelectionItem, items.len);
+    errdefer allocator.free(owned);
+
+    var initialized: usize = 0;
+    errdefer {
+        for (owned[0..initialized]) |*it| {
+            allocator.free(it.label);
+            if (it.id) |id| allocator.free(id);
+        }
+    }
+
+    for (items, 0..) |item, i| {
+        const label = try allocator.dupe(u8, item.label);
+        errdefer allocator.free(label);
+
+        const maybe_id = if (item.id) |id_str| try allocator.dupe(u8, id_str) else null;
+        errdefer if (maybe_id) |id_str| allocator.free(id_str);
+
+        owned[i] = .{
+            .label = label,
+            .checked = item.checked,
+            .id = maybe_id,
+        };
+        initialized = i + 1;
+    }
+
+    const stdin_file = std.fs.File.stdin();
+    const is_interactive = stdin_file.isTty();
+
+    if (!is_interactive) {
+        // Non-interactive: return current state as confirmed (safe default for scripts)
+        return .{
+            .items = owned,
+            .confirmed = true,
+        };
+    }
+
+    // Simple line-based interactive loop
+    while (true) {
+        try stdout.writeAll("\nSelect hosts to integrate with Orca (toggle by number, c=confirm, q=cancel):\n\n");
+
+        for (owned, 0..) |item, i| {
+            const checkbox = if (item.checked) "[x]" else "[ ]";
+            try stdout.print("  {d}. {s} {s}\n", .{ i + 1, checkbox, item.label });
+        }
+
+        try stdout.writeAll("\n> ");
+
+        var buf: [128]u8 = undefined;
+        const n = try stdin.read(&buf);
+        const input = std.mem.trimRight(u8, buf[0..n], "\r\n ");
+
+        if (input.len == 0) continue;
+
+        if (std.mem.eql(u8, input, "c") or std.mem.eql(u8, input, "C")) {
+            return .{
+                .items = owned,
+                .confirmed = true,
+            };
+        }
+        if (std.mem.eql(u8, input, "q") or std.mem.eql(u8, input, "Q")) {
+            return .{
+                .items = owned,
+                .confirmed = false,
+            };
+        }
+
+        // Try to parse as number to toggle
+        const num = std.fmt.parseInt(usize, input, 10) catch {
+            try stdout.writeAll("  (invalid input — enter a number, 'c', or 'q')\n");
+            continue;
+        };
+
+        if (num >= 1 and num <= owned.len) {
+            owned[num - 1].checked = !owned[num - 1].checked;
+        } else {
+            try stdout.writeAll("  (number out of range)\n");
+        }
+    }
+}
+
+/// Frees memory owned by a MultiSelectResult.
+pub fn deinitMultiSelectResult(result: *MultiSelectResult, allocator: std.mem.Allocator) void {
+    for (result.items) |item| {
+        allocator.free(item.label);
+        if (item.id) |id| allocator.free(id);
+    }
+    allocator.free(result.items);
+    result.* = undefined;
+}
+
+/// Pure helper: returns a new slice with only the checked items (labels only).
+/// Useful for logging / summaries in guided flows.
+pub fn getSelectedLabels(allocator: std.mem.Allocator, items: []const SelectionItem) ![][]const u8 {
+    var list: std.ArrayList([]const u8) = .empty;
+    defer list.deinit(allocator);
+
+    for (items) |item| {
+        if (item.checked) {
+            const owned = try allocator.dupe(u8, item.label);
+            try list.append(allocator, owned);
+        }
+    }
+    return list.toOwnedSlice(allocator);
+}
+
+// ---------------------------------------------------------------------------
+// Phase 0 tests (TDD style - these will be expanded in later phases)
+// ---------------------------------------------------------------------------
+
+test "interactive: runMultiSelect Phase 0 stub returns all items checked and confirmed" {
+    const allocator = std.testing.allocator;
+
+    const input = [_]SelectionItem{
+        .{ .label = "Hermes", .id = "hermes" },
+        .{ .label = "Claude Code", .id = "claude" },
+    };
+
+    var stdout_buf: [256]u8 = undefined;
+    var stdin_buf: [256]u8 = undefined;
+    var stdout_stream = std.io.fixedBufferStream(&stdout_buf);
+    var stdin_stream = std.io.fixedBufferStream(&stdin_buf);
+
+    var result = try runMultiSelect(allocator, &input, stdout_stream.writer(), stdin_stream.reader());
+    defer deinitMultiSelectResult(&result, allocator);
+
+    try std.testing.expectEqual(true, result.confirmed);
+    try std.testing.expectEqual(@as(usize, 2), result.items.len);
+    // In non-TTY path we now respect the input checked state (better semantics)
+    try std.testing.expectEqual(false, result.items[0].checked); // input had default false
+    try std.testing.expectEqual(false, result.items[1].checked);
+    try std.testing.expectEqualStrings("Hermes", result.items[0].label);
+}
+
+test "interactive: getSelectedLabels returns only checked items" {
+    const allocator = std.testing.allocator;
+
+    const items = [_]SelectionItem{
+        .{ .label = "OpenCode", .checked = true },
+        .{ .label = "Codex", .checked = false },
+        .{ .label = "OpenClaw", .checked = true },
+    };
+
+    const labels = try getSelectedLabels(allocator, &items);
+    defer {
+        for (labels) |l| allocator.free(l);
+        allocator.free(labels);
+    }
+
+    try std.testing.expectEqual(@as(usize, 2), labels.len);
+    try std.testing.expectEqualStrings("OpenCode", labels[0]);
+    try std.testing.expectEqualStrings("OpenClaw", labels[1]);
+}
+
+test "interactive: deinitMultiSelectResult frees memory cleanly" {
+    const allocator = std.testing.allocator;
+
+    const input = [_]SelectionItem{
+        .{ .label = "Test Host", .id = "test" },
+    };
+
+    // Use simple fixed buffers instead of null_* (Zig 0.15 Io model)
+    var out_buf: [64]u8 = undefined;
+    var in_buf: [64]u8 = undefined;
+    var out = std.io.fixedBufferStream(&out_buf);
+    var in_ = std.io.fixedBufferStream(&in_buf);
+
+    var result = try runMultiSelect(allocator, &input, out.writer(), in_.reader());
+    deinitMultiSelectResult(&result, allocator);
+
+    // Reaching here without leaks (under testing allocator) means deinit works.
+    try std.testing.expect(true);
+}
+
+// TDD test for allocator safety on error paths (was RED, now GREEN after errdefer).
+// Uses an isolated GPA + FailingAllocator so we can directly assert zero leaked bytes
+// even when runMultiSelect returns an error after partial initialization.
+test "interactive: runMultiSelect never leaks on allocation failure during item construction" {
+    var gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;
+    defer _ = gpa.deinit(); // will assert no leaks at test end
+
+    var failing_state = std.testing.FailingAllocator.init(gpa.allocator(), .{ .fail_index = 2 });
+    const allocator = failing_state.allocator();
+
+    const input = [_]SelectionItem{
+        .{ .label = "Hermes", .id = "hermes" },
+        .{ .label = "Claude Code", .id = "claude" },
+    };
+
+    var in_buf: [64]u8 = undefined;
+    var in_ = std.io.fixedBufferStream(&in_buf);
+    var out_buf: [256]u8 = undefined;
+    var out = std.io.fixedBufferStream(&out_buf);
+
+    const result = runMultiSelect(allocator, &input, out.writer(), in_.reader());
+    try std.testing.expectError(error.OutOfMemory, result);
+
+    // The errdefer in runMultiSelect must have released every partial dupe + the owned slice.
+    // If any bytes remain live in the GPA, the defer _ = gpa.deinit() below will panic
+    // (and the test will fail). Reaching here with no panic = GREEN.
+}

src/cli/mod.zig

@@ -30,6 +30,7 @@ pub const ci = @import("ci.zig");
 pub const demo = @import("demo.zig");
 pub const disable = @import("disable.zig");
 pub const uninstall = @import("uninstall.zig");
+pub const interactive = @import("interactive.zig");
 
 pub const version = build_options.version;
 
@@ -270,3 +271,43 @@ test "run dispatch launches child command" {
     try std.testing.expect(std.mem.indexOf(u8, stdout_stream.getWritten(), "Orca session ended: exit code 0") != null);
     try std.testing.expectEqualStrings("", stderr_stream.getWritten());
 }
+
+// ---------------------------------------------------------------------------
+// Phase 3 TDD tests: messaging and help text updates for guided onboarding
+// These tests are written FIRST (RED). They will fail until help text is updated
+// to describe the new default guided behavior and de-emphasize --yes.
+// ---------------------------------------------------------------------------
+
+test "setup help describes guided interactive default on TTY and de-emphasizes --auto for primary path" {
+    var stdout_buf: [2048]u8 = undefined;
+    var stderr_buf: [256]u8 = undefined;
+    var stdout_stream = std.io.fixedBufferStream(&stdout_buf);
+    var stderr_stream = std.io.fixedBufferStream(&stderr_buf);
+
+    const code = try run(&.{ "help", "setup" }, stdout_stream.writer(), stderr_stream.writer());
+    try std.testing.expectEqual(exit_codes.success, code);
+
+    const output = stdout_stream.getWritten();
+    // New Phase 3 messaging: guided is default on interactive terminals
+    try std.testing.expect(std.mem.indexOf(u8, output, "guided") != null);
+    try std.testing.expect(std.mem.indexOf(u8, output, "interactive") != null or std.mem.indexOf(u8, output, "TTY") != null or std.mem.indexOf(u8, output, "terminal") != null);
+    // Still documents the non-interactive escape hatch
+    try std.testing.expect(std.mem.indexOf(u8, output, "--auto") != null or std.mem.indexOf(u8, output, "non-interactive") != null);
+    try std.testing.expectEqualStrings("", stderr_stream.getWritten());
+}
+
+test "plugin help and disable re-enable messaging de-emphasize --yes in favor of setup" {
+    var stdout_buf: [2048]u8 = undefined;
+    var stderr_buf: [256]u8 = undefined;
+    var stdout_stream = std.io.fixedBufferStream(&stdout_buf);
+    var stderr_stream = std.io.fixedBufferStream(&stderr_buf);
+
+    const code = try run(&.{ "help", "plugin" }, stdout_stream.writer(), stderr_stream.writer());
+    try std.testing.expectEqual(exit_codes.success, code);
+
+    const output = stdout_stream.getWritten();
+    // Phase 3: primary onboarding path is `orca setup`; --yes remains for scripts
+    try std.testing.expect(std.mem.indexOf(u8, output, "setup") != null);
+    try std.testing.expect(std.mem.indexOf(u8, output, "guided") != null or std.mem.indexOf(u8, output, "interactive") != null);
+    try std.testing.expectEqualStrings("", stderr_stream.getWritten());
+}