insert branches with modify (#107)

* add insert branch operation to modify TUI

Add `i` (insert below) and `I` (insert above) key bindings to the
interactive modify view, allowing users to insert new empty branches
into an existing stack. This follows Vim-inspired semantics where
lowercase `i` inserts below the cursor and uppercase `I` inserts above.

## TUI behavior

When the user presses `i` or `I`, the TUI enters an insert input mode
(similar to rename mode) where they type a new branch name. The input
is validated against git ref naming rules, local branch uniqueness, and
in-stack name collisions. On confirm, a placeholder node is inserted at
the correct position in the branch list with a green "✚ insert"
annotation badge and green connector styling.

Insert is a structure operation — it works alongside fold, rename, and
drop, but is mutually exclusive with reorder (consistent with existing
mode exclusivity rules). Undo (`z`) removes the inserted node cleanly.

## Apply engine

At apply time (Step 2 in the pipeline, between renames and folds), the
engine creates the new git branch at the parent branch's tip via
`git.CreateBranch` and inserts a `BranchRef` into the stack metadata at
the correct position. If the insertion changes the base of a branch
that has an open PR, `affectsPRs` is set to trigger a required
`gh stack submit` afterward.

## Header shortcut updates

- Combined the fold shortcuts into a single line: `d/u - fold down/up`
- Added insert shortcuts on their own line: `i/I - insert below/above`
- Reordered fold references throughout to list "down" before "up" for
  consistency with the insert shortcut ordering

## Files changed

- types.go: ActionInsertBelow/ActionInsertAbove types, IsInserted field,
  InsertedBranches in ApplyResult
- model.go: key bindings, insert input mode, undo, mode exclusivity,
  annotation, styling, header shortcuts, effective-index tracking to
  prevent false reorder detection when inserts shift node positions
- styles.go: green insert badge/branch/connector styles
- status.go: insert counting in pending change summary
- help.go: new "Insert below / above" section, reordered fold heading
- apply.go: BuildPlan and ApplyPlan handle insert actions
- modify.go: updated command description and success summary
- README.md: updated keybindings table

## Test coverage

- 16 new TUI tests: insert below/above, top/bottom edges, undo, mode
  exclusivity, merged branch guard, cancel/empty input, duplicate name
  validation, pending summary counting, annotation rendering, mixed
  operations with drop/fold, apply acceptance
- 4 new apply tests: BuildPlan produces correct insert actions,
  ApplyPlan creates branches and updates stack metadata, insert at
  stack start uses trunk as parent, affectsPRs triggered when inserting
  before a branch with an open PR

* update add error msg to direct users to modify for inserting branches

* docs updates

* fix insert branch bugs in modify TUI

Fix three bugs with the insert branch feature in the modify TUI, and
adjust rename behavior on inserted nodes.

## Bug 1: False "moved" annotations on existing branches

After inserting a branch, all branches below the insertion point
displayed "↕ moved 1 layer down" annotations. This happened because
`nodeAnnotation` and `toNodeData` compared each node's
`OriginalPosition` against its raw array index, which gets shifted
when an inserted node is added to the slice.

Fix: introduce an `effectiveIdx` parameter that counts only
non-inserted nodes, so position comparisons reflect the original
ordering. The View loop computes effective indices by incrementing
only for non-inserted nodes and passes them to the rendering
functions.

## Bug 2: Header branch count inflated by staged inserts

The branch count in the header ("N branches") included inserted
placeholder nodes, making it appear as though the stack had grown
before changes were applied.

Fix: `buildHeaderConfig` now excludes `IsInserted` nodes from the
branch count. The count reflects only the original branches in the
stack.

## Bug 3: Operations allowed on inserted placeholder nodes

Inserted nodes could be folded into other branches, which makes no
sense for a placeholder with no commits. Additionally, the "last
branch" guard counted inserted nodes as active, allowing users to
drop all original branches and bypass the empty-stack check.

Fix:
- `fold()` rejects inserted nodes with a descriptive error message.
- `toggleDrop()` on an inserted node removes it entirely and pops
  the original insert action from the undo stack (clean cancellation
  rather than a separate undo entry).
- All three "active branch" guards (`toggleDrop`, `fold`, `tryApply`)
  now exclude `IsInserted` nodes, ensuring at least one original
  branch always remains in the stack.

## Rename on inserted branches

Instead of blocking renames on inserted nodes, pressing `r` now
enters rename mode and updates the insert action's name in place.
The node's `Ref.Branch` and `PendingAction.NewName` are both updated
directly — no separate rename action is created in the undo stack.
This lets users fix a typo without having to drop and re-insert.

## Tests added

- `TestInsertDoesNotShowMovedAnnotation` — verifies no false move
  annotations appear on existing branches after an insert
- `TestBranchCountExcludesInserts` — verifies header count stays
  stable after insert
- `TestCannotFoldInsertedBranch` — verifies fold is blocked
- `TestCannotRenameInsertedBranch` — verifies rename updates the
  insert name in place
- `TestDropInsertedBranchRemovesIt` — verifies drop removes the node
- `TestDropInsertedBranchCanBeUndone` — verifies drop pops the
  original insert from the undo stack
- `TestCannotDropAllOriginalBranchesWithInsert` — verifies the
  empty-stack guard excludes inserted nodes

* ensure cannot fold into an inserted branch

* rm dead code

* delete inserted branches during abort

Author: skarim

README.md

@@ -245,7 +245,7 @@ Interactively restructure the current stack.
 gh stack modify [flags]
 ```
 
-Opens a terminal UI for restructuring a stack. You can rename, drop, reorder, and fold branches into adjacent ones. All the changes are staged during the preview and applied at once on save.
+Opens a terminal UI for restructuring a stack. You can drop, fold, insert, rename, and reorder branches. All the changes are staged during the preview and applied at once on save.
 
 If the stack of PRs has been created on GitHub, run `gh stack submit` afterwards to push the changes and recreate the stack.
 
@@ -259,6 +259,7 @@ If the stack of PRs has been created on GitHub, run `gh stack submit` afterwards
 - **Drop** (`x`): Remove a branch and its commits from the stack. Local branch and associated PR are preserved.
 - **Fold down** (`d`): Absorb a branch's commits into the branch below (toward trunk). Folded branch removed from stack.
 - **Fold up** (`u`): Absorb a branch's commits into the branch above (away from trunk). Folded branch removed from stack.
+- **Insert** (`i`/`I`): Insert a new empty branch into the stack. `i` inserts below the cursor; `I` inserts above.
 - **Reorder** (`Shift+↑`/`Shift+↓`): Move a branch up (away from trunk) or down (toward trunk) in the stack.
 - **Rename** (`r`): Rename a branch locally and in the stack metadata.
 - **Undo** (`z`): Undo the last staged action.
@@ -272,7 +273,8 @@ If the stack of PRs has been created on GitHub, run `gh stack submit` afterwards
 | `c` | View commits |
 | `x` | Drop branch |
 | `r` | Rename branch |
-| `u/d` | Fold branch up/down |
+| `i/I` | Insert branch below/above |
+| `d/u` | Fold branch down/up |
 | `Shift+↑`/`Shift+↓` | Move branch up/down |
 | `z` | Undo last action |
 | `Ctrl+S` | Apply all changes |

cmd/add.go

@@ -85,7 +85,8 @@ func runAdd(cfg *config.Config, opts *addOptions, args []string) error {
 	// idx < 0 means we're on the trunk — that's allowed (we'll create
 	// a new branch from it). Only block if we're in the middle of the stack.
 	if idx >= 0 && idx < len(s.Branches)-1 {
-		cfg.Errorf("can only add branches on top of the stack; run `%s` to switch to %q", cfg.ColorCyan("gh stack top"), s.Branches[len(s.Branches)-1].Branch)
+		cfg.Errorf("can only add branches to the top of the stack; run `%s` then `%s`", cfg.ColorCyan("gh stack top"), cfg.ColorCyan("gh stack add"))
+		cfg.Printf("Or to restructure your stack and insert a branch, use `%s`", cfg.ColorCyan("gh stack modify"))
 		return ErrInvalidArgs
 	}
 

cmd/add_test.go

@@ -78,6 +78,7 @@ func TestAdd_OnlyAllowedOnTopOfStack(t *testing.T) {
 	output := collectOutput(cfg, outR, errR)
 
 	assert.Contains(t, output, "top of the stack")
+	assert.Contains(t, output, "gh stack modify")
 }
 
 func TestAdd_MutuallyExclusiveFlags(t *testing.T) {

cmd/modify.go

@@ -29,6 +29,7 @@ func ModifyCmd(cfg *config.Config) *cobra.Command {
 Operations available:
   • Drop branches from the stack
   • Fold branches into adjacent branches
+  • Insert new branches into the stack
   • Reorder branches
   • Rename branches
 
@@ -168,6 +169,10 @@ func printModifySuccess(cfg *config.Config, result *modifyview.ApplyResult) {
 		cfg.Printf("  Renamed: %s → %s", r.OldName, r.NewName)
 	}
 
+	for _, name := range result.InsertedBranches {
+		cfg.Printf("  Inserted: %s", name)
+	}
+
 	for _, d := range result.DroppedPRs {
 		cfg.Printf("  Dropped: %s (PR #%d remains open — close with `%s`)",
 			d.Branch, d.PRNumber, cfg.ColorCyan(fmt.Sprintf("gh pr close %d", d.PRNumber)))

docs/src/assets/screenshots/modify-stack-tui.png

@@ -33,15 +33,15 @@ You can also add PRs to an existing stack from the GitHub UI. See [Adding to an
 
 ### How can I modify my stack?
 
-Use `gh stack modify` to restructure a stack. It opens an interactive terminal UI where you can reorder, drop, fold (combine), and rename branches — then applies all changes at once. See the [Restructuring Stacks](/gh-stack/guides/modify/) guide for a full walkthrough.
+Use `gh stack modify` to restructure a stack. It opens an interactive terminal UI where you can reorder, drop, fold (combine), insert, and rename branches — then applies all changes at once. See the [Restructuring Stacks](/gh-stack/guides/modify/) guide for a full walkthrough.
 
 Alternatively, you can manually tear down and re-create the stack with `gh stack unstack` and `gh stack init`:
 
 ```sh
 # 1. Remove the stack
 gh stack unstack
 
-# 2. Make structural changes (reorder, rename, delete branches)
+# 2. Make structural changes (reorder, rename, insert, delete branches)
 git branch -m api-roots api-routes
 
 # 3. Re-create the stack with the new structure

docs/src/content/docs/faq.md

@@ -3,7 +3,7 @@ title: Restructuring Stacks
 description: How to use `gh stack modify` to restructure a stack.
 ---
 
-`gh stack modify` provides an interactive terminal UI for restructuring a stack locally. You can drop, fold, rename, and reorder branches and then apply all your changes at once.
+`gh stack modify` provides an interactive terminal UI for restructuring a stack locally. You can drop, fold, insert, rename, and reorder branches and then apply all your changes at once.
 
 ![The modify stack terminal UI](../../../assets/screenshots/modify-stack-tui.png)
 
@@ -12,6 +12,7 @@ description: How to use `gh stack modify` to restructure a stack.
 Use `modify` when you need to:
 - **Remove** a branch from the stack
 - **Combine** two branches into one
+- **Insert** a new branch into the stack
 - **Rename** a branch
 - **Reorder** branches
 
@@ -46,21 +47,25 @@ Absorbs the selected branch's commits into the branch below it (toward trunk) vi
 
 Absorbs the selected branch's commits into the branch above it (away from trunk). Since the branch above already contains the folded branch's commits in its history, this is handled by adjusting what is considered the first unique commit for the branch. The folded branch is removed from the stack.
 
+### Insert below / above (`i` / `I`)
+
+Inserts a new empty branch into the stack at the cursor position. Lowercase `i` inserts below the cursor (toward trunk); uppercase `I` inserts above the cursor (away from trunk). An inline prompt appears to enter the new branch name. The branch is created at apply time, pointing at the parent branch's tip.
+
 ### Rename (`r`)
 
 Opens an inline prompt to enter a new name for the branch. The branch is renamed locally and in the stack metadata. On the next `submit`, the new branch name is pushed to GitHub.
 
 ### Reorder (`Shift+↑`/`Shift+↓`)
 
-Moves the selected branch up (away from trunk) or down (toward trunk) in the stack. A cascading rebase adjusts all affected branches. Note: reordering and structural changes (drop/fold/rename) cannot be mixed in the same session.
+Moves the selected branch up (away from trunk) or down (toward trunk) in the stack. A cascading rebase adjusts all affected branches. Note: reordering and structural changes (drop/fold/insert/rename) cannot be mixed in the same session.
 
 ### Undo (`z`)
 
 Reverses the most recent staged action. You can undo multiple times to step back through your changes.
 
 ## Applying changes
 
-Press `Ctrl+S` to apply all staged changes. Nothing is modified until you save. The apply phase renames branches, folds/drops branches, and runs a cascading rebase to create a linear commit history with the desired stack state.
+Press `Ctrl+S` to apply all staged changes. Nothing is modified until you save. The apply phase renames branches, inserts new branches, folds/drops branches, and runs a cascading rebase to create a linear commit history with the desired stack state.
 
 ### Handling conflicts
 
@@ -94,8 +99,7 @@ This also works if `modify` was interrupted (e.g., terminal crash). A pre-modify
 ## Limitations
 
 - Cannot modify merged branches (they are locked)
-- Cannot add new branches (use `gh stack add` instead)
 - Cannot split a branch into multiple branches
 - Cannot move branches between different stacks
 - Requires an interactive terminal
-- Reordering and structural changes (drop/fold/rename) cannot be mixed in the same session
+- Reordering and structural changes (drop/fold/insert/rename) cannot be mixed in the same session

docs/src/content/docs/guides/modify.md

@@ -93,7 +93,7 @@ Commits created by a server-side rebase are **not signed**. If your repository r
 
 ## Unstacking
 
-If you want to reorder or reorganize the PRs in a stack, you must first dissolve the stack and then re-create it. You can unstack PRs from the UI.
+If you want to reorder or reorganize the PRs in a stack from the UI, you must first dissolve the stack and then re-create it. For CLI users, `gh stack modify` provides an interactive way to [restructure a stack](/gh-stack/guides/modify/) — including reordering, inserting, dropping, and renaming branches — without needing to dissolve it.
 
 ### Dissolving the Entire Stack
 

docs/src/content/docs/guides/ui.md

@@ -299,7 +299,7 @@ All branches in a stack should be part of the same feature or project. If you ne
 
 ## Restructuring a Stack
 
-When you need to change the composition of a stack — remove a branch, combine branches, change the order, or rename a branch — use `gh stack modify`:
+When you need to change the composition of a stack — remove a branch, combine branches, insert a new branch, change the order, or rename a branch — use `gh stack modify`:
 
 ```sh
 # Open the modify TUI
@@ -309,6 +309,8 @@ gh stack modify
 #   x     → drop a branch
 #   d     → fold down (into branch below)
 #   u     → fold up (into branch above)
+#   i     → insert below
+#   I     → insert above
 #   Shift+↑/↓ → reorder
 #   r     → rename
 #   z     → undo

docs/src/content/docs/guides/workflows.md

@@ -89,7 +89,8 @@ While the PR UI provides the review and merge experience, the `gh stack` CLI han
 - **Creating PRs** — `gh stack submit` pushes branches and creates or updates PRs, linking them as a Stack on GitHub.
 - **Navigating the stack** — `gh stack up`, `down`, `top`, and `bottom` let you move between layers without remembering branch names.
 - **Syncing everything** — `gh stack sync` fetches, rebases, pushes, and updates PR state in one command.
-- **Tearing down stacks** — `gh stack unstack` removes a stack from GitHub and local tracking if you need to restructure it.
+- **Restructuring stacks** — `gh stack modify` opens an interactive terminal UI to drop, fold, insert, rename, and reorder branches in a stack.
+- **Tearing down stacks** — `gh stack unstack` removes a stack from GitHub and local tracking.
 - **Checking out a stack** — `gh stack checkout <pr-number>` pulls down a stack, with all its branches, from GitHub to your local machine.
 
 The CLI is not required to use Stacked PRs — the underlying git operations are standard. But it makes the workflow simpler, and you can create Stacked PRs from the CLI instead of the UI.