docs: migrate common features content and refine structure

- Add comprehensive profiles/authentication docs
- Add output formats documentation
- Add JMESPath queries documentation
- Add async operations documentation
- Streamline quickstart to 60-second Docker experience
- Move shell completions to Reference
- Reorder sections for better flow

Author: joshrotenberg

docs/src/SUMMARY.md

@@ -1,22 +1,17 @@
 # Summary
 
-[Introduction](./introduction.md)
-
-# Getting Started
+# Introduction
 
+- [Overview](./introduction.md)
+- [Quick Start](./getting-started/quickstart.md)
 - [Installation](./getting-started/installation.md)
-- [Profiles & Authentication](./getting-started/profiles.md)
-- [Common Features](./getting-started/common-features.md)
-  - [Output Formats](./getting-started/output-formats.md)
-  - [JMESPath Queries](./getting-started/jmespath-queries.md)
-  - [Async Operations](./getting-started/async-operations.md)
-- [Shell Completions](./getting-started/shell-completions.md)
 
-# Walkthrough
+# Common Features
 
-- [Overview & Concepts](./walkthrough/overview.md)
-- [Cloud Quick Examples](./walkthrough/cloud-examples.md)
-- [Enterprise Quick Examples](./walkthrough/enterprise-examples.md)
+- [Profiles & Authentication](./common-features/profiles.md)
+- [Output Formats](./common-features/output-formats.md)
+- [JMESPath Queries](./common-features/jmespath-queries.md)
+- [Async Operations](./common-features/async-operations.md)
 
 # Redis Cloud
 
@@ -49,6 +44,12 @@
   - [Diagnostics](./enterprise/operations/diagnostics.md)
   - [Migrations](./enterprise/operations/migration.md)
 
+# Walkthrough
+
+- [Overview & Concepts](./walkthrough/overview.md)
+- [Cloud Quick Examples](./walkthrough/cloud-examples.md)
+- [Enterprise Quick Examples](./walkthrough/enterprise-examples.md)
+
 # Cookbook
 
 - [Overview](./cookbook/README.md)
@@ -71,6 +72,7 @@
 
 - [Environment Variables](./reference/environment-variables.md)
 - [Configuration File](./reference/config-file.md)
+- [Shell Completions](./reference/shell-completions.md)
 - [Security](./reference/security.md)
 - [Troubleshooting](./reference/troubleshooting.md)
 - [rladmin Comparison](./reference/rladmin.md)

docs/src/common-features/async-operations.md

@@ -1,153 +1,138 @@
 # Async Operations
 
-The `redisctl` CLI provides comprehensive support for asynchronous operations across both Redis Cloud and Redis Enterprise APIs. All create, update, and delete operations support the `--wait` flag family for tracking long-running operations.
+Many Redis Cloud and Enterprise operations are asynchronous - they return immediately with a task ID while the work happens in the background. redisctl handles this automatically.
 
-## Overview
+## The --wait Flag
 
-Many Redis Cloud API operations are asynchronous, returning immediately with a task ID while the operation continues in the background. The `--wait` flags allow you to:
-
-- Wait for operations to complete before returning
-- Track progress with visual indicators
-- Set custom timeouts for long operations
-- Configure polling intervals
-
-## Wait Flag Options
-
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--wait` | Wait for operation to complete | Timeout: 600s |
-| `--wait-timeout <seconds>` | Custom timeout duration | 600 |
-| `--wait-interval <seconds>` | Polling interval | 10 |
-
-## Basic Usage
+Use `--wait` to block until the operation completes:
 
 ```bash
-# Create database and wait for completion
-redisctl cloud database create --subscription-id 12345 \
-  --data @database.json --wait
-
-# With custom timeout for large operations
-redisctl cloud database create --subscription-id 12345 \
-  --data @large-db.json --wait --wait-timeout 1800
-
-# With faster polling for quick operations
-redisctl cloud database update --subscription-id 12345 \
-  --database-id 67890 --data @updates.json \
-  --wait --wait-interval 2
-```
-
-## Progress Tracking
-
-When using the `--wait` flag, redisctl provides real-time progress tracking:
+# Returns immediately with task ID
+redisctl cloud database create --subscription-id 123 --data '{...}'
 
+# Waits for completion, returns final result
+redisctl cloud database create --subscription-id 123 --data '{...}' --wait
 ```
-Creating database...
-⠋ Waiting for task 12345 to complete... (10s)
-⠙ Status: processing (20s)
-⠹ Status: processing (30s)
-✓ Database creation completed successfully
-```
-
-## Supported Operations
 
-Async operations are supported across all major command categories:
+## Polling Options
 
-- [Database Operations](./database-operations.md) - Create, update, delete, import, backup, migrate
-- [Subscription Management](./subscription-management.md) - Regular and fixed subscriptions
-- [Network Connectivity](./network-connectivity.md) - VPC Peering, PSC, Transit Gateway
-- [ACL Management](./acl-management.md) - Rules, roles, and users
-- [User & Account Management](./user-management.md) - Users and provider accounts
+Control how redisctl polls for completion:
 
-## Error Handling
+```bash
+redisctl cloud subscription create \
+  --data '{...}' \
+  --wait \
+  --poll-interval 10 \    # Check every 10 seconds (default: 5)
+  --max-wait 600          # Timeout after 10 minutes (default: 300)
+```
 
-### Timeout Behavior
+## Task Management
 
-If an operation exceeds the timeout:
-- The CLI exits with an error
-- The task continues running in the background
-- You can check status using the task ID
+### Check Task Status
 
 ```bash
-# Operation times out
-Error: Operation timed out after 600 seconds. Task 12345 is still running.
+# Cloud
+redisctl cloud task get <task-id>
 
-# Check task status manually
-redisctl cloud task get 12345
+# Enterprise
+redisctl enterprise action get <action-id>
 ```
 
-### Recovery Options
+### List Recent Tasks
 
 ```bash
-# Retry with longer timeout
-redisctl cloud database create --data @database.json \
-  --wait --wait-timeout 1800
+# Cloud - list all tasks
+redisctl cloud task list
 
-# Check task status without waiting
-redisctl cloud task list --status pending
+# Enterprise - list actions
+redisctl enterprise action list
 ```
 
-## Best Practices
+## Common Async Operations
 
-### Choosing Timeouts
+### Redis Cloud
 
-- **Small operations**: Default 600s is usually sufficient
-- **Large databases**: Increase to 1800s (30 min) or more
-- **Bulk operations**: Consider 3600s (1 hour) for very large datasets
-- **Network operations**: May need longer timeouts in some regions
+- `subscription create/delete`
+- `database create/update/delete`
+- `vpc-peering create/delete`
+- `cloud-account create/delete`
 
-### Polling Intervals
+### Redis Enterprise
 
-- **Default (10s)**: Good balance for most operations
-- **Fast operations (2-5s)**: For operations you expect to complete quickly
-- **Long operations (30-60s)**: Reduce API calls for very long operations
+- `database create/update/delete`
+- `cluster join/remove-node`
+- `module upload`
 
-### Automation
+## Error Handling
 
-The `--wait` flags are designed for automation:
+When `--wait` is used and an operation fails:
 
 ```bash
-#!/bin/bash
-# CI/CD pipeline example
-set -e  # Exit on error
-
-# Create infrastructure
-redisctl cloud subscription create --data @prod-sub.json \
-  --wait --wait-timeout 1800
+$ redisctl cloud database create --data '{...}' --wait
+Error: Task failed: Invalid memory configuration
+
+# Check task details
+$ redisctl cloud task get abc-123
+{
+  "taskId": "abc-123",
+  "status": "failed",
+  "error": "Invalid memory configuration"
+}
+```
 
-SUB_ID=$(redisctl cloud subscription list -q "[0].id" -o json)
+## Scripting Patterns
 
-redisctl cloud database create --subscription-id $SUB_ID \
-  --data @prod-db.json --wait --wait-timeout 900
+### Wait and Extract Result
 
-echo "Infrastructure ready!"
+```bash
+# Create and get the new database ID
+DB_ID=$(redisctl cloud database create \
+  --subscription-id 123 \
+  --data '{"name": "mydb"}' \
+  --wait \
+  -q 'databaseId')
+
+echo "Created database: $DB_ID"
 ```
 
-## Parallel Operations
+### Fire and Forget
+
+```bash
+# Start multiple operations in parallel
+redisctl cloud database delete 123 456 &
+redisctl cloud database delete 123 789 &
+wait
+```
 
-You can run multiple async operations in parallel:
+### Custom Polling
 
 ```bash
-#!/bin/bash
-# Create multiple databases in parallel
-for i in {1..5}; do
-  redisctl cloud database create --subscription-id 12345 \
-    --data @db-$i.json --wait &
+# Start operation
+TASK_ID=$(redisctl cloud database create --data '{...}' -q 'taskId')
+
+# Custom polling loop
+while true; do
+  STATUS=$(redisctl cloud task get $TASK_ID -q 'status')
+  echo "Status: $STATUS"
+  
+  if [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ]; then
+    break
+  fi
+  
+  sleep 10
 done
-
-# Wait for all background jobs
-wait
-echo "All databases created!"
 ```
 
-## Implementation Details
+## Timeouts
+
+If an operation exceeds `--max-wait`:
 
-All async operations use the centralized `handle_async_response` function which:
-- Extracts task IDs from API responses
-- Polls for task completion
-- Provides consistent progress indicators
-- Handles timeouts and errors uniformly
+```bash
+$ redisctl cloud subscription create --data '{...}' --wait --max-wait 60
+Error: Operation timed out after 60 seconds. Task ID: abc-123
+
+# Check manually
+$ redisctl cloud task get abc-123
+```
 
-The system automatically detects task IDs from various response formats:
-- `taskId` field in response
-- `links` array with task references
-- Nested task objects
+The operation continues in the background - only the CLI stops waiting.