diff --git a/cli/bash/commands/basectl/subcommands/gh_branch_worktree.sh b/cli/bash/commands/basectl/subcommands/gh_branch_worktree.sh
index 5b109018..7fd0109e 100644
--- a/cli/bash/commands/basectl/subcommands/gh_branch_worktree.sh
+++ b/cli/bash/commands/basectl/subcommands/gh_branch_worktree.sh
@@ -295,7 +295,7 @@ base_gh_branch_prune_local() {
         printf 'No merged local branches found.\n'
     fi
     if ((skipped_worktree > 0)); then
-        printf 'Hint: run `basectl gh worktree prune` to inspect stale worktrees.\n'
+        printf 'Hint: run `basectl gh worktree prune` to preview these worktrees, then `basectl gh worktree prune --yes` and rerun this command.\n'
     fi
     printf 'Summary: %s %s, %s skipped worktree, %s skipped upstream, %s failed.\n' \
         "$deleted" "$([[ "$dry_run" -eq 1 ]] && printf 'would delete' || printf 'deleted')" \
@@ -514,6 +514,11 @@ base_gh_worktree_prune() {
             --yes)
                 dry_run=0
                 ;;
+            --remote)
+                base_gh_usage_error base_gh_worktree_usage \
+                    "Option '--remote' is only supported by 'basectl gh branch prune'. Run 'basectl gh branch prune --remote' for remote branch cleanup."
+                return $?
+                ;;
             -h|--help)
                 base_gh_worktree_usage
                 return 0
diff --git a/cli/bash/commands/basectl/tests/gh-branch-worktree.bats b/cli/bash/commands/basectl/tests/gh-branch-worktree.bats
index de0e5212..a1a7493f 100644
--- a/cli/bash/commands/basectl/tests/gh-branch-worktree.bats
+++ b/cli/bash/commands/basectl/tests/gh-branch-worktree.bats
@@ -65,6 +65,14 @@ load ./basectl_helpers.bash
     [[ "$output" != *"basectl gh issue create"* ]]
 }
 
+@test "basectl gh worktree prune explains that remote cleanup belongs to branch prune" {
+    run_basectl gh worktree prune --remote
+
+    [ "$status" -eq 2 ]
+    [[ "$output" == *"Option '--remote' is only supported by 'basectl gh branch prune'."* ]]
+    [[ "$output" == *"Run 'basectl gh branch prune --remote' for remote branch cleanup."* ]]
+}
+
 @test "basectl gh branch usage errors return status 2" {
     run_basectl gh branch stale --days never
 
@@ -219,7 +227,7 @@ load ./basectl_helpers.bash
 
     [ "$status" -eq 0 ]
     [[ "$output" == *"SKIP   merged-work  attached to worktree "*"/merged-worktree"* ]]
-    [[ "$output" == *'Hint: run `basectl gh worktree prune` to inspect stale worktrees.'* ]]
+    [[ "$output" == *'Hint: run `basectl gh worktree prune` to preview these worktrees, then `basectl gh worktree prune --yes` and rerun this command.'* ]]
     [[ "$output" == *"Summary: 0 deleted, 1 skipped worktree, 0 skipped upstream, 0 failed."* ]]
     git -C "$repo" show-ref --verify --quiet refs/heads/merged-work
 }
diff --git a/docs/github-workflow.md b/docs/github-workflow.md
index 680f984f..33c0dcf9 100644
--- a/docs/github-workflow.md
+++ b/docs/github-workflow.md
@@ -438,6 +438,12 @@ a merged GitHub PR, then deletes the now-free local branch when safe. Resolve an
 reported GitHub verification failures and rerun the preview before applying it
 with `--yes`.
 
+When `basectl gh branch prune` reports branches attached to worktrees, preview
+those worktrees with `basectl gh worktree prune`, apply the safe removals with
+`basectl gh worktree prune --yes`, and rerun the branch-prune command. The
+`--remote` option belongs to `basectl gh branch prune`; worktree pruning only
+removes local worktrees and their local branches.
+
 ## Superseded Pull Requests
 
 A pull request closed because another pull request supersedes it has a