blackwell-systems · blackwell-systems · Nov 29, 2025 · Nov 29, 2025 · Nov 29, 2025 · Nov 29, 2025
@@ -79,7 +79,7 @@ jobs:
             vault/restore-env.sh
             vault/restore-git.sh
             vault/restore-ssh.sh
-            vault/sync-to-bitwarden.sh
+            vault/sync-to-vault.sh
           )
 
           ERRORS=0

@@ -126,7 +126,7 @@ These run automatically on `git commit`.
 ├── vault/                  # Multi-vault integration (Bitwarden, 1Password, pass)
 │   ├── _common.sh          # Single source of truth (IMPORTANT!)
 │   ├── restore-*.sh        # Restore scripts for each category
-│   └── sync-to-bitwarden.sh
+│   └── sync-to-vault.sh
 ├── zsh/                    # Shell configuration
 │   └── zsh.d/              # Modular zsh config (10 files)
 ├── macos/                  # macOS-specific configs
@@ -236,6 +236,51 @@ When modifying zsh config:
 
 ---
 
+## 🔒 Git Safety Rules
+
+**CRITICAL: Follow these rules to prevent merge conflicts and diverging branches.**
+
+### 1. Always sync before working
+- Run `git fetch && git status` at the start of every session
+- If the branch has diverged from remote, STOP and ask the user before proceeding
+- Run `git pull --rebase` before making any commits
+
+### 2. Never force push
+- Do not use `git push --force` or `git push -f`
+- If a push is rejected, ask the user how to proceed
+
+### 3. Check before committing
+- Run `git status` before staging changes
+- Ensure you're on the correct branch
+- Verify no unexpected changes are staged
+
+### 4. One session at a time
+- If you detect uncommitted changes you didn't make, ask the user
+- If remote has commits not in local, pull before continuing
+
+### Session Start Hook
+
+This repository includes a session start hook that automatically checks git sync status:
+
+```json
+{
+  "hooks": [
+    {
+      "event": "on_session_start",
+      "command": "git fetch && git status --porcelain=v2 --branch",
+      "description": "Check git sync status at session start"
+    }
+  ]
+}
+```
+
+The hook output will show:
+- `# branch.ab +N -M` - N commits ahead, M commits behind remote
+- If behind remote, run `git pull --rebase` before making changes
+- If diverged, ask the user before proceeding
+
+---
+
 ## 📋 Commit Message Guidelines
 
 Use conventional commits format:
@@ -343,4 +388,4 @@ Before completing work, verify:
 ---
 
 **Last Updated:** 2025-11-29
-**Version:** 1.7.0
+**Version:** 1.8.0
@@ -210,8 +210,8 @@ View test results in the GitHub Actions tab.
 ```
 feat: Add drift detection to health check
 
-Implements --drift flag that compares local files with vault
-items. Helps identify unsync'd changes before switching machines.
+Implements --drift flag that compares local files with Bitwarden
+vault items. Helps identify unsync'd changes before switching machines.
 
 Closes #42
 ```
@@ -229,7 +229,7 @@ Fixes #38
 docs: Add security maintenance schedule to README
 
 Documents recommended frequency for rotating SSH keys, AWS credentials,
-and vault master password.
+and Bitwarden password.
 ```
 
 ### Pre-commit Hooks
@@ -314,7 +314,7 @@ Once approved:
 Browse [open issues](https://github.com/blackwell-systems/dotfiles/issues) for ideas, or propose your own:
 
 **Desired features:**
-- [x] Support for additional secret managers (1Password, pass) ✅ Implemented in v1.7.0
+- [ ] Support for additional secret managers (age, pass, 1Password)
 - [ ] Web-based metrics dashboard
 - [ ] Automated rollback on failed upgrades
 - [ ] Plugin system for extensibility
@@ -364,14 +364,11 @@ Help test and improve support for:
 ### Testing Vault Scripts
 
 ```bash
-# Set up test vault account (recommended!)
-# Bitwarden:
+# Set up test Bitwarden account (recommended!)
 export BW_SESSION="$(bw unlock --raw)"
-# 1Password: op signin
-# pass: no setup needed
 
 # Test vault operations (use test account!)
-dotfiles vault check
+./vault/check-vault-items.sh -v
 dotfiles vault sync --dry-run SSH-Config
 ```
 

@@ -43,7 +43,7 @@
 | Capability           | This Repo                                      | Typical Dotfiles                 |
 |----------------------|-----------------------------------------------|----------------------------------|
 | **Secrets management** | Multi-vault (Bitwarden, 1Password, pass)      | Manual copy between machines     |
-| **Health validation**  | 573-line checker with `--fix`                 | None                             |
+| **Health validation**  | 446-line checker with `--fix`                 | None                             |
 | **Drift detection**    | Compare local vs vault state                  | None                             |
 | **Schema validation**  | Validates SSH keys & config structure         | None                             |
 | **Unit tests**         | 80+ bats-core tests                           | Rare                             |
@@ -63,7 +63,7 @@
 | **Bidirectional Sync** | ✅ Local ↔ Vault | ❌ | ❌ | ❌ | ❌ |
 | **Cross-Platform** | ✅ macOS, Linux, Windows, WSL2, Docker | ⚠️ Limited | ⚠️ macOS only | ⚠️ macOS only | ⚠️ Limited |
 | **Claude Code Sessions** | ✅ Portable via `/workspace` | ❌ | ❌ | ❌ | ❌ |
-| **Health Checks** | ✅ 573 lines + auto-fix | ❌ | ❌ | ❌ | ❌ |
+| **Health Checks** | ✅ 446 lines + auto-fix | ❌ | ❌ | ❌ | ❌ |
 | **Drift Detection** | ✅ Local vs Vault | ❌ | ❌ | ❌ | ❌ |
 | **Schema Validation** | ✅ SSH keys, configs | ❌ | ❌ | ❌ | ❌ |
 | **Unit Tests** | ✅ 80+ bats tests | ❌ | ❌ | ❌ | ❌ |
@@ -112,7 +112,7 @@
 
 1. **Only dotfiles with multi-vault backend support** - Bitwarden, 1Password, or pass with unified API
 2. **Only dotfiles with Claude Code session portability** - `/workspace` symlink + auto-redirect
-3. **Only dotfiles with comprehensive health checks** - 573-line validator with auto-fix
+3. **Only dotfiles with comprehensive health checks** - 446-line validator with auto-fix
 4. **Only dotfiles with drift detection** - Compare local vs vault state
 5. **Only dotfiles with schema validation** - Ensures SSH keys/configs are valid before restore
 6. **Only dotfiles with Docker bootstrap testing** - Reproducible CI/CD environments
@@ -138,13 +138,15 @@ SKIP_WORKSPACE_SYMLINK=true SKIP_CLAUDE_SETUP=true ./bootstrap/bootstrap-linux.s
 # Then manually configure ~/.ssh, ~/.aws, ~/.gitconfig
 ```
 
-> 💡 **Don't use a vault?** No problem!
+> 💡 **Don't use a vault manager?** No problem!
 >
 > The vault system is completely optional. Run with `--minimal` flag:
 > ```bash
 > curl -fsSL https://raw.githubusercontent.com/blackwell-systems/dotfiles/main/install.sh | bash -s -- --minimal
 > ```
 > Then manually configure `~/.ssh`, `~/.aws`, `~/.gitconfig`. All shell config, aliases, and tools still work!
+>
+> Or choose your preferred vault backend: Bitwarden (default), 1Password, or pass.
 
 Inspired by: holman/dotfiles, thoughtbot/dotfiles, mathiasbynens/dotfiles
 
@@ -172,7 +174,7 @@ Inspired by: holman/dotfiles, thoughtbot/dotfiles, mathiasbynens/dotfiles
 
 To clone via SSH (recommended), you’ll also want an SSH key configured with GitHub. If you don’t have Git yet, you can either:
 - install it the way you normally would on your platform, or  
-- download this repository as a ZIP from GitHub, extract it, and run `bootstrap-mac.sh` / `bootstrap-linux.sh` – the scripts will install Git and your chosen vault CLI for you.
+- download this repository as a ZIP from GitHub, extract it, and run `bootstrap-mac.sh` / `bootstrap-linux.sh` / `bootstrap-windows.sh` – the scripts will install Git and configure your environment.
 
 ---
 
@@ -206,9 +208,8 @@ cd ~/workspace/dotfiles
 ./bootstrap/bootstrap-linux.sh    # Linux / WSL2 / Lima / Docker
 
 # 3. Restore secrets from vault
-# Bitwarden: bw login && export BW_SESSION="$(bw unlock --raw)"
-# 1Password: op signin
-# pass: (uses GPG, no login needed)
+bw login                    # or: op signin (1Password) / gpg for pass
+export BW_SESSION="$(bw unlock --raw)"  # Bitwarden only
 ./vault/bootstrap-vault.sh
 
 # 4. Verify
@@ -218,9 +219,9 @@ dotfiles doctor
 **That's it.** Shell configured, secrets restored, health validated.
 
 <details>
-<summary><b>Don't use a vault?</b></summary>
+<summary><b>Don't use a vault manager?</b></summary>
 
-The vault system is completely optional. Two options:
+The vault system supports Bitwarden, 1Password, and pass. Or skip it entirely:
 
 **Option 1: Use `--minimal` flag**
 ```bash
@@ -583,7 +584,7 @@ dotfiles/
 │   │   └── pass.sh           # pass (GPG) backend
 │   ├── bootstrap-vault.sh    # Orchestrator
 │   ├── restore-*.sh          # Restore SSH, AWS, Git, env
-│   ├── sync-to-bitwarden.sh  # Sync local → vault
+│   ├── sync-to-vault.sh      # Sync local → vault
 │   ├── validate-schema.sh    # Validate vault item structure
 │   └── check-vault-items.sh  # Pre-flight validation
 │
@@ -738,6 +739,7 @@ To customize:
 | macOS (Intel) | ✅ Fully tested | Auto-detects architecture |
 | Lima (Ubuntu 24.04) | ✅ Fully tested | Recommended Linux VM for macOS |
 | WSL2 (Windows) | ✅ Auto-detected | Uses Linux bootstrap |
+| Windows (Git Bash/MSYS2) | ✅ Native support | Uses Windows bootstrap |
 | Ubuntu/Debian | ✅ Compatible | Tested on Ubuntu 24.04 |
 | Arch/Fedora/BSD | ⚠️ Experimental | 15-30 min adaptation needed |
 
@@ -750,7 +752,7 @@ To customize:
 - **[Template Guide](docs/templates.md)** - Machine-specific configuration templates
 - **[Architecture](docs/architecture.md)** - System diagrams and component overview
 - **[Troubleshooting](docs/troubleshooting.md)** - Common issues and solutions
-- **[Vault README](vault/README.md)** - Multi-vault system details
+- **[Vault README](vault/README.md)** - Multi-vault backend details
 - **[CONTRIBUTING.md](CONTRIBUTING.md)** - Contributor guide
 - **[SECURITY.md](SECURITY.md)** - Security policy
 - **[CHANGELOG.md](CHANGELOG.md)** - Version history
@@ -782,7 +784,7 @@ ssh -T git@github.com    # Test connection
 # Bitwarden
 export BW_SESSION="$(bw unlock --raw)"
 
-# 1Password
+# 1Password - re-sign in
 op signin
 ```
 

@@ -0,0 +1,140 @@
+#!/usr/bin/env bash
+# ============================================================
+# FILE: bootstrap-windows.sh
+# Windows bootstrap (Git Bash / MSYS2 / Cygwin)
+# Usage:
+#   ./bootstrap-windows.sh              # Standard bootstrap
+#   ./bootstrap-windows.sh --interactive  # Prompt for options
+#   ./bootstrap-windows.sh --help       # Show help
+# ============================================================
+set -euo pipefail
+
+# DOTFILES_DIR is parent of bootstrap/
+DOTFILES_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+# ============================================================
+# Detect Windows environment
+# ============================================================
+IS_GITBASH=false
+IS_MSYS2=false
+IS_CYGWIN=false
+export PLATFORM_NAME="Windows"
+
+case "$(uname -s)" in
+    MINGW*)
+        IS_GITBASH=true
+        export PLATFORM_NAME="Git Bash"
+        ;;
+    MSYS*)
+        IS_MSYS2=true
+        export PLATFORM_NAME="MSYS2"
+        ;;
+    CYGWIN*)
+        IS_CYGWIN=true
+        export PLATFORM_NAME="Cygwin"
+        ;;
+esac
+
+# Source shared bootstrap functions
+# shellcheck source=bootstrap/_common.sh
+source "$DOTFILES_DIR/bootstrap/_common.sh"
+
+# Parse arguments (sets INTERACTIVE flag)
+parse_bootstrap_args "$@"
+
+# Run interactive configuration if --interactive
+run_interactive_config
+
+echo "=== Windows bootstrap starting ($PLATFORM_NAME) ==="
+
+# ============================================================
+# 1. Check prerequisites
+# ============================================================
+echo "Checking prerequisites..."
+
+if ! command -v git >/dev/null 2>&1; then
+    fail "Git is required. Please install Git for Windows first."
+    exit 1
+fi
+
+if ! command -v zsh >/dev/null 2>&1; then
+    warn "Zsh not found. Some features may not work."
+    if $IS_MSYS2; then
+        echo "Install zsh with: pacman -S zsh"
+    elif $IS_GITBASH; then
+        echo "For full zsh support, consider using MSYS2 or WSL2 instead."
+    fi
+fi
+
+# ============================================================
+# 2. MSYS2-specific package installation
+# ============================================================
+if $IS_MSYS2 && command -v pacman >/dev/null 2>&1; then
+    echo "Installing packages via pacman..."
+    pacman -Syu --noconfirm --needed \
+        git zsh curl wget \
+        2>/dev/null || warn "Some packages may not have installed"
+fi
+
+# ============================================================
+# 3. Workspace layout (shared)
+# ============================================================
+setup_workspace_layout
+
+# ============================================================
+# 4. Skip /workspace symlink on Windows (requires admin)
+# ============================================================
+if [[ "${SKIP_WORKSPACE_SYMLINK:-}" != "true" ]]; then
+    echo "Note: /workspace symlink requires administrator privileges on Windows."
+    echo "Skipping automatic creation. To create manually (as admin):"
+    echo "  mklink /D C:\\workspace %USERPROFILE%\\workspace"
+    echo ""
+    echo "Or set SKIP_WORKSPACE_SYMLINK=true to suppress this message."
+fi
+
+# ============================================================
+# 5. Dotfiles symlinks (shared)
+# ============================================================
+link_dotfiles
+
+# ============================================================
+# 6. Shell configuration
+# ============================================================
+if command -v zsh >/dev/null 2>&1; then
+    if [[ "$SHELL" != "$(command -v zsh)" ]]; then
+        echo "Note: To use zsh as default shell on Windows:"
+        if $IS_MSYS2; then
+            echo "  Add to ~/.bashrc: exec zsh"
+        elif $IS_GITBASH; then
+            echo "  Add to ~/.bashrc: exec zsh (if zsh is installed)"
+        fi
+    fi
+fi
+
+# ============================================================
+# Done - Platform-specific tips
+# ============================================================
+echo "=== Windows bootstrap complete ($PLATFORM_NAME) ==="
+echo ""
+echo "Next steps:"
+echo "  - Open a new shell to use the dotfiles configuration"
+echo "  - Some features (Homebrew, Lima) are not available on Windows"
+echo ""
+
+if $IS_GITBASH; then
+    echo "Git Bash notes:"
+    echo "  - Consider using WSL2 for full Linux compatibility"
+    echo "  - Homebrew is not available; use chocolatey or scoop for packages"
+    echo ""
+elif $IS_MSYS2; then
+    echo "MSYS2 notes:"
+    echo "  - Use 'pacman -S <package>' to install packages"
+    echo "  - Some tools may need to be installed separately"
+    echo ""
+fi
+
+echo "To restore secrets from vault:"
+echo "  # Bitwarden: bw login && export BW_SESSION=\"\$(bw unlock --raw)\""
+echo "  # 1Password: op signin"
+echo "  # pass: (uses GPG, ensure gpg is configured)"
+echo "  dotfiles vault restore"
@@ -1,4 +1,11 @@
 {
+  "hooks": [
+    {
+      "event": "on_session_start",
+      "command": "git fetch && git status --porcelain=v2 --branch",
+      "description": "Check git sync status at session start"
+    }
+  ],
   "permissions": {
     "allow_bash": true,
     "allow_read": true,