docs updates

Author: skarim

README.md

@@ -316,15 +316,28 @@ Fetch, rebase, push, and sync PR state in a single command.
 gh stack sync [flags]
 ```
 
-Performs a safe, non-interactive synchronization of the entire stack:
+Performs a synchronization of the entire stack:
 
-1. **Fetch** — fetches the latest changes from `origin`
-2. **Fast-forward trunk** — fast-forwards the trunk branch to match the remote (skips if diverged)
-3. **Cascade rebase** — rebases all stack branches onto their updated parents (only if trunk moved). If a conflict is detected, all branches are restored to their original state and you are advised to run `gh stack rebase` to resolve conflicts interactively
-4. **Push** — pushes all branches (uses `--force-with-lease` if a rebase occurred)
-5. **Sync PRs** — syncs PR state from GitHub and reports the status of each PR
-6. **Sync the stack** — links the stack's open PRs into a stack on GitHub, creating the remote stack object if it doesn't exist yet or updating it if it's partially formed. Only happens when two or more PRs exist; sync never opens PRs (use `gh stack submit` for that)
-7. **Prune** — in interactive terminals, prompts to delete local branches for merged PRs. Use `--prune` to prune automatically
+1. **Fetch** — fetches the latest changes from `origin`.
+2. **Reconcile the remote stack** — mirrors the GitHub stack locally. When PRs have been added to the stack on GitHub (the remote is ahead of your local stack), their branches are pulled down and appended to your local stack automatically. When the local and remote stacks have genuinely diverged (for example, you added a branch locally while different PRs were added to the stack on GitHub), you are prompted to resolve (see [Diverged stacks](#diverged-stacks) below). In a non-interactive terminal a divergence aborts the sync (nothing is pushed or updated).
+3. **Fast-forward trunk** — fast-forwards the trunk branch to match the remote (skips if diverged).
+4. **Cascade rebase** — rebases all stack branches onto their updated parents (only if trunk moved). If a conflict is detected, all branches are restored to their original state, and you are advised to run `gh stack rebase` to resolve conflicts interactively.
+5. **Push** — pushes all branches (uses `--force-with-lease` if a rebase occurred).
+6. **Sync PRs** — syncs PR state from GitHub and reports the status of each PR.
+7. **Sync the stack** — links the stack's open PRs into a stack on GitHub, creating the remote stack object if it doesn't exist yet or updating it if it's partially formed. This only happens when two or more PRs exist; sync never opens PRs (use `gh stack submit` for that).
+8. **Prune** — in interactive terminals, prompts to delete local branches for merged PRs. Use `--prune` to prune automatically.
+
+A clean remote-ahead update (PRs added on top of your local stack) is pulled down automatically without prompting, so `sync` is safe to run in automation. Sync only prompts when the stacks have truly diverged.
+
+#### Diverged stacks
+
+When neither stack is a clean prefix of the other — for example, you added a branch locally while separate PRs were added to the same stack on GitHub — sync cannot merge the two automatically. In an interactive terminal it offers three choices:
+
+- **Use the remote stack as the source of truth** — replaces your local stack composition with the remote's, pulling any missing branches. If you were on a branch that the remote stack no longer contains, you're moved to the nearest surviving branch. Requires a clean working state with no uncommitted changes.
+- **Delete the stack on GitHub** — deletes the stack object on GitHub and stops the sync. Your PRs and local branches are untouched (only the stack on GitHub is removed); recreate the stack with `gh stack submit` (run `gh stack modify` first if you want to change its structure). This is the way to make GitHub match your local stack, because `submit` — unlike `sync` — also creates PRs for any branches you haven't submitted yet.
+- **Cancel** — aborts the sync without pushing branches or updating any PRs.
+
+In a non-interactive terminal, a divergence aborts the sync (exit success) without pushing branches or updating PRs; resolve it by unstacking and recreating the stack.
 
 | Flag | Description |
 |------|-------------|
@@ -377,6 +390,8 @@ If every PR in the stack has already been merged, that stack is complete and can
 
 In an interactive terminal, `submit` opens a full-screen, mouse- and keyboard-driven editor on a single screen. Every branch without a PR is included by default — deselect any you don't want on the left panel (<kbd>Ctrl</kbd>+<kbd>X</kbd>). Because each PR builds on the branch below it, deselecting a branch also deselects the ones stacked above it, and re-including a branch re-includes the ones below it. Draft each PR's title, description (with a markdown preview and `$EDITOR` escape), and choose ready-for-review or draft on the right, then submit them all at once with <kbd>Ctrl</kbd>+<kbd>S</kbd>. Pass `--auto` (or run in CI) to skip the editor and use auto-generated titles.
 
+If the branches already have open PRs but no stack exists on GitHub, you will have the option to link the PRs into a stack with <kbd>Ctrl</kbd>+<kbd>B</kbd>.
+
 In the editor, new PRs default to ready for review; flip any PR to draft with the ready ↔ draft toggle. With `--auto`, new PRs are created as drafts unless you pass `--open`.
 
 | Flag | Description |

docs/package-lock.json

@@ -51,4 +51,4 @@ gh stack sync
 
 - **`gh stack push`** pushes branches only (uses `--force-with-lease` for safety). It does not create or update PRs.
 - **`gh stack submit`** pushes branches and creates or updates PRs, linking them as a Stack on GitHub.
-- **`gh stack sync`** is the all-in-one command: fetch, rebase, push, sync PR state, link open PRs into a Stack on GitHub, and optionally prune local branches for merged PRs.
+- **`gh stack sync`** is the all-in-one command: fetch, rebase, push, sync stack/PR state, link open PRs into a Stack on GitHub, and optionally prune local branches for merged PRs. If there is a divergence between local and remote stacks, you will be prompted to resolve.

docs/src/content/docs/guides/stacked-prs.md

@@ -130,15 +130,28 @@ gh stack sync
 
 This command:
 1. Fetches the latest changes from the remote
-2. Fast-forwards the trunk branch
-3. Rebases all remaining stack branches onto the updated trunk
-4. Pushes the updated branches
-5. Syncs PR state from GitHub
-6. Links the open PRs into a Stack on GitHub (creating or updating the remote stack when two or more PRs exist)
-7. Prompts to prune local branches for merged PRs (use `--prune` to prune automatically)
+2. Reconciles the remote stack with your local stack
+3. Fast-forwards the trunk branch
+4. Rebases all remaining stack branches onto the updated trunk
+5. Pushes the updated branches
+6. Syncs PR state from GitHub
+7. Links the open PRs into a Stack on GitHub (creating or updating the remote stack when two or more PRs exist)
+8. Prompts to prune local branches for merged PRs (use `--prune` to prune automatically)
 
 If a conflict is detected during the rebase, all branches are restored to their original state, and you're advised to run `gh stack rebase` to resolve conflicts interactively.
 
+### Pulling in PRs added to the stack on GitHub
+
+If PRs are added to the stack on GitHub by someone else, `gh stack sync` fetches the new PRs' branches and appends them to your local stack so it mirrors the remote.
+
+If your local and remote stacks have diverged — for example, you added a branch locally while different PRs/branches were added to the same stack on GitHub — sync can't merge them automatically. In an interactive terminal it offers three choices:
+
+- **Use the remote stack as the source of truth** — replaces your local stack composition with the remote's, pulling any missing branches. If you were on a branch that the remote stack no longer contains, you're moved to the nearest surviving branch. Requires a clean working state with no uncommitted changes.
+- **Delete the stack on GitHub** — deletes the stack object on GitHub and stops the sync. Your PRs and local branches are untouched (only the stack on GitHub is removed); recreate the stack with `gh stack submit` (run `gh stack modify` first if you want to change its structure). This is the way to make GitHub match your local stack, because `submit` — unlike `sync` — also creates PRs for any branches you haven't submitted yet.
+- **Cancel** — aborts the sync without pushing branches or updating any PRs.
+
+In a non-interactive terminal, a divergence aborts the sync (exit success) without pushing branches or updating PRs; resolve it by unstacking and recreating the stack.
+
 ## Rebasing Your Stack
 
 Stacked PRs rely on rebasing rather than merge commits to keep each branch's diff clean and reviewable. If you're coming from a merge-commit workflow, the key difference is: instead of merging upstream changes into your branch (which creates a merge commit with multiple parents), you replay your commits on top of the latest base. The result is a linear history where each PR shows only its specific changes.

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

@@ -88,7 +88,7 @@ While the PR UI provides the review and merge experience, the `gh stack` CLI han
 - **Pushing branches** — `gh stack push` pushes all branches to the remote.
 - **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, updates PR state, and links open PRs into a Stack on GitHub in one command.
+- **Syncing everything** — `gh stack sync` fetches, rebases, pushes, updates PR state, and links open PRs into a Stack on GitHub in one command. It also syncs the stack's remote state, pulling down branches for any PRs added to the stack on GitHub.
 - **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|url>` pulls down a stack, with all its branches, from GitHub to your local machine.

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

@@ -278,6 +278,8 @@ In an interactive terminal, `submit` opens a full-screen editor on a single scre
 
 Press <kbd>Ctrl</kbd>+<kbd>S</kbd> to submit all included PRs at once. The editor supports both keyboard and mouse input. Pass `--auto` (or run in a non-interactive terminal, such as CI) to skip the editor and use auto-generated titles.
 
+If the branches already have open PRs but no stack exists on GitHub, you will have the option to link the PRs into a stack with <kbd>Ctrl</kbd>+<kbd>B</kbd>.
+
 In the editor, new PRs default to **ready for review**; flip any PR to **draft** with the ready ↔ draft toggle. With `--auto`, new PRs are created as **drafts** unless you pass `--open`.
 
 | Flag | Description |
@@ -302,15 +304,28 @@ Fetch, rebase, push, and sync PR state in a single command.
 gh stack sync [flags]
 ```
 
-Performs a safe, non-interactive synchronization of the entire stack:
+Performs a synchronization of the entire stack:
 
 1. **Fetch** — fetches the latest changes from `origin`.
-2. **Fast-forward trunk** — fast-forwards the trunk branch to match the remote (skips if diverged).
-3. **Cascade rebase** — rebases all stack branches onto their updated parents (only if trunk moved). If a conflict is detected, all branches are restored to their original state, and you are advised to run `gh stack rebase` to resolve conflicts interactively.
-4. **Push** — pushes all branches (uses `--force-with-lease` if a rebase occurred).
-5. **Sync PRs** — syncs PR state from GitHub and reports the status of each PR.
-6. **Sync the stack** — links the stack's open PRs into a stack on GitHub, creating the remote stack object if it doesn't exist yet or updating it if it's partially formed. This only happens when two or more PRs exist; sync never opens PRs (use `gh stack submit` for that).
-7. **Prune** — in interactive terminals, prompts to delete local branches for merged PRs. Use `--prune` to prune automatically.
+2. **Reconcile the remote stack** — mirrors the GitHub stack locally. When PRs have been added to the stack on GitHub (the remote is ahead of your local stack), their branches are pulled down and appended to your local stack automatically. When the local and remote stacks have genuinely diverged (for example, you added a branch locally while different PRs were added to the stack on GitHub), you are prompted to resolve (see [Diverged stacks](#diverged-stacks) below). In a non-interactive terminal a divergence aborts the sync (nothing is pushed or updated).
+3. **Fast-forward trunk** — fast-forwards the trunk branch to match the remote (skips if diverged).
+4. **Cascade rebase** — rebases all stack branches onto their updated parents (only if trunk moved). If a conflict is detected, all branches are restored to their original state, and you are advised to run `gh stack rebase` to resolve conflicts interactively.
+5. **Push** — pushes all branches (uses `--force-with-lease` if a rebase occurred).
+6. **Sync PRs** — syncs PR state from GitHub and reports the status of each PR.
+7. **Sync the stack** — links the stack's open PRs into a stack on GitHub, creating the remote stack object if it doesn't exist yet or updating it if it's partially formed. This only happens when two or more PRs exist; sync never opens PRs (use `gh stack submit` for that).
+8. **Prune** — in interactive terminals, prompts to delete local branches for merged PRs. Use `--prune` to prune automatically.
+
+A clean remote-ahead update (PRs added on top of your local stack) is pulled down automatically without prompting, so `sync` is safe to run in automation. Sync only prompts when the stacks have truly diverged.
+
+#### Diverged stacks
+
+When neither stack is a clean prefix of the other — for example, you added a branch locally while separate PRs were added to the same stack on GitHub — sync cannot merge the two automatically. In an interactive terminal it offers three choices:
+
+- **Use the remote stack as the source of truth** — replaces your local stack composition with the remote's, pulling any missing branches. If you were on a branch that the remote stack no longer contains, you're moved to the nearest surviving branch. Requires a clean working state with no uncommitted changes.
+- **Delete the stack on GitHub** — deletes the stack object on GitHub and stops the sync. Your PRs and local branches are untouched (only the stack on GitHub is removed); recreate the stack with `gh stack submit` (run `gh stack modify` first if you want to change its structure). This is the way to make GitHub match your local stack, because `submit` — unlike `sync` — also creates PRs for any branches you haven't submitted yet.
+- **Cancel** — aborts the sync without pushing branches or updating any PRs.
+
+In a non-interactive terminal, a divergence aborts the sync (exit success) without pushing branches or updating PRs; resolve it by unstacking and recreating the stack.
 
 | Flag | Description |
 |------|-------------|