teamctl_ui/
onboarding.rs

1//! Onboarding tutorial — multi-step walkthrough of the TUI.
2//!
3//! Triggered automatically on first launch (sentinel file at
4//! `.team/state/ui-tutorial-completed` — separate from PR-UI-1's
5//! `~/.config/teamctl/ui-tutorial-completed`, which marks
6//! per-machine completion; the per-team sentinel lets a brand-new
7//! checkout teach a returning operator about its specific shape
8//! without re-prompting machine-wide).
9//!
10//! Reopenable from any non-modal state via the `t` chord — the
11//! statusline's always-visible `· t tutorial` hint is the
12//! discovery surface. Skippable via `Esc` or first key per SPEC.
13
14use std::path::PathBuf;
15
16#[derive(Debug, Clone, Copy)]
17pub struct Step {
18    pub heading: &'static str,
19    pub body: &'static str,
20}
21
22pub const STEPS: &[Step] = &[
23    Step {
24        heading: "Welcome to teamctl-ui",
25        body: "A live view of your team. Agents sidebar on the left, with Detail above Mailbox on the right. Press any key to advance, Esc to leave.",
26    },
27    Step {
28        heading: "Agents + state glyphs",
29        body: "Each agent shows a single-cell glyph: ● working · ○ idle · ! approval pending · ✕ stopped · ? unknown. Tab to focus the Agents column, j/k to walk it.",
30    },
31    Step {
32        heading: "Detail pane",
33        body: "The selected agent's tmux session streams here. The title line shows which agent you're following; lines tail-clip to fit.",
34    },
35    Step {
36        heading: "Mailbox tabs",
37        body: "Inbox / Sent / Channel / Wire — `→` walks forward, `←` walks back, when the mailbox pane is focused. Tab itself always cycles pane focus, never tabs. Inbox is DMs to the focused agent; Sent is everything that agent has emitted (DMs, telegram replies, channel posts, wire broadcasts); Wire is project-wide broadcasts.",
38    },
39    Step {
40        heading: "Mailbox row UX",
41        body: "Inside the mailbox: j/k walks rows, PageDown/PageUp jumps a screen, Home/End jumps to ends. `f` filters by sender substring, `/` searches by body substring — both compose, both per-tab, Esc reverts, Enter keeps. ⏎ on a selected row opens a detail modal with the full body + metadata; Esc or q closes. Every row carries a short relative-time stamp (`2m`/`1h`/`3d`) on the right.",
42    },
43    Step {
44        heading: "Approvals",
45        body: "When an agent files request_approval, a stripe appears at the top. Press `a` to open the modal, then `y` to approve or Shift-`N` to deny. j/k cycle if multiple are pending.",
46    },
47    Step {
48        heading: "Compose",
49        body: "@ DMs the focused agent; ! broadcasts to a channel (picker first). The editor is vim-style — i to insert, Esc to normal, Ctrl+Enter to send, Esc Esc to cancel.",
50    },
51    Step {
52        heading: "Layouts",
53        body: "Ctrl+W toggles Wall view (4 agents at once + scroll). Ctrl+M toggles Mailbox-first (channel-feed centric). Both fall back to Triptych on toggle.",
54    },
55    Step {
56        heading: "Splits",
57        body: "Ctrl+| / Ctrl+- split the detail pane so you can watch two agents at once. Ctrl+H/J/K/L cycles between splits, Ctrl+W q closes the focused one.",
58    },
59    Step {
60        heading: "Help + quit",
61        body: "? opens the full keymap. q quits (with confirm). t reopens this tour. You're ready.",
62    },
63];
64
65/// Per-team sentinel file path. Returns `None` when no team root
66/// is reachable — onboarding is then a noop and the tutorial
67/// auto-trigger doesn't fire.
68pub fn sentinel_path(team_root: &std::path::Path) -> PathBuf {
69    team_root.join("state/ui-tutorial-completed")
70}
71
72pub fn has_completed(team_root: &std::path::Path) -> bool {
73    sentinel_path(team_root).exists()
74}
75
76/// Mark this team's tutorial as completed by creating the
77/// sentinel file. The design intent is **presence-based**: only
78/// the file's existence matters, never its contents — a partial
79/// write that leaves an empty / truncated file still satisfies
80/// `has_completed`. That's accidentally robust to crash-during-
81/// write (the auto-trigger correctly fires once, then any later
82/// completion makes it stop firing forever) but the property is
83/// load-bearing, not coincidental: `has_completed` deliberately
84/// does NOT validate file content. Future readers tempted to
85/// add atomic-rename or content-validation should know that the
86/// existing crash-safety story already lives entirely in the
87/// presence check; tightening write semantics doesn't strengthen
88/// the contract, it just adds surface area.
89pub fn mark_completed(team_root: &std::path::Path) -> std::io::Result<()> {
90    let path = sentinel_path(team_root);
91    if let Some(parent) = path.parent() {
92        std::fs::create_dir_all(parent)?;
93    }
94    std::fs::write(&path, b"")
95}
96
97#[cfg(test)]
98mod tests {
99    use super::*;
100    use std::fs;
101
102    #[test]
103    fn step_count_under_ten() {
104        // SPEC budget: <90s skim. 10 short steps is the cap (T-131
105        // PR-4 added a Mailbox-row-UX step to cover scroll / filter /
106        // search / detail modal / time indicator); we're at the
107        // ceiling now — adding more steps means revisiting the
108        // skim-budget.
109        assert!(
110            STEPS.len() <= 10,
111            "tutorial bloated to {} steps",
112            STEPS.len()
113        );
114    }
115
116    #[test]
117    fn sentinel_round_trip_in_tempdir() {
118        let tmp = tempfile::tempdir().unwrap();
119        let root = tmp.path();
120        assert!(!has_completed(root));
121        mark_completed(root).unwrap();
122        assert!(has_completed(root));
123        // Marker file is empty — content doesn't matter, only
124        // existence does.
125        let marker = sentinel_path(root);
126        let bytes = fs::read(&marker).unwrap();
127        assert!(bytes.is_empty());
128    }
129}
teamctl_ui/onboarding.rs

teamctl_ui/
onboarding.rs
