@@ -17,7 +17,7 @@ No Makefile, no code generation, no external linter config. Standard Go toolchai
 
 - `cmd/`: One Cobra command per file. Each exports `<Name>Cmd(cfg *config.Config)` with logic in `run<Name>()`.
 - `internal/git/`: `Ops` interface (52 methods) wrapping git CLI. `MockOps` for tests. Package-level functions delegate to swappable `ops` variable.
-- `internal/github/`: `ClientOps` interface (11 methods) for GitHub API. `MockClient` for tests.
+- `internal/github/`: `ClientOps` interface (13 methods) for GitHub API. `MockClient` for tests. Stack operations use the public Stacks REST API (`/repos/{owner}/{repo}/stacks`).
 - `internal/config/`: `Config` struct passed to all commands. Holds I/O, colors, and test hooks (`SelectFn`, `ConfirmFn`, `InputFn`, `GitHubClientOverride`).
 - `internal/stack/`: Stack file (`.git/gh-stack`, JSON) management with file locking.
 - `internal/tui/`: bubbletea views (`stackview`, `modifyview`).
 
@@ -35,7 +35,7 @@ internal/
     gitops.go                # Ops interface (52 methods)
     mock_ops.go              # MockOps. Each method has a corresponding *Fn field.
   github/                    # github.ClientOps interface + real Client
-    client_interface.go      # ClientOps interface (11 methods)
+    client_interface.go      # ClientOps interface (13 methods)
     mock_client.go           # MockClient. Uses function-pointer fields for testing.
   stack/                     # stack file (.git/gh-stack) management, JSON schema, locking
     schema.json              # JSON Schema for the stack file format
@@ -109,13 +109,14 @@ if errors.As(err, &exitErr) { ... }
 ### Key interfaces
 
 - **`git.Ops`** (`internal/git/gitops.go`): 52 methods wrapping git CLI calls. The production implementation uses `cli/go-gh`'s `client.Command()` via `run()` and `runSilent()` helpers. Package-level functions (e.g., `git.CurrentBranch()`) delegate to a swappable package-level `ops` variable.
-- **`github.ClientOps`** (`internal/github/client_interface.go`): 11 methods for GitHub API (PRs, stacks). Injected via `cfg.GitHubClientOverride` in tests.
-- **`config.Config`** (`internal/config/config.go`): Central configuration passed to all commands. Holds I/O streams, color functions, and test hook fields (`SelectFn`, `ConfirmFn`, `InputFn`, `TokenForHostFn`, `RepoOverride`).
+- **`github.ClientOps`** (`internal/github/client_interface.go`): 13 methods for GitHub API (PRs, stacks). Stack operations use the public Stacks REST API (`/repos/{owner}/{repo}/stacks`): `ListStacks`, `FindStackForPR`, `GetStack`, `CreateStack`, `AddToStack` (delta append), `Unstack`. Injected via `cfg.GitHubClientOverride` in tests.
+- **`config.Config`** (`internal/config/config.go`): Central configuration passed to all commands. Holds I/O streams, color functions, and test hook fields (`SelectFn`, `ConfirmFn`, `InputFn`, `RepoOverride`).
 
 ### Stack file
 
 - **Location:** `.git/gh-stack` (JSON format, schema version 1).
 - **Schema:** `internal/stack/schema.json`.
+- **Identity:** each stack stores GitHub's global `id` (string) and repo-scoped `number` (int, shown in the GitHub UI and used as the primary way to reference a stack, e.g. `gh stack checkout <number>`). `number` may be `0` for stack files created before it was tracked; it is backfilled from the API on the next stack operation.
 - **Locking:** Exclusive file lock at `.git/gh-stack.lock` with 5-second timeout. Errors surface as `LockError`.
 - **Staleness:** Concurrent modifications detected via `StaleError`.
 
 
@@ -19,10 +19,6 @@ Stacked PRs is currently in private preview. This feature will **not work** unle
 gh extension install github/gh-stack
 ```
 
-:::note[Authentication]
-The `gh stack` CLI requires OAuth authentication via `gh auth login`. Personal access tokens (PATs) are not supported.
-:::
-
 ## Set Up AI Agent Integration
 
 If you use AI coding agents (like GitHub Copilot), install the gh-stack skill so they know how to work with Stacked PRs:
 
@@ -12,7 +12,7 @@ gh extension install github/gh-stack
 Requires the [GitHub CLI](https://cli.github.com/) (`gh`) v2.0+.
 
 :::note[Authentication]
-The `gh stack` CLI requires OAuth authentication via `gh auth login`. Personal access tokens (PATs) are not supported.
+The `gh stack` CLI uses your GitHub CLI authentication — run `gh auth login` if you haven't already.
 :::
 
 ---
@@ -135,13 +135,15 @@ gh stack view --json
 
 ### `gh stack checkout`
 
-Check out a stack from a pull request number, URL, or branch name.
+Check out a stack by its stack number, a pull request number, a PR URL, or a branch name.
 
 ```sh
-gh stack checkout [<pr-number> | <pr-url> | <branch>]
+gh stack checkout [<stack-number> | <pr-number> | <pr-url> | <branch>]
 ```
 
-When a PR number or URL is provided (e.g., `123` or `https://github.com/owner/repo/pull/123`), the command fetches the stack on GitHub, pulls the branches, and sets up the stack locally. If the stack already exists locally and matches, it switches to the branch. If the local and remote stacks have different compositions, you'll be prompted to resolve the conflict.
+A bare number is interpreted first as a stack or PR number (repo-scoped identifiers shown in the GitHub UI). If nothing matches the number, it is tried as a branch name.
+
+When a remote stack is referenced, the command fetches the stack on GitHub, pulls the branches, and sets up the stack locally. If the stack already exists locally and matches, it switches to the branch. If the local and remote stacks have different compositions, you'll be prompted to resolve the conflict.
 
 When a branch name is provided, the command resolves it against locally tracked stacks only.
 
@@ -150,6 +152,9 @@ When run without arguments in an interactive terminal, shows a menu of all local
 **Examples:**
 
 ```sh
+# Check out a stack by its stack number
+gh stack checkout 7
+
 # Check out a stack by PR number
 gh stack checkout 42
 
@@ -229,28 +234,31 @@ gh stack modify --abort
 
 ### `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`.
 
 ```sh
-gh stack unstack [flags]
+gh stack unstack [<stack-number>] [flags]
 ```
 
-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 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.
 
-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.
+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.
 
 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 |
 |------|-------------|
-| `--local` | Only delete the stack locally (keep it on GitHub) |
+| `--local` | Only remove the stack locally (keep it on GitHub) |
 
 **Examples:**
 
 ```sh
-# Delete the stack on GitHub and remove local tracking
+# Unstack the current stack on GitHub and remove local tracking
 gh stack unstack
 
+# Unstack a specific stack by its stack number
+gh stack unstack 7
+
 # Only remove local tracking
 gh stack unstack --local
 ```
@@ -317,7 +325,7 @@ Performs a synchronization of the entire stack:
 
 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
+**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:
 
 
@@ -161,9 +161,11 @@ Small, incidental fixes (e.g., fixing a typo you noticed) can go in the current
 | View stack details (JSON) | `gh stack view --json` |
 | Switch branches up/down in stack | `gh stack up [n]` / `gh stack down [n]` |
 | Switch to top/bottom branch | `gh stack top` / `gh stack bottom` |
+| Check out by stack number | `gh stack checkout 7` |
 | Check out by PR | `gh stack checkout 42` |
 | Check out by branch (local only) | `gh stack checkout feature-auth` |
-| Tear down a stack to restructure it | `gh stack unstack` |
+| Tear down the current stack to restructure it | `gh stack unstack` |
+| Tear down a specific stack by number | `gh stack unstack 7` |
 
 ---