update docs with link cmd details

Author: skarim

README.md

@@ -307,6 +307,42 @@ gh stack submit --auto
 gh stack submit --draft
 ```
 
+### `gh stack link`
+
+Link PRs into a stack on GitHub without local tracking.
+
+```
+gh stack link [flags] <branch-or-pr> <branch-or-pr> [...]
+```
+
+Creates or updates a stack on GitHub from branch names or PR numbers. This command does not store or modify any `gh stack` local tracking state. It is designed for users who manage branches with other tools locally (e.g., jj, Sapling, git-town) and want to simply open a stack of PRs.
+
+Arguments are provided in stack order (bottom to top). Branch arguments are automatically pushed to the remote before creating or looking up PRs. For branches that already have open PRs, those PRs are used. For branches without PRs, new PRs are created automatically with the correct base branch chaining. Existing PRs whose base branch doesn't match the expected chain are corrected automatically.
+
+If the PRs are not yet in a stack, a new stack is created. If some of the PRs are already in a stack, the existing stack is updated to include the new PRs. Existing PRs are never removed from a stack — the update is additive only.
+
+| Flag | Description |
+|------|-------------|
+| `--base <branch>` | Base branch for the bottom of the stack (default: `main`) |
+| `--draft` | Create new PRs as drafts |
+| `--remote <name>` | Remote to push to (defaults to auto-detected remote) |
+
+**Examples:**
+
+```sh
+# Link branches into a stack (pushes branches, creates PRs, creates stack)
+gh stack link feature-auth feature-api feature-ui
+
+# Link existing PRs by number
+gh stack link 10 20 30
+
+# Add branches to an existing stack of PRs
+gh stack link 42 43 feature-auth feature-ui
+
+# Use a different base branch and create PRs as drafts
+gh stack link --base develop --draft feat-a feat-b feat-c
+```
+
 ### `gh stack view`
 
 View the current stack.

cmd/link.go

@@ -26,10 +26,10 @@ func LinkCmd(cfg *config.Config) *cobra.Command {
 		Short: "Link PRs into a stack on GitHub without local tracking",
 		Long: `Create or update a stack on GitHub from branch names or PR numbers.
 
-This command works entirely via the GitHub API and does not modify
-any local state. It is designed for users who manage branches with
-external tools (e.g. jj) and want to use GitHub stacked PRs without
-adopting local stack tracking.
+This command does not rely on gh-stack local tracking state. It is
+designed for users who manage branches with external tools (e.g. jj)
+and want to use GitHub stacked PRs without adopting local stack
+tracking.
 
 Arguments are provided in stack order (bottom to top). Each argument
 can be a branch name or a PR number. For numeric arguments, the

docs/src/content/docs/faq.md

@@ -188,11 +188,12 @@ No. Stacked PRs are built on standard git branches and regular pull requests. Yo
 
 ### Will this work with a different tool for stacking?
 
-Yes, you can continue to use your tool of choice (e.g., jj, Sapling, ghstack, git-town, etc.) to manage stacks locally and push up your branches to GitHub.
+Yes, you can continue to use your tool of choice (e.g., jj, Sapling, git-town, etc.) to manage stacks locally and push up your branches to GitHub.
 
 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 open your PRs as a stack:
+You can also use the `gh stack link` command in conjunction with other tools to open your PRs as a stack:
+
 
 ```bash
 # Create a stack of branches locally using jj
@@ -208,7 +209,30 @@ jj new -m "third change"
 jj bookmark create change3 --revision @
 # ...
 
-# Use gh stack to submit a stack of PRs
+# Push branches and link them as a stack on GitHub
+# (creates PRs automatically if they don't exist)
+gh stack link change1 change2 change3
+```
+
+This doesn't create any local tracking and only hits the APIs to create Stacked PRs.
+
+If the provided branches already have open PRs, `link` will use them. If not, it creates PRs with the correct base branch chaining.
+
+To add more to the stack, run `link` again, but be sure to include the full list of PRs/branches in the stack:
+
+```bash
+gh stack link 123 124 125 change4 change5
+```
+
+You can also use `--base` to specify a different trunk branch and `--draft` to create PRs as drafts:
+
+```bash
+gh stack link --base develop --draft change1 change2 change3
+```
+
+Alternatively, if you want full local stack tracking (for commands like `rebase`, `sync`, and navigation), you can adopt existing branches to local tracking with `gh stack`:
+
+```bash
 gh stack init --adopt change1 change2 change3
 gh stack submit
 ```

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

@@ -312,6 +312,42 @@ gh stack unstack --local
 gh stack unstack feature-auth
 ```
 
+### `gh stack link`
+
+Link PRs into a stack on GitHub without local tracking.
+
+```sh
+gh stack link [flags] <branch-or-pr> <branch-or-pr> [...]
+```
+
+Creates or updates a stack on GitHub from branch names or PR numbers. This command does not create or modify any `gh-stack` local tracking state. It is designed for users who manage branches with other tools locally (e.g., jj, Sapling, git-town) and want to simply open a stack of PRs.
+
+Arguments are provided in stack order (bottom to top). Branch arguments are automatically pushed to the remote before creating or looking up PRs. For branches that already have open PRs, those PRs are used. For branches without PRs, new PRs are created automatically with the correct base branch chaining. Existing PRs whose base branch doesn't match the expected chain are corrected automatically.
+
+If the PRs are not yet in a stack, a new stack is created. If some of the PRs are already in a stack, the existing stack is updated to include the new PRs. Existing PRs are never removed from a stack — the update is additive only.
+
+| Flag | Description |
+|------|-------------|
+| `--base <branch>` | Base branch for the bottom of the stack (default: `main`) |
+| `--draft` | Create new PRs as drafts |
+| `--remote <name>` | Remote to push to (defaults to auto-detected remote) |
+
+**Examples:**
+
+```sh
+# Link branches into a stack (pushes, creates PRs, creates stack)
+gh stack link feature-auth feature-api feature-ui
+
+# Link existing PRs by number
+gh stack link 10 20 30
+
+# Add branches to an existing stack of PRs
+gh stack link 42 43 feature-auth feature-ui
+
+# Use a different base branch and create PRs as drafts
+gh stack link --base develop --draft feat-a feat-b feat-c
+```
+
 ---
 
 ## Navigation

skills/gh-stack/SKILL.md

@@ -56,11 +56,12 @@ git config remote.pushDefault origin     # if multiple remotes exist (skips remo
 2. **When a prefix is set, pass only the suffix to `add`.** `gh stack add auth` with prefix `feat` → `feat/auth`. Passing `feat/auth` creates `feat/feat/auth`.
 3. **Always use `--auto` with `gh stack submit`** to auto-generate PR titles. Without `--auto`, `submit` prompts for a title for each new PR.
 4. **Always use `--json` with `gh stack view`.** Without `--json`, the command launches an interactive TUI that cannot be operated by agents. There is no other appropriate flag — always pass `--json`.
-5. **Use `--remote <name>` when multiple remotes are configured**, or pre-configure `git config remote.pushDefault origin`. Without this, `push`, `submit`, `sync`, and `checkout` trigger an interactive remote picker.
+5. **Use `--remote <name>` when multiple remotes are configured**, or pre-configure `git config remote.pushDefault origin`. Without this, `push`, `submit`, `sync`, `link`, and `checkout` trigger an interactive remote picker.
 6. **Avoid branches shared across multiple stacks.** If a branch belongs to multiple stacks, commands exit with code 6. Check out a non-shared branch first.
 7. **Plan your stack layers by dependency order before writing code.** Foundational changes (models, APIs, shared utilities) go in lower branches; dependent changes (UI, consumers) go in higher branches. Think through the dependency chain before running `gh stack init`.
 8. **Use standard `git add` and `git commit` for staging and committing.** This gives you full control over which changes go into each branch. The `-Am` shortcut is available but should not be the default approach—stacked PRs are most effective when each branch contains a deliberate, logical set of changes.
 9. **Navigate down the stack when you need to change a lower layer.** If you're working on a frontend branch and realize you need API changes, don't hack around it at the current layer. Navigate to the appropriate branch (`gh stack down`, `gh stack checkout`, or `gh stack bottom`), make and commit the changes there, run `gh stack rebase --upstack`, then navigate back up to continue.
+10. **Use `gh stack link` for external tool workflows.** When branches are managed by an external tool (jj, Sapling, etc.), use `gh stack link branch-a branch-b`. `link` does not rely on local tracking state and is intended for API-driven PR and stack management. Always provide at least 2 branch names or PR numbers.
 
 **Never do any of the following — each triggers an interactive prompt or TUI that will hang:**
 - ❌ `gh stack view` or `gh stack view --short` — always use `gh stack view --json`
@@ -555,6 +556,54 @@ gh stack submit --auto --draft
 
 ---
 
+### Link branches as a stack (no local tracking) — `gh stack link`
+
+Link PRs into a stack on GitHub without creating any local tracking state. This is the recommended approach if you are managing stacked branches with other tools (jj, Sapling, git-town) and want to simply create GitHub Stacked PRs via an API.
+
+```
+gh stack link [flags] <branch-or-pr> <branch-or-pr> [...]
+```
+
+```bash
+# Link branches into a stack (pushes, creates PRs, creates stack)
+gh stack link branch-a branch-b branch-c
+
+# Use a different base branch and create PRs as drafts
+gh stack link --base develop --draft branch-a branch-b branch-c
+
+# Link existing PRs by number
+gh stack link 10 20 30
+
+# Add branches to an existing stack of PRs
+gh stack link 42 43 feature-auth feature-ui
+```
+
+| Flag | Description |
+|------|---------|
+| `--base <branch>` | Base branch for the bottom of the stack (default: `main`) |
+| `--draft` | Create new PRs as drafts |
+| `--remote <name>` | Remote to push to (use if multiple remotes exist) |
+
+**Behavior:**
+
+- Arguments are provided in stack order (bottom to top)
+- Each argument can be a branch name or a PR number. Numeric arguments are tried as PR numbers first; if no PR with that number exists, the argument is treated as a branch name
+- Branch arguments are pushed to the remote automatically (non-force, atomic)
+- For branches without open PRs, new PRs are created with auto-generated titles and the correct base branch chaining (first branch uses `--base`, subsequent branches use the previous branch)
+- Existing PRs whose base branch doesn't match the expected chain are corrected automatically
+- If the PRs are not yet in a stack, a new stack is created. If some PRs are already in a stack, the stack is updated (additive only — existing PRs are never removed)
+- Does **not** create or modify any local state
+
+**Output (stderr):**
+
+- `Pushing N branches to <remote>...`
+- `Found PR #N for branch <name>` for branches with existing PRs
+- `Created PR #N for <branch> (base: <base>)` for newly created PRs
+- `Updated base branch for PR #N to <base>` when base branches are corrected
+- `Created stack with N PRs` or `Updated stack to N PRs`
+
+---
+
 ### Sync the stack — `gh stack sync`
 
 Fetch, rebase, push, and sync PR state in a single command. This is the recommended command for routine synchronization.