feat(keychain): make Keychain default backend for secrets #295
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
BREAKING CHANGE: Keychain is now the default backend instead of Bitwarden. This removes the need for `dot unlock` for basic secret operations. Backend Configuration: - FLOW_SECRET_BACKEND=keychain (default) - Keychain only, no unlock needed - FLOW_SECRET_BACKEND=bitwarden - Bitwarden only (legacy mode) - FLOW_SECRET_BACKEND=both - Both backends (Keychain primary, Bitwarden sync) New Commands: - dot secret status - Show backend configuration - dot secret sync - Sync Keychain ↔ Bitwarden - dot secret sync --to-bw - Push Keychain → Bitwarden - dot secret sync --from-bw - Pull Bitwarden → Keychain - dot secret sync --status - Show differences Token Workflows Updated: - dot token github/npm/pypi now respect backend config - Bitwarden checks are conditional on _dot_secret_needs_bitwarden() - Keychain storage is conditional on _dot_secret_uses_keychain() - Added missing Keychain storage to npm/pypi wizards Files Changed (7): - lib/core.zsh: Added backend configuration functions - lib/dispatchers/dot-dispatcher.zsh: Added status/sync commands - lib/keychain-helpers.zsh: Updated help with new commands - commands/secret-tutorial.zsh: Fixed auto-run bug - docs/reference/REFCARD-TOKEN-SECRETS.md: Updated with backend section - docs/specs/SPEC-keychain-default-phase-1-2026-01-24.md: Feature spec - tests/test-keychain-default.zsh: 20 tests for backend switching Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add two test suites for the Keychain Default Phase 1 feature: 1. test-keychain-default-automated.zsh (47 tests) - CI-ready automated tests across 10 test groups - Function existence, backend configuration, helper behavior matrix - Status/sync command verification, help text, command routing - File structure validation, integration sanity checks 2. interactive-keychain-default-dogfooding.zsh (15 tests) - ADHD-friendly gamified interactive testing - Dog feeding mechanics (hunger, happiness tracking) - Visual output verification by user - Star rating system for completion progress All 47 automated tests passing. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Update spec status to Complete with all approval checkboxes marked: - Spec reviewed ✓ - Implementation started ✓ - Tests passing (67 tests) ✓ - Documentation updated ✓ - PR #295 created ✓ Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Keep the ZSH_EVAL_CONTEXT-based detection from dev branch, which correctly detects direct execution vs sourced context. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Data-Wise
pushed a commit
that referenced
this pull request
Jan 25, 2026
- PR #295 merged to dev (backend abstraction) - 67 tests passing (20 unit + 47 automated) - Keychain-only default (optional Bitwarden) - Documentation health check (196 → 0 warnings) - v5.18.0 release complete
Data-Wise
pushed a commit
that referenced
this pull request
Jan 25, 2026
- Update version to 5.19.0 in package.json, CLAUDE.md, flow.plugin.zsh - Update README badges - Add v5.19.0 release notes to CHANGELOG.md - Keychain-default backend (PR #295) - Backend abstraction with 3 modes - 67 comprehensive tests - Zero Bitwarden dependency by default
10 tasks
Data-Wise
added a commit
that referenced
this pull request
Jan 25, 2026
* chore: update .STATUS for v5.17.0 release - Moved v5.17.0 to 'Just Released' section - Updated phase to v5.18.0 (Planning) - Updated version roadmap - Updated recommended next steps - Captured release workflow accomplishments Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * docs(tutorial): add GIF demos to Tutorial 23 - Token Automation - Generated 4 optimized GIF demos (293KB total) - 01-isolated-check.gif (59KB) - 02-cache-speed.gif (75KB) - 03-verbosity.gif (88KB) - 04-integration.gif (71KB) - Fixed VHS tape Output paths (use ./ prefix) - Fixed tape 3 syntax error (removed $? special chars) - Embedded GIFs in tutorial at 4 key locations - 40% size reduction with gifsicle optimization Completes visual documentation for v5.17.0 token automation feature. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * chore: update .STATUS for v5.17.0 GIF completion - Added post-release enhancement section - Documented 4 GIF demos (293KB optimized) - Updated immediate actions (removed GIF generation) - Updated timestamp and status Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * docs: Day 1 - Automation setup & first master doc **Automation Scripts (Skeletons):** - scripts/generate-api-docs.sh - Auto-generate API reference - scripts/generate-doc-dashboard.sh - Coverage metrics - scripts/check-doc-updates.sh - Missing doc warnings **Meta-Guide Enhancements:** - Added comprehensive feature documentation checklist - When adding features (6 sections, 20+ checkboxes) - When modifying features (5 sections) - When removing features (4 sections) - Added documentation decision tree (Mermaid) - Added automation script usage guide **First Master Document:** - docs/help/00-START-HERE.md (600+ lines) - Main documentation hub - 5 ADHD-friendly navigation sections - 8 documentation type overviews - 4 learning paths (Developer, Teacher, Researcher, Weekend) - Interactive learning features **Implementation:** Reference Consolidation Plan Day 1/7 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * docs: Day 2 - Quick Reference & Workflows guides **QUICK-REFERENCE.md (1,000+ lines):** - Complete command reference for all 12 dispatchers - Core commands with expected outputs - Dopamine features (win/yay/goal/streak) - Environment variables & keyboard shortcuts - Tips & tricks for productivity **Sections:** - Core Commands (work, finish, dash, hop, catch) - Git Dispatcher (g) - feature workflow, advanced git - Claude Code (cc) - AI pair programming - R, Quarto, MCP, Obsidian dispatchers - Worktree (wt) - parallel development - DOT (dot) - dotfiles & secrets (Touch ID) - Teaching (teach) - course management - Terminal, Prompt, Vibe dispatchers - Dopamine features & goal tracking **WORKFLOWS.md (800+ lines):** - Daily workflows (morning → work → end of day) - Git workflows (feature branch, worktrees, bug fixes) - Project workflows (setup, context switching) - Teaching workflows (course setup, lecture prep, exams) - Research workflows (R packages, Quarto publishing) - Plugin workflows (226 git aliases, clipboard, z nav) - Advanced workflows (parallel dev, token rotation) - Troubleshooting workflows **Implementation:** Reference Consolidation Plan Day 2/7 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * docs: Day 3 - Troubleshooting guide **TROUBLESHOOTING.md (600+ lines):** - Quick diagnostics (health check first) - Installation issues (plugin not loaded, deps missing) - Command not found errors - Git integration problems (auth, slow ops, conflicts) - Token & authentication (rotation, keychain, expiration) - Performance problems (slow commands, cache issues) - Plugin issues (git aliases, fzf, conflicts) - Atlas integration issues - Teaching workflow issues (Scholar, Quarto, deployment) - Configuration problems (.STATUS, env vars, completions) - Getting help (issue templates, docs links) - Diagnostic commands reference - Prevention tips (regular checks, updates, backups) **Implementation:** Reference Consolidation Plan Day 3/7 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * docs: Day 3 - Start MASTER-DISPATCHER-GUIDE (6/12 dispatchers) **MASTER-DISPATCHER-GUIDE.md (1,500+ lines):** - Framework complete with progressive disclosure pattern - 6 dispatchers fully documented (50% complete): - g (Git) - Beginner → Advanced with feature workflow - cc (Claude Code) - Simple launcher - r (R packages) - Development cycle - qu (Quarto) - Publishing workflow - mcp (MCP servers) - Server management - obs (Obsidian) - Note management **Structure per Dispatcher:** - Basics (Beginner) - Essential daily commands - Intermediate - Advanced features & workflows - Advanced - Power user features & automation - Reference - Complete command list (collapsible) **Remaining 6 dispatchers (Day 4):** - wt (Worktrees) - Parallel development - dot (Dotfiles & Secrets) - Touch ID integration - teach (Teaching) - Course management + Scholar - tm (Terminal) - Profile management - prompt (Prompt engine) - Claude/Gemini switching - v (Vibe mode) - Focus mode **Target:** 3,000-4,000 lines total (currently 1,500) **Implementation:** Reference Consolidation Plan Day 3/7 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * docs: Day 4 - Complete MASTER-DISPATCHER-GUIDE (12/12 dispatchers) **MASTER-DISPATCHER-GUIDE.md (3,000+ lines) - COMPLETE:** Added remaining 6 dispatchers with full documentation: **wt (Worktrees) - Advanced:** - Parallel development without branch switching - Beginner: create, list, remove, prune - Intermediate: workflow patterns (Feature A + urgent Feature B) - Advanced: best practices, integration with work command **dot (Dotfiles & Secrets) - Intermediate → Advanced:** - Dotfile management (edit, sync, restore) - macOS Keychain integration (Touch ID) - Token rotation workflow - Beginner: set/get/list secrets - Intermediate: rotation, git integration - Advanced: backup/restore, automation patterns, cache management **teach (Teaching) - Intermediate → Advanced:** - Course management + Scholar AI integration - Beginner: init, status, deploy - Intermediate: content analysis (AI-powered), exam/quiz generation - Advanced: Scholar templates, batch analysis, deployment workflows **tm (Terminal) - Beginner:** - Terminal profile management - Commands: title, profile, ghost mode, status - Use cases: project-specific profiles, focus mode, presentations **prompt (Prompt Engine) - Beginner:** - AI engine switching (Claude ↔ Gemini) - Commands: status, toggle, use - Use cases: compare responses, cost optimization **v (Vibe Mode) - Beginner:** - Focus mode for deep work - Enables: music, Do Not Disturb, notifications off - Commands: on, off, status - Integration with work sessions **Additional Content:** - Dispatcher comparison table - Progressive disclosure throughout - 300+ code examples with expected outputs - Complete reference sections (collapsible) **Implementation:** Reference Consolidation Plan Day 4/7 - COMPLETE Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * docs: Day 5 - API Reference template & Architecture guide **MASTER-API-REFERENCE.md (1,000+ lines) - Template:** - Complete template structure for API documentation - Documented ~30 core functions with full examples - Function index framework (alphabetical) - Auto-generation integration points - Coverage tracking: 853 total functions, 421 documented (49.4%) **Sections:** - Core Library (logging, colors, project utils, cache) - Keychain Helpers (Touch ID, secret management) - Git Helpers (token validation, branch utils) - Teaching Libraries (concept extraction, analysis cache) - Function Index (A-Z, will be auto-generated) - Change Log (v5.15.0 → v5.17.0) - Contributing guide (adding new functions) **Ready for automation:** `scripts/generate-api-docs.sh` will populate remaining functions --- **MASTER-ARCHITECTURE.md (2,500+ lines) - Complete:** - 8 comprehensive Mermaid diagrams - System overview & layer architecture - Architecture principles (Pure ZSH, ADHD-optimized, Dispatcher pattern) - Component design (Core, Dispatchers, Cache) - Data flow diagrams (Session lifecycle, Git ops, Teaching workflow) - Plugin system architecture - Security model (Keychain, token rotation) - Performance optimization (sub-10ms targets, metrics) - Testing strategy (423 tests, pyramid structure) - Future architecture (remote sync, plugin v2, web dashboard) - Design decision log (3 ADRs) **Mermaid Diagrams:** 1. High-level architecture 2. Layer architecture 3. Cache strategy (multi-layer) 4. Session lifecycle 5. Git operations with token validation 6. Teaching analysis workflow 7. ZSH plugin architecture 8. Secret management (macOS Keychain) **Implementation:** Reference Consolidation Plan Day 5/7 - COMPLETE Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * docs: Day 6 - Implement automation scripts **Complete implementation of 3 automation scripts:** 1. **generate-api-docs.sh (280 lines)** - Extracts function documentation from lib/*.zsh files - Parses structured comment blocks (Function, Purpose, Arguments, etc.) - Generates API documentation entries in MASTER-API-REFERENCE.md format - Options: --dry-run, --file (specific file) - Statistics: total/documented functions, coverage % - Supports both `function name()` and `name()` syntax 2. **generate-doc-dashboard.sh (280 lines)** - Auto-generates docs/DOC-DASHBOARD.md - Coverage metrics by category (Core, Dispatchers, Git, Keychain, Teaching) - Stale documentation detection (> 90 days) - Missing documentation warnings - Visual progress bar and priority recommendations - Quick links to all master documents 3. **check-doc-updates.sh (310 lines)** - Detects new/modified/removed functions since last commit - Checks if documentation was updated alongside code - Warns about undocumented changes - Options: --since COMMIT (default: HEAD~10) - Categories: functions, dispatchers, commands - Actionable recommendations **Features:** - Color-coded output (green/yellow/red/blue) - Structured error handling (set -euo pipefail) - Comprehensive usage documentation - Integration with existing docs structure **Usage:** ```bash # Generate API docs (dry-run mode) ./scripts/generate-api-docs.sh --dry-run # Generate coverage dashboard ./scripts/generate-doc-dashboard.sh # Check for missing doc updates ./scripts/check-doc-updates.sh --since v5.16.0 ``` **Status:** Day 6 complete (automation infrastructure ready) **Next:** Day 7 (archive old files, deploy documentation) * fix: resolve dashboard script issues **Fixed 3 critical issues in generate-doc-dashboard.sh:** 1. **Percentage comparison error** - Removed % symbol before numeric comparisons - Use integer comparison instead of bc floating point - Extract integer part with cut for comparison 2. **Progress bar rendering** - Fixed character encoding issue - Now properly displays █ blocks proportional to coverage 3. **Dispatcher counting** - Fixed: was counting all grep matches instead of unique dispatcher sections - Now correctly counts 12 dispatchers (100%) - Uses fixed total (12) and counts documented from MASTER-DISPATCHER-GUIDE **Results:** - Dashboard now accurately shows 2.7% coverage (19/704 functions) - All categories display correct percentages - Priority correctly shows CRITICAL for <50% coverage - Identifies 9 commands missing documentation **Test:** ```bash ./scripts/generate-doc-dashboard.sh cat docs/DOC-DASHBOARD.md ``` * fix: resolve check-doc-updates macOS compatibility **Fixed BSD grep compatibility issues:** 1. **Replaced Perl regex (-P flag) with Extended regex (-E)** - macOS grep doesn't support -P (Perl regex) - Rewrote patterns using -E and sed for extraction - extract_functions: sed to extract function names - detect_new_functions: sed to parse git diff output - detect_removed_functions: sed to parse git diff output 2. **Simplified summary generation** - Removed recount logic that was causing arithmetic errors - Now shows static next steps message - Counts are already displayed in each section **Test results:** ```bash ./scripts/check-doc-updates.sh --since v5.16.0 ``` **Detected correctly:** - 30 new undocumented functions (v5.17.0 token automation) - 2 modified dispatchers (g, dot) - 4 modified commands (dash, doctor, flow, work) - 0 removed functions - 0 modified documented functions **Status:** All 3 automation scripts now functional on macOS * docs: Day 7 - Archive 66 old reference files **Archived 66 scattered reference files → 3 master documents** **Created:** - `docs/reference/.archive/` directory - `docs/reference/.archive/README.md` - Complete migration map **Archived files (66 total):** - 13 dispatcher-specific references → MASTER-DISPATCHER-GUIDE.md - 7 API references → MASTER-API-REFERENCE.md - 3 architecture docs → MASTER-ARCHITECTURE.md - 10 quick reference cards → help/QUICK-REFERENCE.md - 2 workflow guides → help/WORKFLOWS.md - 4 help/navigation docs → help/00-START-HERE.md - 27 other specialized/duplicate docs → consolidated **Remaining in docs/reference/:** - MASTER-API-REFERENCE.md (1,000+ lines) - MASTER-DISPATCHER-GUIDE.md (3,000+ lines) - MASTER-ARCHITECTURE.md (2,500+ lines) **Archive README includes:** - Complete migration map (old → new locations) - 66-file inventory with categories - Search instructions - Restoration guide **File moves:** - From: docs/reference/\*.md (69 files) - To: docs/reference/.archive/ (66 files) - Kept: 3 MASTER-* files **Impact:** - Reduced reference/ from 69 → 3 files (95% reduction) - All content preserved and consolidated - Clear migration path documented **Next:** Update mkdocs.yml navigation to reflect new structure * docs: Update mkdocs.yml navigation for consolidated structure **Streamlined navigation (71 entries → 9 master entries)** **Before:** - Reference section: 71 entries across 8 subsections - API Reference: 4 entries - Quick References: 5 entries - Dispatchers: 15 entries - Quick Reference Cards: 9 entries - Project Tools: 6 entries - Specialized sections: 32 entries **After:** - Help & Quick Reference: 4 entries (NEW) - 🏠 Start Here - ⚡ Quick Reference - 🔧 Workflows - 🩺 Troubleshooting - Reference: 5 entries - 📚 Master API Reference - 🎯 Master Dispatcher Guide - 🏗️ Master Architecture - 📊 Documentation Dashboard - Legacy Docs Archive **Changes:** 1. New "Help & Quick Reference" top-level section - Quick access to all help/ docs - ADHD-friendly emoji icons - Progressive disclosure pattern 2. Simplified Reference section - 3 master documents (complete coverage) - Documentation dashboard (auto-generated metrics) - Archive link for historical reference 3. Removed 66 archived entries - All content preserved in master docs - Migration map in .archive/README.md - Broken links will 404 (expected, intentional) **Navigation reduction:** 92% fewer navigation entries **User benefit:** Clearer structure, easier to find content **Maintainability:** Single source of truth per topic **Testing:** ```bash mkdocs serve # Verify navigation works mkdocs build # Check for broken links ``` * docs: Update .STATUS for documentation consolidation completion **Documentation Consolidation: Days 1-7 ✅ COMPLETE** **Summary:** - Status: 100% complete (all 7 days implemented) - Impact: 66 files → 7 master documents (95% reduction) - Lines: ~16,500 new master docs, ~36,000 archived - Automation: 3 scripts (870 lines) for maintenance - Deployment: Live at https://Data-Wise.github.io/flow-cli/ **Day 7 Completion (2026-01-24):** - Implemented & tested 3 automation scripts - Archived 66 files with complete migration map - Updated mkdocs.yml navigation (71 → 9 entries) - Built and deployed documentation site - Generated coverage dashboard (2.7% → 80% target) **Master Documents (7 total):** 1. 00-START-HERE.md (600 lines) - Main hub 2. QUICK-REFERENCE.md (1,000 lines) - Commands 3. WORKFLOWS.md (800 lines) - Real workflows 4. TROUBLESHOOTING.md (600 lines) - Common issues 5. MASTER-DISPATCHER-GUIDE.md (3,000 lines) - 12 dispatchers 6. MASTER-API-REFERENCE.md (1,000 lines) - API docs 7. MASTER-ARCHITECTURE.md (2,500 lines) - Architecture **Next Steps (v5.18.0 planning):** - Option A: API documentation completion (2.7% → 80%) - Option B: Config→concept graph integration - Option C-E: Other enhancements **Status:** Ready for v5.18.0 planning * docs(api): Add comprehensive doctor-cache.zsh documentation (13 functions) - Document all cache management functions - Add performance metrics and integration details - Include JSON format specification - Update TOC and library organization - Part of API documentation improvement (2.7% → 80% target) * docs(api): Add doctor command internal API documentation (7 functions) - Document logging helpers (_doctor_log_*) - Document ADHD-friendly category selection menu - Document fix application functions - Document token fix automation - Add Commands Internal API section - Update TOC Progress: 19 → 32 → 39 functions (4.5% → 5.5% coverage) * docs(api): Complete v5.17.0 token automation documentation (30 functions) Documented all new token automation functions: - work.zsh: 3 functions (GitHub integration) - dot-dispatcher.zsh: 5 functions (token rotation, aging, logging) - g-dispatcher.zsh: 2 functions (GitHub remote detection, silent validation) Token Automation Coverage: - ✅ doctor-cache.zsh: 13 functions (caching layer) - ✅ doctor.zsh: 7 functions (ADHD-friendly menu, logging) - ✅ work.zsh: 3 functions (session integration) - ✅ dot-dispatcher.zsh: 5 functions (token lifecycle) - ✅ g-dispatcher.zsh: 2 functions (git integration) Total: 30 new functions fully documented Coverage: 2.7% → 6.8% (19 → 49 functions) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * docs: Update .STATUS for API documentation Phase 1 completion Phase 1 Complete: - 30 v5.17.0 token automation functions documented - Coverage: 2.7% → 7.0% (+158% increase) - All doctor-cache, command helpers, dispatcher integration Progress: - ✅ doctor-cache.zsh: 13 functions - ✅ doctor.zsh: 7 functions - ✅ work.zsh: 3 functions - ✅ dot-dispatcher.zsh: 5 functions - ✅ g-dispatcher.zsh: 2 functions Next Priority: Teaching libraries (Phase 2) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * docs(api): Add comprehensive Teaching Libraries documentation (Phase 2 start) Documented concept-extraction.zsh (8/13 functions): - _extract_concepts_from_frontmatter - _parse_introduced_concepts - _parse_required_concepts - _get_week_from_file - _get_concept_line_number - _build_concept_graph - _load_concept_graph - _save_concept_graph Added comprehensive overview for all 6 teaching libraries: - concept-extraction.zsh (13 functions) - YAML parsing - prerequisite-checker.zsh (20+ functions) - DAG validation - analysis-cache.zsh (40+ functions) - SHA-256 caching - report-generator.zsh (30+ functions) - Markdown/JSON reports - ai-analysis.zsh (15+ functions) - Claude CLI integration - slide-optimizer.zsh (20+ functions) - Heuristic slide breaks Features documented: - Two frontmatter format support (simple + array) - Concept graph building and caching - Integration workflow (extract → validate → cache → analyze) - Performance metrics (50-100ms cached, 2-5s fresh) Coverage: 7.0% → 8.0% (49 → 56 functions, +14% increase) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * docs: Update .STATUS for Phase 2 progress (Teaching Libraries) Phase 2 Started: - concept-extraction.zsh: 8/13 functions documented (62%) - Coverage: 7.0% → 8.0% (+14% increase) - Teaching libraries overview added Progress Summary: - Phase 1 complete: 30 v5.17.0 token automation functions - Phase 2 started: Teaching libraries (8 functions) - Total: 56/704 functions (8.0% coverage) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * docs(api): Complete Teaching Libraries documentation - Phase 2 complete (24 functions) Documented all 6 teaching libraries with comprehensive API reference: **concept-extraction.zsh** (8 functions) - ✅ COMPLETE - All YAML frontmatter parsing functions - Concept graph building and caching - Week extraction and validation **prerequisite-checker.zsh** (5 key functions documented): - _check_prerequisites - Complete validation - _validate_concept_graph - Graph integrity - _detect_circular_dependencies - Cycle detection - _build_prerequisite_tree - Transitive closure - _format_prerequisite_tree_display - Terminal visualization **analysis-cache.zsh** (7 key functions documented): - SHA-256 content hashing - Cache get/set with TTL - Concurrent access (flock) - Automatic cleanup **report-generator.zsh** (4 key functions documented): - Markdown report generation - JSON export - Interactive terminal display - Distribution tables **ai-analysis.zsh** (4 key functions documented): - Claude CLI integration - Cost estimation and tracking - Batch processing - Full/quick analysis modes **slide-optimizer.zsh** (4 key functions documented): - Heuristic break detection - Timing estimation - Key concept extraction - Optimization suggestions Features documented: - All frontmatter formats (simple + array) - Complete caching infrastructure - Cost tracking and batch operations - Comprehensive output formats - Optimization heuristics Integration: - Referenced archived TEACH-ANALYZE-API-REFERENCE.md for complete details - Documented workflow: extract → validate → cache → analyze → optimize - Performance metrics included Coverage: 8.0% → 11.4% (56 → 80 functions, +43% increase) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * chore: update .STATUS for Phase 2 completion (11.4% coverage) * docs: complete documentation consolidation - archive 66 files, update navigation - Archive 66 legacy reference files to docs/reference/.archive/ - Update all internal documentation links - Add 7 new brainstorm/planning documents - Add learning path integration documents - Update mkdocs.yml navigation (71 → 9 entries) - Maintain backward compatibility with archive README Documentation consolidation v5.18.0 complete. * docs(api): Complete Git Helpers documentation - Phase 3 complete (14 functions) - Document all 17 git helper functions from lib/git-helpers.zsh - Fix incorrect function names (_flow_git_* → _git_*) - Add Phase 1 (Smart Post-Generation) functions (11) - Add Phase 2 (Branch-Aware Deployment) functions (6) - Coverage: 11.4% → 13.4% (80 → 94 functions, +14 increase) Teaching workflow git integration fully documented. * docs(api): Complete Keychain Helpers documentation - Phase 4 complete (7 functions) - Document all 7 keychain helper functions from lib/keychain-helpers.zsh - Fix incorrect function names (_flow_keychain_* → _dot_kc_*) - Add secret management functions (add, get, list, delete) - Add Bitwarden import and help functions - Add main dispatcher (_dot_secret_kc) - Coverage: 13.4% → 13.8% (94 → 97 functions, +3 increase) macOS Keychain integration fully documented. * chore: update .STATUS for Phase 4 completion (13.8% coverage) * docs: add link check ignore file and fix broken nav entries - Create .linkcheck-ignore for expected broken links in archived files - Remove broken nav entry: reference/REFCARD-QUARTO-PHASE2.md (archived) - Remove broken nav entry: reference/TESTING-QUICK-REF.md (archived) - Document expected broken links in archived, planning, spec, and bug docs Documentation health check complete. * docs(fix): fix 54 broken links in critical documentation hubs Fix broken internal links in three key documentation hub files after consolidation to master documents: - DOC-INDEX.md: Fixed 26 broken links - Updated reference documentation section to MASTER-* files - Updated API/architecture/user documentation tables - Completely rewrote "Recent Documentation Updates" for v5.18.0 - Updated version to v5.18.0-dev - help/00-START-HERE.md: Fixed 11 broken links - Fixed beginner/intermediate/advanced tutorial path references - Updated reference cards to master documents - Fixed researcher/developer guide links - Updated documentation stats (13.8% coverage, 23 tutorials) - Updated version to v5.18.0-dev - tutorials/LEARNING-PATH-INDEX.md: Fixed 17 broken links - Updated all DISPATCHER-REFERENCE.md → MASTER-DISPATCHER-GUIDE.md - Updated COMMAND-QUICK-REFERENCE.md → help/QUICK-REFERENCE.md - Updated ALIAS-REFERENCE-CARD.md → MASTER-DISPATCHER-GUIDE.md - Updated ARCHITECTURE-OVERVIEW.md → MASTER-ARCHITECTURE.md - Added section anchors for dispatcher references - Updated version to v5.18.0-dev Total: 54 broken links fixed across 3 critical documentation files Related to documentation consolidation (66 files → 7 master docs) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * chore: update .STATUS with documentation health check completion Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * docs(version): bump version to v5.18.0-dev Update version references across documentation to reflect v5.18.0-dev milestone after completing documentation consolidation and API coverage improvement. Changes: - docs/index.md: Version badge + v5.18.0 "What's New" section - Documentation Consolidation (66 → 7 files, 95% reduction) - API Coverage Improvement (2.7% → 13.8%, +411% increase) - Moved v5.17.0 to "Previous Releases" - docs/help/QUICK-REFERENCE.md: Version field v5.17.0-dev → v5.18.0-dev - CLAUDE.md: Updated all version references - Current Version: v5.18.0-dev - Latest Release: v5.17.0 (2026-01-23) - Updated status and development cycle sections - Marked v5.17.0 as released with PR links - README.md: Version badge + v5.18.0 "What's New" - Added v5.18.0 section with documentation highlights - Marked v5.17.0 as released Version progression: v5.17.0-dev → v5.18.0-dev Latest release: v5.17.0 (2026-01-23) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * chore: update .STATUS with v5.18.0 milestone completion Session summary for v5.18.0 milestone (2.5 hours): - API Documentation Phases 2-4 complete (83 total functions) - Documentation health check (54 critical links fixed) - Version update to v5.18.0-dev (all docs updated) Coverage: 2.7% → 13.8% (+411% increase) Commits: 10 total (all pushed and deployed) Status: v5.18.0 milestone complete, ready for release Next options: A) Continue API documentation (toward 80% coverage) B) Prepare v5.18.0 release (create PR, tag, publish) C) Feature development (new capabilities) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * docs(token-secrets): comprehensive documentation & code cleanup PHASE 1: Code Cleanup - Remove dead code: _dot_secret_kc() function (never called) - Add inline comments explaining -j flag security model - Update tests to use _dot_secret() instead of _dot_secret_kc() - Verify no remaining references to removed function PHASE 2: Quick Reference Card - Create 2-page REFCARD-TOKEN-SECRETS.md (350+ lines) - Scannable command table, workflows, architecture diagram - ADHD-friendly layout with visual hierarchy - Provider-specific notes (GitHub, npm, PyPI) PHASE 3: Comprehensive Guide - Create TOKEN-MANAGEMENT-COMPLETE.md (1000+ lines) - 10 sections covering complete token lifecycle - Step-by-step workflows with expected output - Migration guides, security best practices - Troubleshooting for common issues PHASE 4: Interactive Tutorial - Create commands/secret-tutorial.zsh (600+ lines) - 7 interactive lessons with progress tracking - Safe demo mode (creates fake token for practice) - ADHD-friendly design with visual feedback - Integrated into dot secret dispatcher PHASE 5: Documentation Integration - Update mkdocs.yml navigation - Add tutorial command to dot secret help Files modified: 6 (lib, tests, mkdocs.yml) Files created: 3 (tutorial, guide, quick ref) Total documentation: ~2000 lines Test coverage: 36/39 tests passing (92.3%) Architecture clarifications: - Dual storage (Bitwarden + Keychain) is intentional - Metadata -j flag usage is correct and documented - Security model explained in inline comments Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * chore: create worktree for v5.19.0 Keychain-default Phase 1 - Created feature branch: feature/keychain-default-phase-1 - Worktree location: ~/.git-worktrees/flow-cli/feature-keychain-default-phase-1 - Updated .STATUS with active worktree tracking - Ready for Phase 1 implementation (6 hours estimated) Plan: /Users/dt/.claude/plans/parsed-hugging-platypus.md Spec: docs/specs/SPEC-KEYCHAIN-DEFAULT-v5.19.0.md * chore: update .STATUS with v5.19.0 planning session completion Session Summary: - Comprehensive brainstorming (12 user decisions) - Created implementation plan (3 phases, 18 hours) - Saved spec: docs/specs/SPEC-KEYCHAIN-DEFAULT-v5.19.0.md - Created worktree for Phase 1 - Ready for NEW implementation session Next: Start new session in worktree for Phase 1 implementation * fix(tutorial): prevent auto-launch on plugin load **Root Cause:** Tutorial auto-launched every time flow-cli loaded because: 1. Source detection used ${(%):-%x} == ${0} which matches when sourced 2. Path resolution used ${0:A:h}/../.. instead of $FLOW_PLUGIN_DIR **Changes:** - Use ZSH_EVAL_CONTEXT for proper source detection (only "toplevel" when executed directly) - Use $FLOW_PLUGIN_DIR for reliable path resolution **Testing:** - Plugin loads silently without tutorial ✅ - Tutorial works when called via 'dot secret tutorial' ✅ Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * docs: add Claude Code environment troubleshooting guide **What:** - Created comprehensive troubleshooting guide for Claude Code environment - Documents tutorial auto-launch bug fix (commit e7d24e0) - Explains flow-cli behavior in different shell contexts **Key Topics:** - Bug fix details (source detection, path resolution) - Claude Code shell snapshot behavior - Why flow-cli doesn't load automatically in Claude Code - Workarounds for Claude Code sessions - Diagnostic commands and testing checklist **Files:** - docs/troubleshooting/CLAUDE-CODE-ENVIRONMENT.md (new) - CHANGELOG.md (updated with bug fix entry) - mkdocs.yml (added to Help & Quick Reference section) **Benefits:** - Future reference for similar issues - Helps users understand Claude Code limitations - Documents testing procedures for plugin loading Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * docs(fix): update broken links in index.md and add validation report **What:** - Fixed 4 broken links in docs/index.md - Created comprehensive documentation validation report **Broken Links Fixed:** - DOCTOR-TOKEN-API-REFERENCE.md → .archive/ path - REFCARD-OPTIMIZATION.md → .archive/ path - COMMAND-QUICK-REFERENCE.md (2x) → help/QUICK-REFERENCE.md **Validation Results:** - ✅ Build: SUCCESS (0 errors, 196 non-critical warnings) - ✅ New content: CLAUDE-CODE-ENVIRONMENT.md validated - ✅ Navigation: All links working - ✅ Deployment: APPROVED **Files:** - docs/index.md (4 link updates) - docs/DOCS-VALIDATION-REPORT-2026-01-24.md (comprehensive report) **Impact:** - Homepage now links to correct documentation - Reduced warnings from 200 → 196 - All critical paths validated Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * chore: release v5.18.0 **Version Bump:** - package.json: 5.16.0 → 5.18.0 - flow.plugin.zsh: 5.16.0 → 5.18.0 - README.md: v5.18.0-dev → v5.18.0 - CLAUDE.md: Updated all version references - CHANGELOG.md: Moved Unreleased → v5.18.0 (2026-01-24) **Release Highlights:** - Tutorial auto-launch bug fix - Claude Code environment troubleshooting guide - Documentation link fixes - 38 commits since v5.17.0 **Changes in v5.18.0:** - Fixed: Tutorial auto-launch (source detection + path resolution) - Added: Claude Code troubleshooting guide (303 lines) - Fixed: 4 broken documentation links in index.md - Fixed: Release script for archived references Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * chore: update .STATUS with v5.18.0 release completion * docs: update version badge to v5.18.0 (remove -dev suffix) * docs: fix all broken links and markdown formatting - Fixed 196 → 0 WARNING/ERROR messages in mkdocs build - Updated 130+ files with corrected reference links - Mapped archived files (reference/*.md → reference/.archive/*.md) - Updated links to master documents (MASTER-DISPATCHER-GUIDE, MASTER-API-REFERENCE) - Fixed code file links in bug docs (converted to code references) - Removed placeholder tutorial links (XX-title.md, 24-git-workflow.md) - Formatted all markdown files with prettier - All builds now succeed with only 9 INFO-level anchor warnings Changes: - COMMAND-QUICK-REFERENCE.md → help/QUICK-REFERENCE.md - DISPATCHER-REFERENCE.md → MASTER-DISPATCHER-GUIDE.md - ARCHITECTURE.md → MASTER-ARCHITECTURE.md - Many archived references → .archive/ directory Build status: ✅ Clean (0 errors, 0 warnings) * feat(keychain): make Keychain default backend for secrets (#295) * feat(keychain): make Keychain default backend for secrets BREAKING CHANGE: Keychain is now the default backend instead of Bitwarden. This removes the need for `dot unlock` for basic secret operations. Backend Configuration: - FLOW_SECRET_BACKEND=keychain (default) - Keychain only, no unlock needed - FLOW_SECRET_BACKEND=bitwarden - Bitwarden only (legacy mode) - FLOW_SECRET_BACKEND=both - Both backends (Keychain primary, Bitwarden sync) New Commands: - dot secret status - Show backend configuration - dot secret sync - Sync Keychain ↔ Bitwarden - dot secret sync --to-bw - Push Keychain → Bitwarden - dot secret sync --from-bw - Pull Bitwarden → Keychain - dot secret sync --status - Show differences Token Workflows Updated: - dot token github/npm/pypi now respect backend config - Bitwarden checks are conditional on _dot_secret_needs_bitwarden() - Keychain storage is conditional on _dot_secret_uses_keychain() - Added missing Keychain storage to npm/pypi wizards Files Changed (7): - lib/core.zsh: Added backend configuration functions - lib/dispatchers/dot-dispatcher.zsh: Added status/sync commands - lib/keychain-helpers.zsh: Updated help with new commands - commands/secret-tutorial.zsh: Fixed auto-run bug - docs/reference/REFCARD-TOKEN-SECRETS.md: Updated with backend section - docs/specs/SPEC-keychain-default-phase-1-2026-01-24.md: Feature spec - tests/test-keychain-default.zsh: 20 tests for backend switching Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * test(keychain-default): add comprehensive dogfooding test suites Add two test suites for the Keychain Default Phase 1 feature: 1. test-keychain-default-automated.zsh (47 tests) - CI-ready automated tests across 10 test groups - Function existence, backend configuration, helper behavior matrix - Status/sync command verification, help text, command routing - File structure validation, integration sanity checks 2. interactive-keychain-default-dogfooding.zsh (15 tests) - ADHD-friendly gamified interactive testing - Dog feeding mechanics (hunger, happiness tracking) - Visual output verification by user - Star rating system for completion progress All 47 automated tests passing. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * docs(spec): mark keychain-default-phase-1 as complete Update spec status to Complete with all approval checkboxes marked: - Spec reviewed ✓ - Implementation started ✓ - Tests passing (67 tests) ✓ - Documentation updated ✓ - PR #295 created ✓ Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> --------- Co-authored-by: Test User <test@example.com> Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com> * chore: update .STATUS with v5.19.0 Phase 1 completion - PR #295 merged to dev (backend abstraction) - 67 tests passing (20 unit + 47 automated) - Keychain-only default (optional Bitwarden) - Documentation health check (196 → 0 warnings) - v5.18.0 release complete * chore: add tests/logs/ to .gitignore * chore: prepare v5.19.0 release - Update version to 5.19.0 in package.json, CLAUDE.md, flow.plugin.zsh - Update README badges - Add v5.19.0 release notes to CHANGELOG.md - Keychain-default backend (PR #295) - Backend abstraction with 3 modes - 67 comprehensive tests - Zero Bitwarden dependency by default --------- Co-authored-by: Test User <test@example.com> Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
dot unlockrequired!)dot secret statusanddot secret synccommandsBreaking Changes
FLOW_SECRET_BACKENDnow defaults tokeychaininstead of requiring Bitwarden. Users who want the old behavior can setFLOW_SECRET_BACKEND=bitwarden.Backend Configuration
keychain(default)bitwardenbothNew Commands
Test plan
Files Changed (7)
lib/core.zsh- Backend configuration functionslib/dispatchers/dot-dispatcher.zsh- Status/sync commands, token workflow updateslib/keychain-helpers.zsh- Updated help textcommands/secret-tutorial.zsh- Fixed auto-run bugdocs/reference/REFCARD-TOKEN-SECRETS.md- Backend documentationdocs/specs/SPEC-keychain-default-phase-1-2026-01-24.md- Feature spectests/test-keychain-default.zsh- 20 tests🤖 Generated with Claude Code