docs: clear up ambiguity surrounding script behavior

Author: elasticdog

CHANGELOG.md

@@ -13,6 +13,7 @@ The format is based on [Keep a Changelog][1], and this project adheres to
 ### Added
 
 - Explicit safety checks for all external dependencies.
+- Improved documentation to remove behavioral ambiguity.
 
 ## [0.1.1] - 2024-08-12
 

README.md

@@ -4,9 +4,10 @@
 
 ---
 
-A script to automate adding SSH keys to the local [SSH agent][1] using
-passphrases stored in [Bitwarden][2]. It retrieves passphrases securely using
-the [Bitwarden CLI][3], then uses [`expect`][4] to interact with [`ssh-add`][5].
+A script to add a passphrase-protected SSH key to your local [`ssh-agent`][1] by
+leveraging credentials stored in [Bitwarden][2]. It securely retrieves the
+passphrase via the [Bitwarden CLI][3], then uses [`expect`][4] to automate the
+authentication process with [`ssh-add`][5].
 
 [1]: https://www.ssh.com/academy/ssh/agent
 [2]: https://bitwarden.com/
@@ -20,9 +21,10 @@ the [Bitwarden CLI][3], then uses [`expect`][4] to interact with [`ssh-add`][5].
 bw-ssh-add <BITWARDEN-ITEM-ID> [SSH-ADD-ARGUMENTS...]
 ```
 
-- The first argument is passed to `bw` as either a search term or an item's
-  globally unique identifier to retrieve the passphrase.
-- All additional arguments are passed through to `ssh-add` unchanged. Refer to
+- The first argument serves as input for `bw get password`, either as a search
+  term or as an item's globally unique identifier, to retrieve the key's
+  passphrase.
+- Any additional arguments are passed through to `ssh-add` unchanged. Refer to
   the [`ssh-add` man page][6] for details on available options.
 
 [6]: https://man.openbsd.org/ssh-add.1

bw-ssh-add

@@ -4,15 +4,17 @@ set -euo pipefail
 #
 # bw-ssh-add - https://github.com/elasticdog/bw-ssh-add
 #
-# This script automates adding SSH keys to the local SSH agent using passphrases
-# stored in Bitwarden. It retrieves passphrases securely using the Bitwarden
-# CLI, then uses `expect` to interact with `ssh-add`.
+# This script adds a passphrase-protected SSH key to your local `ssh-agent`
+# by leveraging credentials stored in Bitwarden. It securely retrieves
+# the passphrase via the Bitwarden CLI, then uses `expect` to automate the
+# authentication process with `ssh-add`.
 #
 # Usage: bw-ssh-add <BITWARDEN-ITEM-ID> [SSH-ADD-ARGUMENTS...]
 #
-# - The first argument is passed to `bw` as either a search term or an item's
-#   globally unique identifier to retrieve the passphrase.
-# - All additional arguments are passed through to `ssh-add` unchanged. Refer to
+# - The first argument serves as input for `bw get password`, either as a search
+#   term or as an item's globally unique identifier, to retrieve the key's
+#   passphrase.
+# - Any additional arguments are passed through to `ssh-add` unchanged. Refer to
 #   the `ssh-add` man page for details on available options.
 #
 # The script sets an expiration time for the added key: