docs: update .agents.md with new functions and test count

Author: Qbandev

.agents.md

@@ -23,7 +23,8 @@ wave-notes-setup/
 │   └── run_tests.sh        # Local test runner
 └── .github/
     └── workflows/
-        └── test.yml        # CI workflow (shellcheck + bats)
+        ├── test.yml             # CI workflow (shellcheck + bats)
+        └── release-please.yml   # Automated releases with release-please
 ```
 
 ## Key Components
@@ -33,8 +34,10 @@ wave-notes-setup/
 - **Configuration Precedence**: defaults → ~/.wave-notes.conf → env vars
 - **Key Functions**:
   - `detect_waveterm_config()` - Finds Wave Terminal config path (supports v0.9+ and older)
+  - `check_wave_installed()` - Blocks installation if Wave Terminal not found
+  - `validate_widgets()` - Validates JSON with jq or python3 fallback
   - `install_scratchpad_script()` - Generates ~/bin/wave-scratch.sh
-  - `install_widgets()` - Merges widgets into widgets.json (jq or Python fallback)
+  - `install_widgets()` - Merges widgets into widgets.json with validation and rollback
   - `get_max_display_order()` - Preserves existing widget ordering
 
 ### 2. wave-scratch.sh (Generated)
@@ -124,7 +127,7 @@ This is a Wave Terminal limitation. Minimize with:
 ## Development Workflow
 
 ```bash
-# Run automated tests (46 tests)
+# Run automated tests (54 tests)
 ./test/run_tests.sh
 
 # Or run bats directly
@@ -145,7 +148,7 @@ cat ~/.config/waveterm/widgets.json | jq .
 
 ## Test Coverage
 
-The test suite includes **46 tests** covering:
+The test suite includes **54 tests** covering:
 
 ### Unit Tests (install.bats)
 - `detect_waveterm_config()` - Path detection for both v0.9+ and older
@@ -154,7 +157,9 @@ The test suite includes **46 tests** covering:
 - `get_existing_order()` - Preserve existing widget positions
 - `create_directories()` - Directory creation
 - `install_scratchpad_script()` - Script generation and content verification
-- `install_widgets()` - JSON merging, backup creation, no hardcoded colors
+- `install_widgets()` - JSON merging, backup creation, validation, rollback
+- `check_wave_installed()` - Wave Terminal detection (config dirs, wsh command)
+- `validate_widgets()` - JSON validation with jq/python3 fallback
 
 ### Unit Tests (uninstall.bats)
 - `remove_widgets()` - Selective removal of notes-* widgets
@@ -175,13 +180,13 @@ The test suite includes **46 tests** covering:
 | `detect_waveterm_config()` | Find Wave Terminal config directory | None |
 | `load_config()` | Load configuration (defaults → file → env) | None |
 | `check_macos()` | Verify running on macOS | None |
-| `check_wave_terminal()` | Verify Wave Terminal is installed | None |
-| `check_wsh()` | Check if wsh command is available | None |
+| `check_wave_installed()` | Block install if Wave Terminal not found | None |
+| `validate_widgets()` | Validate JSON with jq or python3 fallback | `$1`: widgets.json path |
 | `create_directories()` | Create notes and bin directories | None |
 | `install_scratchpad_script()` | Generate wave-scratch.sh | None |
 | `get_max_display_order()` | Find highest widget order | `$1`: widgets.json path |
 | `get_existing_order()` | Get widget's current order | `$1`: path, `$2`: key, `$3`: default |
-| `install_widgets()` | Merge widgets into widgets.json | None |
+| `install_widgets()` | Merge widgets with validation and rollback | None |
 | `run_uninstall()` | Execute uninstall procedure | None |
 | `parse_args()` | Parse CLI arguments | `$@`: arguments |
 
@@ -224,8 +229,10 @@ The scripts use `set -euo pipefail`:
 
 ### Error Recovery
 
-- **Backup before modify**: widgets.json is backed up before changes
+- **Backup before modify**: widgets.json is backed up with chmod 600 before changes
 - **Atomic writes**: Use temp file + mv for JSON writes
+- **JSON validation**: Validate widgets.json after generation (jq or python3 fallback)
+- **Rollback on failure**: Restore backup if validation fails; remove invalid file on fresh install
 - **Origin verification**: Only delete scripts with "Generated by" header
 - **User confirmation**: Destructive operations require explicit consent