update docs

Author: skarim

README.md

@@ -76,7 +76,9 @@ Initialize a new stack in the current repository.
 gh stack init [flags] [branches...]
 ```
 
-Creates an entry in `.git/gh-stack` to track stack state. In interactive mode (no arguments), prompts you to name branches and offers to use the current branch as the first layer. In interactive mode, you'll also be prompted to set an optional branch prefix (unless adopting existing branches). When a prefix is set, branch names you enter are automatically prefixed. When explicit branch names are given, creates any that don't already exist (branching from the trunk). The trunk defaults to the repository's default branch unless overridden with `--base`.
+Initializes a new stack locally. In interactive mode (no arguments), prompts for a branch name and offers to use the current branch as the first layer. If a branch name contains slashes (e.g., `feat/api`), prompts if you would like to use a prefix (e.g., `feat/`) for all branches in the stack.
+
+When explicit branch names are given, existing branches are adopted automatically and any missing branches are created. The trunk defaults to the repository's default branch unless overridden with `--base`.
 
 Use `--numbered` with `--prefix` to enable auto-incrementing numbered branch names (`prefix/01`, `prefix/02`, …). Without `--numbered`, you'll always be prompted to provide a meaningful branch name.
 
@@ -85,7 +87,6 @@ Enables `git rerere` automatically so that conflict resolutions are remembered a
 | Flag | Description |
 |------|-------------|
 | `-b, --base <branch>` | Trunk branch for the stack (defaults to the repository's default branch) |
-| `-a, --adopt` | Adopt existing branches into a stack instead of creating new ones |
 | `-p, --prefix <string>` | Set a branch name prefix for the stack |
 | `-n, --numbered` | Use auto-incrementing numbered branch names (requires `--prefix`) |
 
@@ -102,7 +103,7 @@ gh stack init feature-auth feature-api feature-ui
 gh stack init --base develop feature-auth
 
 # Adopt existing branches into a stack
-gh stack init --adopt feature-auth feature-api
+gh stack init feature-auth feature-api
 
 # Set a prefix — you'll be prompted for a branch name
 gh stack init -p feat

docs/src/content/docs/faq.md

@@ -35,17 +35,17 @@ You can also add PRs to an existing stack from the GitHub UI. See [Adding to an
 
 Use `gh stack modify` to restructure a stack. It opens an interactive terminal UI where you can reorder, drop, fold (combine), and rename branches — then applies all changes at once. See the [Restructuring Stacks](/gh-stack/guides/modify/) guide for a full walkthrough.
 
-Alternatively, you can manually tear down and re-create the stack with `gh stack unstack` and `gh stack init --adopt`:
+Alternatively, you can manually tear down and re-create the stack with `gh stack unstack` and `gh stack init`:
 
 ```sh
 # 1. Remove the stack
 gh stack unstack
 
 # 2. Make structural changes (reorder, rename, delete branches)
-git branch -m old-name new-name
+git branch -m api-roots api-routes
 
 # 3. Re-create the stack with the new structure
-gh stack init --adopt branch-1 branch-2 branch-3
+gh stack init db-migrations api-routes frontend
 ```
 
 ### How do I delete my stack?
@@ -263,9 +263,9 @@ You can also use `--base` to specify a different trunk branch and `--open` to ma
 gh stack link --base develop --open 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`:
+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 init`:
 
 ```bash
-gh stack init --adopt change1 change2 change3
+gh stack init change1 change2 change3
 gh stack submit
 ```

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

@@ -137,6 +137,34 @@ This command:
 
 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.
 
+## Existing Branches into a Stack
+
+If you already have a set of branches that form a logical chain, you can organize them into a stack by passing them to `gh stack init`. Existing branches are adopted automatically — no special flags needed.
+
+```sh
+# Adopt three existing branches into a stack (bottom to top)
+gh stack init feat/auth feat/api feat/ui
+```
+
+The order matters: branches are listed from bottom (closest to trunk) to top (furthest from trunk). Any PRs already open for these branches are detected and linked to the stack.
+
+You can also mix existing and new branches in one command:
+
+```sh
+# feat/auth exists, feat/api-v2 will be created
+gh stack init feat/auth feat/api-v2
+```
+
+After organizing branches into a stack, run `gh stack submit` to create a Stack on GitHub and link the PRs together.
+
+```sh
+# View the new stack
+gh stack view
+
+# Create/update PRs and link them as a Stack on GitHub
+gh stack submit
+```
+
 ## Structuring Your Stack
 
 Think of a stack from the reviewer's perspective: the PRs should tell a **cohesive story**. A reviewer reading the PRs in sequence should understand the progression of changes.

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

@@ -27,9 +27,9 @@ Initialize a new stack in the current repository.
 gh stack init [flags] [branches...]
 ```
 
-Creates an entry in `.git/gh-stack` to track stack state. In interactive mode (no arguments), prompts you to name branches and offers to use the current branch as the first layer. You'll also be prompted to set an optional branch prefix. When a prefix is set, branch names you enter are automatically prefixed.
+Initializes a new stack locally. In interactive mode (no arguments), prompts for a branch name and offers to use the current branch as the first layer. If a branch name contains slashes (e.g., `feat/api`), prompts if you would like to use a prefix (e.g., `feat/`) for all branches in the stack.
 
-When explicit branch names are given, creates any that don't already exist (branching from the trunk). The trunk defaults to the repository's default branch unless overridden with `--base`.
+When explicit branch names are given, existing branches are adopted automatically and any missing branches are created. The trunk defaults to the repository's default branch unless overridden with `--base`.
 
 Use `--numbered` with `--prefix` to enable auto-incrementing branch names (`prefix/01`, `prefix/02`, …).
 
@@ -38,7 +38,6 @@ Enables `git rerere` automatically so that conflict resolutions are remembered a
 | Flag | Description |
 |------|-------------|
 | `-b, --base <branch>` | Trunk branch for the stack (defaults to the repository's default branch) |
-| `-a, --adopt` | Adopt existing branches into a stack instead of creating new ones |
 | `-p, --prefix <string>` | Set a branch name prefix for the stack |
 | `-n, --numbered` | Use auto-incrementing numbered branch names (requires `--prefix`) |
 
@@ -48,14 +47,14 @@ Enables `git rerere` automatically so that conflict resolutions are remembered a
 # Interactive — prompts for branch names
 gh stack init
 
-# Non-interactive — specify branches upfront
-gh stack init feature-auth feature-api feature-ui
+# Non-interactive — specify first branch upfront
+gh stack init feature-auth
 
 # Use a different trunk branch
 gh stack init --base develop feature-auth
 
-# Adopt existing branches into a stack
-gh stack init --adopt feature-auth feature-api
+# Adopt or create multiple branches at once
+gh stack init feature-auth feature-api feature-ui
 
 # Set a prefix — prompts for a branch name suffix
 gh stack init -p feat
@@ -235,7 +234,7 @@ You must have a branch from the stack checked out locally. The command targets t
 
 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.
 
-This is useful when you need to restructure a stack — remove a branch, reorder branches, rename branches, or make other large changes. After unstacking, use `gh stack init --adopt` to re-create the stack with the desired structure.
+This is useful when you need to restructure a stack — 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 — existing branches are adopted automatically.
 
 | Flag | Description |
 |------|-------------|

skills/gh-stack/SKILL.md

@@ -141,7 +141,8 @@ Small, incidental fixes (e.g., fixing a typo you noticed) can go in the current
 |------|---------|
 | Create a stack (recommended) | `gh stack init -p feat auth` |
 | Create a stack without prefix | `gh stack init auth` |
-| Adopt existing branches | `gh stack init --adopt branch-a branch-b` |
+| Create a stack of multiple branches | `gh stack init auth api frontend` |
+| Adopt existing branches | `gh stack init existing-branch-a existing-branch-b` |
 | Set custom trunk | `gh stack init --base develop branch-a` |
 | Add a branch to stack (suffix only if prefix set) | `gh stack add api-routes` |
 | Add branch + stage all + commit | `gh stack add -Am "message" api-routes` |
@@ -387,7 +388,7 @@ gh stack unstack
 git branch -m old-branch-1 new-branch-1
 
 # 3. Re-create the stack with the new structure
-gh stack init --base main --adopt new-branch-1 new-branch-2 new-branch-3
+gh stack init --base main new-branch-1 new-branch-2 new-branch-3
 ```
 
 ---
@@ -417,21 +418,20 @@ gh stack init branch-a branch-b branch-c
 # Use a different trunk branch
 gh stack init --base develop branch-a branch-b
 
-# Adopt existing branches into a stack
-gh stack init --adopt branch-a branch-b branch-c
+# Adopt existing branches into a stack (handled automatically if the branches exist)
+gh stack init branch-a branch-b branch-c
 ```
 
 | Flag | Description |
 |------|-------------|
 | `-b, --base <branch>` | Trunk branch (defaults to the repo's default branch) |
-| `-a, --adopt` | Adopt existing branches instead of creating new ones |
 | `-p, --prefix <string>` | Branch name prefix. Subsequent `add` calls only need the suffix (e.g., with `-p feat`, `gh stack add auth` creates `feat/auth`) |
 
 **Behavior:**
 
 - Using `-p` is recommended — it simplifies branch naming for subsequent `add` calls
 - Creates any branches that don't already exist (branching from the trunk branch)
-- In `--adopt` mode: validates all branches exist, rejects if any is already in a stack or has an existing PR
+- Existing branches are adopted automatically; missing branches are created from the trunk
 - Checks out the last branch in the list
 - Enables `git rerere` so conflict resolutions are remembered across rebases. On first run in a repo, this may trigger a confirmation prompt — pre-configure with `git config rerere.enabled true` to avoid it
 
@@ -797,7 +797,7 @@ gh stack unstack [flags]
 ```bash
 # Tear down the stack (locally and on GitHub), then rebuild
 gh stack unstack
-gh stack init --base main --adopt branch-2 branch-1 branch-3 # reordered
+gh stack init --base main branch-2 branch-1 branch-3 # reordered
 
 # Only remove local tracking (keep the stack on GitHub)
 gh stack unstack --local