Update generated CLI documentation for version release/0.20.4 (#212)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: slarse

content/docs/commands/but-agent.mdx

@@ -3,45 +3,53 @@ title: "`but agent`"
 description: "Set up GitButler for AI coding agents."
 ---
 
-Use `but agent setup` to install GitButler agent skills and write workflow
-instructions into supported agent instruction files. To install or update the
-skill files without writing instructions, use
-[`but skill`](/commands/but-skill).
-
-Running `but agent` with no subcommand starts the same wizard.
+Runs a guided setup wizard for installing GitButler agent skills and
+writing workflow steering instructions into supported agent instruction
+files.
 
 ## Examples
 
-Start the interactive setup wizard:
+Start the interactive setup wizard (`but agent setup` is equivalent):
 
 ```text
-but agent setup
+but agent
 ```
 
-Print the default workflow instructions without modifying files:
+Print the default generated steering text:
 
 ```text
 but agent setup --print
 ```
 
-**Usage:** `but agent [COMMAND]`
+**Usage:** `but agent <COMMAND>`
 
 ## Subcommands
 
 ### `but agent setup`
 
 Configure GitButler skills and workflow instructions for coding agents.
 
-The wizard asks which agents you use, whether setup applies to this repository,
-globally, or both, and which workflow preferences to include. Before
-writing, it shows the skill install paths, instruction files, any repository
-`but setup` step, and the exact generated text.
+Starts an interactive wizard that generates GitButler workflow steering,
+installs selected agent skills, and optionally writes the generated
+steering into agent instruction files.
+
+## Examples
+
+Start the setup wizard:
+
+```text
+but agent setup
+```
+
+Print the default steering text without modifying files:
 
-In a non-interactive terminal, use `--print`.
+```text
+but agent setup --print
+```
 
 **Usage:** `but agent setup [OPTIONS]`
 
 **Options:**
 
-* `--print` - Print the default workflow instructions without prompting or
-  modifying files
+* `--print` — Print the default generated steering text without prompting or modifying files
+

content/docs/commands/but-amend.mdx

@@ -1,14 +1,21 @@
 ---
 title: "`but amend`"
-description: "Amend a file change into a specific commit and rebases any dependent commits."
+description: "Amend one or more file changes into a specific commit and rebases any dependent commits."
 ---
 
-Wrapper for `but rub <file> <commit>`.
+Use `but amend <commit> --changes <file-or-hunk>[,<file-or-hunk>...]`.
 
-**Usage:** `but amend <FILE> <COMMIT>`
+**Usage:** `but amend <TARGET_OR_SOURCE> [OPTIONS]`
 
 ## Arguments
 
-* `<FILE>` — File ID to amend (required)
-* `<COMMIT>` — Commit ID to amend into (required)
+* `<TARGET_OR_SOURCE>` — Commit ID to amend into.
+
+In the legacy two-positional form, this can be the source ID. (required)
+
+## Options
+
+* `-p`, `--changes` `<CHANGES>` — Uncommitted file or hunk CLI IDs to amend into the commit.
+
+Can be specified multiple times or as comma-separated values.
 

content/docs/commands/but-commit.mdx

@@ -19,7 +19,7 @@ It will not commit changes staged to other branches.
 
 Use `but commit empty --before <target>` or `but commit empty --after <target>`
 to insert a blank commit. This is useful for creating a placeholder
-commit that you can amend changes into later using `but mark`, `but rub` or `but absorb`.
+commit that you can amend changes into later using `but rub` or `but absorb`.
 
 **Usage:** `but commit <COMMAND> [BRANCH] [OPTIONS]`
 
@@ -30,14 +30,13 @@ commit that you can amend changes into later using `but mark`, `but rub` or `but
 Insert a blank commit before or after the specified commit.
 
 This is useful for creating a placeholder commit that you can
-then amend changes into later using `but mark`, `but rub` or `but absorb`.
+then amend changes into later using `but rub` or `but absorb`.
 
-You can modify the empty commit message at any time using `but reword`.
+You can provide a message with `-m` or modify it later using `but reword`.
 
 This allows for a more Jujutsu style workflow where you create commits
-first and then fill them in as you work. Create an empty commit, mark it
-for auto-commit, and then just work on your changes. Write the commit
-message whenever you prefer.
+first and then fill them in as you work. Create an empty commit and
+then rub or absorb changes into it whenever you prefer.
 
 ## Examples
 
@@ -77,12 +76,15 @@ If a target is provided without --before or --after, defaults to --before behavi
 
 * `--before` `<BEFORE>` — Insert the blank commit before this commit or branch
 * `--after` `<AFTER>` — Insert the blank commit after this commit or branch
+* `-m`, `--message` `<MESSAGE>` — Commit message for the inserted blank commit
 
 ## Options
 
 * `-m`, `--message` `<MESSAGE>` — Commit message
 * `--message-file` `<FILE>` — Read commit message from file
 * `-c`, `--create` — Whether to create a new branch for this commit. If the branch name given matches an existing branch, that branch will be used instead. If no branch name is given, a new branch with a generated name will be created
+* `--before` `<BEFORE>` — Insert the commit before this commit or branch
+* `--after` `<AFTER>` — Insert the commit after this commit or branch
 * `-o`, `--only` — Only commit staged files, not unstaged files
 * `-a`, `--all` — No-op compatibility flag for git commit -a
 * `-n`, `--no-hooks` — Bypass pre-commit hooks

content/docs/commands/but-completions.mdx

@@ -0,0 +1,24 @@
+---
+title: "`but completions`"
+description: "Generate `but` shell completions."
+---
+
+## Examples
+
+```bash
+# bash, put in .bashrc or .bash_profile depending on system setup
+eval "$(but completions bash)"
+
+# zsh, put in .zshrc
+eval "$(but completions zsh)"
+
+# fish, put in config.fish
+but completions fish | source
+```
+
+**Usage:** `but completions [SHELL]`
+
+## Arguments
+
+* `<SHELL>` — The shell to generate completions for, or the one extracted from the SHELL environment variable
+

content/docs/commands/but-mark.mdx

@@ -6,7 +6,7 @@ description: "Move a commit or branch to a different location."
 Commit moves:
 - By default, commits are moved to be before (below) the target.
 - Use `--after` to move the commit after (above) the target instead.
-
+- Use comma-separated commit IDs to move multiple commits together.
 - When moving to a branch, the commit is placed at the top of that branch's stack.
 
 Branch moves:
@@ -21,18 +21,36 @@ Move a commit before another commit:
 but move abc123 def456
 ```
 
+Move multiple commits before another commit:
+
+```text
+but move abc123,789abc def456
+```
+
 Move a commit after another commit:
 
 ```text
 but move abc123 def456 --after
 ```
 
+Move multiple commits after another commit:
+
+```text
+but move abc123,789abc def456 --after
+```
+
 Move a commit to a different branch (places at top):
 
 ```text
 but move abc123 my-feature-branch
 ```
 
+Move multiple commits to a different branch (places at top):
+
+```text
+but move abc123,789abc my-feature-branch
+```
+
 Stack one branch on top of another:
 
 ```text
@@ -49,7 +67,7 @@ but move feature/frontend zz
 
 ## Arguments
 
-* `<SOURCE>` — Commit/branch identifier to move (required)
+* `<SOURCE>` — Commit/branch identifier to move. Use comma-separated commit IDs for multi-commit moves (required)
 * `<TARGET>` — Target commit/branch identifier, or zz to unstack a branch (required)
 
 ## Options

content/docs/commands/but-move.mdx

@@ -16,18 +16,18 @@ You can rub a file from one commit to another.
 Each cell shows what happens when you rub SOURCE → TARGET:
 
 ```text
-SOURCE ↓ / TARGET →  │ zz (unassigned) │ Commit     │ Branch      │ Stack
+SOURCE ↓ / TARGET →  │ zz (uncommitted) │ Commit     │ Branch      │ Stack
 ─────────────────────┼─────────────────┼────────────┼─────────────┼────────────
 File/Hunk            │ Unstage         │ Amend      │ Stage       │ Stage
 Commit               │ Undo            │ Squash     │ Move        │ -
 Branch (all changes) │ Unstage all     │ Amend all  │ Reassign    │ Reassign
 Stack (all changes)  │ Unstage all     │ -          │ Reassign    │ Reassign
-Unassigned (zz)      │ -               │ Amend all  │ Stage all   │ Stage all
+Uncommitted (zz)     │ -               │ Amend all  │ Stage all   │ Stage all
 File-in-Commit       │ Uncommit        │ Move       │ Uncommit to │ -
 ```
 
 Legend:
-- `zz` is a special target meaning "unassigned" (no branch)
+- `zz` is a special target meaning "uncommitted" (no branch)
 - `-` means the operation is not supported
 - "all changes" / "all" refers to all uncommitted changes from that source
 

content/docs/commands/but-rub.mdx

@@ -6,10 +6,6 @@ description: "Manage AI agent skills for GitButler."
 Skills provide enhanced AI capabilities for working with GitButler through
 Claude Code, Codex, and other AI assistants.
 
-For most agent setup, use [`but agent setup`](/commands/but-agent). It wraps
-skill installation with workflow instructions. Use `but skill` when you only
-need to install, update, check, or place the skill files yourself.
-
 Use `but skill install` to install the GitButler skill files. By default,
 it prompts for scope (repository or global home directory) and then format.
 When run outside a git repository, local scope is unavailable and the

content/docs/commands/but-skill.mdx

@@ -15,5 +15,6 @@ Wrapper for `but rub <source> zz`.
 
 ## Options
 
-* `-d`, `--discard` — Discard the selected committed changes instead of moving them to unassigned
+* `-d`, `--discard` — Discard the selected committed changes instead of moving them to uncommitted
+* `--diff` — Show the resulting uncommitted diff after uncommitting