docs updates

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 |

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.

docs/src/content/docs/introduction/overview.md

@@ -192,14 +192,16 @@ The command checks these conditions before opening the TUI:
 | Drop | `x` | Remove branch and its commits from stack. Local branch and associated PR are preserved. |
 | Fold down | `d` | Absorb commits into branch below (toward trunk). Folded branch removed from stack. |
 | Fold up | `u` | Absorb commits into branch above (away from trunk). Folded branch removed from stack. |
+| Insert below | `i` | Insert a new empty branch below the cursor (toward trunk). |
+| Insert above | `I` | Insert a new empty branch above the cursor (away from trunk). |
 | Move down | `Shift+↓` | Reorder branch down (toward trunk) in the stack |
 | Move up | `Shift+↑` | Reorder branch up (away from trunk) in the stack |
 | Rename | `r` | Rename the branch (opens inline prompt) |
 | Undo | `z` | Undo the last staged action |
 
 **Apply phase:**
 
-When you press `Ctrl+S`, the staged changes are applied by renaming branches, folding/dropping branches, and running a cascading rebase to create a linear commit history with the desired stack state.
+When you press `Ctrl+S`, the staged changes are applied by renaming branches, inserting new branches, folding/dropping branches, and running a cascading rebase to create a linear commit history with the desired stack state.
 
 If a rebase conflict occurs, you can:
 - Resolve conflicts, stage files, and run `gh stack modify --continue`
@@ -234,7 +236,7 @@ You must have a branch from the stack checked out locally. The command targets t
 
 Deletes the stack on GitHub first, if it exists, then removes it from local tracking. If the remote deletion fails, the local state is left untouched so you can retry. Use `--local` to skip the remote deletion and only remove local tracking.
 
-This is useful when you need to restructure a stack — remove a branch, reorder branches, rename branches, or make other large changes. After unstacking, use `gh stack init` to re-create the stack with the desired structure — existing branches are adopted automatically.
+This is useful when you need to restructure a stack — remove a branch, insert a branch, reorder branches, rename branches, or make other large changes. After unstacking, use `gh stack init` to re-create the stack with the desired structure — existing branches are adopted automatically.
 
 | Flag | Description |
 |------|-------------|