feat(dot): Secret Management v2.0 Phase 1 (#198)

* feat(dot): add Secret Management v2.0 Phase 1

Implements comprehensive secret lifecycle management for the DOT dispatcher:

NEW COMMANDS:
- `dot secret add <name>` - Store secrets with hidden input
  - Supports `--expires <days>` for expiration tracking
  - Supports `--notes <text>` for metadata
  - JSON metadata stored in Bitwarden notes field
- `dot secret check` - Dashboard showing expiring/expired secrets
  - Color-coded status (✓ valid, ⚠ expiring, ❌ expired)
  - Configurable warning threshold (default 30 days)
- `dot secret help` - Help text for all secret subcommands
- `dot lock` - Lock vault and clear session cache

SESSION CACHE (15-MIN IDLE TIMEOUT):
- File-based cache at ~/.cache/dot/session
- Tracks unlock time and last activity
- Auto-locks after 15 min inactivity (configurable via DOT_SESSION_IDLE_TIMEOUT)
- `dot` status shows vault state and time remaining
- Helper functions: _dot_session_cache_{init,save,touch,expired,clear}

ALSO INCLUDES:
- v5.1.1 enhancements: ZDOTDIR support, auto-add, file creation
- Updated completions for new commands
- Updated DOT-DISPATCHER-REFERENCE.md documentation
- Added SPEC for Secret Management v2.0
- Test Suite 13 with 22 new tests (93 total)
- E2E test suite (14 tests)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* docs: update .STATUS with Secret Management v2.0 Phase 1 completion

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: Data-Wise

.STATUS

@@ -8,7 +8,63 @@
 ## Priority: 1
 ## Progress: 100
 
-## Focus: v5.1.0 Bug Fixes Complete ✅
+## Focus: Secret Management v2.0 Phase 1 Complete ✅
+
+## ✅ Just Completed (2026-01-11):
+- **Secret Management v2.0 Phase 1** ✅ COMPLETE
+  - **PR:** #198 (feature/secret-management-v2-phase1 → main)
+  - **Implementation:** ~350 lines of new functionality
+
+  **New Commands:**
+  - `dot secret add <name>` - Store secrets with hidden input
+    - `--expires <days>` for expiration tracking
+    - `--notes <text>` for metadata
+    - JSON metadata in Bitwarden notes field
+  - `dot secret check` - Dashboard showing expiring/expired secrets
+    - Color-coded: ✓ valid, ⚠ expiring, ❌ expired
+    - Configurable warning threshold (default 30 days)
+  - `dot secret help` - Help text for all secret subcommands
+  - `dot lock` - Lock vault and clear session cache
+
+  **Session Cache (15-min idle timeout):**
+  - File-based cache at `~/.cache/dot/session`
+  - Tracks unlock time and last activity
+  - Auto-locks after 15 min inactivity
+  - Configurable via `DOT_SESSION_IDLE_TIMEOUT`
+  - `dot` status shows vault state + time remaining
+  - 7 helper functions: `_dot_session_cache_{init,save,touch,expired,clear}`, `_dot_session_time_remaining{,_fmt}`
+
+  **Tests:**
+  - Test Suite 13: 22 new tests for Phase 1 features
+  - Total: 93 unit tests + 14 E2E tests (all passing)
+
+## ✅ Just Completed (2026-01-10):
+- **DOT v5.1.1 Test Suite Created** ✅ COMPLETE
+  - **Unit Tests:** `test-dot-v5.1.1-unit.zsh` (19 tests, 100% passing)
+  - **E2E Tests:** `test-dot-v5.1.1-e2e.zsh` (14 tests, 100% passing)
+  - **Interactive Dogfooding:** `interactive-dot-dogfooding.zsh` (8 dishes, "Dotfile Chef" theme)
+  - **Total DOT Tests:** 104 automated tests (71 + 19 + 14)
+
+  **Test Coverage:**
+  - `_dot_add_file()` helper function
+  - `_dot_add()` standalone command
+  - `_dot_has_bitwarden_template()` detection
+  - `_dot_print_summary()` with contextual tips
+  - ZDOTDIR support in security checks
+  - Path resolution (full paths, tilde, fuzzy)
+  - File creation with mkdir -p
+  - Template detection for Bitwarden secrets
+
+- **DOT Secret Management v2.0 SPEC** 📋 DRAFTED
+  - **File:** `docs/specs/SPEC-dot-secret-management-v2-2026-01-10.md`
+  - **Scope:** Full token lifecycle (create, store, use, rotate, revoke)
+  - **Features:**
+    - Phase 1: `dot secret add`, expiry check, 15-min cache
+    - Phase 2: Token wizards (github, npm, pypi), dashboard
+    - Phase 3: Refresh/rotate, direnv integration, CI sync
+  - **User Story:** Developer managing GH tokens, NPM tokens, PyPI for CI/CD
+  - **Acceptance:** Full token lifecycle works end-to-end
+  - **Security:** Time-based 15-min cache, no secrets in history
 
 ## ✅ Just Completed (2026-01-11):
 - **DOT Dispatcher Bug Fixes** ✅ COMPLETE
@@ -909,12 +965,43 @@ _g_feature_status() {
 - 2025-12-25: Legacy 140KB functions archived
 - 2025-12-25: Symlink-only external integrations
 
-## wins: v5.0.0 RELEASED (2026-01-09) 🚀, DOT DISPATCHER v1.2.0 SHIPPED, 112+ tests passing, Documentation deployed, Enhancement roadmap ready
-## streak: 9
-## last_active: 2026-01-09
+## wins: Secret Management v2.0 Phase 1, 93 unit tests + 14 E2E tests, Session cache with 15-min timeout
+## streak: 11
+## last_active: 2026-01-11
 
 ## 🎯 Next Action:
-**Focus:** v5.0.0 Released - Monitor Homebrew & Plan v5.1.0 🎯
+**Focus:** Secret Management v2.0 Phase 2 🎯
+
+**Phase 1 Complete:** ✅
+- `dot secret add`, `dot secret check`, `dot lock`
+- 15-min session cache with auto-lock
+- 22 new tests (Test Suite 13)
+
+**Options:**
+
+**1. Implement Secret Management v2.0 Phase 2** (~3-4 hours)
+```bash
+# Token wizards from spec:
+- dot token github    # GitHub PAT creation wizard
+- dot token npm       # NPM token wizard
+- dot token pypi      # PyPI token wizard
+- dot secrets         # Dashboard of all secrets
+```
+
+**2. Implement Phase 3** (~2-3 hours)
+```bash
+# Advanced features:
+- dot token <name> --refresh    # Token rotation
+- dot secrets sync github       # Sync to GitHub repo secrets
+- dot env init                  # Generate .envrc for direnv
+```
+
+**3. Performance Optimizations** (v5.2.0)
+```bash
+# From enhancement plan:
+- Dashboard status line caching (30s TTL)
+- Git operation batching
+```
 
 **✅ v5.0.0 Release Complete (2026-01-09):**
 - **Status:** Released and deployed
@@ -1181,3 +1268,22 @@ dot help               # Verify new dispatcher
 - 2026-01-09: DOCS - Live at https://Data-Wise.github.io/flow-cli/
 - 2026-01-09: STATUS - Updated .STATUS with v5.0.0 release completion
 - 2026-01-09: COMPLETE - v5.0.0 fully released (tag, release, docs deployed)
+- 2026-01-10: TEST - Created test-dot-v5.1.1-unit.zsh (19 unit tests for new DOT features)
+- 2026-01-10: TEST - Created test-dot-v5.1.1-e2e.zsh (14 E2E tests with real chezmoi)
+- 2026-01-10: TEST - Created interactive-dot-dogfooding.zsh (8 dishes, "Dotfile Chef" theme)
+- 2026-01-10: TEST - Fixed nullglob for cleanup (no matches error)
+- 2026-01-10: TEST - Fixed read-only variable `status` → `resolve_status`
+- 2026-01-10: TEST - Fixed ask_confirmation Enter handling (newline as default)
+- 2026-01-10: TEST - Total DOT test coverage: 104 automated tests (71 + 19 + 14)
+- 2026-01-10: SPEC - Created SPEC-dot-secret-management-v2-2026-01-10.md
+- 2026-01-10: SPEC - Deep brainstorm: 8 questions, full lifecycle features
+- 2026-01-10: SPEC - Phases: Foundation → Token Wizards → Lifecycle
+- 2026-01-10: SPEC - Features: dot secret add, dot token github/npm/pypi, dot secrets dashboard
+- 2026-01-10: SPEC - Security: 15-min cache, expiration tracking, no secrets in history
+- 2026-01-10: STATUS - Updated .STATUS with test suite and spec completion
+- 2026-01-11: FEAT - Implemented Secret Management v2.0 Phase 1 (dot secret add/check, dot lock)
+- 2026-01-11: FEAT - Added 15-min session cache with auto-lock (7 helper functions)
+- 2026-01-11: FEAT - Added vault status to `dot` status display (time remaining)
+- 2026-01-11: TEST - Added Test Suite 13 with 22 new tests (93 total unit tests)
+- 2026-01-11: DOCS - Updated help text with new secret commands
+- 2026-01-11: PR - Created #198 (feature/secret-management-v2-phase1 → main)

completions/_dot

@@ -13,7 +13,8 @@ _dot() {
     's:Show dotfile sync status (alias)'
     'help:Show help message'
     'version:Show version information'
-    'edit:Edit a dotfile with preview'
+    'add:Add file to chezmoi'
+    'edit:Edit a dotfile with preview (auto-add/create)'
     'e:Edit a dotfile (alias)'
     'sync:Pull changes from remote'
     'pull:Pull changes from remote (alias)'
@@ -62,8 +63,15 @@ _dot() {
       ;;
     args)
       case "$line[1]" in
+        add)
+          # Complete file paths (for files not yet tracked)
+          _files
+          ;;
         edit|e)
-          _describe -t files 'managed file' files
+          # Complete both managed files AND file paths (for auto-add/create)
+          _alternative \
+            'files:managed file:_describe -t files managed\ file files' \
+            'paths:file path:_files'
           ;;
         diff|d|apply|a)
           _describe -t files 'managed file' files

docs/reference/DOT-DISPATCHER-REFERENCE.md

@@ -2,7 +2,7 @@
 
 **Command:** `dot`
 **Purpose:** Dotfile management via chezmoi and Bitwarden
-**Version:** v5.1.0 (Critical Improvements)
+**Version:** v5.1.1 (Auto-Add & Template Enhancements)
 
 ---
 
@@ -18,6 +18,14 @@ The `dot` dispatcher provides a unified interface for managing dotfiles with che
 - ⚡ **Fast** (< 500ms for most operations)
 - 🔌 **Optional** (graceful degradation if tools not installed)
 
+**✨ New in v5.1.1:**
+- ➕ **`dot add`** - Standalone command to add files to chezmoi
+- 🆕 **Auto-add in edit** - `dot edit` offers to add untracked files
+- 📁 **File creation** - `dot edit ~/.newrc` creates new files with `mkdir -p`
+- 🔐 **Template auto-unlock** - Auto-prompts for BW vault when editing `.tmpl` files
+- 📋 **Summary with tips** - Shows next step hints after operations
+- 🏠 **ZDOTDIR support** - Uses standard `${ZDOTDIR:-$HOME}` for shell config paths
+
 **✨ New in v5.1.0:**
 - 🔍 **Hash-based change detection** - SHA-256 comparison catches all edits (even < 1s)
 - 🎯 **Smart error handling** - Specific guidance for each Bitwarden error type
@@ -31,9 +39,18 @@ The `dot` dispatcher provides a unified interface for managing dotfiles with che
 # Check dotfile status
 dot
 
+# Add a file to chezmoi (v5.1.1+)
+dot add ~/.bashrc
+
 # Edit a dotfile (with preview & apply)
 dot edit .zshrc
 
+# Edit untracked file (prompts to add - v5.1.1+)
+dot edit ~/.bashrc
+
+# Create new file (auto-creates parent dirs - v5.1.1+)
+dot edit ~/.config/newapp/config.zsh
+
 # Preview changes without applying (v5.1.0+)
 dot apply --dry-run
 
@@ -87,6 +104,31 @@ Show version information.
 
 ### Dotfile Management
 
+#### `dot add FILE` (v5.1.1+)
+
+Add a file to chezmoi for tracking.
+
+**Features:**
+- Adds existing files to chezmoi
+- Shows source path in chezmoi directory
+- Provides next step hint
+
+**Examples:**
+```bash
+dot add ~/.bashrc        # Add bash config
+dot add ~/.config/app/config.toml  # Add nested config
+```
+
+**Output:**
+```
+✓ Added ~/.bashrc to chezmoi
+  Source: ~/.local/share/chezmoi/dot_bashrc
+
+💡 Tip: dot edit .bashrc to make changes
+```
+
+---
+
 #### `dot edit FILE` / `dot e FILE`
 
 Edit a dotfile with preview and apply workflow.
@@ -97,22 +139,112 @@ Edit a dotfile with preview and apply workflow.
 - Shows diff preview
 - Prompts to apply changes
 - Fuzzy path matching (e.g., `dot edit zshrc` finds `.zshrc`)
+- **Auto-add untracked files** (v5.1.1) - Offers to add existing files not yet tracked
+- **Create new files** (v5.1.1) - Creates non-existent files with `mkdir -p`
+- **Template auto-unlock** (v5.1.1) - Prompts to unlock BW vault for `.tmpl` files
+- **Summary with tips** (v5.1.1) - Shows next step hint after operation
 
 **Examples:**
 ```bash
 dot edit .zshrc          # Edit ZSH config
 dot edit zshrc           # Fuzzy match works too
 dot e gitconfig          # Short alias
+dot edit ~/.bashrc       # Auto-add if untracked (v5.1.1+)
+dot edit ~/.config/new/app.zsh  # Create new file (v5.1.1+)
 ```
 
-**Workflow:**
+**Workflow for tracked files:**
 1. Calculates SHA-256 hash of file before editing
 2. Opens file in editor
 3. You make changes and save (even quick edits < 1s are detected!)
 4. Compares hash after saving - detects ANY content change
 5. Shows diff: `Modified: ~/.zshrc`
 6. Prompts: `Apply changes? [Y/n/d(iff)]`
 7. If yes: Runs `chezmoi apply`
+8. Shows summary with next step tip
+
+**Workflow for untracked files (v5.1.1+):**
+```
+$ dot edit ~/.bashrc
+
+⚠ File not tracked: ~/.bashrc
+
+  a - Add to chezmoi and edit
+  n - Cancel
+
+Add? [a/n] a
+
+✓ Added ~/.bashrc to chezmoi
+ℹ Opening in vim: dot_bashrc
+
+[editor opens, you make changes]
+
+✓ Changes detected!
+─────────────────────────────────────────────────
+[diff preview]
+─────────────────────────────────────────────────
+
+Apply? [Y/n/d] y
+
+✓ Applied changes
+
+📋 ~/.bashrc | Added + Applied
+💡 Tip: dot push to sync to remote
+```
+
+**Workflow for new files (v5.1.1+):**
+```
+$ dot edit ~/.config/newapp/config.zsh
+
+⚠ File does not exist: ~/.config/newapp/config.zsh
+
+  c - Create, add to chezmoi, and edit
+  n - Cancel
+
+Create? [c/n] c
+
+⊙ Created directory: ~/.config/newapp
+✓ Created ~/.config/newapp/config.zsh
+✓ Added ~/.config/newapp/config.zsh to chezmoi
+ℹ Opening in vim: dot_config/newapp/config.zsh
+```
+
+**Template auto-unlock (v5.1.1+):**
+
+When editing `.tmpl` files that contain `{{ bitwarden ... }}` syntax:
+```
+$ dot edit .env.tmpl
+
+[editor opens, you make changes]
+
+✓ Changes detected!
+
+🔐 This template uses Bitwarden secrets.
+   Unlock vault to preview expanded values?
+
+  y - Unlock and preview
+  s - Skip preview (show raw template)
+  n - Cancel
+
+Unlock? [y/s/n] y
+
+ℹ Unlocking Bitwarden vault...
+[password prompt]
+✓ Vault unlocked
+
+─────────────────────────────────────────────────
+[diff preview with secrets expanded]
+─────────────────────────────────────────────────
+
+Apply? [Y/n] y
+
+✓ Applied changes
+
+📋 .env.tmpl | Edited (secrets expanded) + Applied
+💡 Tip: dot push to sync to remote
+```
+
+If you skip unlock, the diff shows raw template syntax like `{{ bitwarden "item" "field" }}`.
 
 **Why hash-based detection? (v5.1.0)**