From f5bbf5f4230506cb552c9f00eb309d0c408d4a3a Mon Sep 17 00:00:00 2001
From: Danny Ben Shitrit <db@dannyben.com>
Date: Wed, 1 Jul 2026 14:41:03 +0300
Subject: [PATCH] update completions related pages

---
 src/advanced/bash-completion.md | 32 +++++++++++++++++++++-----------
 src/configuration/argument.md   | 12 ++++++++++++
 src/configuration/command.md    |  5 +++++
 src/configuration/flag.md       |  4 ++--
 4 files changed, 40 insertions(+), 13 deletions(-)

diff --git a/src/advanced/bash-completion.md b/src/advanced/bash-completion.md
index 9a0cecd..89975d1 100644
--- a/src/advanced/bash-completion.md
+++ b/src/advanced/bash-completion.md
@@ -37,29 +37,39 @@ By running `bashly generate --upgrade`, your completions function
 (generated with `bashly add completions`) will be regenerated.
 !!!
 
-## Custom command completions
+## Custom argument completions
 
 In addition to the automatic suggestion of subcommands and flags, you can
 instruct bashly to also suggest files, directories, users, git branches and
-more. To do this, add another option in your `bashly.yml` on the command you
-wish to alter:
+more.
+
+For positional arguments, add `completions` to the argument that should receive
+these suggestions:
 
 ```yaml bashly.yml
 commands:
 - name: upload
   help: Upload a file
-  completions:
-  - <directory>
-  - <user>
-  - $(git branch 2> /dev/null)
+  args:
+  - name: source
+    help: File to upload
+    required: true
+    completions:
+    - <file>
+    - <directory>
+    - $(git branch 2> /dev/null)
 
 ```
 
+The `completions` option is still supported on commands as a fallback for
+positional arguments, but it is discouraged for new configurations. Prefer
+placing completions directly on the relevant `args` entry.
+
 ## Custom flag completions
 
-The `completions` option is also available on flags that have an `arg`.
-Similarly to the `allowed` option for arguments, the allowed list is added
-to the suggestions automatically (without the need to use `completions`).
+For flag values, add `completions` to flags that have an `arg`. Similarly to
+the `allowed` option for arguments and flags, the allowed list is added to the
+suggestions automatically (without the need to use `completions`).
 
 ```yaml bashly.yml
 commands:
@@ -78,7 +88,7 @@ commands:
 ```
 
 - Anything between `<...>` will be added using the `compgen -A action` flag.
-- Anything else, will be appended to the `compgen -W` flag.
+- Anything else will be appended to the `compgen -W` flag.
 
 !!! Note
 In case you are using the
diff --git a/src/configuration/argument.md b/src/configuration/argument.md
index a89592c..660a2b5 100644
--- a/src/configuration/argument.md
+++ b/src/configuration/argument.md
@@ -94,9 +94,21 @@ define required arguments after it.
 Limit the allowed values to a specified whitelist. Can be used in conjunction
 with [`default`](#default) or [`required`](#required).
 
+Allowed values are also added to generated bash completions automatically.
+
 [!button variant="primary" icon="code-review" text="Whitelist Example"](https://github.com/bashly-framework/bashly/tree/master/examples/whitelist#readme)
 
 
+### completions
+
+[!badge Array of Strings]
+
+Specify an array of additional completion suggestions when used in conjunction
+with `bashly add completions`.
+
+[!ref](/advanced/bash-completion.md)
+
+
 ### repeatable
 
 [!badge Boolean]
diff --git a/src/configuration/command.md b/src/configuration/command.md
index 8e973f4..b6ba6ef 100644
--- a/src/configuration/command.md
+++ b/src/configuration/command.md
@@ -295,6 +295,11 @@ To access arguments captured by `catch_all` in your script, use the
 Specify an array of additional completion suggestions when used in conjunction
 with `bashly add completions`.
 
+This command-level option is supported as a fallback for positional arguments,
+but it is discouraged for new configurations. Prefer setting
+[`completions`](argument.md#completions) on the relevant argument, or on the
+relevant [`flag`](flag.md#completions) when completing a flag value.
+
 [!ref](/advanced/bash-completion.md)
 
 
diff --git a/src/configuration/flag.md b/src/configuration/flag.md
index d9dc3d6..7c95333 100644
--- a/src/configuration/flag.md
+++ b/src/configuration/flag.md
@@ -154,8 +154,8 @@ This option should be specified on both sides of the exclusivity.
 
 [!badge Array of Strings]
 
-Specify an array of additional completion suggestions when used in conjunction
-with `bashly add completions`.
+Specify an array of additional completion suggestions for this flag's value
+when used in conjunction with `bashly add completions`.
 
 Remember to set the [`arg`](#arg) name when using this option.