more detailed help instructions

Co-authored-by: Copilot <copilot@github.com>

Author: skarim

cmd/modify.go

@@ -164,7 +164,7 @@ func printModifySuccess(cfg *config.Config, result *modifyview.ApplyResult) {
 	}
 
 	cfg.Printf("")
-	cfg.Printf("Run `%s` to push branches and recreate the stack on GitHub",
+	cfg.Printf("Run `%s` to push your changes and update the stack of PRs on GitHub",
 		cfg.ColorCyan("gh stack submit"))
 }
 

internal/modify/apply.go

@@ -587,7 +587,13 @@ func ContinueApply(
 					cfg.Printf("  %s", f)
 				}
 			}
-			return fmt.Errorf("rebase conflict on %s — resolve and run `gh stack modify --continue` again", branchName)
+			cfg.Printf("")
+			cfg.Printf("Resolve the conflicts, stage with `%s`, then run `%s`",
+				cfg.ColorCyan("git add <file>"),
+				cfg.ColorCyan("gh stack modify --continue"))
+			cfg.Printf("Or restore the stack with `%s`",
+				cfg.ColorCyan("gh stack modify --recover"))
+			return fmt.Errorf("rebase conflict on %s", branchName)
 		}
 
 		cfg.Successf("Rebased %s onto %s", branchName, newBase)
@@ -619,8 +625,9 @@ func ContinueApply(
 		cfg.Warningf("failed to save stack: %v", err)
 	}
 
-	cfg.Successf("Modify apply completed")
-	cfg.Printf("Run `%s` to push branches and recreate the stack on GitHub",
+	cfg.Successf("Stack modified successfully")
+	cfg.Printf("")
+	cfg.Printf("Run `%s` to push your changes and update the stack of PRs on GitHub",
 		cfg.ColorCyan("gh stack submit"))
 	return nil
 }

internal/tui/modifyview/help.go

@@ -6,51 +6,58 @@ import (
 	"github.com/charmbracelet/lipgloss"
 )
 
-type helpEntry struct {
-	keys string
-	desc string
-}
-
-var helpEntries = []helpEntry{
-	{"↑/↓, k/j", "Select branch"},
-	{"f", "View files changed"},
-	{"c", "View commits"},
-	{"x", "Drop branch from stack"},
-	{"r", "Rename branch"},
-	{"u", "Fold up (merge into branch above)"},
-	{"d", "Fold down (merge into branch below)"},
-	{"shift+↑/↓, K/J", "Reorder branch up/down"},
-	{"z", "Undo last action"},
-	{"ctrl+s", "Apply all changes"},
-	{"q/esc", "Cancel and exit (abandon changes)"},
-}
-
-// renderHelpOverlay renders a centered help overlay.
+// renderHelpOverlay renders a centered help overlay with a guide to modify operations.
 func renderHelpOverlay(width, height int) string {
 	var b strings.Builder
 
-	title := helpTitleStyle.Render("Keyboard Shortcuts")
+	title := helpTitleStyle.Render("Modify Stack")
 	b.WriteString(title)
-	b.WriteString("\n\n")
+	b.WriteString("\n")
+	b.WriteString(helpDescStyle.Render("Restructure your stack by dropping, folding, renaming, or reordering branches."))
+	b.WriteString("\n")
 
-	maxKeyWidth := 0
-	for _, e := range helpEntries {
-		w := lipgloss.Width(e.keys)
-		if w > maxKeyWidth {
-			maxKeyWidth = w
-		}
+	sections := []struct {
+		heading string
+		body    string
+	}{
+		{
+			"Drop (x)",
+			"Remove a branch and its commits from the stack.\nThe local branch is preserved; the PR stays open on GitHub.",
+		},
+		{
+			"Fold up / down (u / d)",
+			"Merge a branch's commits into an adjacent branch.\nFold up absorbs into the branch above; fold down into the branch below.",
+		},
+		{
+			"Rename (r)",
+			"Rename a branch locally. The new name is pushed on submit.",
+		},
+		{
+			"Reorder (Shift+↑/↓)",
+			"Move a branch up or down in the stack.\nA cascading rebase adjusts all affected branches.",
+		},
 	}
 
-	for _, e := range helpEntries {
-		keyVisWidth := lipgloss.Width(e.keys)
-		keyPad := strings.Repeat(" ", maxKeyWidth-keyVisWidth+2)
-		b.WriteString(helpKeyStyle.Render(e.keys))
-		b.WriteString(keyPad)
-		b.WriteString(helpDescStyle.Render(e.desc))
+	for _, s := range sections {
 		b.WriteString("\n")
+		b.WriteString(helpKeyStyle.Render(s.heading))
+		b.WriteString("\n")
+		for _, line := range strings.Split(s.body, "\n") {
+			b.WriteString(helpDescStyle.Render(line))
+			b.WriteString("\n")
+		}
 	}
 
 	b.WriteString("\n")
+	b.WriteString(helpKeyStyle.Render("Applying changes"))
+	b.WriteString("\n")
+	b.WriteString(helpDescStyle.Render("Press " + helpKeyStyle.Render("Ctrl+S") + " to apply all staged changes. Nothing is modified until you save."))
+	b.WriteString("\n")
+	b.WriteString(helpDescStyle.Render("If you have open PRs, run ") + helpKeyStyle.Render("gh stack submit") + helpDescStyle.Render(" afterwards to push the updated"))
+	b.WriteString("\n")
+	b.WriteString(helpDescStyle.Render("branches and recreate the stack of PRs on GitHub."))
+
+	b.WriteString("\n\n")
 	b.WriteString(statusBarStyle.Render("Press ? or Esc to close"))
 
 	content := b.String()

internal/tui/shared/header.go

@@ -51,12 +51,12 @@ const ArtDisplayWidth = 20
 
 // HeaderConfig controls what the header displays.
 type HeaderConfig struct {
-	ShowArt          bool             // true for View (GitHub logo), false for Modify
-	Title            string           // "GitHub Stacks" or "Modify Mode"
-	Subtitle         string           // version string, or empty
-	InfoLines        []HeaderInfoLine // info rows (stack info)
-	Shortcuts        []ShortcutEntry  // keyboard shortcuts
-	ShortcutColumns  int              // number of columns for shortcuts (default 1; set 2 for side-by-side)
+	ShowArt         bool             // whether to display GitHub logo
+	Title           string           // heading next to logo art
+	Subtitle        string           // version string, or empty
+	InfoLines       []HeaderInfoLine // info rows (stack info)
+	Shortcuts       []ShortcutEntry  // keyboard shortcuts
+	ShortcutColumns int              // number of columns for shortcuts (default 1; set 2 for side-by-side)
 }
 
 // ShouldShowHeader returns whether the header should be displayed.

internal/tui/stackview/model.go

@@ -409,7 +409,7 @@ func (m Model) buildHeaderConfig() shared.HeaderConfig {
 
 	return shared.HeaderConfig{
 		ShowArt:  true,
-		Title:    "GitHub Stacks",
+		Title:    "View Stack",
 		Subtitle: "v" + m.version,
 		InfoLines: []shared.HeaderInfoLine{
 			{Icon: "✓", Label: "Stack initialized"},

internal/tui/stackview/model_test.go

@@ -184,7 +184,7 @@ func TestView_HeaderShownWhenTallEnough(t *testing.T) {
 	view := m.View()
 	assert.Contains(t, view, "┌")
 	assert.Contains(t, view, "┘")
-	assert.Contains(t, view, "GitHub Stacks")
+	assert.Contains(t, view, "View Stack")
 	assert.Contains(t, view, "v0.0.1")
 	assert.Contains(t, view, "Base: main")
 	assert.Contains(t, view, "2 branches")
@@ -203,7 +203,7 @@ func TestView_HeaderHiddenWhenShort(t *testing.T) {
 	view := m.View()
 	// Should NOT contain header box
 	assert.NotContains(t, view, "┌")
-	assert.NotContains(t, view, "GitHub Stacks")
+	assert.NotContains(t, view, "View Stack")
 	// Should NOT contain help bar either (hints are only in header)
 	assert.NotContains(t, view, "commits")
 }
@@ -218,7 +218,7 @@ func TestView_HeaderHiddenWhenNarrow(t *testing.T) {
 
 	view := m.View()
 	assert.NotContains(t, view, "┌")
-	assert.NotContains(t, view, "GitHub Stacks")
+	assert.NotContains(t, view, "View Stack")
 }
 
 func TestView_HeaderWithoutShortcutsWhenMediumWidth(t *testing.T) {
@@ -231,7 +231,7 @@ func TestView_HeaderWithoutShortcutsWhenMediumWidth(t *testing.T) {
 
 	view := m.View()
 	assert.Contains(t, view, "┌", "header should be shown")
-	assert.Contains(t, view, "GitHub Stacks", "info should be shown")
+	assert.Contains(t, view, "View Stack", "info should be shown")
 	assert.NotContains(t, view, "checkout", "shortcuts should be hidden at this width")
 }