docs: Update bmai.md with prerequisites, example, and improved docume…

…ntation

docs/bmai.md

@@ -2,44 +2,65 @@
 
 The `bmai` command helps generate bash-my-aws functions from natural language descriptions using AI. It reads the project's conventions and generates compliant functions that follow the established patterns.
 
+## Prerequisites
+
+- Install and configure [llm](https://github.com/simonw/llm)
+  ```bash
+  pip install llm
+  ```
+- Configure an LLM provider (e.g., OpenAI API key)
+  ```bash
+  llm keys set openai
+  ```
+
 ## Usage
 
 ```bash
 source ~/.bash-my-aws/lib/extras/bmai
-bmai 'list ec2 instances'
+bmai "list s3 buckets"
 ```
 
 ## Features
 
 - Generates authentic bash-my-aws functions from natural language descriptions
 - Follows established conventions and patterns
 - Creates functions that integrate with existing BMA commands
-- Outputs to a temporary file for review before use
+- Saves generated functions for review
 
 ## Installation
 
-The `bmai` command is included in the extras directory. To use it:
+The `bmai` command is included in the extras directory:
 
-1. Ensure you have the `llm` command line tool installed
-2. Source the bmai script:
-   ```bash
-   source ~/.bash-my-aws/lib/extras/bmai
-   ```
+```bash
+source ~/.bash-my-aws/lib/extras/bmai
+```
 
 ## Examples
 
 ```bash
-# Generate a command to list EC2 instances
-bmai 'list ec2 instances'
-
-# Generate a command to show VPC endpoints
-bmai 'show vpc endpoints'
-
-# Generate a command to delete old snapshots
-bmai 'delete snapshots older than 30 days'
+# Generate a command to list S3 buckets
+$ bmai "list s3 buckets"
+s3-buckets() {
+  # List S3 buckets in current region
+  #
+  #   $ s3-buckets
+  #   example-bucket   2019-12-14  NEVER_UPDATED  NO_STACK
+  #   another-bucket   2020-03-01  NEVER_UPDATED  NO_STACK
+
+  aws s3api list-buckets \
+    --output text \
+    --query "
+      Buckets[].[
+        Name,
+        CreationDate,
+        join(',', ['NEVER_UPDATED']),
+        join(',', ['NO_STACK'])
+      ]" |
+  columnise
+}
 ```
 
-Generated functions will be saved to:
+Generated functions are saved to:
 `~/.bash-my-aws/contrib/ai/slop/`
 
 ## How It Works
@@ -57,3 +78,5 @@ The generated functions follow BMA conventions including:
 - Proper error handling
 - Clear documentation and examples
 
+Note: The example above shows the author's original response after realizing how simple and elegant the S3 bucket listing function could be while still following all conventions.
+