docs on rebase stack button behavior

Author: skarim

docs/src/content/docs/faq.md

@@ -113,7 +113,7 @@ Yes. There must be a **fully linear history** between each of the branches in th
 If the stack is not linear (e.g., after changes were pushed to a lower branch), you can fix it in two ways:
 
 - **From the CLI** — Run `gh stack rebase` to perform a cascading rebase locally and then push with `gh stack push`.
-- **From the UI** — Click the **Rebase Stack** button in the merge box to trigger a cascading rebase across all branches in the stack.
+- **From the UI** — Click the **Rebase Stack** button in the merge box to trigger a server-side cascading rebase. This rebases the entire stack on top of the latest trunk, updates every unmerged branch on top of its base branch, and force-pushes the results. See [Rebasing from the UI](/gh-stack/guides/ui/#rebasing-from-the-ui) for details.
 
 ## Merging Stacked PRs
 

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

@@ -77,6 +77,20 @@ Before a PR in the stack can be merged, the following conditions must be met:
 
 ![Merge box for a stacked pull request](../../../assets/screenshots/stack-merge-box.png)
 
+## Rebasing from the UI
+
+When the stack is not linear (e.g., after changes were pushed to a lower branch, or after `main` has moved ahead), a **Rebase Stack** button appears in the merge box. Clicking it triggers a server-side cascading rebase that:
+
+1. Rebases the entire stack on top of the latest trunk (e.g., `main`) HEAD.
+2. Rebases every unmerged branch on top of the latest changes from its base branch, working from the bottom of the stack upward.
+3. Force-pushes each rebased branch to update the remote.
+
+After the rebase completes, all PRs in the stack reflect the updated branches and CI checks are re-triggered.
+
+:::note[Commit signing]
+Commits created by a server-side rebase are **not signed**. If your repository requires signed commits, we recommend using the CLI. Running `gh stack rebase` uses local git operations, so the generated commits will follow your local git signing configuration. After rebasing locally, you can force push your updated branches with `gh stack push`.
+:::
+
 ## 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.

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

@@ -74,7 +74,7 @@ Stacks support all three merge methods:
 
 Rebasing is the trickiest part of working with Stacked PRs, and GitHub handles it automatically:
 
-- **In the PR UI** — A rebase button lets you trigger a cascading rebase across all branches in the stack.
+- **In the PR UI** — A **Rebase Stack** button lets you trigger a server-side cascading rebase. It rebases the entire stack on top of the latest trunk, updates every unmerged branch, and force-pushes the results. See [Rebasing from the UI](/gh-stack/guides/ui/#rebasing-from-the-ui) for details.
 - **From the CLI** — `gh stack rebase` performs the same cascading rebase locally.
 - **After partial merges** — When you merge a PR at the bottom of the stack, the remaining branches are automatically rebased so the next PR targets `main` and is ready for review and merge.
 - **Safe squash-merge handling** — Squash merges are fully supported. The rebase engine safely replays your unique commits on top of the squashed base, avoiding artificial merge conflicts. See the [FAQ](/gh-stack/faq/#how-does-squash-merge-work) for a detailed description of how this works.