Release: Documentation reorganization and screenshots

Taskfile.yml

@@ -47,7 +47,7 @@ tasks:
       - |
         echo "Waiting for LocalStack to be ready..."
         for i in $(seq 1 30); do
-          if curl -s --connect-timeout 2 --max-time 5 http://localhost:4566/_localstack/health 2>/dev/null | grep -q '"s3": "running"'; then
+          if curl -s --connect-timeout 2 --max-time 5 http://localhost:4566/_localstack/health 2>/dev/null | grep -qE '"s3": "(available|running)"'; then
             echo "LocalStack started at http://localhost:4566"
             exit 0
           fi
@@ -92,7 +92,48 @@ tasks:
       - ./claws
 
   demo:record:
-    desc: Record demo.gif using VHS + LocalStack (Linux only - --network host required)
+    desc: Record all demos (gif + screenshots) using VHS + LocalStack
+    deps: [build, localstack:start, localstack:demo-setup]
+    preconditions:
+      - sh: '[ "$(uname -s)" = "Linux" ]'
+        msg: "demo:record requires Linux (--network host not supported on macOS/Windows)"
+    cmds:
+      - task: demo:record:gif
+      - task: demo:record:themes
+      - task: demo:record:features
+
+  demo:record:gif:
+    desc: Record demo.gif only
+    deps: [build, localstack:start, localstack:demo-setup]
+    preconditions:
+      - sh: '[ "$(uname -s)" = "Linux" ]'
+        msg: "demo:record requires Linux (--network host not supported on macOS/Windows)"
+    cmds:
+      - |
+        docker run --rm --network host \
+          -v "$(pwd)":/vhs \
+          -v "$(pwd)/scripts/demo-aws-config:/root/.aws:ro" \
+          -e AWS_ENDPOINT_URL=http://localhost:4566 \
+          -e AWS_EC2_METADATA_DISABLED=true \
+          ghcr.io/charmbracelet/vhs docs/tapes/demo.tape
+
+  demo:record:themes:
+    desc: Record theme screenshots only
+    deps: [build, localstack:start, localstack:demo-setup]
+    preconditions:
+      - sh: '[ "$(uname -s)" = "Linux" ]'
+        msg: "demo:record requires Linux (--network host not supported on macOS/Windows)"
+    cmds:
+      - |
+        docker run --rm --network host \
+          -v "$(pwd)":/vhs \
+          -v "$(pwd)/scripts/demo-aws-config:/root/.aws:ro" \
+          -e AWS_ENDPOINT_URL=http://localhost:4566 \
+          -e AWS_EC2_METADATA_DISABLED=true \
+          ghcr.io/charmbracelet/vhs docs/tapes/themes.tape
+
+  demo:record:features:
+    desc: Record feature screenshots only
     deps: [build, localstack:start, localstack:demo-setup]
     preconditions:
       - sh: '[ "$(uname -s)" = "Linux" ]'
@@ -101,12 +142,10 @@ tasks:
       - |
         docker run --rm --network host \
           -v "$(pwd)":/vhs \
+          -v "$(pwd)/scripts/demo-aws-config:/root/.aws:ro" \
           -e AWS_ENDPOINT_URL=http://localhost:4566 \
-          -e AWS_ACCESS_KEY_ID=test \
-          -e AWS_SECRET_ACCESS_KEY=test \
-          -e AWS_DEFAULT_REGION=us-east-1 \
           -e AWS_EC2_METADATA_DISABLED=true \
-          ghcr.io/charmbracelet/vhs:v0.10.0 cassette.tape
+          ghcr.io/charmbracelet/vhs docs/tapes/features.tape
 
   test-localstack:
     desc: Run integration tests with LocalStack

docs/configuration.md

@@ -0,0 +1,121 @@
+# Configuration
+
+## AWS Credentials
+
+claws uses your standard AWS configuration:
+
+- `~/.aws/credentials` - AWS credentials
+- `~/.aws/config` - AWS configuration (region, profile)
+- Environment variables: `AWS_PROFILE`, `AWS_REGION`, `AWS_ACCESS_KEY_ID`, etc.
+
+## Configuration File
+
+Optional settings can be stored in `~/.config/claws/config.yaml`:
+
+```yaml
+timeouts:
+  aws_init: 10s           # AWS initialization timeout (default: 5s)
+  multi_region_fetch: 60s # Multi-region parallel fetch timeout (default: 30s)
+  tag_search: 45s         # Tag search timeout (default: 30s)
+  metrics_load: 30s       # CloudWatch metrics load timeout (default: 30s)
+  log_fetch: 15s          # CloudWatch Logs fetch timeout (default: 10s)
+
+concurrency:
+  max_fetches: 100        # Max concurrent API fetches (default: 50)
+
+cloudwatch:
+  window: 15m             # Metrics data window period (default: 15m)
+
+autosave:
+  enabled: true           # Save region/profile/theme on change (default: false)
+
+startup:                  # Applied on launch if present
+  profiles:               # Multiple profiles supported
+    - production
+  regions:
+    - us-east-1
+    - us-west-2
+
+theme: nord               # Preset: dark, light, nord, dracula, gruvbox, catppuccin
+
+# Or use preset with custom overrides:
+# theme:
+#   preset: dracula
+#   primary: "#ff79c6"
+#   danger: "#ff5555"
+```
+
+The config file is **not created automatically**. Create it manually if needed.
+
+CLI flags (`-p`, `-r`, `-t`, `--autosave`, `--no-autosave`) override config file settings.
+
+## Themes
+
+claws includes 6 built-in color themes:
+
+| Theme | Description |
+|-------|-------------|
+| `dark` | Default dark theme (pink/magenta accents) |
+| `light` | For light-background terminals |
+| `nord` | Nordic, calm blue palette |
+| `dracula` | Popular dark theme (purple/pink) |
+| `gruvbox` | Retro, warm earth tones |
+| `catppuccin` | Modern pastel (Mocha variant) |
+
+### Theme Previews
+
+| dark | light | nord |
+|------|-------|------|
+| ![dark](images/theme-dark.png) | ![light](images/theme-light.png) | ![nord](images/theme-nord.png) |
+
+| dracula | gruvbox | catppuccin |
+|---------|---------|------------|
+| ![dracula](images/theme-dracula.png) | ![gruvbox](images/theme-gruvbox.png) | ![catppuccin](images/theme-catppuccin.png) |
+
+### Switching Themes
+
+```bash
+# Via command line
+claws -t nord
+
+# Via command mode (runtime)
+:theme dracula
+```
+
+If autosave is enabled, theme changes are persisted to the config file.
+
+### Custom Theme Colors
+
+Override specific colors from a preset:
+
+```yaml
+theme:
+  preset: dracula
+  primary: "#ff79c6"
+  danger: "#ff5555"
+  success: "#50fa7b"
+```
+
+## Read-Only Mode
+
+Disable all destructive actions:
+
+```bash
+# Via flag
+claws --read-only
+
+# Via environment variable
+CLAWS_READ_ONLY=1 claws
+```
+
+## Debug Logging
+
+Enable debug logging to a file:
+
+```bash
+claws -l debug.log
+```
+
+## IAM Permissions
+
+For required IAM permissions, see [iam-permissions.md](iam-permissions.md).

docs/keybindings.md

@@ -0,0 +1,116 @@
+# Key Bindings
+
+Complete reference for all keyboard shortcuts in claws.
+
+## General Navigation
+
+| Key | Action |
+|-----|--------|
+| `j` / `k` | Navigate up/down |
+| `h` / `l` | Navigate within category (service list) |
+| `Enter` / `d` | View resource details |
+| `Esc` | Go back |
+| `q` / `Ctrl+c` | Quit |
+
+## Views & Modes
+
+| Key | Action |
+|-----|--------|
+| `:` | Command mode (e.g., `:ec2/instances`) |
+| `:` + `Enter` | Go to dashboard (home) |
+| `~` | Go to dashboard (from service browser) |
+| `:services` | Go to service browser |
+| `/` | Filter mode (fuzzy search) |
+| `?` | Show help |
+
+## Resource Browser
+
+| Key | Action |
+|-----|--------|
+| `Tab` | Next resource type |
+| `1-9` | Switch to resource type by number |
+| `a` | Open actions menu |
+| `m` | Mark resource for comparison |
+| `d` | Describe (or diff if marked) |
+| `c` | Clear filter and mark |
+| `N` | Load next page (pagination) |
+| `M` | Toggle inline metrics (EC2, RDS, Lambda) |
+| `y` | Copy resource ID to clipboard |
+| `Y` | Copy resource ARN to clipboard |
+| `Ctrl+r` | Refresh (including metrics) |
+
+## Profile & Region
+
+| Key | Action |
+|-----|--------|
+| `R` | Select AWS region(s) (multi-select supported) |
+| `P` | Select AWS profile(s) (multi-select supported) |
+
+## Commands
+
+| Command | Action |
+|---------|--------|
+| `:q` / `:quit` | Quit |
+| `:login [name]` | AWS console login (default: `claws-login` profile) |
+| `:ec2/instances` | Navigate to EC2 instances |
+| `:sort <col>` | Sort by column (ascending) |
+| `:sort desc <col>` | Sort by column (descending) |
+| `:tag <filter>` | Filter by tag (e.g., `:tag Env=prod`) |
+| `:tags` | Browse all tagged resources |
+| `:diff <name>` | Compare current row with named resource |
+| `:diff <n1> <n2>` | Compare two named resources |
+| `:theme <name>` | Change color theme |
+| `:autosave on/off` | Enable/disable config autosave |
+
+## Mouse Support
+
+| Action | Effect |
+|--------|--------|
+| Hover | Highlight item under cursor |
+| Click | Select item / navigate |
+| Scroll wheel | Scroll through lists |
+| Click on tabs | Switch resource type |
+| Back button | Navigate back (same as Esc) |
+
+## Navigation Shortcuts (Context-dependent)
+
+These shortcuts navigate to related resources based on the current context:
+
+| Key | Action |
+|-----|--------|
+| `v` | View VPC / Versions |
+| `s` | View Subnets / Streams / Stages |
+| `g` | View Security Groups |
+| `r` | View Route Tables / Roles / Resources |
+| `e` | View Events / Executions / Endpoints |
+| `l` | View CloudWatch Logs |
+| `o` | View Outputs / Operations |
+| `i` | View Images / Indexes |
+
+## Region Selector (`R` key)
+
+| Key | Action |
+|-----|--------|
+| `j` / `k` | Navigate up/down |
+| `Space` | Toggle region selection |
+| `a` | Select all regions |
+| `n` | Deselect all regions |
+| `/` | Filter regions |
+| `Enter` | Apply selection |
+| `Esc` | Cancel |
+
+Selected regions are queried in parallel; resources display with Region column.
+
+## Profile Selector (`P` key)
+
+| Key | Action |
+|-----|--------|
+| `j` / `k` | Navigate up/down |
+| `Space` | Toggle profile selection |
+| `l` | SSO login for selected profile |
+| `L` | Console login for selected profile (`:login`) |
+| `/` | Filter profiles |
+| `Enter` | Apply selection |
+| `Esc` | Cancel |
+
+Selected profiles are queried in parallel; resources display with Profile and Account columns.