Changelog

All notable changes to this dotfiles repository will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

[4.0.0] - 2026-04-15

Stable Release - Full Go CLI, Multi-Platform Distribution, Code Quality

This is the first stable v4 release. The codebase has been fully rewritten in Go, all distribution channels are automated, and the code quality bar has been raised through multiple inspection cycles.

See rc1–rc6 release notes below for the full history of changes since v3.

[4.0.0-rc6] - 2026-04-15

Release Candidate 6 - Distribution, Code Quality & Platform Fixes

Added

GoReleaser-based release workflow — Replaced manual binary build workflow with GoReleaser. Homebrew tap (blackwell-systems/homebrew-tap), Scoop bucket (blackwell-systems/scoop-bucket), and winget (BlackwellSystems.blackdot) are now automatically updated on every tag push. No more manual SHA256 updates.
go install support — Updated module path to github.com/blackwell-systems/blackdot/v4 (Go major version convention). Installable via go install github.com/blackwell-systems/blackdot/v4/cmd/blackdot@latest.
Homebrew tap formula — brew install blackwell-systems/tap/blackdot now works.
Scoop bucket — scoop install blackdot now works via blackwell-systems/scoop-bucket.
Devcontainer feature (ghcr.io) — Fixed publish workflow broken since Dec 2025. Feature now publishes to ghcr.io/blackwell-systems/blackdot on every release.
Tmux integration with session persistence — Added tmux to Brewfile.minimal as a core tool. Bootstrap now installs TPM (Tmux Plugin Manager) and symlinks blackdot/tmux/tmux.conf to ~/.config/tmux/tmux.conf. Default config includes tmux-resurrect for session save/restore (Ctrl-A + Ctrl-s to save, Ctrl-A + Ctrl-r to restore). Uses XDG standard path (tmux.conf not .tmux.conf).
Makefile for local development builds — make build compiles for the host architecture, make build-linux / make build-darwin cross-compile for both amd64 and arm64, and make build-all builds everything. Embeds version, commit, and date via ldflags. This is for contributors building from source — end users continue to install via install.sh.
Architecture-dispatch wrapper script — scripts/blackdot-wrapper.sh auto-detects OS and architecture and execs the correct platform-specific binary (e.g. blackdot-linux-arm64). Installed as bin/blackdot by make build-linux so a single path works on mixed-arch shared filesystems and bind-mounted container volumes.
SSH keys subcommands — blackdot tools ssh keys is now a parent command with list, load, unload, and clear subcommands. Both ssh keys unload <key> and ssh unload <key> work. Called without a subcommand it still lists keys.
SSH hosts alias — blackdot tools ssh hosts now works as an alias for ssh list, which is more intuitive for displaying configured SSH hosts.
SSH remove-host command — blackdot tools ssh remove-host <name> removes a host block and all its directives from ~/.ssh/config. Inverse of add-host.
Auto-install prompt on missing binary — When shell init detects no compatible binary (e.g. first time in a Lima VM or Docker container), it prompts Install now? [y/N] in interactive shells. Answering y downloads the correct platform binary automatically. Answering n explains degraded mode and how to install later.
Degraded-mode banner on Linux/container entry — When entering a Lima VM or container where the blackdot binary is not installed, a visible warning is displayed explaining that features, vault, and CLI commands are unavailable, with the install command to fix it.
AUTO_CD — setopt AUTO_CD enabled in 20-env.zsh so typing .. or any directory path navigates without the cd prefix.
Devcontainer Integration
- New blackdot devcontainer command for generating devcontainer configurations
- blackdot devcontainer init - generate devcontainer.json with blackdot feature
- blackdot devcontainer images - list available base images
- blackdot devcontainer services - list available services for docker-compose
- --services flag for init command to generate docker-compose.yml
- --stack flag for init command to apply service presets (web, aws, full, mongo)
- Docker Compose support with postgres, redis, mysql, mongo, sqlite, localstack, minio
- Health checks for all services with automatic readiness detection
- Conflict detection for incompatible service combinations
- Automatic environment variable injection for service connections
- Support for Go 1.23, Python 3.13, Node 22, Rust, Java 21, Ubuntu, Alpine, Debian
- Four presets: minimal, developer, claude, full
- SSH agent socket forwarding for git operations in containers
- VS Code extension recommendations per language
- Startup banner displaying "[blackdot] ⚫💨📦 credentials loaded" after setup completes
Devcontainer Feature for ghcr.io
- Publishable devcontainer feature at ghcr.io/blackwell-systems/blackdot
- Install script for container builds
- Shell integration for bash/zsh
- Configurable presets and versions
CI/CD
- GitHub Actions workflow to publish devcontainer feature to ghcr.io
- Automatic version tagging matching blackdot releases
CLI Enhancements
- Shell completion command (blackdot completion) for bash, zsh, fish, and powershell
- --dry-run flag for backup restore - preview files before restoring
- --dry-run flag for rollback - preview rollback without making changes
- --dry-run flag for features enable/disable/preset - preview feature changes
Documentation
- New docs/devcontainers.md user guide
- Devcontainer section in CLI reference
- Added to feature registry as devcontainer integration
Test Coverage
- Comprehensive tests for internal/cli/cli_test.go
- Tests for internal/shell/shell_test.go (77.4% coverage)
- Tests for internal/template/engine_test.go (71.4% coverage)
- 16 tests for devcontainer command

Changed

SSH list/hosts output — Now displays a styled colored table with Host, HostName, User, Port, and IdentityFile columns instead of a plain text list.
SSH agent output — Now displays loaded keys in a styled colored table instead of raw ssh-add -l output.
blackdot command uses resolved binary — shell-init emits a blackdot() wrapper function that always invokes the platform-correct binary. Prevents exec format error on shared filesystems.
Shell-init cache is platform-specific — Cache file is now shell-init-${os}-${arch}.zsh so macOS and Linux don't overwrite each other on shared filesystems.
README rewrite — 734 → 232 lines. Value proposition up front, inline links to docsify site pages.
Documentation Improvements
- Updated architecture diagram to night mode for better visibility
- Renamed primary alias from d to b for blackdot branding consistency
- Removed README-FULL.md, moved unique content to subdocs
- Updated directory structure documentation to reflect Go-based architecture
- Improved docsify coverpage with separate platform-specific install blocks
- Updated dotclaude integration docs for Go migration (removed shell script references)
- Streamlined README (removed use cases section, fixed broken links)
- Fixed BRAND.md link path (moved to docs/)

Fixed

Code quality fixes from inspection — Resolved 7 findings from automated inspection:
- registry.go: strings.ReplaceAll("_","_") no-op → (".", "_") — feature names with dots were not normalizing to correct env var format
- doctor.go: Removed dead total variable; replaced duplicate getBlackdotDir() with canonical BlackdotDir()
- template.go: Renamed errors variable that was shadowing the stdlib errors package
- config.go: Silent json.Unmarshal discard now returns error on malformed JSON — prevents silent config corruption
- backup.go: tw.Write() return value was ignored; now checked
- shell_init.go: Wired internal/shell package for auto-detection; was previously unused in production
Cross-platform binary resolution — Shell init prefers platform-specific binaries with ELF/Mach-O format validation. Fixes exec format error when a macOS host shares dotfiles with a Lima/NFS-mounted Linux VM.
Installer saves platform-specific binary names — Saved as blackdot-${os}-${arch} with a symlink; multiple platforms can coexist on shared filesystems.
Zsh modules not loading in new tmux panes — Switched zshrc from ${0:A:h} to ${(%):-%x}. $0 resolves to the shell name during automatic startup, causing zero modules to load in tmux panes.
Homebrew PATH not available in tmux panes — Moved Homebrew shellenv to early PATH setup in 00-init.zsh, before binary resolution.
Modern CLI tools block shell when feature disabled — ls, ll, la etc. now fall back to coreutils equivalents instead of printing "Feature disabled".
Alias/function collisions in zsh — Removed 11 duplicate aliases causing parse error near '()' on shell load.
os.Exit() breaking testability — Replaced 3 os.Exit(1) calls with proper error returns; converted Run handlers to RunE.
Silent error ignoring — Added proper error handling in tools_python.go, tools_cdk.go, tools_rust.go, tools_docker.go.
Context propagation in vault functions — Added context.Context to all 14 vault operations; Bitwarden CLI calls are now cancellable with Ctrl+C.
Architecture diagram contrast and readability
PowerShell module manifest missing Initialize-Starship export
PASS_PREFIX in vault docs updated from dotfiles to blackdot

Removed

Zellij — Removed from Brewfile, config, and bootstrap. Tmux with resurrect covers the same use case.

[4.0.0-rc5] - 2025-12-11

Release Candidate 5 - Final Blackdot Rebrand Polish

Changed

Complete Rebrand Finalization
- Final pass on all JSON and fixture files
- Documentation and config files fully updated
- CLI branding refinement with visual identity
- All remaining Dotfiles strings replaced in user-facing output

Added

Binary name added to .gitignore for cleaner repository
Visual branding enhancement in CLI output
Improved cross-platform consistency in naming

Fixed

Remaining references to Dotfiles in Go CLI
User-facing strings now consistently use blackdot terminology
Documentation consistency across all file types

[4.0.0-rc4] - 2025-12-11

Release Candidate 4 - Rebrand Completion & CI Improvements

Changed

Complete Rebrand Finalization
- Shell scripts and templates updated with blackdot branding
- Go CLI fully rebranded (commands, paths, config)
- All hooks and shell modules updated
- Setup detection now uses blackdot directory name
- Config CLI uses blackdot paths throughout

Added

Documentation Improvements
- Comprehensive cross-platform documentation updates
- Improved cross-platform awareness in README
- Updated README-FULL.md for Go-first architecture
- Condensed Features section in README (563 to 24 lines)
- Added missing ssh_tools and docker_tools feature documentation
CI/CD Enhancements
- Enhanced Windows testing with module import validation
- Package validation for winget schema
- Corrected packages.json validation path

Fixed

Setup detection to use blackdot directory name consistently
Config CLI paths and branding throughout codebase
CI validation paths for Windows package schema

[4.0.0-rc3] - 2025-12-10

Release Candidate 3 - Complete Rebrand + Vault Go Parity

BREAKING CHANGE: Complete rebrand from dotfiles to blackdot. All commands, environment variables, paths, and configuration locations have been renamed.

Changed - Complete Rebrand (dotfiles → blackdot)

Go Module & CLI
- Renamed Go module from github.com/user/dotfiles to github.com/blackwell-systems/blackdot
- CLI binary renamed from dotfiles to blackdot
- All internal package paths updated
Environment Variables (DOTFILES_* → BLACKDOT_*)
- DOTFILES_DIR → BLACKDOT_DIR
- DOTFILES_DEBUG → BLACKDOT_DEBUG
- DOTFILES_OFFLINE → BLACKDOT_OFFLINE
- DOTFILES_VAULT_BACKEND → BLACKDOT_VAULT_BACKEND
- DOTFILES_SKIP_CHECKSUM → BLACKDOT_SKIP_CHECKSUM
- All other DOTFILES_* variables renamed to BLACKDOT_*
Configuration Paths
- ~/.config/dotfiles/ → ~/.config/blackdot/
- ~/.cache/dotfiles/ → ~/.cache/blackdot/
- ~/workspace/dotfiles/ → ~/workspace/blackdot/
Shell Scripts & Aliases
- Command alias: dotfiles → blackdot (short alias d retained)
- Function names: dotfiles-upgrade → blackdot-upgrade
- Cache files: .dotfiles-update-check → .blackdot-update-check
- All zsh/zsh.d/*.zsh files updated
- All vault/*.sh scripts updated
- All lib/*.sh scripts updated
Install & Deployment
- install.sh updated with new ASCII art and paths
- Dockerfile.medium updated with new paths
- Binary names: dotfiles-${os}-${arch} → blackdot-${os}-${arch}
Documentation
- Selective update of command references, env vars, paths, URLs
- Preserved generic "dotfiles" references where conceptually appropriate

Added - Vault Go Implementation (Full Feature Parity)

All shell script functionality now implemented in Go, enabling multi-backend support:

SSH Key Handling
- extractSSHPrivateKey() - Extracts private key block from vault notes
- extractSSHPublicKey() - Extracts public key and creates .pub file
- Validates key structure (OPENSSH, RSA, EC, DSA key formats)
Pre-restore Safety
- Drift check before restore (warns if local files differ from vault)
- Auto-backup via blackdot backup create before restore
- Per-file backup (.bak-TIMESTAMP) before overwriting
Enhanced vault status
- Full drift detection (local vs vault comparison)
- Shows drifted items, missing from vault, missing locally
- Displays vault.last_pull and vault.last_push timestamps
- Recommends next actions based on state
Interactive Discovery (vault scan)
- Merge/Replace/Preview options for existing config
- Automatic backup before overwrite
- Saves directly to ~/.config/blackdot/vault-items.json
Timestamps & State
- Tracks vault.last_pull and vault.last_push in config.json
- Saves drift state to ~/.cache/blackdot/vault-state.json
- Human-readable "Xm ago", "Xh ago", "Xd ago" display
Offline Mode
- BLACKDOT_OFFLINE=1 skips vault operations gracefully
Environment Secrets
- Creates ~/.local/load-env.sh loader script automatically
- Proper 600 permissions on secrets files
CLI Help
- Fixed subcommand help to show flags properly
- All vault subcommands now display their specific options

Added - Migration Support

User Migration Script (scripts/migrate-dotfiles-to-blackdot.sh)
- Renames config directories
- Updates environment variables in shell configs
- Migrates aliases and functions
- Backs up before making changes

Added - Windows Native Support

PowerShell One-Line Installer (install-windows.ps1)
- Native Windows installation via PowerShell
- Automatic git installation via winget if missing
- PowerShell module auto-import configuration
- Minimal mode support for shell-only config
- Usage: irm https://raw.githubusercontent.com/blackwell-systems/blackdot/main/install-windows.ps1 | iex
PowerShell Module Enhancements
- Complete feature parity with Zsh implementation (1,346 lines)
- Triple-layer hook system (Go CLI + Zsh runtime + PowerShell runtime)
- Native Windows path handling
- Cross-platform Go binary execution

Changed - Documentation Overhaul

Comprehensive documentation updates to reflect v4.0.0-rc3 Go-first architecture:

Architecture Documentation
- Complete rewrite of directory structure in README-FULL.md
- Removed references to 11 deleted lib/*.sh files
- Added Go implementation structure (cmd/, internal/, powershell/)
- Updated Framework Architecture diagrams with Mermaid
- Added Templates to architecture diagram
- Platform table now includes Windows native support
- Architecture layers diagram updated: Go CLI + Shell integration (Zsh/PowerShell)
Command Reference Updates
- Fixed 14 files with dotfiles → blackdot command references
- Updated cli-reference.md with correct command examples
- Fixed Mermaid diagrams in architecture.md (sync, doctor, backup)
- Updated all code blocks to use blackdot CLI
- Removed duplicate sections and outdated content
Cross-Platform Documentation
- README-FULL.md: Added Windows/PowerShell examples throughout
- Platform-Independent Components section rewritten for Go architecture
- SSH key auto-add examples for both Zsh and PowerShell
- Environment variable examples for Zsh and PowerShell
- DOTCLAUDE-INTEGRATION.md: Added PowerShell configuration examples
- Configuration structure updated to show powershell/ directory
Hook System Documentation
- Complete rewrite of hooks.md (191 additions, 55 deletions)
- Documented triple-layer architecture (Go CLI + Zsh + PowerShell)
- Added PowerShell hook examples for all 24 hook points
- Mermaid diagram showing platform branching
- PowerShell cmdlets documented: Register/Invoke/Get/Test-BlackdotHook
- Native PowerShell hooks comparison table
- Cross-platform hook file support (.sh and .ps1)
Go-First Architecture Documentation
- CLAUDE.md: Complete rewrite of "Adding a New Feature" workflow
- Updated feature registry references (lib/_features.sh → internal/feature/registry.go)
- Updated configuration layer references (lib/_config.sh → internal/config/config.go)
- Updated backup customization (bin/blackdot-backup → internal/cli/backup.go)
- Updated vault system references to vaultmux Go library
- Developer guide now shows Go code examples
File Path Corrections
- developer-tools.md: Fixed zsh.d file paths (50-aws.zsh → 60-aws.zsh, etc.)
- templates.md: Fixed DEBUG command examples
- backup.md: Fixed restore and config command references
- features.md: Fixed features check examples
- windows-setup.md: Fixed doctor/setup command references
Removed Obsolete Documentation
- Deleted DESIGN-workspace-target.md (574 lines of outdated planning doc)
- Deleted extending-backends.md (550 lines describing shell-based vault extension)
- Vault extension now done via vaultmux Go library contribution
- Removed sidebar links to deleted documentation
Documentation Condensing
- vault-README.md: Condensed by 38% while improving clarity
- Updated vault and state docs for vaultmux architecture
- Minimized README and fixed outdated references
- Simplified one-line install documentation

Fixed

Vault subcommand help now shows proper flags (--force, --dry-run, etc.)
Config paths consistently use blackdot instead of dotfiles

Removed

Vault Shell Scripts - Deleted 20 shell scripts and backend implementations (~6,000 lines) now that Go has full parity:
- 16 vault operations scripts: vault/*.sh (restore-.sh, sync-.sh, create-.sh, delete-.sh, etc.)
- 3 backend implementations: vault/backends/*.sh (bitwarden.sh, 1password.sh, pass.sh)
- 1 interface specification: vault/backends/_interface.md
- All functionality now in internal/cli/vault.go + vaultmux Go library
Shell script vault fallback (Go implementation now has full parity)
Legacy DOTFILES_* environment variables (use BLACKDOT_*)
Old backup file README_12_03_2025.md

Repository

Repo rename ready: blackwell-systems/dotfiles → blackwell-systems/blackdot
- All internal references updated
- Docsify config updated
- Install/uninstall URLs updated

Migration Guide

Update shell config:

# Replace in ~/.zshrc or ~/.bashrc:
export DOTFILES_DIR=...  →  export BLACKDOT_DIR=...

Move config directory:

mv ~/.config/dotfiles ~/.config/blackdot

Or run the migration script:

./scripts/migrate-dotfiles-to-blackdot.sh

Update aliases:

# Old: dotfiles status
# New: blackdot status

[4.0.0-rc2] - 2025-12-10

Added

Windows Support Enhancements
- PowerShell hook for blocking dangerous git operations (force push, hard reset)
- PowerShell git sync check hook
- Starship prompt configuration for Windows (119 lines)
- Added Starship to Windows packages (enhanced tier)
Enhanced Go Setup Wizard (internal/cli/setup.go)
- Windows workspace junction support
- Cross-platform prompt theme configuration
- Improved state detection and inference
- Better error handling and user feedback
- Expanded from basic implementation to production-ready (356 lines of improvements)
Documentation
- Comprehensive rebranding strategy document (dotfiles → blackdot)
- Complete Go setup wizard implementation plan (IMPL-setup-wizard-go.md, 618 lines)
- Expanded Go refactor documentation with Windows support details
- Updated hooks README with PowerShell examples

Changed

install.sh - Now prefers Go binary by default
bootstrap-dotfiles.sh - Enhanced with better p10k handling
Brewfile.minimal - Added age package for encryption support
PowerShell module - Added Windows-specific utilities and helpers

Fixed

Release workflow validation now uses Go tests instead of deprecated BATS suite
Added zsh dependency installation in CI validation step

[4.0.0-rc1] - 2025-12-09

WARNING - Breaking Changes: This is a major release. The Go binary is now the sole CLI implementation. Shell fallback (DOTFILES_USE_GO=0) has been removed. Direct calls to bin/blackdot-* scripts and sourcing lib/*.sh libraries will no longer work.

Known Issues

BATS test suite migration in progress - old shell script tests temporarily disabled
Use Go test suite for validation: go test ./...
Full test suite coverage will be restored in v4.0.0 final release

Changed

Phase 3 Migration Complete - Go binary is now the sole CLI implementation
- Renamed binary from dotfiles-go to blackdot
- Removed shell fallback (DOTFILES_USE_GO escape hatch no longer available)
- Deleted 19 deprecated bin/blackdot-* shell scripts (~7,500 lines)
- Deleted 12 deprecated lib/*.sh libraries (~5,500 lines)
- Simplified 40-aliases.zsh by removing fallback code (~550 lines)
- Total reduction: ~13,500 lines of shell code
Binary Download Now Default - install.sh downloads Go binary by default
- No longer need --binary flag for recommended install
- Use --no-binary to opt-out if needed
- Simpler install: curl -fsSL <url> | bash now includes binary

Added

Shell Init Command - New blackdot shell-init for shell function initialization
- Outputs feature_enabled, require_feature, feature_exists, feature_status functions
- Supports zsh, bash, fish, and PowerShell
- Usage: eval "$(dotfiles shell-init zsh)" in shell config
- Replaces deleted lib/_features.sh with Go-backed implementation
- Updated 00-init.zsh to use shell-init instead of sourcing deleted libs
Cross-Platform CI - New GitHub Actions workflow for Go testing
- Tests on ubuntu-latest, macos-latest, windows-latest
- Builds binaries for all platform/arch combinations
- PowerShell script validation on Windows
- Updated test.yml for Go-first testing
Checksum Verification - Binary downloads now verified against SHA256 checksums
- Automatically downloads SHA256SUMS.txt from release
- Supports both sha256sum (Linux) and shasum (macOS)
- Graceful fallback if checksums unavailable
- Skip with BLACKDOT_SKIP_CHECKSUM=true if needed

Removed

bin/blackdot-backup, bin/blackdot-config, bin/blackdot-diff
bin/blackdot-doctor, bin/blackdot-drift, bin/blackdot-encrypt
bin/blackdot-features, bin/blackdot-hook, bin/blackdot-lint
bin/blackdot-metrics, bin/blackdot-migrate, bin/blackdot-packages
bin/blackdot-setup, bin/blackdot-sync, bin/blackdot-template
bin/blackdot-uninstall, bin/blackdot-vault
lib/_cli_features.sh, lib/_config.sh, lib/_config_layers.sh
lib/_drift.sh, lib/_encryption.sh, lib/_errors.sh
lib/_features.sh, lib/_paths.sh, lib/_progress.sh
lib/_state.sh, lib/_templates.sh, lib/_vault.sh

[3.2.0] - 2025-12-09

Changed

License - Changed from MIT License to Apache License 2.0
- LICENSE file updated to Apache License 2.0
- All documentation and badges updated (README.md, docs/*, CONTRIBUTING.md, etc.)
- Provides additional patent protection and contributor license terms
- Code remains free and open source
- Effective starting with v3.2.0 and all future releases

Added

Phase 2 Shell Switchover Complete - Go binary is now the primary CLI
- ZSH blackdot function delegates to Go binary when available
- Shell-only commands (cd, edit) stay in shell
- Features enable/disable updates both Go config and in-memory shell state
- Escape hatch: DOTFILES_USE_GO=0 forces shell implementation
- Tool group aliases: sshtools, awstools, cdktools, gotools, rusttools, pytools, dockertools, claudetools
- Individual hyphenated aliases: ssh-keys, aws-profiles, cdk-status, etc.
PowerShell Module Improvements (v3.1.0)
- Fixed d alias export (now properly exported via New-Alias)
- Added tool group functions to manifest
- Full parity with ZSH tool aliases
- Hook system: 24 hook points, file/function/JSON hooks
Windows PowerShell One-Line Installer - Native Windows onboarding experience
- New Install.ps1 bootstrap script for PowerShell users
- Usage: irm https://raw.githubusercontent.com/.../Install.ps1 | iex
- Features: repo clone, Go binary download, module setup, optional packages
- Supports presets: -Preset developer, -Preset minimal, etc.
- Supports options: -SkipPackages, -SkipBinary, -WorkspaceTarget
- Matches the curl | bash experience for Unix users
- Git Bash: install.sh now prompts to also set up PowerShell module
Rollback Command - Instant rollback to last backup with safety confirmation
- Go CLI: New rollback command with --to, --list, -y/--yes flags
- ZSH: Fixed rollback to handle --help, --list, added confirmation prompt
- Both versions now prompt [y/N] before restoring (only "y"/"yes" proceeds)
- Use -y flag to skip confirmation for scripts/automation
Go CLI Help Styling - All commands now match ZSH help output exactly
- Custom printXxxHelp() functions for vault, features, doctor, tools, backup, config, encrypt
- Consistent styling: bold cyan titles, yellow commands, dim descriptions
- Unknown command error handling matches ZSH: "Unknown command: X" with help hint
ZSH encrypt command - Age encryption now accessible via blackdot encrypt
- Wired bin/blackdot-encrypt into the dotfiles() function
- Added Security section to help output
- Commands: init, encrypt, decrypt, edit, list, status, push-key
Runtime Feature Guards - All shell tool modules now support instant enable/disable
- No shell reload required when toggling features with blackdot features enable/disable
- Converted modules: aws_helpers, cdk_tools, rust_tools, go_tools, python_tools, docker_tools, ssh_tools, claude_integration, modern_cli, nvm_integration, sdkman_integration
- Pattern: Aliases converted to wrapper functions with require_feature guards
- Blocked commands show helpful message: "Feature 'X' is disabled. Enable with: dotfiles features enable X"
- Fixed: set -euo pipefail removed from _features.sh (was killing interactive shells)
- Fixed: _logging.sh now sourced in 00-init.zsh for pass/fail/warn/info functions
Cross-Platform Developer Tools (blackdot tools)
- New tools parent command with 8 tool categories
- All tools work on Linux, macOS, and Windows
- Feature Flag Integration - Tools respect their feature flags like ZSH:
  - ssh → ssh_tools, aws → aws_helpers, cdk → cdk_tools
  - go → go_tools, rust → rust_tools, python → python_tools
  - docker → docker_tools, claude → claude_integration
  - Disabled tools show helpful error with enable command
- SSH Tools (blackdot tools ssh)
  - keys - List SSH keys with fingerprints
  - gen - Generate ED25519 key pairs
  - list - List configured SSH hosts
  - agent - Show SSH agent status
  - fp - Show fingerprints in SHA256/MD5 formats
  - copy - Copy public key to remote host
  - tunnel - Create SSH port forward tunnel
  - socks - Create SOCKS5 proxy
  - status - Color-coded ASCII art status banner
- AWS Tools (blackdot tools aws)
  - profiles - List all AWS profiles
  - who - Show current AWS identity
  - login - SSO login to AWS profile
  - switch - Set AWS_PROFILE (prints export command)
  - assume - Assume IAM role for cross-account access
  - clear - Clear temporary credentials
  - status - Color-coded ASCII art status banner
- CDK Tools (blackdot tools cdk)
  - init - Initialize new CDK project
  - env - Set CDK_DEFAULT_ACCOUNT/REGION from AWS profile
  - env-clear - Clear CDK environment variables
  - outputs - Show CloudFormation stack outputs
  - context - Show or clear CDK context
  - status - Color-coded ASCII art status banner
- Go Tools (blackdot tools go)
  - new - Create new Go project with standard structure
  - init - Initialize Go module
  - test - Run tests with options
  - cover - Run tests with coverage report
  - lint - Run go vet and golangci-lint
  - outdated - Show outdated dependencies
  - update - Update all dependencies
  - build-all - Cross-compile for all platforms
  - bench - Run benchmarks
  - info - Show Go environment info
- Rust Tools (blackdot tools rust)
  - new - Create new Rust project
  - update - Update Rust toolchain
  - switch - Switch Rust toolchain
  - lint - Run cargo check + clippy
  - fix - Format and auto-fix with clippy
  - outdated - Show outdated dependencies
  - expand - Expand macros (for debugging)
  - info - Show Rust environment info
- Python Tools (blackdot tools python)
  - new - Create new Python project with uv
  - clean - Clean Python artifacts
  - venv - Create virtual environment
  - test - Run pytest
  - cover - Run pytest with coverage
  - info - Show Python environment info
- Docker Tools (blackdot tools docker)
  - ps - List containers (with -a for all)
  - images - List Docker images
  - ip - Get container IP address
  - env - Show container environment variables
  - ports - Show all container ports
  - stats - Show resource usage (with -f for live)
  - vols - List volumes
  - nets - List networks (with --inspect for details)
  - inspect - Inspect container with JSON path filtering
  - clean - Remove stopped containers and dangling images
  - prune - System prune (with -a for aggressive)
  - status - Color-coded ASCII art status banner
- Claude Tools (blackdot tools claude)
  - status - Show Claude Code configuration (Bedrock profile, SSO status, paths)
  - bedrock - Print export commands for AWS Bedrock backend
  - max - Print export commands for Anthropic Max backend
  - switch - Interactive backend switcher
  - init - Initialize ~/.claude/ from dotfiles templates (hooks, commands, settings)
  - env - Show all Claude-related environment variables
  - Full parity with ZSH claude integration (70-claude.zsh)
Binary Distribution (GitHub Releases)
- Pre-built Go CLI binaries for all platforms
- Linux: amd64, arm64
- macOS: amd64 (Intel), arm64 (Apple Silicon)
- Windows: amd64, arm64
- SHA256 checksums for all binaries
- Automated via GitHub Actions on tag push
PowerShell Module v1.2.0 (powershell/)
- Claude tools integration - Full parity with ZSH and Go CLI
  - claude-status - Show Claude Code configuration
  - claude-bedrock - Configure AWS Bedrock backend (-Eval to set env vars)
  - claude-max - Configure Anthropic Max backend (-Eval to clear vars)
  - claude-switch - Interactive backend switcher
  - claude-init - Initialize ~/.claude/ from templates
  - claude-env - Show Claude environment variables
  - Aliases: cb (claude-bedrock), cm (claude-max)
PowerShell Module v1.1.0 (powershell/)
- Cross-platform Windows support with complete ZSH hooks parity
- Full Hook System (24 hook points - identical to ZSH)
  - Lifecycle: pre_install, post_install, pre_bootstrap, post_bootstrap, pre_upgrade, post_upgrade
  - Vault: pre_vault_pull, post_vault_pull, pre_vault_push, post_vault_push
  - Doctor: pre_doctor, post_doctor, doctor_check
  - Shell: shell_init, shell_exit, directory_change
  - Setup: pre_setup_phase, post_setup_phase, setup_complete
  - Template: pre_template_render, post_template_render
  - Encryption: pre_encrypt, post_decrypt
- Hook Registration Methods
  - File-based: ~/.config/blackdot/hooks/<point>/*.ps1
  - Function-based: Register-DotfilesHook -Point "..." -ScriptBlock {...}
  - JSON config: Same hooks.json format as ZSH
- Hook Features
  - Timeout support via PowerShell Jobs
  - Fail-fast option (HOOKS_FAIL_FAST)
  - Verbose mode (HOOKS_VERBOSE)
  - Feature gating (checks parent features)
- Hook Management Functions
  - Register-DotfilesHook / Unregister-DotfilesHook
  - Invoke-DotfilesHook (hook_run equivalent)
  - Get-DotfilesHook / Get-DotfilesHookPoints
  - Add-DotfilesHook / Remove-DotfilesHook / Test-DotfilesHook
- Tool Aliases - 50+ functions wrapping blackdot tools commands
  - SSH: ssh-keys, ssh-gen, ssh-tunnel, ssh-status
  - AWS: aws-profiles, aws-who, aws-login, aws-switch, aws-status
  - CDK: cdk-init, cdk-env, cdk-outputs, cdk-status
  - Go: go-new, go-test, go-lint, go-info
  - Rust: rust-new, rust-lint, rust-info
  - Python: py-new, py-test, py-info
- Environment Management - Proper handling of env vars for aws-switch, aws-assume, cdk-env
- Installation Script - Install-Dotfiles.ps1 for easy setup
- Short alias d for blackdot command
Windows Package Management (powershell/Install-Packages.ps1)
- winget-based package installer (equivalent to brew bundle)
- Three tiers matching Brewfile: minimal, enhanced, full
- Installs: bat, fd, ripgrep, fzf, eza, zoxide, glow, dust, jq
- Development: Go, Rust, Python, fnm (Node.js)
- Cloud: AWS CLI, Bitwarden CLI, 1Password CLI, age
- Optional: Docker Desktop, VS Code, Windows Terminal
- Dry-run mode with -DryRun flag
fnm Integration (Cross-platform Node.js version manager)
- Replaces NVM on Windows (NVM is Unix-only)
- Functions: fnm-install, fnm-use, fnm-list, Initialize-Fnm
- Auto-switches when entering directories with .nvmrc or .node-version
- Auto-initialized on module load
Zoxide Integration (Smart directory navigation)
- Auto-initialized on module load
- z command for jumping to directories
- Initialize-Zoxide for manual init
Docker Tools for PowerShell
- 12 wrapper functions: docker-ps, docker-images, docker-ip, docker-env, docker-ports, docker-stats, docker-vols, docker-nets, docker-inspect, docker-clean, docker-prune, docker-status
Windows Documentation
- docs/windows-setup.md - Complete Windows setup guide
- Updated powershell/README.md with all 85+ functions
- Windows section added to main README
Go CLI Complete - All 11 core commands ported with verified parity
- features - Feature registry management (list, enable, disable, preset)
- doctor - Health checks with ASCII banner
- lint - Syntax validation (55 files)
- hook - Full hook system (list, run, add, remove, test)
- encrypt - Age encryption management
- template - Template rendering with RaymondEngine
- vault - All 8 vault subcommands
- diff, drift, sync - Vault operations
- setup, uninstall, packages - Setup wizard
- Side-by-side testing confirms identical behavior
Chezmoi Import Tool (blackdot import chezmoi)
- Migrate from chezmoi repositories to blackwell-dotfiles
- Converts Go template syntax to Handlebars automatically
- Handles chezmoi prefixes: dot_, private_, executable_, symlink_, etc.
- Converts .chezmoi.os, .chezmoi.hostname, etc. to standard variables
- Parses chezmoi.toml config for template variables
- Dry-run mode for previewing changes
- Verbose mode for detailed progress
Vault Create/Delete Commands (blackdot vault create|delete)
- vault create <item-name> [content] - Create new vault items
  - Content from argument, file (--file), or stdin
  - Dry-run mode (-n) to preview without changes
  - Force mode (-f) to overwrite existing items
- vault delete <item-name>... - Delete vault items
  - Bulk deletion of multiple items
  - Protected items (SSH-, AWS-, Git-Config) require confirmation
  - Dry-run mode for safe preview
  - Force mode skips confirmation (except protected items)
Standard Handlebars Template Syntax (Phase B)
- Templates now use standard Handlebars syntax: {{#if}}, {{#unless}}, {{#each}}, {{/if}}
- Bash engine supports both legacy ({% if %}) and Handlebars syntax
- Migrated 4 template files to standard syntax:
  - templates/configs/99-local.zsh.tmpl
  - templates/configs/gitconfig.tmpl
  - templates/configs/ssh-config.tmpl
  - templates/configs/claude.local.tmpl
- All 364 tests passing with new syntax
Go Template Engine (Phase C) (internal/template/raymond_engine.go)
- Raymond-based Handlebars engine for proper AST parsing
- 15 registered helpers: eq, ne, upper, lower, capitalize, trim, replace, append, prepend, quote, squote, truncate, length, basename, dirname, default
- Preprocessor converts {{#else}} to {{else}} for bash template compatibility
- Variable resolution with DOTFILES_TMPL_* environment override
- Auto-detection of hostname, os, user, home, shell
- 20 parity tests verifying Go output matches bash output
- Both engines coexist for safe transition (strangler fig pattern)
Go Lint Command (internal/cli/lint.go)
- Checks ZSH syntax: zsh/zsh.d/*.zsh, zshrc, p10k.zsh
- Checks Bash syntax: bootstrap/*.sh, vault/*.sh, lib/*.sh
- Validates config files (Brewfile existence)
- Runs shellcheck if available (on bootstrap/*.sh)
- Matches bash dotfiles-lint output format (55 files checked)
- --verbose and --fix flags supported
Go Backup Command (internal/cli/backup.go)
- Create, list, restore, clean subcommands
- Uses tar.gz compression matching bash format
- Backup naming: backup-YYYYMMDD-HHMMSS.tar.gz (matches bash)
- Cross-compatible: Can restore bash-created backups
- Supports both backup- and backup_ naming conventions
- Finds latest backup by modification time
- Handles bash wrapper directory format in archives
Go Metrics Command (internal/cli/metrics.go)
- JSONL metrics visualization from ~/.blackdot-metrics.jsonl
- Three modes: summary (default), --graph (ASCII bar chart), --all (full list)
- Statistics: average score, total errors/warnings/fixed, perfect runs %
- Trend analysis: compares last 5 vs previous 5 health checks
- Platform distribution display
- Color-coded output matching bash behavior
Go Uninstall Command (internal/cli/uninstall.go)
- --dry-run/-n: Preview what would be removed
- --keep-secrets/-k: Preserve SSH/AWS/Git configs
- Removes symlinks: .zshrc, .p10k.zsh, ghostty config, .claude
- Removes config files: metrics file, backups directory
- Interactive confirmation for secrets and repository deletion
- Output matches bash implementation exactly
Go Status Command (internal/cli/status.go)
- City skyline ASCII art visual dashboard
- Checks symlink status (zshrc, claude, /workspace)
- SSH keys loaded count
- AWS authentication status
- Lima VM status (macOS only)
- Claude profile detection (dotclaude integration)
- Suggested fixes for any detected issues
Go Packages Command (internal/cli/packages.go)
- --check/-c: Show what's missing from Brewfile
- --install/-i: Install missing packages via brew bundle
- --outdated/-o: Show outdated Homebrew packages
- --tier/-t: Select tier (minimal/enhanced/full)
- Tier priority: flag > config.json > BREWFILE_TIER env > default
- Parses Brewfile for formulas and casks
- Compares against installed packages
Go Drift Command (internal/cli/drift.go)
- --quick/-q: Fast check against cached state (no vault access)
- Full mode: Connects to vault and compares current contents
- SHA256 checksums for reliable drift detection
- Reads cached state from ~/.cache/dotfiles/vault-state.json
- Tracks: SSH, AWS, Git configs, env secrets, template variables
Go Diff Command (internal/cli/diff.go)
- --sync/-s: Preview what sync would push to vault
- --restore/-r: Preview what restore would change locally
- Item-specific diff: diff SSH-Config, diff Git-Config, etc.
- Color-coded unified diff output with line limits
- Session validation with helpful unlock instructions
Go Hook Command (internal/cli/hook.go)
- Subcommands: list, run, add, remove, points, test
- 7 hook categories: Lifecycle, Vault, Doctor, Shell, Setup, Template, Encryption
- 23 hook points with descriptions
- File-based hooks: ~/.config/blackdot/hooks/<point>/*.sh
- JSON-configured hooks: ~/.config/blackdot/hooks.json
- Timeout support and fail-fast option
- Verbose mode for debugging hook execution
Go Encrypt Command (internal/cli/encrypt.go)
- Subcommands: init, file, decrypt, edit, list, status, push-key
- Age encryption (age-keygen, age) for secure file storage
- --keep/-k: Keep original when encrypting/decrypting
- --dry-run/-n: Preview what would be done
- --force/-f: Force key regeneration
- Pattern matching for files that should be encrypted
- Vault integration for key backup/recovery
Go Doctor Command (internal/cli/doctor.go)
- 10 check sections: Version, Core Components, Required Commands, SSH, AWS, Vault, Shell, Claude, Templates
- Health score calculation (0-100) with color-coded interpretation
- --fix/-f: Auto-fix permission issues (SSH keys, AWS credentials)
- --quick/-q: Fast checks only (skip vault status)
- Failed checks and warnings tracking with fix suggestions
- Metrics saving to ~/.blackdot-metrics.jsonl
- Banner with ASCII art matching bash implementation
Go Sync Command (internal/cli/sync.go)
- Bidirectional vault sync with smart direction detection
- --dry-run/-n: Preview changes without making them
- --force-local/-l: Push all local changes to vault
- --force-vault/-v: Pull all vault content to local
- --verbose: Show detailed checksum comparison
- SHA256 checksums for reliable change detection
- Drift state tracking for baseline comparison
- Updates config timestamps after successful sync
Go Setup Command (internal/cli/setup.go)
- Full 7-phase interactive setup wizard in Go
- --status/-s: Show current setup status without running wizard
- --reset/-r: Reset state and re-run setup from beginning
- State inference: auto-detects existing installations from filesystem
- Progress bars with Unicode visualization (█░)
- Phase completion persistence to config.json
- Feature preset selection (minimal/developer/claude/full)
- Next steps guidance based on configuration
- Vault backend detection (bitwarden, 1password, pass)
- Claude/dotclaude integration detection
- Template system detection
Interactive Template Setup (blackdot template init)
- Prompts for essential variables: git name, email, machine type, GitHub username
- Auto-detects defaults from git config --global
- Machine type choice menu with detected value highlighted
- Generates _variables.local.sh with user's values pre-filled
- Offers editor for advanced configuration after essentials
- Replaces "copy example file and edit" workflow with guided setup
Template-Vault Integration (blackdot template vault)
- Push/pull template variables to/from vault for cross-machine portability
- vault push - Backup local config to vault
- vault pull - Restore config from vault on new machines
- vault diff - Show differences between local and vault
- vault sync - Bidirectional sync with conflict detection
- vault status - Show sync status at a glance
- Supports all vault backends (bitwarden, 1password, pass)
- Automatic backup on pull, conflict resolution options
Short alias d for blackdot command
- Quick access: d status, d doctor, d features, etc.
macOS Settings Command (blackdot macos) - Go CLI
- Full parity with ZSH blackdot macos command
- apply - Apply settings from macos/settings.sh
- preview - Dry-run showing what would change
- discover - Discover current macOS settings (with --generate, --snapshot, --compare)
- Feature-gated: Requires macos_settings feature enabled
- Only shows in help output on Darwin systems
- Wraps existing shell scripts in macos/ directory

Fixed

Go CLI error handling (internal/cli/root.go)
- Fixed: All errors were showing "Unknown command: tools" instead of actual error message
- Now correctly distinguishes between "unknown command/flag" errors and execution errors
- Execution errors show the actual error message with [ERROR] prefix
Config get/show/source for arbitrary keys (internal/cli/config.go)
- Fixed: config get test.key returned empty even when config set user test.key hello succeeded
- Root cause: Used cfg.Get() which only knew predefined keys (vault., features.)
- Fix: Use getFromJSONFile() to read arbitrary nested keys from config layers
Age encryption in minimal tier
- Added age to Brewfile.minimal - required for blackdot encrypt feature
- Added FiloSottile.age to Windows $MinimalPackages in Install-Packages.ps1
PowerShell d alias not exported
- Fixed: Alias was created with -Scope Global which prevented export
- Changed to New-Alias in module scope for proper export via Export-ModuleMember
Vault session caching (blackdot vault unlock/status)
- Fixed: vault status always showing "Not authenticated" even after successful unlock
- Root cause: Bitwarden CLI's --session argument doesn't work reliably; must use BW_SESSION env var
- Fix: Updated vaultmux v0.3.1 to use BW_SESSION environment variable instead of --session CLI argument
- Session token now properly persisted to JSON cache file and validated on status check
Go CLI exit codes and flag validation (edge case testing)
- diff: Now returns non-zero exit code when vault is not unlocked
- diff: Added mutual exclusion check - --sync and --restore cannot be used together
- encrypt status: Now returns non-zero exit code when age is not installed or encryption not initialized
Nested {{#if}} block extraction bug (lib/_templates.sh)
- Fixed stray } character appearing in output when using nested conditionals
- Root cause: Two bugs in process_conditionals function:
  1. Line 917: Extra } in pattern match was being concatenated as literal
  2. Lines 935-938: Missing {{/if}} preservation in elif branch
- Templates like A{{#if x}}B{{#if y}}C{{/if}}D{{/if}}E now correctly produce ABCDE
- All nested conditional test cases pass
Machine type preservation in template system
- User-set TMPL_AUTO[machine_type] in _variables.local.sh was being overwritten by auto-detection
- Fixed variable loading order: now loads user files before auto-detection
- build_auto_vars() now preserves existing user-set values

[3.1.0] - 2025-12-06

Added

Developer Tools Documentation (docs/developer-tools.md)
- Comprehensive 400+ line guide covering AWS, CDK, Rust, Go, NVM, SDKMAN integrations
- All aliases and helper commands documented with examples
- Example workflows for each tool suite
- Feature flags for enabling/disabling tool integrations
- Added to Docsify coverpage, sidebar, and README Quick Navigation
ZSH Hooks Documentation (docs/hooks.md)
- New "Understanding ZSH Hooks" section explaining native ZSH hook functions
- Coverage of precmd_functions, preexec_functions, chpwd_functions, zshexit_functions, periodic_functions, zshaddhistory_functions
- Common patterns: auto-venv activation, command timing, history filtering
- How dotfiles hooks map to native ZSH mechanisms
- Performance considerations and best practices
- Using native ZSH hooks alongside dotfiles hooks
CDK Tools Integration (cdk_tools feature)
- Aliases: cdkd, cdks, cdkdf, cdkw, cdkls, cdkdst, cdkb, cdkda, cdkhs, cdkhsf
- Helpers: cdk-env, cdkall, cdkcheck, cdkhotswap, cdkoutputs, cdkinit, cdkctx
- cdktools command with styled help and status display
- Tab completions for stack and profile arguments
- Status color: green (in project), cyan (installed), red (not installed)
Rust Tools Integration (rust_tools feature)
- Aliases: cb, cr, ct, cc, ccl, cf, cbr, cw, cba, cclean
- Helpers: rust-update, rust-switch, rust-new, rust-lint, rust-fix, rust-outdated, rust-expand
- rusttools command with styled help and status display
- Tab completions for toolchain switching
Go Tools Integration (go_tools feature)
- Aliases: gob, gor, got, gotv, gof, gom, gov, gog, goi
- Helpers: gocover, goinit, go-new, go-lint, go-update, go-outdated, go-bench, go-build-all
- gotools command with styled help and status display
- Shows module name and Go version requirements
Python Tools Integration (python_tools feature)
- Powered by uv for fast Python package management
- uv aliases: uvs, uvr, uva, uvad, uvrm, uvl, uvu, uvt, uvv, uvpy
- pytest aliases: pt, ptv, ptx, ptxv, ptc, ptl, pts, ptk
- Auto-venv: Prompts to activate venv on cd (configurable: notify/auto/off)
- Helpers: uv-new, uv-clean, uv-info, uv-python-setup, pt-watch, pt-cov
- pythontools command with styled help and status display
- Tab completions for project templates and Python versions
AWS Tools Tab Completions
- awsset <TAB> and awslogin <TAB> complete with AWS profiles
CLI Color Styling
- Consistent color scheme across all dotfiles help commands
- Bold+Cyan headers, Yellow commands, Dim descriptions
- Styled: blackdot help, blackdot macos, blackdot vault, blackdot template
- Styled: dotfiles-backup, dotfiles-drift, dotfiles-lint, dotfiles-packages, dotfiles-migrate

Changed

Feature categories reorganized - All third-party tool integrations now consistently in integration category
- Moved aws_helpers and cdk_tools from optional to integration
- optional category now only for dotfiles-specific features (vault, templates, hooks, etc.)
- integration category for all external tool helpers (aws, cdk, rust, go, nvm, sdkman, etc.)

Fixed

Hook command early loop exit (bin/blackdot-hook)
- Fixed ((i++)) returning falsy value when i=0, causing loop to exit prematurely
- Changed to safe increment pattern: i=$((i + 1)) and count=$((count + 1))
- blackdot hook list now correctly shows all hooks and categories
Missing Template & Encryption hook categories (bin/blackdot-hook)
- Added Template hooks (pre_template_render, post_template_render) to list and points
- Added Encryption hooks (pre_encrypt, post_decrypt) to list and points
- Updated usage help text with all 7 hook categories
Metrics now saved after blackdot doctor - Health scores written to ~/.blackdot-metrics.jsonl
Vault unlock errexit issues - Fixed silent exit on ((attempts++)) and session caching
Vault session persistence - Use BW_SESSION env var instead of --session flag

[3.0.0] - 2024-12-05

🎨 MAJOR RELEASE - v3.0 Framework Architecture

This is a comprehensive framework redesign that transforms dotfiles from a collection of scripts into a modular, feature-driven system. All breaking changes, new features, and improvements from the v3 development cycle are included in this single release.

Added - Framework Core

Hook System - Extensible event-driven hook system (lib/_hooks.sh)
- Event-based hook triggers at 8 lifecycle points: shell_init, directory_change, pre_vault_pull, post_vault_pull, pre_vault_push, post_vault_push, doctor_check, pre_uninstall
- blackdot hook command for managing hooks
- blackdot hook list - Show all available hooks and their status
- blackdot hook run <event> [--dry-run] - Manually trigger hooks
- blackdot hook enable <path> - Enable hook script
- blackdot hook disable <path> - Disable hook script
- blackdot hook validate [path] - Validate hook scripts
- Automatic hook discovery from ~/hooks/ and $BLACKDOT_DIR/hooks/
- Per-directory hook support via .dotfiles-hooks/
- Hook script naming convention: [priority]-descriptive-name.{sh,zsh}
- Priority-based execution (00-99, lower runs first)
- Hook environment with context variables ($DOTFILES_HOOK_, $DOTFILES_)
- Safety features: timeouts, error isolation, validation
- Shell integration hooks automatically loaded
- Example hooks provided for common use cases
- Comprehensive documentation at docs/hooks.md
- 874 test cases covering all hook functionality
Template Pipeline Filters - Transform variables during template rendering
- {{ variable | upper }} - Convert to uppercase
- {{ variable | lower }} - Convert to lowercase
- {{ variable | trim }} - Remove leading/trailing whitespace
- {{ variable | replace:old:new }} - String replacement
- {{ variable | default:fallback }} - Provide default value
- {{ variable | sanitize_path }} - Sanitize for safe path usage
- Chain multiple filters: {{ email | lower | trim }}
- Works in {{#if}} conditions and {{#each}} loops
- Documented in docs/templates.md
- 206 test cases for template functionality
CLI Feature Awareness - Smart CLI that adapts to enabled features (lib/_cli_features.sh)
- blackdot help only shows commands for enabled features (cleaner UX)
- blackdot help --all shows all commands with enabled/disabled indicators (● / ○)
- Feature guards prevent running disabled commands with helpful enable message
- --force flag bypasses feature guard for any command
- Command-to-feature mapping: vault→vault, config→config_layers, backup→backup_auto, etc.
- Section-level filtering in help output (Vault Operations, Backup & Safety, etc.)
- Footer shows hidden features when commands are filtered
- DOTFILES_CLI_SHOW_ALL=true env var - Always show all commands in help
- DOTFILES_FORCE=true env var - Bypass all feature guards (for scripting/CI)
- cli_feature_filter meta-feature - Disable to show all commands, bypass all guards
- Subcommand awareness - vault:pull, config:get have granular feature mappings
- Per-command help - blackdot help <cmd> shows feature status and subcommands
Configuration Layers System - Hierarchical config resolution (lib/_config_layers.sh)
- 5-layer priority: env > project > machine > user > defaults
- blackdot config get <key> [default] - Get value with layer resolution
- blackdot config set <layer> <key> <value> - Set in specific layer
- blackdot config show <key> - Display value from all layers
- blackdot config source <key> - Get value with source info (JSON)
- blackdot config list - Show layer locations and status
- blackdot config merged - Show merged config from all layers
- blackdot config init machine|project - Initialize layer configs
- Project config (.blackdot.json) travels with repos
- Machine config (~/.config/blackdot/machine.json) stays local
- Environment variable override: DOTFILES_<KEY> (e.g., BLACKDOT_VAULT_BACKEND)
Feature Registry - Centralized control for all optional features (lib/_features.sh)
- blackdot features - List all features with enabled/disabled status
- blackdot features enable <name> [--persist] - Enable a feature (optionally persist to config)
- blackdot features disable <name> [--persist] - Disable a feature
- blackdot features preset <name> [--persist] - Apply a preset (minimal, developer, claude, full)
- blackdot features check <name> - Check if enabled (for scripts, returns exit code)
- blackdot features --json - JSON output for automation
- Three categories: core (always enabled), optional, integration
- Dependency resolution: enabling claude_integration auto-enables workspace_symlink
- Backward compatible with SKIP_* environment variables
- State persisted to config.json features object
Vault Setup Wizard v2 - Complete redesign of vault onboarding flow
- Educational phase explains how vault storage works before any configuration
- Three setup modes: Existing (import from vault), Fresh (create new), Manual (configure yourself)
- User guides system to their secrets location (folder/vault/directory) instead of random scanning
- Backend-specific location support:
  - Bitwarden: folders
  - 1Password: vaults and tags (planned)
  - pass: directories
- Respects existing naming conventions in vault
- Works on new machines (vault-first discovery)
- See: docs/design/vault-setup-wizard-v2.md for full design rationale
Vault Location Management - Unified location handling across backends
- vault_location field in vault-items.json schema
- vault_get_location(), vault_set_location() in abstraction layer
- vault_list_locations(), vault_list_items_in_location(), vault_create_location()
- Backward compatible: no vault_location = legacy behavior (global search)
Bitwarden Folder Support - Organize vault items in Bitwarden folders
- vault_backend_list_locations() - List all folders
- vault_backend_location_exists() - Check if folder exists
- vault_backend_create_location() - Create new folder
- vault_backend_list_items_in_location() - List items in folder or by prefix
- vault_backend_create_item_in_location() - Create item in specific folder
pass Directory Support - Location-aware operations for pass backend
- vault_backend_list_locations() - List top-level directories
- vault_backend_location_exists() - Check if directory exists
- vault_backend_create_location() - Create new directory
- vault_backend_list_items_in_location() - List items in directory
- vault_backend_create_item_in_location() - Create item in specific directory
Input Validation & Sanitization - Defensive input handling in setup wizard
- sanitize_input() - Remove control characters, null bytes, trim whitespace
- validate_location_name() - Validate folder/vault/directory names (no path traversal)
- validate_file_path() - Validate local file paths
- validate_item_name() - Validate vault item names match naming convention
- prompt_location_name() - Validated prompt for location names
- prompt_file_path() - Validated prompt for file paths

Fixed

Missing feature guard on config command - blackdot config now properly respects config_layers feature state
- Shows helpful "feature not enabled" message when disabled
- Consistent with other feature-gated commands (vault, backup, template)
- Use --force to bypass if needed
Missing feature guard on Claude shell module - 70-claude.zsh now respects claude_integration feature
- Shell functions (claude(), claude-bedrock(), etc.) only load when feature enabled
- Consistent with feature-first architecture
Underscore in vault item names - Regex now allows underscores in item names
- Pattern changed from ^[A-Z][A-Za-z0-9-]*$ to ^[A-Z][A-Za-z0-9_-]*$
- Fixes validation error for items like SSH-Enterprise_Ghub
- Updated both lib/_vault.sh and vault/vault-items.schema.json
Recursive dependency collection in feature enable - Transitive dependencies now correctly listed
- dep variable in for loop wasn't local, causing nested deps to be lost in recursion
- Before: blackdot features enable dotclaude showed "Enabling: workspace_symlink"
- After: Shows "Enabling: workspace_symlink claude_integration" (full chain)
- Affects bin/blackdot-features dependency collection
Missing color variables in CLI help - blackdot help now works without errors
- $BOLD, $CYAN, $NC weren't defined in shell context
- Added color definitions to 40-aliases.zsh with TTY detection
- Fixes "parameter not set" error when running help commands
blackdot vault status hanging - Status command no longer prompts for password
- Changed from vault_get_session() (interactive) to vault_check_session() (non-interactive)
- Shows "Vault locked" with unlock instructions instead of hanging
- Introduced vault_check_session() function for non-interactive session validation
Vault unlock password prompt invisible - Now shows clear "Master password: " prompt
- Uses read -s for hidden input from /dev/tty
- Shows retry count on incorrect password
- 1Password shows info about biometric/password auth
- Fixed stdin consumption by adding </dev/null to bw commands
Vault unlock silent exit - Fixed script exiting before password prompt (two issues)
- vault_read_cached_session failure triggered errexit from sourced _config.sh
- Now uses || session="" pattern to handle expected failures gracefully
- ((attempts++)) with attempts=0 returns exit status 1, triggering errexit
- Changed to ((++attempts)) (pre-increment) to return success on first iteration
Color escape codes showing raw - Fixed across multiple commands
- blackdot config list - Changed printf to echo -e
- blackdot config help - Changed heredoc to echo -e statements
- blackdot hook help - Changed heredoc to echo -e statements
blackdot lint path detection - Fixed "Could not find dotfiles directory" error
- Simplified path detection to match other scripts
- Added shebang-aware syntax checking (zsh files use zsh -n, bash use bash -n)
Features not persisting after setup - Setup phases now enable and persist features
- Added feature_persist() calls for workspace, vault, claude, templates phases
- Features are now saved to config.json when setup completes

Added - CLI Improvements

blackdot vault CLI - Unified vault management command wrapping all vault operations
- blackdot vault unlock - Unlock vault with clear password prompt (hidden input)
- blackdot vault lock - Lock vault and clear cached session
- blackdot vault status - Full status with drift detection
- blackdot vault quick - Quick status check (login/unlock only)
- blackdot vault restore/pull - Restore secrets from vault
- blackdot vault push - Push local secrets to vault
- blackdot vault list - List vault items
- blackdot vault scan - Scan for local secrets
- Provides clearer UX than raw bw commands
Feature preset selection in setup wizard - Choose feature presets during setup
- Offers minimal, developer, claude, and full presets at end of setup
- Persists selected features to config.json

Changed

Schema relaxed - vault_items no longer required in vault-items.json
- Allows minimal config with just vault_location during initial setup
- Added support for $schema and $comment fields in JSON

Documentation

Vault Setup Wizard v2 Design Document - Comprehensive design at docs/design/vault-setup-wizard-v2.md
- Problem statement and design principles
- User flow diagrams for all three setup modes
- Backend-specific implementation plans
- Schema changes and migration paths
- Risk assessment and success criteria

Planned

1Password Backend Location Support - Vault and tag-based organization
- vault_backend_list_locations() for vaults
- Tag support as alternative location type
- Migration from ONEPASSWORD_VAULT env var to config
- See docs/design/vault-setup-wizard-v2.md for implementation plan

Added - v3.0 Core Features (consolidated from earlier releases)

Vault Schema Validation (Pain Point #4) - Prevent invalid configurations
- JSON schema for vault-items.json with comprehensive validation rules
- vault_validate_schema() function in lib/_vault.sh validates required fields, types, naming conventions
- Automatic validation before all vault sync operations (push/pull)
- Standalone blackdot vault validate command for manual validation
- Clear error messages showing exactly what's wrong and how to fix it
- Graceful degradation when jq is not installed (warning instead of failure)
- Schema file: vault/vault-items.schema.json with JSON Schema Draft 2020-12
- Validates: required fields (path, required, type), enum values (file/sshkey), item name patterns
Setup Wizard Progress Bar (Pain Point #8) - Visual feedback for setup progress
- Unicode progress bar with 20-character visualization (█ filled, ░ empty)
- show_progress() function displays current step (e.g., "Step 3 of 7: Packages")
- show_steps_overview() function shows all 7 steps upfront with descriptions
- Beautiful bordered sections using box drawing characters (╔═╗║╠╣╚═╝)
- Progress percentage calculation (14%, 29%, 43%, etc.)
- All 7 setup phases: workspace, symlinks, packages, vault, secrets, claude, template
- Overview shown at wizard start with safety reminder ("Safe to exit anytime")
Structured Error Handling Library (Pain Point #6) - Actionable error messages
- lib/_errors.sh - Comprehensive error handling with 15 pre-built error functions
- Structured format: What / Why / Impact / Fix / Help URL
- Error functions: error_vault_locked, error_missing_dep, error_git_not_configured, etc.
- All errors include specific fix commands and documentation links
- Multiline fix command support with color-coded output
- Export functions for use in subshells
Health Score Interpretation (Pain Point #7) - Understand your dotfiles health
- Color-coded health status: 🟢 Healthy (80-100), 🟡 Minor (60-79), 🟠 Needs Work (40-59), 🔴 Critical (0-39)
- "Quick Fixes" section lists each failed check with exact fix command
- Tracks failures and warnings with associated fixes
- Shows potential score improvement: "95/100 if all issues fixed"
- Auto-fix suggestions for permission-related issues
- Celebrates perfect scores with emoji and encouragement
- Enhanced bin/blackdot-doctor with comprehensive summary section
Vault Status Command (Pain Point #12) - Full visibility into vault sync state
- blackdot vault status - Comprehensive vault status dashboard
- Shows backend configuration (type, login status, unlock status)
- Lists all vault items with counts (config items, SSH keys)
- Sync history with human-readable timestamps ("2h ago", "3d ago")
- Comprehensive drift detection comparing 6 key config files
- Actionable recommendations based on drift status
- Beautiful formatted output with sections and emojis
- Timestamp tracking: saves vault.last_pull and vault.last_push to config.json
- ISO 8601 format timestamps in UTC
Template System Documentation (Pain Point #10) - Hidden gem now visible
- Massively enhanced template documentation in main README (8 lines → 132 lines)
- 3 real-world examples: Git config, SSH config, environment variables
- Clear problem/solution framing for multi-machine use cases
- Quick start 5-step workflow
- Auto-detected variables documentation (HOSTNAME, OS, USER, etc.)
- Use cases: work vs personal, multi-cloud, team onboarding
- Template syntax examples with conditionals and loops
v3.0 Command Namespace - Git-inspired command names (BREAKING CHANGE)
- NEW commands: vault setup, vault scan, vault pull, vault push, vault status
- Git-inspired naming: pull/push instead of restore/sync
- Clearer intent: setup (not init), scan (not discover)
- See: vault/README.md for complete command reference
Top-Level Backup & Rollback Commands - Safety features promoted to first-class
- blackdot backup - Create backup of current configuration
- blackdot backup list - List all available backups
- blackdot backup restore <name> - Restore specific backup
- blackdot rollback - Instant rollback to last backup
- blackdot rollback --to <name> - Rollback to specific backup
- Backup moved out of vault namespace for clearer separation
- Implements v3.0 design goal: mandatory safety features
Enhanced Help Text - Clean, focused CLI help
- Main help (blackdot help) shows complete command structure
- Vault help (blackdot vault help) with clear command categories
- Color-coded sections for better readability
- Removed version labels and migration noise
JSON Config System (v3.0) - Modern configuration format with nested structure
- lib/_config.sh - JSON config abstraction layer with type-safe functions
- config_get, config_set, config_get_bool, config_set_bool
- config_array_add, config_array_remove for array management
- config_get_array for retrieving array values
- Nested configuration: vault.backend, setup.completed[], paths.*
- Validation and backup functions built-in
- Uses jq for JSON manipulation (already a dependency)
- Default config with sensible defaults for all v3.0 settings
Migration Tools (v3.0) - Automated migration from v2.x to v3.0
- bin/blackdot-migrate - Unified migration orchestrator
- bin/blackdot-migrate-config - INI→JSON config migration
- bin/blackdot-migrate-vault-schema - v2→v3 vault schema migration
- blackdot migrate - Top-level command in main CLI
- Interactive confirmation with --yes flag to skip
- Timestamped backups before all migrations
- Detects if migration is needed (idempotent)
- Shows migration summary with before/after comparison
Vault Schema v3.0 - Simplified, consistent vault item structure
- Single secrets[] array replaces separate ssh_keys/vault_items/syncable_items
- Eliminates duplication between ssh_keys and vault_items
- Per-item control: sync (always/manual), backup (true/false), required (true/false)
- Consistent schema: name, path, type, required, sync, backup
- Migration preserves all existing items and metadata
- version field indicates schema version
Configurable Workspace Target - Customize where /workspace points
- New setup wizard step (Step 1 of 7): Interactive workspace configuration
- New WORKSPACE_TARGET environment variable to specify custom directory
- New paths.workspace_target config option in config.json
- /workspace symlink name stays constant (for Claude Code portability)
- Only the TARGET directory is configurable (default: ~/workspace)
- Priority order: env var > config.json > default
- New lib/_paths.sh helper with get_workspace_target() and get_dotfiles_dir()
- All CLI tools updated to use configurable paths
- Usage: WORKSPACE_TARGET=~/code ./install.sh or configure via wizard
- Supports users with existing project layouts (~/code, ~/projects, ~/dev)
- Zero breaking changes - default behavior unchanged

Changed

BREAKING: Vault commands renamed - Old commands removed entirely
- vault init → vault setup
- vault discover → vault scan
- vault restore → vault pull
- vault sync → vault push
- vault backup → top-level backup command
- No migration period - clean break for greenfield deployment
State Management Backend (v3.0) - Now uses JSON config instead of INI files
- lib/_state.sh refactored to use JSON config as backend
- State stored in setup.completed[] array instead of INI sections
- API unchanged: state_completed(), state_complete(), state_reset() still work
- Backward compatible: existing scripts don't need changes
- Config stored in ~/.config/blackdot/config.json (v3 format)
v3.0 Breaking Changes Design - Comprehensive redesign proposal (DESIGN-v3.md)
- Git-inspired command names: setup, scan, pull, push (replaces init, discover, restore, sync)
- Config format migration: INI → JSON (consistent with vault-items.json, native jq support)
- Mandatory auto-backup before all destructive operations
- Package tier selection in setup wizard (minimal/enhanced/full)
- Enhanced error messages with fix commands and documentation links
- Health score interpretation with auto-fix command
- Simplified vault schema (eliminates duplication)
- 4-week implementation timeline with auto-migration strategy
- See DESIGN-v3.md for full details
Pain-Point Analysis Refactoring - Updated pain-point-analysis.md with v3.0 solutions
- All 23 pain points now include v3.0 solutions
- Cross-referenced with DESIGN-v3.md sections
- v2.3 solutions documented alongside v3.0 enhancements
- Updated executive summary with v3.0 vision
- Phased implementation roadmap (4 weeks)
- Success criteria and next steps

Fixed

Critical Bug Fixes - Comprehensive code audit identified and fixed 4 critical/high severity issues
- Progress bar division by zero (CRITICAL): Added guards to prevent crash if total=0 or current>total
  - show_progress() now validates inputs and clamps values to safe ranges
  - Prevents overflow when current step exceeds total steps
  - File: bin/blackdot-setup lines 75-95
- Lost package installation exit status (CRITICAL): Fixed exit code capture in brew bundle
  - Changed from $? (captures while loop status) to ${pipestatus[1]} (captures brew status)
  - Prevents false "success" reports when package installation actually failed
  - File: bin/blackdot-setup line 370
- Missing schema validation in setup wizard (HIGH): Added validation to vault configuration phase
  - Setup wizard now validates vault-items.json immediately after creation/editing
  - Interactive fix flow: detects errors → opens editor → re-validates → confirms before continuing
  - Prevents proceeding with invalid config that would fail mysteriously during vault operations
  - File: bin/blackdot-setup lines 513-544
- Test environment stderr pollution (HIGH): Fixed unit test failure in CI
  - Config initialization messages were leaking into test output (4 lines instead of expected 2)
  - Suppressed stderr during _common.sh sourcing in test helper functions
  - File: test/vault_common.bats line 83
- All 119 tests now pass reliably in both local and CI environments
v3.0 Consistency Audit - Eliminated all v2.x command and config references (23 instances)
- Updated 7 vault scripts to use v3.0 commands (setup/scan/pull/push)
- Updated 9 documentation files with correct v3.0 command examples
- vault/init-vault.sh now uses centralized lib/_config.sh instead of inline INI parsing
- All config file references updated: state.ini/config.ini → config.json
- File Locations tables updated to reflect v3.0 JSON format
- State Management documentation sections rewritten for v3.0
- Complete codebase now consistent with v3.0 command namespace
- Affects: vault scripts, bootstrap, docs (17 files total)
Documentation Quick Wins - Improved clarity on common pain points (#5, #9, #14, #15)
- CLAUDE.md placement (#14): Added prominent header explaining it's for AI agents, not users
- Workspace symlink purpose (#15): Expanded explanation of /workspace symlink benefits
  - Clear problem/solution format showing why it enables Claude Code session portability
  - Explains different paths = different sessions = lost history without symlink
  - Updated in README.md and docs/README.md
- Multi-vault clarification (#9): Clarified "multi-vault" means one backend at a time
  - Added note explaining system supports multiple backends but you use one active backend
  - Documented switching process with blackdot vault setup
  - Updated docs/vault-README.md
- Vault merge preview (#5): Improved confusing "manual items" terminology
  - Changed "Preserved manual items" → "Preserved items in config but not discovered"
  - Added explanation: "may be custom paths, moved files, or items from other machines"
  - Updated merge/replace prompts with clearer recommendations (existing vs. fresh machines)
  - Added tip explaining what merge preserves
  - Updated vault/discover-secrets.sh
Documentation v3.0 Audit - Updated all documentation for tier selection feature
- Fixed outdated package counts in README.md, docs/README-FULL.md, docs/architecture.md, docs/cli-reference.md
- Updated BREWFILE_TIER documentation to reflect interactive wizard (was env var only)
- Corrected package counts: 18/43/61 (was incorrectly documented as 15/40/80 or 40/80/120+)
- Added "How it works" sections explaining config.json persistence
- Emphasized interactive setup wizard over environment variable approach
- Affects: README.md (3 sections), docs/README-FULL.md, docs/architecture.md, docs/cli-reference.md
Unit Test Compatibility - Fixed 47 failing tests caused by export -f statements
- Removed bash-specific export -f statements from lib/_config.sh
- Functions sourced from library files don't need explicit export
- Improves cross-shell compatibility (bash/zsh/sh)
- Tests now pass: 75/76 unit tests, 21/21 integration tests, 22/22 error scenarios
- Only 1 minor test remains (SSH key count environmental issue)
Vault Command Clarity - Improved help text to clarify relationship between init and discover
- Added workflow section showing: First time → init, Re-scan → discover
- Highlighted that vault init includes auto-discovery as part of setup
- Reduced confusion about command order and purpose
- Addresses pain-point #1: "Do I run init first or discover first?"

Added

Automatic Backup Before Restore - Vault restore now auto-creates backup
- Creates timestamped backup before overwriting any local secrets
- Shows backup location and restore command
- Added blackdot vault backup command (exposed existing bin/blackdot-backup)
- Eliminates fear of losing local changes during restore
- Addresses pain-point #2: "No rollback/undo" concern
Package Tier Selection (#3) - Interactive tier selection in setup wizard
- Presents 3 tiers with package counts and time estimates:
  - Minimal: 18 packages (~2 min) - Essentials only
  - Enhanced: 43 packages (~5 min) - Modern tools, no containers (RECOMMENDED)
  - Full: 61 packages (~10 min) - Everything (Docker, etc.)
- Saves tier preference in config.json (packages.tier)
- Uses saved preference if re-running setup
- Shows accurate package count and progress during installation
- Makes invisible tier options visible (was hidden env variable)
- Addresses pain-point #3: "Brewfile tier selection invisible"
Package Installation Progress - Setup wizard now shows real-time progress
- Displays package count before installation
- Streams brew output with highlighted progress
- Shows "(X installed)" counter during installation
- Time estimate maintained: "~5-10 minutes"
- Addresses pain-point #3: "Is it frozen?" confusion

[2.3.0] - 2025-12-04

Fixed

Dynamic Path Resolution - Fixed hardcoded paths in zsh configuration
- All blackdot commands now work regardless of installation location
- Introduced $BLACKDOT_DIR environment variable (auto-detected from config location)
- Replaced all hardcoded $HOME/workspace/dotfiles paths with $BLACKDOT_DIR
- Fixed initial path calculation bug (needed :h:h:h not :h:h for 3 directory levels)
- Fixes issue where commands would fail if dotfiles weren't at exact expected path
- Fixes "vault/discover-secrets.sh: no such file or directory" error
- Affects: 40-aliases.zsh, 50-functions.zsh, 10-plugins.zsh, 20-env.zsh
- Critical for users who clone dotfiles to custom locations
Vault Backend Permissions - Fixed missing execute permissions on vault backends
- vault/backends/bitwarden.sh, 1password.sh, pass.sh now executable
- Resolves potential execution failures when directly invoking backends
- Audit finding: Critical issue resolved
Brew Bundle Resilience - Bootstrap no longer fails on package link conflicts
- Common issue: npm-installed packages (like bw) conflicting with Homebrew versions
- Auto-detects unlinked packages and attempts to fix with brew link --overwrite
- Bootstrap continues even if some packages have link issues (non-fatal)
- Provides clear feedback about what was fixed vs what needs manual attention
- Fixes #UX: "why should it fail just because something is installed already"
Homebrew Installation Resilience - Retry logic for network failures
- Homebrew installation now retries up to 3 times with exponential backoff (2s, 4s, 8s)
- Provides helpful error messages on failure (network issues, rate limiting, requirements)
- Offers option to continue without Homebrew or abort (user choice)
- Prevents bootstrap failure due to temporary network hiccups
- Applies to both macOS and Linux (Linuxbrew) installations
Brew Bundle Compatibility - Removed deprecated --no-lock flag
- Fixes "invalid option: --no-lock" error in setup wizard
- Compatible with Homebrew 5.0+ which removed this flag
- Setup wizard now works correctly on latest Homebrew versions
Homebrew Path Detection - Use actual installation path after fresh install
- macOS bootstrap now detects which Homebrew was just installed
- Directly uses the installation path instead of checking all possible locations
- Clearer logic: only checks paths after fresh installation
- Handles Apple Silicon (/opt/homebrew) vs Intel (/usr/local) correctly

Added

Vault Init Command - New blackdot vault init for easy vault configuration
- Configure or reconfigure vault backend anytime
- No need to reset setup state or run full wizard
- Detects existing configuration and asks to reconfigure
- Clear guidance when skipping vault setup
- Accessible via blackdot vault init or blackdot vault init --force
Vault Auto-Discovery - Automatically detect secrets in standard locations
- New blackdot vault discover command scans for existing secrets
- Auto-detects SSH keys in ~/.ssh/ (all key types)
- Discovers AWS configs, Git config, npm, pypi, docker configs
- Supports custom paths: --ssh-path and --config-path options
- Generates vault-items.json automatically with smart naming
- Intelligent Merge Logic - Safely merges with existing config (non-destructive)
  - Preserves manual additions (items not auto-discovered)
  - Preserves manual customizations (e.g., required: false)
  - Creates automatic backup before merge
  - Use --force to skip merge and overwrite completely
  - Requires jq for merge (gracefully falls back if not available)
- Integrated into blackdot vault init with auto-discover option
- No more manual JSON editing for standard setups
- Preview mode with --dry-run flag
- Eliminates biggest UX friction point in vault setup

Documentation

Vault Discover Documentation - Added comprehensive docs for auto-discovery
- Documented in root README.md and docs/README-FULL.md
- Usage examples and integration with vault init
- Audit finding: Critical documentation gap resolved
Brewfile Tier Documentation - Added BREWFILE_TIER environment variable docs
- Documented in Prerequisites sections of README.md and README-FULL.md
- Explains minimal/enhanced/full tier options
- Shows how to set before bootstrap
- Audit finding: High-priority documentation gap resolved

Improved

Installation Flow - Smoother onboarding experience
- install.sh now prompts "Run setup wizard now? [Y/n]" after installation
- Automatically loads new shell and runs setup if user confirms
- No more manual "exec zsh" → "dotfiles setup" dance
- Minimal mode shows numbered steps for manual configuration
Setup Completion - Context-aware next steps after wizard completes
- Shows dynamic recommendations based on what was configured
- Vault configured → Suggests blackdot vault restore
- Templates configured → Suggests blackdot template render
- Always shows blackdot doctor for health check
- Helpful commands and documentation links
Setup Progress Indicators - Shows "Step X of 6" for all wizard phases
- Clear progress tracking throughout setup wizard
- Time estimates for long operations (Packages: ~5-10 min)
- Users always know how far along they are
- Audit recommendation: High-priority UX improvement implemented
Shell Feature Discovery - Highlights new ZSH features post-setup
- Setup completion now shows useful shell aliases and tools
- Conditionally displays features based on what's actually installed
- Enhanced ls commands (ll, la, lt) with eza
- Git shortcuts (gst, gd, gco, etc.)
- Fuzzy search with fzf (Ctrl+R)
- Smart directory navigation with zoxide (z command)
- Terminal file manager with yazi (y command)
- Adapts to minimal/enhanced/full Brewfile tiers
- Helps users discover what they just installed
Vault Schema Validation - Suggests running validation after vault configuration
- Setup completion now recommends blackdot vault validate
- Catches schema errors before attempting restore
- Audit recommendation: Proactive error prevention
Vault Setup UX - Better experience for configuring and skipping vault
- Setup wizard now asks "Reconfigure vault?" if already configured
- Distinguishes between "skipped" vs "configured" in status display
- Skipped vault shows [⊘] icon with hint: "run 'dotfiles vault init'"
- Configured vault shows backend name in status
- All skip paths mention how to configure later
- Fixes UX issue where skipping vault permanently locked you out of configuration
macOS /workspace Symlink Handling - Better guidance for read-only filesystem
- Detects macOS read-only root filesystem (Catalina+)
- Provides clear instructions for using synthetic.conf (Apple-approved method)
- Shows exact commands to create persistent root-level symlink
- Explains that ~/workspace still works without /workspace symlink
- No longer shows confusing "fix manually" command that won't work on modern macOS

[2.2.0] - 2025-12-03

Added

Brewfile Tiers - Tiered package management for flexible installation sizes
- Brewfile.minimal (~15 packages) - Essentials only (git, zsh, jq, shell plugins)
- Brewfile.enhanced (~40 packages) - Modern CLI tools without containers (fzf, ripgrep, bat, eza)
- Brewfile (~80 packages) - Full install including Docker, Node, advanced tools
- Control tier with BREWFILE_TIER=minimal|enhanced|full environment variable
- Bootstrap scripts automatically select correct Brewfile based on tier
- Default tier is "full" (maintains backwards compatibility)
- Use cases:
  - minimal - CI/CD, servers, containers, resource-constrained environments
  - enhanced - Developer workstations without container needs
  - full - Complete toolkit including Docker/Lima for full-stack development
- All tiers work on macOS (Homebrew) and Linux (Linuxbrew)
- macOS-specific casks automatically skipped on Linux
Templates Onboarding - Added interactive template setup to setup wizard
- New STEP 6 in blackdot setup guides users through template configuration
- Explains use cases: work vs personal git email, different SSH keys, machine-specific env vars
- Runs blackdot template init interactively during onboarding
- Defaults to "No" (opt-in) to keep setup fast for users who don't need templates
- Shows how to enable later: blackdot template init
- Integrates with state management system (resume support)
- Updated README hero section to show complete 6-step flow
- Makes templates discoverable without forcing complexity

Changed

Modularity Documentation - Emphasized optional components throughout docs
- Updated tagline: "Opinionated" → "Modular, batteries-included"
- Added "Pick What You Want" section to README with Component Matrix
- Multiple one-line install options shown upfront (Full/Minimal/Custom)
- Added "Modular Architecture" section to docs/architecture.md
- Added "Modular Design" section to docs/cli-reference.md
- Enhanced install.sh help text with modular install instructions
- Documented all SKIP_* environment variables prominently
- Updated Docsify coverpage to emphasize modularity
- Philosophy: "Everything is optional except shell config"

[2.1.0] - 2025-12-03

Added

Smart Secrets Onboarding - Intelligent first-time setup for users with existing secrets
- Detects local secrets (SSH keys, AWS creds, Git config) vs vault items
- Categorizes as "local only", "vault only", or "synced"
- Offers to PUSH local secrets to vault for new users migrating their setup
- Offers to RESTORE from vault for users on new machines
- Shows sync status for items that exist in both locations
- create-vault-item.sh supports custom file paths for non-standard locations
- Dramatically improves onboarding for users who already have local credentials
Vault Items Configuration File - User-editable JSON config for vault items
- ~/.config/blackdot/vault-items.json defines SSH keys, vault items, syncable items
- No more hardcoded organization-specific values in source code
- vault/vault-items.example.json provides template to customize
- blackdot setup creates config automatically during wizard
- require_vault_config() ensures config exists before vault operations
Template CLI Help Improvements - Better discoverability in blackdot template help
- Added list command to help output (shows available templates with status)
- Added {{#each}} loop syntax to template syntax section
- Added DOCUMENTATION section with links to docs/templates.md and online guide
Template JSON Arrays - {{#each}} loops now support JSON configuration
- New templates/_arrays.local.json for cleaner array definitions
- blackdot template arrays command to view/manage arrays
- blackdot template arrays --export-json exports shell arrays to JSON format
- blackdot template arrays --validate validates JSON syntax
- Falls back to shell arrays if no JSON file present
Docker Container Taxonomy - Multiple container sizes for different needs
- Dockerfile.extralite (~50MB) - Ultra-minimal for quick exploration
- Dockerfile.lite (~250MB) - Lightweight with vault CLI support (Bitwarden, 1Password, pass)
- Dockerfile.medium (~400MB) - Ubuntu with Homebrew for full dotfiles functionality
- Added Powerlevel10k shell theme to lite container
- New docs/docker.md documenting all container options
- Welcome messages on container startup with quick start instructions
Mock Vault for Testing - Test vault commands without real credentials
- test/mocks/setup-mock-vault.sh creates fake GPG key + pass store
- Populates all expected vault items with mock credentials
- Works with pass backend (export BLACKDOT_VAULT_BACKEND=pass)
- Options: --no-pass (no passphrase), --clean (reset)
Minimal Mode Documentation - Clarified what --minimal skips and how to enable features later

Fixed

Bitwarden CLI in Alpine - Switched to standalone binary to fix ESM compatibility issues
Container bootstrap directory - Fixed missing bootstrap/ in Docker containers
Test Suite Compatibility - Fixed all 76 tests to work with config-based vault items
- Made VAULT_CONFIG_FILE environment variable override-able for tests
- Installed jq in all CI test jobs (was missing)
- Used absolute paths /usr/bin/sort and /usr/bin/jq to fix PATH issues in zsh -c contexts
- Fixed zsh PATH variable corruption: renamed path → item_path in DOTFILES_ITEMS loop
- Tests now pass: 76/76 (100% pass rate)

[2.0.1] - 2025-12-02

Added

Help hint for subcommand options - Main blackdot help now shows: "Run 'dotfiles --help' for detailed options"
State Management in Quick Navigation - Added link to state-management.md in docsify homepage

[2.0.0] - 2025-12-02

Breaking Changes

Removed blackdot init command - Now use blackdot setup instead
Removed install.sh --interactive flag - Bootstrap now prompts to run blackdot setup
Renamed vault/bootstrap-vault.sh to vault/restore.sh for clarity

Added

Unified Setup Wizard (blackdot setup) - New interactive setup with persistent state
- Five-phase setup: symlinks → packages → vault → secrets → claude
- Progress persistence in ~/.config/blackdot/state.ini and ~/.config/blackdot/config.ini
- Resume support: continue where you left off if interrupted
- State inference: auto-detects existing installations from filesystem
- Visual status dashboard with checkmarks (blackdot setup --status)
- Reset capability (blackdot setup --reset)
State Management Library (lib/_state.sh) - Pure zsh INI file parsing
- Functions: state_init, state_completed, state_complete, state_needs_setup
- Config API: config_get, config_set for persistent preferences
- State inference: state_infer detects symlinks, packages, vault, secrets, Claude
- Files: ~/.config/blackdot/state.ini (phase completion), ~/.config/blackdot/config.ini (user prefs)
macOS Settings Command (blackdot macos) - Expose macOS settings management
- blackdot macos apply - Apply settings from settings.sh
- blackdot macos preview - Dry-run mode
- blackdot macos discover - Capture current settings
Vault Restore Preview - blackdot vault restore --preview shows what would be restored without making changes
Documentation Updates
- New docs/state-management.md - Dedicated state system documentation
- State Management section in docs/cli-reference.md with INI file format examples
- blackdot macos command reference with all subcommands and options
- Updated all references from blackdot init to blackdot setup
- Added macos command to architecture diagram

Changed

Renamed bootstrap-vault.sh to restore.sh - Clearer naming for vault orchestrator
Removed blackdot init - Replaced by blackdot setup with better state management
Vault Backend Persistence - Backend choice now saved to config file
- Priority: config file → environment variable → default (bitwarden)
- Persists across sessions without needing to export env var
Simplified install.sh - Removed --interactive flag
- Bootstrap scripts now tell user to run blackdot setup
- Cleaner separation: install.sh handles clone/bootstrap, setup handles configuration
dotfiles-drift Multi-Backend Support - Now works with all vault backends (Bitwarden, 1Password, pass)
- Uses lib/_vault.sh abstraction instead of hardcoded Bitwarden commands
- Dynamic backend name in messages
- Backend-specific login hints
dotclaude Install URL - Updated to GitHub raw URL (raw.githubusercontent.com/blackwell-systems/dotclaude/main/install.sh)
Status Dashboard - Simplified ASCII art header (dimmed city skyline, no embedded indicators)
Post-Install Prompt - Made exec zsh prompt more prominent with yellow highlight

Fixed

Template Engine: {{#if}} inside {{#each}} - Conditionals now work correctly inside loops
- Added process_loop_conditionals() function to evaluate loop variables
Template Engine: Nested {{#else}} - Fixed stray {{/if}} tags in output
- Properly matches {{#else}} at correct nesting depth
pass Function Name Collision - Fixed conflict in dotfiles-setup between pass CLI and logging function
- Uses command pass to explicitly call the CLI
Test: Doctor Claude Detection - Fixed test failing when real claude installed
- Test now isolates PATH to exclude system claude

[1.8.4] - 2025-12-02

Added

dotclaude Integration Documentation - Comprehensive integration guide (docs/DOTCLAUDE-INTEGRATION.md)
- Architecture diagrams showing system boundaries and data flow
- Division of responsibilities (dotclaude: profiles, dotfiles: secrets)
- Usage workflows for multi-client, OSS vs work, multi-machine, and secrets rotation
- Configuration, troubleshooting, and security best practices
Mermaid Diagram Support - Dark mode compatible diagrams throughout documentation
- Configured dark theme for better contrast in docs
- Converted ASCII diagrams to Mermaid in README-FULL
- Architecture diagrams for multi-platform, workspace, and organizational structure

Changed

Installation Command Pattern - Replaced confusing bash -s -- pattern with familiar download-first approach
- All documentation now uses: curl -fsSL ... -o install.sh && bash install.sh --interactive
- Updated install.sh header comments and --help text
- Consistent pattern across README, docs, and CLI reference
Badge Reorganization - Improved visual hierarchy in README
- Moved Zsh badge to row 1 (after Blackwell Systems)
- Removed duplicate Tests count badge
- Added dotclaude integration badge
Comparison Tables - Made collapsible for better readability
- "Quick Comparison: This Repo vs Typical Dotfiles" now collapsible
- "Why This Repo vs chezmoi?" now collapsible
README-FULL Modernization - Updated architecture diagrams and removed outdated claims
- Removed "Key Innovation: Portable Claude Code Sessions" marketing language
- Simplified diagrams for better resolution and readability
- Directory structure now collapsible with full ASCII tree

Documentation

Added dotclaude integration links throughout documentation ecosystem
Added comprehensive badge set to README-FULL
Cross-linked dotfiles and dotclaude documentation sites
Improved feature presentation with code blocks and collapsible sections
Updated coverpage formatting and Development & Testing section

[1.8.3] - 2025-12-01

Added

GitHub Sponsors Support - Added github: blackwell-systems to FUNDING.yml
Collapsible README Sections - Made Acknowledgments, Troubleshooting, The dotfiles Command, and Project Structure collapsible for better readability
DOTFILES_SKIP_DRIFT_CHECK documentation - Added missing environment variable to Optional Components

Changed

Vault-Agnostic blackdot init - Major refactor of interactive setup wizard
- Auto-detects all vault backends (Bitwarden, 1Password, pass)
- Prompts user to choose vault (never auto-selects)
- Option to skip vault setup entirely
- Backend-specific login/unlock flows
- Fixes Alpine/Linux issue where pass was auto-selected
Integrated install.sh with blackdot init - install.sh --interactive now calls the wizard automatically
Simplified Quick Start - Reduced from 4 manual steps to 2 (clone → dotfiles init)
Reordered README Sections - End sections now: Acknowledgments → Trademarks → License
Updated Project Structure - Added lib/_vault.sh and test/fixtures/ subdirectory
Removed Bitwarden Bias - All documentation now vault-agnostic

Documentation

Updated README.md, docs/README.md, docs/README-FULL.md with simplified install flow
Updated docs/cli-reference.md with comprehensive blackdot init documentation
All install documentation now consistently promotes 2-step flow

[1.8.2] - 2025-12-01

Added

Test Drive Guide (docs/TESTDRIVE.md) - Comprehensive Docker exploration guide
- Sample workflows for safe testing
- dotclaude integration examples
- FAQ and troubleshooting
Added "Try Before Installing" section to README with Docker instructions

Fixed

Improved template validation tests for better error handling

[1.8.1] - 2025-12-01

Fixed

Template tests now correctly source _logging.sh (fixes 3 failing tests)
Removed misleading codecov badge (shell coverage tracking is unreliable)

[1.8.0] - 2025-12-01

Added

dotclaude Integration - Claude Code profile management across machines
- blackdot status shows active Claude profile (if dotclaude installed)
- blackdot doctor validates Claude/dotclaude setup with install hints
- blackdot vault syncs ~/.claude/profiles.json to vault
- blackdot drift detects Claude profile changes vs vault
- blackdot packages suggests dotclaude for Claude users
- blackdot init offers dotclaude installation during setup wizard
- See docs/claude-code.md for details
Dockerfile.lite - Lightweight Alpine container for CLI exploration
{{#each}} Template Loops - Iterate over arrays with named fields
- Define SSH_HOSTS array in _variables.local.sh
- Use {{#each ssh_hosts}}...{{/each}} in templates
- Access fields: {{ name }}, {{ hostname }}, {{ user }}, {{ identity }}, {{ extra }}
- Conditionals work inside loops for optional fields
- ssh-config.tmpl now generates hosts from SSH_HOSTS array
Template Tests (test/templates.bats) - Unit tests for template engine
Vault Backend Guide (docs/extending-backends.md) - How to add new vault providers

Fixed

Template Engine: {{#if}} inside {{#each}} - Conditionals now work correctly inside loops
- {{#if extra}}...{{/if}} now evaluates loop variables properly
- Added process_loop_conditionals() function to handle loop-scoped conditions
Template Engine: Nested {{#else}} handling - Fixed stray {{/if}} tags in output
- Properly matches {{#else}} at the correct nesting level
- No longer grabs nested conditionals' else blocks

[1.7.0] - 2025-11-29

Added - Multi-Vault Backend Support

Vault Abstraction Layer

Multi-vault support - Choose your preferred secret management backend:
- Bitwarden (bw) - Default, full-featured, cloud-synced
- 1Password (op) - v2 CLI with biometric auth
- pass (pass) - GPG-based, git-synced, local-first
lib/_vault.sh - Unified vault API with pluggable backends
vault/backends/ - Backend implementations
- bitwarden.sh - Bitwarden CLI backend
- 1password.sh - 1Password CLI v2 backend
- pass.sh - pass (GPG) backend
- _interface.md - Interface specification for backend implementations
BLACKDOT_VAULT_BACKEND - Environment variable to select backend (defaults to bitwarden)

Backward Compatibility

Legacy bw_* functions still work (aliased to new vault_* API)
Existing vault items and workflows unchanged
Session caching unified across backends (.vault-session)

Added - Root Directory Cleanup

Consolidated bootstrap/ Directory

Moved bootstrap scripts to bootstrap/ for cleaner repository root
- bootstrap/bootstrap-mac.sh - macOS setup
- bootstrap/bootstrap-linux.sh - Linux/WSL2/Lima setup
- bootstrap/bootstrap-dotfiles.sh - Symlink creation
- bootstrap/_common.sh - Shared bootstrap functions (already here)

Relocated Configuration Files

Moved codecov.yml to .github/ - CI configuration with other GitHub files
Moved claude.local.example to claude/ - Example config with Claude settings
Moved NOTES.md and BRAND.md to docs/ - Documentation in docs directory

Removed

VERSION file - Redundant with CHANGELOG.md as source of truth
bootstrap-lima.sh symlink - Deprecated alias for bootstrap-linux.sh

Changed

Bootstrap scripts updated to find BLACKDOT_DIR from parent directory
install.sh updated with new bootstrap script paths
Dockerfile updated with new bootstrap script path
All CI workflow paths updated for new locations
Updated all documentation with new paths and project structure

Documentation

Updated project structure in README.md, docs/README.md, CLAUDE.md
Updated Quick Start instructions with new bootstrap paths
Updated claude.local.example path references

[1.6.0] - 2025-11-28

Added - CLI Reorganization

bin/ Directory Structure

Moved CLI scripts to bin/ for cleaner repository root
- dotfiles-doctor - Health validation
- dotfiles-drift - Drift detection
- dotfiles-backup - Backup/restore
- dotfiles-diff - Preview changes
- dotfiles-init - Setup wizard
- blackdot-metrics - Metrics visualization (renamed from show-metrics.sh)
- dotfiles-uninstall - Clean removal (renamed from uninstall.sh)

Changed

Scripts now source lib/_logging.sh from $BLACKDOT_DIR/lib/ (parent of bin/)
zsh/zsh.d/40-aliases.zsh updated to reference bin/ paths
All test files updated with new paths
CI/CD workflow updated with new paths
Removed .sh extensions from CLI scripts for cleaner invocation

Documentation

Updated project structure in README.md and docs/README.md
Updated ROADMAP.md to mark CLI reorganization as completed
Updated CHANGELOG.md with v1.6.0 entry

[1.5.0] - 2025-11-28

Added - Offline Mode Support

Offline Mode

DOTFILES_OFFLINE=1 - Skip all Bitwarden vault operations gracefully
- is_offline() - Check if offline mode is enabled
- require_online() - Helper to skip vault operations in offline mode
- require_bw() and require_logged_in() - Skip checks in offline mode

Use Cases

Air-gapped environments without Bitwarden access
Bitwarden service outages
Development/testing without vault connectivity
CI/CD pipelines without secrets

Changed

vault/bootstrap-vault.sh - Exits gracefully with helpful message in offline mode
vault/sync-to-bitwarden.sh - Skips sync with explanation in offline mode
Updated all documentation with offline mode usage

Documentation

Added offline mode to README.md and docs/README.md environment flags
Added "Air-gapped/Offline" use case to both READMEs
Updated vault documentation with offline mode examples
Updated ROADMAP.md - marked offline mode as completed

[1.4.0] - 2025-11-28

Added - Bootstrap Consolidation & Safety Features

Bootstrap Shared Library

bootstrap/_common.sh - Shared bootstrap functions
- parse_bootstrap_args() - Argument parsing (--interactive, --help)
- prompt_yes_no() - Interactive yes/no prompts
- run_interactive_config() - Interactive setup wizard
- setup_workspace_layout() - ~/workspace directory creation
- setup_workspace_symlink() - /workspace symlink setup
- link_dotfiles() - Dotfiles symlinking
- run_brew_bundle() - Homebrew bundle installation
- add_brew_to_zprofile() - Homebrew PATH setup

Pre-Restore Drift Check

Safety feature - Prevents accidental data loss during blackdot vault restore
- Detects when local files have changed since last vault sync
- Warns user and suggests options: sync first, force restore, or review diff
- check_item_drift() - Check single item for drift
- check_pre_restore_drift() - Check all syncable items
- skip_drift_check() - Check DOTFILES_SKIP_DRIFT_CHECK env var
- --force flag to skip drift check when needed

Changed

bootstrap-mac.sh - Now sources bootstrap/_common.sh for shared functions
bootstrap-linux.sh - Now sources bootstrap/_common.sh for shared functions
vault/bootstrap-vault.sh - Added drift check before restore
Help text updated for blackdot vault restore --force
Reduced code duplication by ~60% in bootstrap scripts

Documentation

Updated docs/ROADMAP.md with completed v1.4.0 improvements
Updated README.md and docs/README.md with new vault restore options
Added bootstrap/ directory to project structure documentation

[1.3.0] - 2025-11-28

Added - Shared Library & Error Tests

Shared Logging Library

lib/_logging.sh - Centralized logging and color functions
- Color definitions (RED, GREEN, YELLOW, BLUE, CYAN, MAGENTA, BOLD, NC)
- Logging functions: info(), pass(), warn(), fail(), dry(), debug()
- Helper functions: section(), separator(), confirm()
- Guard against multiple sourcing
- Works with both bash and zsh

Error Scenario Tests

test/error_scenarios.bats - 20+ error handling tests
- Permission denied scenarios
- Missing file/directory handling
- Invalid data (corrupted backups, invalid JSON)
- Vault/session error states
- Edge cases (empty directories, special characters, symlink loops)
- CLI argument validation
- Concurrent operation safety

Changed

Scripts now use shared lib/_logging.sh instead of inline definitions:
- dotfiles-backup.sh
- dotfiles-diff.sh
- dotfiles-drift.sh
- dotfiles-init.sh
- show-metrics.sh
- uninstall.sh
- bootstrap-mac.sh
- bootstrap-linux.sh
CI/CD workflow now includes error scenario tests
Test runner supports error mode: ./run_tests.sh error
Documentation updated with Windows platform support

Documentation

docs/ROADMAP.md - Future improvements roadmap
- Prioritized improvement list
- Design decisions documentation
- Contributing guidelines for roadmap items

[1.2.2] - 2025-11-28

Added - Code Coverage

Codecov Integration

codecov.yml - Codecov configuration file
- 60% target coverage for project
- 50% target coverage for patches
- Ignores test files, docs, and configs from coverage
- PR comments with coverage diffs
- Flags for unit and integration tests

CI/CD Coverage Job

.github/workflows/test.yml - Added coverage job
- kcov for shell script coverage collection
- Separate unit and integration coverage runs
- Merged coverage reports
- Automatic upload to Codecov
- Coverage badge in README

Changed

Added Codecov badge to README.md and docs/README.md

[1.2.1] - 2025-11-28

Added - Integration Tests

Mock Bitwarden CLI

test/mocks/bw - Mock Bitwarden CLI for testing
- Simulates all bw commands (status, get, list, create, etc.)
- Configurable vault state (locked/unlocked)
- Uses file-based mock data for predictable results

Test Fixtures

test/fixtures/vault-items/ - Sample vault items
- SSH-Config, Git-Config, AWS-Config, AWS-Credentials
- Environment-Secrets
- Realistic JSON structure matching real Bitwarden items

Integration Test Suite

test/integration.bats - 20+ integration tests
- Mock bw CLI validation tests
- Backup create/list/restore cycle tests
- Diff preview tests
- Uninstall dry-run tests
- Error handling tests
- End-to-end workflow tests

Changed

test/run_tests.sh - Enhanced test runner
- Supports unit, integration, or all modes
- Separate execution of unit vs integration tests
- Colored output with clear status
.github/workflows/test.yml - Added integration test job
- Separate CI job for integration tests
- Mock bw CLI setup in CI environment

[1.2.0] - 2025-11-28

Added - CLI Commands

Unified `blackdot` Command Expansion

blackdot diff - Preview changes before sync or restore
- blackdot diff --sync - Show what would be synced to vault
- blackdot diff --restore - Show what restore would change
- Unified diff output with color coding
blackdot backup - Backup and restore configuration
- Creates timestamped tar.gz archives in ~/.blackdot-backups/
- blackdot backup - Create new backup
- blackdot backup --list - List available backups
- blackdot backup restore - Interactive restore from backup
- Auto-cleanup keeps only 10 most recent backups
blackdot init - First-time setup wizard
- Interactive walkthrough for new installations
- Guides through bootstrap, Bitwarden setup, secret restoration
- ASCII art banner and step-by-step progress
blackdot uninstall - Clean removal script
- blackdot uninstall --dry-run - Preview what would be removed
- blackdot uninstall --keep-secrets - Remove dotfiles but keep SSH/AWS/Git
- Safe removal with confirmation prompts

Tab Completion

_dotfiles completion - Full tab completion for dotfiles command
- All subcommands with descriptions
- Vault subcommands with item names
- Flag completions for all options

Added - New Scripts

dotfiles-backup.sh - Backup and restore functionality
dotfiles-diff.sh - Preview changes before sync/restore
dotfiles-init.sh - First-time setup wizard
uninstall.sh - Clean removal script

Added - Documentation

Architecture page (docs/architecture.md)
- Mermaid diagrams for system overview
- Component architecture diagrams
- ZSH module load order diagram
- Vault system sequence diagram
- Data flow summary table
Troubleshooting guide (docs/troubleshooting.md)
- Quick diagnostics section
- Installation issues and fixes
- Shell issues (prompt, completions)
- Bitwarden/vault issues
- Permission fixes
- Platform-specific issues
- Backup/restore issues

Added - CI/CD

Release workflow (.github/workflows/release.yml)
- Automated releases on git tag push
- Changelog generation from commits
- Archive creation (tar.gz and zip)
- SHA256 checksums
- GitHub release with notes
Enhanced test coverage
- test/cli_commands.bats - Tests for all CLI scripts
- Syntax validation for all new scripts
- Help flag tests for all commands

Changed

Updated 40-aliases.zsh with new commands (diff, backup, init, uninstall)
Updated test workflow to validate new scripts
Updated documentation with new commands and features
Expanded blackdot help output with all new commands

Infrastructure

New scripts made executable with proper permissions
Tab completion file added to zsh/completions/
Documentation sidebar updated with new pages

[1.1.0] - 2025-11-27

Added - Automation & Quality

CI/CD Pipeline

GitHub Actions Workflow (.github/workflows/test.yml)
- ShellCheck validation on all scripts (macOS + Linux)
- Markdown linting for documentation quality
- Repository structure validation
- Secrets scanning to prevent accidental commits
- Cross-platform compatibility testing
- Documentation completeness checks

Pre-commit Hooks

ShellCheck Pre-commit Hook (.git/hooks/pre-commit)
- Automatic validation of all shell scripts before commit
- Clear error messages with suggestions
- Prevents broken scripts from being committed

Added - Metrics & Observability

Health Metrics System

Automatic Metrics Collection in check-health.sh
- Records health check results to ~/.blackdot-metrics.jsonl
- Tracks: errors, warnings, fixes, health score (0-100)
- Includes git branch, commit hash, hostname, OS
- Timestamped entries for trend analysis
Metrics Visualization (show-metrics.sh)
- Summary view with statistics and recent trend
- Graph view with ASCII bar chart of health scores
- All-entries view for detailed history
- Color-coded health indicators (green/yellow/red)
- Calculates averages, totals, perfect run percentage

Added - Developer Experience

Improved Upgrade Flow

dotfiles-upgrade Command (replaces dotfiles-update)
- One-command upgrade with comprehensive steps:
  1. Pull latest changes from current branch
  2. Re-run bootstrap to update symlinks
  3. Update Homebrew packages from Brewfile
  4. Run health check with auto-fix
- Clear progress indicators
- Suggests shell restart after completion

Update Notifications

Daily Update Checker in zshrc
- Checks for dotfiles updates once per day
- Caches check result to avoid slowdown
- Shows notification with commit count if behind
- Cross-platform (macOS and Linux)

Local Customizations

.zshrc.local Support
- Machine-specific overrides without modifying tracked files
- Perfect for work laptop vs personal machine differences
- Automatically sourced if present
- Added to .gitignore

Tab Completions

ZSH Completion Scripts (zsh/completions/)
- _awsswitch - AWS profile switching with tab completion
- _awsset - AWS profile setting
- _awslogin - AWS SSO login
- _bw-sync - Bitwarden sync with item suggestions
- _dotfiles-doctor - Health check flags
- _show-metrics - Metrics display modes
Completions automatically loaded on shell startup

Added - Documentation

Multi-Platform Architecture Documentation
- Comprehensive "Multi-Platform Architecture" section in README
- Platform support matrix (macOS, Lima, WSL2, Ubuntu/Debian)
- Architecture layers diagram (10% platform-specific + 90% shared)
- Platform-independent components breakdown
- Guide for adding new platforms (15-30 minutes each)
- WSL2 auto-detection and Windows interop tools support
- Renamed bootstrap-lima.sh → bootstrap-linux.sh (with backward-compatible symlink)
- Platform detection examples showing auto-detection of WSL/Lima/bare Linux
REVIEW.md (8,700 words)
- Comprehensive architecture analysis
- Professional comparison vs FAANG companies
- Security audit and recommendations
- Innovation highlights (Claude session portability, vault SSoT)
- Grade: A+ (96/100)
RECOMMENDATIONS.md (2,500 words)
- Executive summary and assessment
- 5 Quick Wins (< 1 hour each)
- 3 Weekend Projects (CI/CD, metrics, completions)
- Long-term goals and 30-day action plan
- Comparison cheatsheet
README.md Updates
- New "What's New" section
- "Metrics & Observability" section
- "CI/CD & Testing" section
- "Multi-Platform Architecture" section
- Updated Table of Contents

Changed

Multi-Platform Improvements

Renamed bootstrap-lima.sh → bootstrap-linux.sh for clarity
- Now detects WSL2, Lima, or bare Linux automatically
- Platform-specific setup (WSL: Windows interop tools, Lima: integration notes)
- Backward-compatible symlink maintained for existing scripts/docs
Updated all references throughout codebase (CI/CD, docs, health checks)
Enhanced platform detection in bootstrap-linux.sh:
- Detects WSL2 via /proc/version
- Detects Lima via $LIMA_INSTANCE environment variable
- Provides platform-specific tips after installation

Refactored Components

Vault scripts now use shared _common.sh library (~50 lines saved per script)
dotfiles-update deprecated in favor of dotfiles-upgrade
Completion system initialization moved earlier in zshrc

Improved Functionality

check-health.sh now tracks metrics automatically
dotfiles-update shows deprecation warning
Update checker uses cross-platform date calculation

Fixed

SSH key names no longer hardcoded in multiple files
AWS profile names no longer hardcoded in check-health.sh
Completion system properly initialized before plugins

Infrastructure

.gitignore Updates

Added *.local to exclude machine-specific overrides
Added .dotfiles-update-check cache file
Added .blackdot-metrics.jsonl metrics file

New Scripts

show-metrics.sh - Health metrics visualization (183 lines)
.git/hooks/pre-commit - ShellCheck validation (54 lines)
.github/workflows/test.yml - CI/CD pipeline (230 lines)

Directory Structure

Created zsh/completions/ for tab completion scripts
Created .github/workflows/ for GitHub Actions

Security

Pre-commit hooks prevent committing broken scripts
GitHub Actions prevents secrets from being committed
All validation automated and enforced

Performance

Completion system optimized (single compinit call)
Update checker runs max once per 24 hours
Metrics collection is fast and unobtrusive

[1.0.1] - 2024-12-01

Added

vault/_common.sh - Shared library for all vault scripts (colors, logging, session management)
vault/create-vault-item.sh - Create new Bitwarden secure notes
vault/delete-vault-item.sh - Delete Bitwarden items with safety guards
vault/list-vault-items.sh - List vault items with metadata
Shell aliases: bw-restore, bw-sync, bw-create, bw-delete, bw-list, bw-check
Centralized SSH_KEYS and AWS_EXPECTED_PROFILES in _common.sh (single source of truth)
.gitignore to exclude .bw-session and editor files
KEY=VALUE validation in restore-env.sh

Changed

Refactored all vault scripts to use shared _common.sh library
dotfiles-update now detects current branch instead of assuming main
check-health.sh now sources _common.sh for SSH keys and AWS profiles
Updated vault/README.md with comprehensive script documentation

Fixed

SSH key names no longer hardcoded in multiple files
AWS profile names no longer hardcoded in check-health.sh

[1.0.0] - 2024-11-25

Added

Core Infrastructure

Cross-platform bootstrap scripts for macOS and Lima (Linux)
Unified Brewfile for both platforms
Idempotent bootstrap (safe to run multiple times)

Bitwarden Vault System

bootstrap-vault.sh - Orchestrates secret restoration
restore-ssh.sh - Restores SSH keys and config from Bitwarden
restore-aws.sh - Restores AWS config and credentials
restore-env.sh - Restores environment secrets
restore-git.sh - Restores Git config
sync-to-bitwarden.sh - Syncs local changes back to Bitwarden
check-vault-items.sh - Pre-flight validation of vault items

Shell Configuration

Unified zshrc for macOS and Linux (no Oh-My-Zsh dependency)
Powerlevel10k theme with plugins via Homebrew
SSH agent auto-start and key auto-loading
Cross-platform clipboard functions (copy/paste)
Claude CLI routing helpers (Bedrock/Max) with SSO pre-flight

Health & Maintenance

check-health.sh with --fix flag for auto-repairs
check-health.sh with --drift flag for local vs Bitwarden comparison
Comprehensive maintenance checklists in README
Architecture diagram

Modern CLI Tools

fzf - Fuzzy finder with Ctrl+R history search, Ctrl+T file picker
eza - Modern ls replacement with icons, git status, tree view
fd - Fast find alternative (integrates with fzf)
ripgrep - Fast grep alternative (rg)

Documentation

Complete README with all workflows documented
Table of Contents
Troubleshooting guide

Security

All secret files restored with correct permissions (600/644)
Atomic session file creation with umask
Bitwarden session caching with validation

Version History

1.0.0 - Initial stable release with full Bitwarden integration

Uh oh!

FilesExpand file tree

CHANGELOG.md

Latest commit

History

CHANGELOG.md

File metadata and controls

Changelog

[Unreleased]

[4.0.0] - 2026-04-15

[4.0.0-rc6] - 2026-04-15

Added

Changed

Fixed

Removed

[4.0.0-rc5] - 2025-12-11

Changed

Added

Fixed

[4.0.0-rc4] - 2025-12-11

Changed

Added

Fixed

[4.0.0-rc3] - 2025-12-10

Changed - Complete Rebrand (dotfiles → blackdot)

Added - Vault Go Implementation (Full Feature Parity)

Added - Migration Support

Added - Windows Native Support

Changed - Documentation Overhaul

Fixed

Removed

Repository

Migration Guide

[4.0.0-rc2] - 2025-12-10

Added

Changed

Fixed

[4.0.0-rc1] - 2025-12-09

Known Issues

Changed

Added

Removed

[3.2.0] - 2025-12-09

Changed

Added

Fixed

[3.1.0] - 2025-12-06

Added

Changed

Fixed

[3.0.0] - 2024-12-05

Added - Framework Core

Fixed

Added - CLI Improvements

Changed

Documentation

Planned

Added - v3.0 Core Features (consolidated from earlier releases)

Changed

Fixed

Added

[2.3.0] - 2025-12-04

Fixed

Added

Documentation

Improved

[2.2.0] - 2025-12-03

Added

Changed

[2.1.0] - 2025-12-03

Added

Fixed

[2.0.1] - 2025-12-02

Added

[2.0.0] - 2025-12-02

Breaking Changes

Added

Changed

Fixed

[1.8.4] - 2025-12-02

Unified `blackdot` Command Expansion