docs updates

Author: skarim

README.md

@@ -69,7 +69,7 @@ Stack metadata is stored in `.git/gh-stack` (a JSON file, not committed to the r
 Initialize a new stack in the current repository.
 
 ```
-gh stack init [branches...] [flags]
+gh stack init [flags] [branches...]
 ```
 
 Creates an entry in `.git/gh-stack` to track stack state. In interactive mode (no arguments), prompts you to name branches and offers to use the current branch as the first layer. In interactive mode, you'll also be prompted to set an optional branch prefix (unless adopting existing branches). When a prefix is set, branch names you enter are automatically prefixed. When explicit branch names are given, creates any that don't already exist (branching from the trunk). The trunk defaults to the repository's default branch unless overridden with `--base`.
@@ -115,7 +115,7 @@ gh stack init -p feat --numbered
 Add a new branch on top of the current stack.
 
 ```
-gh stack add [branch] [flags]
+gh stack add [flags] [branch]
 ```
 
 Creates a new branch at the current HEAD, adds it to the top of the stack, and checks it out. Must be run while on the topmost branch of a stack. If no branch name is given, prompts for one.
@@ -190,7 +190,7 @@ gh stack checkout
 Pull from remote and do a cascading rebase across the stack.
 
 ```
-gh stack rebase [branch] [flags]
+gh stack rebase [flags] [branch]
 ```
 
 Fetches the latest changes from `origin`, then ensures each branch in the stack has the tip of the previous layer in its commit history. Rebases branches in order from trunk upward. If a branch's PR has been squash-merged, the rebase automatically switches to `--onto` mode to correctly replay commits on top of the merge target.
@@ -331,7 +331,7 @@ gh stack view --json
 Remove a stack from local tracking and delete it on GitHub. Also available as `gh stack delete`.
 
 ```
-gh stack unstack [branch] [flags]
+gh stack unstack [flags] [branch]
 ```
 
 If no branch is specified, uses the current branch to find the stack. Deletes the stack on GitHub first, then removes local tracking. Use `--local` to only remove the local tracking entry.
@@ -414,7 +414,7 @@ gh stack feedback "Support for reordering branches"
 Create a short command alias so you can type less.
 
 ```
-gh stack alias [name] [flags]
+gh stack alias [flags] [name]
 ```
 
 Installs a small wrapper script into `~/.local/bin/` that forwards all arguments to `gh stack`. The default alias name is `gs`, but you can choose any name by passing it as an argument. After setup, you can run `gs push` instead of `gh stack push`.

docs/src/assets/screenshots/merge-box-failing-stack-requirements.png

@@ -158,7 +158,7 @@ Yes, you can continue to use your tool of choice (e.g. jj, Sapling, ghstack, git
 
 Stacked PRs on GitHub are based on the standard pull request model — any tool that creates PRs with the correct base branches can work with them. The `gh stack` CLI is purpose-built for the GitHub experience, but other tools that manage branch chains should be compatible.
 
-You can also use the GitHub CLI in conjunction with other tools to simply create a stack of PRs:
+You can also use the GitHub CLI in conjunction with other tools to open your PRs as a stack:
 
 ```bash
 # Create a stack of branches locally using jj

docs/src/assets/screenshots/stack-merge-box.png

@@ -75,7 +75,7 @@ Before a PR in the stack can be merged, the following conditions must be met:
 - **The stack must be fully rebased** with a linear history
 - **The current PR itself** must meet all branch protection requirements for the stack base
 
-![Merge box showing failing stack requirements](../../../assets/screenshots/merge-box-failing-stack-requirements.png)
+![Merge box for a stacked pull request](../../../assets/screenshots/stack-merge-box.png)
 
 ## Unstacking
 

docs/src/content/docs/faq.md

@@ -33,7 +33,7 @@ gh stack rebase
 # 7. Push the updated branches
 gh stack push
 
-# 8. When the first PR is merged, sync the stack
+# 8. Sync upstream changes as PRs get merged
 gh stack sync
 ```
 
@@ -42,34 +42,37 @@ gh stack sync
 For speed, use a branch prefix with `--numbered` and the `-Am` flags to fold staging, committing, and branch creation into a single command. Branch names are auto-generated as `prefix/01`, `prefix/02`, etc.
 
 ```sh
+# Alias `gh stack` as `gs` for easier use
+gh stack alias
+
 # 1. Start a stack with numbered branches
-gh stack init -p feat --numbered
+gs init -p feat --numbered
 #    → creates feat/01 and checks it out
 
 # 2. Write code for the first layer
 # ... write code ...
 
 # 3. Stage and commit on the current branch
-gh stack add -Am "Auth middleware"
+gs add -Am "Auth middleware"
 #    → feat/01 has no commits yet, so the commit lands here
 
 # 4. Write code for the next layer
 # ... write code ...
 
 # 5. Create the next branch and commit
-gh stack add -Am "API routes"
+gs add -Am "API routes"
 #    → feat/01 already has commits, so feat/02 is created
 
 # 6. Keep going
 # ... write code ...
-gh stack add -Am "Frontend components"
+gs add -Am "Frontend components"
 #    → creates feat/03
 
 # 7. Push everything and create PRs
-gh stack submit
+gs submit
 ```
 
-Each `gh stack add -Am "..."` stages all files, commits, and (if the current branch already has commits) creates a new branch — no separate `git add` or `git commit` needed.
+Each `gs add -Am "..."` stages all files, commits, and (if the current branch already has commits) creates a new branch — no separate `git add` or `git commit` needed.
 
 ## Making Mid-Stack Changes
 

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

@@ -47,37 +47,42 @@ A **stack** is a series of pull requests in the same repository where each PR ta
   <Image src={stackDiagram} alt="A stack of pull requests: main at the bottom, with auth-layer (PR #1), api-endpoints (PR #2), and frontend (PR #3) stacked on top" />
 </div>
 
-GitHub understands stacks end-to-end: the pull request UI shows a **stack map** so reviewers can navigate between layers, branch protection rules are enforced against the **final target branch** (not just the direct base), and CI runs for every PR in the stack.
+GitHub understands stacks end-to-end: the pull request UI shows a **stack map** so reviewers can navigate between layers, branch protection rules are enforced against the **final target branch** (not just the direct base), and CI runs for every PR in the stack as if they were targeting the final branch.
 
 <div style="max-width: 600px; margin: 1.5rem auto;">
   <Image src={stackNavigator} alt="The stack navigator in a pull request header" />
 </div>
 
 ## How It Works
 
-The `gh stack` CLI handles the local workflow: creating branches, keeping them rebased, pushing to GitHub, and creating PRs with the correct base branches. On GitHub, the PR UI gives reviewers the context they need — a stack map for navigation, focused diffs for each layer, and proper rules enforcement.
+The `gh stack` CLI handles the local workflow: creating branches, managing rebases, pushing to GitHub, and creating PRs with the correct base branches. On GitHub, the PR UI gives reviewers the context they need — a stack map for navigation, focused diffs for each layer, and proper rules enforcement.
 
-When you're ready to merge, you merge from the bottom up. Each PR can be merged directly or through the merge queue. When a PR at the bottom is merged, the remaining stack is automatically rebased so the next PR targets `main` and is ready for its own merge.
+When you're ready to merge, you can merge all or a part of the stack. Each PR can be merged directly or through the merge queue. After a merge, the remaining PRs in the stack are automatically rebased so the lowest unmerged PR targets the base branch.
 
 ## Get Started
 
 ```sh
 # Install the CLI extension
 gh extension install github/gh-stack
 
-# Create a stack (creates and checks out the first branch)
-gh stack init auth-layer
+# Alias `gh stack` as `gs` for easier use (optional)
+gh stack alias
+
+# Start a stack (creates and checks out the first branch)
+gs init auth-layer
 # ... make commits ...
-gh stack add api-routes
+
+# Create new layers in the stack (creates and checks out each new branch)
+gs add api-routes
 # ... make commits ...
-gh stack add frontend
+gs add frontend
 # ... make commits ...
 
 # Push all branches
-gh stack push
+gs push
 
 # Open a stack of PRs
-gh stack submit
+gs submit
 ```
 
 Ready to dive in? Start with the [Quick Start guide](/gh-stack/getting-started/quick-start/) or read the [full overview](/gh-stack/introduction/overview/).

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

@@ -3,7 +3,7 @@ title: Overview
 description: What stacked pull requests are, why they matter, and how GitHub supports them natively.
 ---
 
-## The Challenge
+## Why Stacks?
 
 For developers who want to break large changes into smaller, dependent parts, the experience can be painful:
 
@@ -89,8 +89,9 @@ While the PR UI provides the review and merge experience, the `gh stack` CLI han
 - **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.
+- **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 dramatically simpler.
+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 CLI instead of the UI.
 
 ## Thinking About Stack Structure
 

docs/src/content/docs/index.mdx

@@ -381,7 +381,7 @@ gh stack init --base main --adopt new-branch-1 new-branch-2 new-branch-3
 Creates a new stack. Provide branch names as positional arguments.
 
 ```
-gh stack init [branches...] [flags]
+gh stack init [flags] [branches...]
 ```
 
 ```bash
@@ -424,7 +424,7 @@ gh stack init --adopt branch-a branch-b branch-c
 Add a new branch on top of the current stack. Must be run while on the topmost branch (or the trunk if the stack has no branches yet). Always provide an explicit branch name.
 
 ```
-gh stack add [branch] [flags]
+gh stack add [flags] [branch]
 ```
 
 **Recommended workflow — create the branch, then use standard git:**
@@ -578,7 +578,7 @@ gh stack sync [flags]
 Pull from remote and cascade-rebase stack branches. Use this when `sync` reports a conflict or when you need finer control (e.g., rebase only part of the stack).
 
 ```
-gh stack rebase [branch] [flags]
+gh stack rebase [flags] [branch]
 ```
 
 ```bash
@@ -730,7 +730,7 @@ When a branch name is provided, the command resolves it against locally tracked
 Tear down a stack so you can restructure it — 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.
 
 ```
-gh stack unstack [branch] [flags]
+gh stack unstack [flags] [branch]
 ```
 
 ```bash