Show a first-launch primer on the app's vocabulary

One scrollable card — loop, node, edge, the four loop types, Quick Chat,
project — shown once on first launch and reopenable from the sidebar's help
button. A new user's first sight of the app is an empty canvas whose words
mean nothing yet; five short definitions is the cheapest fix there is.

Author: scgopi

graphcode/Sources/Features/App/AppFeature.swift

@@ -33,6 +33,10 @@ struct AppFeature {
     /// Whether the open workspace is a quick chat rather than a graph node's loop.
     func isQuickChat(_ nodeID: UUID) -> Bool { quickChats[id: nodeID] != nil }
 
+    /// Up on first launch (`.task` checks the persisted flag) and whenever the
+    /// sidebar's help button asks for it again.
+    var showingOnboarding = false
+
     /// The orchestrator's needs-attention rollup, across every open project
     /// (docs/05-orchestrator.md#monitoring-surface). Derived rather than stored: it's a
     /// pure function of the graphs the daemon already broadcasts, and a cached copy
@@ -110,6 +114,9 @@ struct AppFeature {
     case selectPreviousLoop
     /// The stop/kill affordance docs/05-orchestrator.md asks the monitor for.
     case stopNodeTapped(projectPath: String, nodeID: UUID)
+    /// The first-launch terminology primer — see `OnboardingView`.
+    case onboardingRequested
+    case onboardingDismissed
     /// The Quick Chats section's actions — see `State.quickChats`.
     case newQuickChatTapped
     case quickChatTapped(UUID)
@@ -136,6 +143,11 @@ struct AppFeature {
       switch action {
       case .task:
         state.quickChats = IdentifiedArray(uniqueElements: quickChatStore.load())
+        // Once, not every launch: the primer's value is on day one, and re-showing it
+        // to someone who has loops running would read as the app forgetting them.
+        if !UserDefaults.standard.bool(forKey: "hasSeenOnboarding") {
+          state.showingOnboarding = true
+        }
         return .merge(
           .run { send in
             for await event in orchestratorClient.connect() {
@@ -290,6 +302,15 @@ struct AppFeature {
             .graphCommand(projectPath: projectPath, command: .stopNode(nodeID)))
         }
 
+      case .onboardingRequested:
+        state.showingOnboarding = true
+        return .none
+
+      case .onboardingDismissed:
+        state.showingOnboarding = false
+        UserDefaults.standard.set(true, forKey: "hasSeenOnboarding")
+        return .none
+
       case .newQuickChatTapped:
         let chat = QuickChat(
           title: "Chat — \(Date().formatted(.dateTime.month(.abbreviated).day()))",

graphcode/Sources/Features/App/AppView.swift

@@ -21,6 +21,16 @@ struct AppView: View {
     }
     .frame(maxWidth: .infinity, maxHeight: .infinity)
     .background(Theme.windowBackground)
+    // First launch only (and the sidebar's help button after that): the app's
+    // vocabulary in one card, before the empty canvas has to explain itself.
+    .sheet(
+      isPresented: Binding(
+        get: { store.showingOnboarding },
+        set: { if !$0 { store.send(.onboardingDismissed) } }
+      )
+    ) {
+      OnboardingView { store.send(.onboardingDismissed) }
+    }
     // Paints the window itself, so the titlebar and toolbar match instead of sitting a
     // shade lighter above the content.
     .containerBackground(Theme.windowBackground, for: .window)

graphcode/Sources/Features/Welcome/OnboardingView.swift

@@ -0,0 +1,80 @@
+import SwiftUI
+
+/// A first-launch primer on the app's vocabulary — loop, node, edge, and the four loop
+/// types — shown once (see `AppFeature.State.showingOnboarding`) and reopenable from
+/// the sidebar's help button. One scrollable card rather than a paged carousel: there
+/// are six ideas to convey and a reader should be able to see them all, not click
+/// through them.
+struct OnboardingView: View {
+  let onDismiss: () -> Void
+
+  var body: some View {
+    VStack(spacing: 0) {
+      VStack(spacing: 6) {
+        Image(systemName: "point.3.connected.trianglepath.dotted")
+          .font(.system(size: 34))
+          .foregroundStyle(Color.accentColor)
+        Text("Welcome to GraphCode").font(.title2).bold()
+        Text("Graphs of live, steerable AI coding sessions. Five words to know:")
+          .font(.subheadline)
+          .foregroundStyle(.secondary)
+      }
+      .padding(.top, 28)
+      .padding(.bottom, 16)
+
+      ScrollView {
+        VStack(alignment: .leading, spacing: 14) {
+          term(
+            "circle.circle", "Loop",
+            "A unit of work an AI coding agent runs in a real terminal session — one you "
+              + "can open, watch, and steer mid-run. Loops keep running with the app closed.")
+          term(
+            "point.3.connected.trianglepath.dotted", "Node",
+            "A loop as drawn on the graph canvas. Click a node to attach to its live "
+              + "terminal — scrollback and all.")
+          term(
+            "arrow.right", "Edge",
+            "A connection between loops, drawn by dragging between nodes: a hand-off "
+              + "that fires when the source finishes, a message, or a spawn.")
+          term(
+            "flag.checkered", "Loop types",
+            "Goal-based runs until a goal is met. Time-based repeats on a cadence in its "
+              + "own prompt — watchers live here. Turn-based pauses for your review each "
+              + "turn. Proactive is a group of loops run as one.")
+          term(
+            "bubble.left", "Quick Chat",
+            "Just a conversation — no goal, no graph. The sidebar section above your "
+              + "projects.")
+          term(
+            "folder", "Project",
+            "A folder you add. It gets its own graph of loops; nothing is ever written "
+              + "inside the folder itself.")
+        }
+        .padding(.horizontal, 28)
+      }
+
+      Button("Get Started") { onDismiss() }
+        .keyboardShortcut(.defaultAction)
+        .controlSize(.large)
+        .padding(.vertical, 20)
+    }
+    .frame(width: 480, height: 560)
+  }
+
+  private func term(_ glyph: String, _ name: String, _ explanation: String) -> some View {
+    HStack(alignment: .top, spacing: 12) {
+      Image(systemName: glyph)
+        .font(.body)
+        .foregroundStyle(Color.accentColor)
+        .frame(width: 22)
+      VStack(alignment: .leading, spacing: 2) {
+        Text(name).font(.headline)
+        Text(explanation).font(.callout).foregroundStyle(.secondary)
+      }
+    }
+  }
+}
+
+#Preview {
+  OnboardingView(onDismiss: {})
+}