update unstack docs

Author: skarim

README.md

@@ -477,26 +477,33 @@ gh stack view --json
 
 ### `gh stack unstack`
 
-Remove a stack from local tracking and delete it on GitHub. Also available as `gh stack delete`.
+Remove a stack from local tracking and unstack it on GitHub. Also available as `gh stack delete`.
 
 ```
-gh stack unstack [flags]
+gh stack unstack [<stack-number>] [flags]
 ```
 
-You must have an active stack checked out locally. The command targets the active stack — the one that contains the currently checked out branch.
+With no argument, the command targets the active stack — the one that contains the currently checked out branch — unstacking it on GitHub and removing local tracking.
 
-Deletes the stack on GitHub first, if it exists, then removes local tracking. Use `--local` to only remove from local tracking.
+Provide a stack number (the identifier shown in the github.com stack UI) to unstack a specific stack on GitHub. This works from anywhere in the repository, whether or not the stack is checked out locally — the number is unstacked directly through the GitHub API. If the stack is also tracked locally, its local tracking is removed as well.
+
+Use `--local` to only remove local tracking without contacting GitHub.
+
+GitHub decides which pull requests can be unstacked: PRs that are queued for merge or have auto-merge enabled are left stacked. When some pull requests remain stacked, the stack is kept (and local tracking, if any, is unchanged).
 
 | Flag | Description |
 |------|-------------|
-| `--local` | Only delete the stack locally (keep it on GitHub) |
+| `--local` | Only remove the stack locally (keep it on GitHub) |
 
 **Examples:**
 
 ```sh
-# Remove the stack from local tracking and GitHub
+# Remove the current stack from local tracking and GitHub
 gh stack unstack
 
+# Unstack a specific stack by its number
+gh stack unstack 7
+
 # Only remove local tracking
 gh stack unstack --local
 ```

docs/src/content/docs/faq.md

@@ -50,7 +50,7 @@ gh stack init db-migrations api-routes frontend
 
 ### How do I delete my stack?
 
-**From the CLI** — Run `gh stack unstack` (or `gh stack delete`) to delete the stack on GitHub and remove local tracking. Use `--local` to only remove local tracking.
+**From the CLI** — Run `gh stack unstack` (or `gh stack delete`) to delete the stack on GitHub and remove local tracking. You can also unstack any stack by its number from anywhere in the repository — `gh stack unstack 7` — whether or not it's checked out locally. Use `--local` to only remove local tracking.
 
 **From the UI** — You can unstack PRs from the GitHub UI — see [Unstacking](/gh-stack/guides/ui/#unstacking) for a walkthrough. This dissolves the association between PRs, turning them back into standard independent PRs.
 

docs/src/content/docs/reference/cli.md

@@ -240,9 +240,11 @@ Remove a stack from local tracking and unstack it on GitHub. Also available as `
 gh stack unstack [<stack-number>] [flags]
 ```
 
-With no argument, the command targets the active stack — the one that contains the currently checked out branch. Provide a stack number (the identifier shown in the github.com stack UI) to target a specific locally tracked stack instead.
+With no argument, the command targets the active stack — the one that contains the currently checked out branch — unstacking it on GitHub and removing local tracking.
 
-PRs that are merged, merging, or queued for merge cannot be removed from a stack on GitHub and are left part of the stack. When every pull request is removed, the stack is dissolved and local tracking is removed; when some pull requests remain stacked, local tracking is kept. Use `--local` to skip the remote operation and only remove local tracking.
+Provide a stack number (the identifier shown in the github.com stack UI) to unstack a specific stack on GitHub. This works from anywhere in the repository, whether or not the stack is checked out locally — the stack is unstacked directly through the GitHub API. When the stack is also available locally, its local tracking is removed as well.
+
+PRs that are merged, merging, or queued for merge cannot be removed from a stack on GitHub and are left part of the stack. When every pull request is removed, the stack is dissolved and any local tracking is removed; when some pull requests remain stacked, the stack is kept and local tracking, if any, is unchanged. Use `--local` to skip the remote operation and only remove local tracking.
 
 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.
 
@@ -256,7 +258,7 @@ This is useful when you need to restructure a stack — remove a branch, insert
 # Unstack the current stack on GitHub and remove local tracking
 gh stack unstack
 
-# Unstack a specific stack by its stack number
+# Unstack a specific stack by its numbe
 gh stack unstack 7
 
 # Only remove local tracking

skills/gh-stack/SKILL.md

@@ -815,24 +815,31 @@ 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.
 
-You must have a branch from the stack checked out locally. The command targets the active stack — the one that contains the currently checked out branch.
+With no argument, the command targets the active stack — the one containing the currently checked out branch — unstacking it on GitHub and removing local tracking.
+
+Provide a stack number to unstack a specific stack on GitHub. This works from anywhere in the repository, whether or not the stack is checked out locally — the number is unstacked directly through the GitHub API (like `gh stack link`, no local tracking required). If the stack is also tracked locally, its local tracking is removed as well.
 
 ```
-gh stack unstack [flags]
+gh stack unstack [<stack-number>] [flags]
 ```
 
 ```bash
-# Tear down the stack (locally and on GitHub), then rebuild
+# Tear down the current stack (locally and on GitHub), then rebuild
 gh stack unstack
 gh stack init --base main branch-2 branch-1 branch-3 # reordered
 
+# Unstack a specific stack by its number, from anywhere in the repo
+gh stack unstack 7
+
 # Only remove local tracking (keep the stack on GitHub)
 gh stack unstack --local
 ```
 
 | Flag | Description |
 |------|-------------|
-| `--local` | Only delete the stack locally (keep it on GitHub) |
+| `--local` | Only remove the stack locally (keep it on GitHub); never contacts GitHub |
+
+> **Note for agents:** `gh stack unstack <number>` is a remote-first API wrapper — it unstacks on GitHub by number from anywhere in the repo, tracked locally or not, and is safe for non-interactive use. `--local` never contacts GitHub; combining `--local` with a number that isn't tracked locally is an error. An unknown stack number returns a "not found on GitHub" error (exit code 2).
 
 ---