Merge feat/fixes-and-niceties-2: Phase 2 UX improvements

- Fix duplicate drifted dotfiles in status
- Improve dotfile column headers ($HOME/$PLONKDIR)
- Fix diff output column ordering
- Add 'plonk add -y' to sync drifted files
- Add selective file deployment 'plonk apply <file1> <file2>'
- Comprehensive BATS test coverage (11 new tests)
- Updated all command documentation

All tests pass.

Author: richhaase

README.md

@@ -118,7 +118,7 @@ The `clone` command:
 ```bash
 # Package management
 plonk install ripgrep fd              # Install and track packages
-plonk install pnpm cargo              # Bootstrap package managers automatically
+plonk install pnpm cargo              # Install package managers (must be available via another manager)
 plonk uninstall ripgrep               # Uninstall and stop tracking
 plonk upgrade                         # Upgrade all packages to latest versions
 plonk upgrade brew:ripgrep            # Upgrade specific package
@@ -127,13 +127,15 @@ plonk info ripgrep                    # Show package details
 
 # Dotfile management
 plonk add ~/.vimrc ~/.zshrc           # Start tracking dotfiles
+plonk add -y                          # Sync all drifted files from $HOME to $PLONKDIR
 plonk rm ~/.vimrc                     # Stop tracking (doesn't delete file)
 plonk dotfiles                        # List dotfiles with state info
 
 # System state
 plonk status                          # Show all managed items (including drift)
 plonk apply                           # Sync system to desired state
-plonk diff                            # Show differences between desired and actual state
+plonk apply ~/.vimrc ~/.zshrc         # Apply only specific dotfiles
+plonk diff                            # Show differences for drifted dotfiles
 plonk doctor                          # Check system health
 
 # Configuration

docs/cli.md

@@ -81,12 +81,14 @@ plonk upgrade htop neovim             # Upgrade multiple packages
 
 ### plonk add
 
-Add dotfiles to management.
+Add dotfiles to management or sync drifted files back.
 
 ```bash
 plonk add ~/.vimrc ~/.zshrc           # Add files
 plonk add ~/.config/nvim/             # Add directory
-plonk add --dry-run ~/.vimrc          # Preview
+plonk add -y                          # Sync all drifted files from $HOME to $PLONKDIR
+plonk add -y --dry-run                # Preview drift sync
+plonk add --dry-run ~/.vimrc          # Preview add
 ```
 
 ### plonk rm
@@ -133,9 +135,10 @@ Install missing packages and deploy missing dotfiles.
 
 ```bash
 plonk apply                           # Apply all changes
+plonk apply ~/.vimrc ~/.zshrc         # Apply only specific dotfiles
 plonk apply --dry-run                 # Preview changes
-plonk apply --packages               # Apply packages only
-plonk apply --dotfiles               # Apply dotfiles only
+plonk apply --packages                # Apply packages only
+plonk apply --dotfiles                # Apply dotfiles only
 ```
 
 ### plonk search

docs/cmds/apply.md

@@ -5,13 +5,15 @@ Reconciles system state by installing missing packages and deploying missing dot
 ## Synopsis
 
 ```bash
-plonk apply [options]
+plonk apply [options] [files...]
 ```
 
 ## Description
 
 The apply command reconciles the system state with the desired configuration by installing packages listed in `plonk.lock` and deploying dotfiles from `$PLONK_DIR`. It acts like a sync operation, bringing the local environment in line with the managed configuration.
 
+When file arguments are provided, apply validates that the specified files are managed by plonk before proceeding.
+
 Apply targets "missing" resources (tracked but not present) and "drifted" dotfiles (modified since deployment), transitioning them to "managed" state. The command uses plonk's internal reconciliation system to identify what needs to be applied.
 
 ## Options
@@ -68,6 +70,9 @@ Files matching `ignore_patterns` are excluded from deployment.
 # Apply all changes (packages and dotfiles)
 plonk apply
 
+# Apply only specific dotfiles
+plonk apply ~/.vimrc ~/.zshrc
+
 # Preview what would be changed
 plonk apply --dry-run
 
@@ -87,3 +92,5 @@ plonk apply --dotfiles
 ## Notes
 
 - The `--packages` and `--dotfiles` flags cannot be used together
+- File arguments cannot be combined with `--packages` or `--dotfiles` flags
+- All specified files must be managed by plonk or command will fail

docs/cmds/diff.md

@@ -39,7 +39,8 @@ The diff command accepts various path formats for the file argument:
 ### Default Behavior
 
 - Uses `git diff --no-index` by default (zero-config)
-- Shows differences with source file first, deployed file second
+- Shows differences with deployed file ($HOME) first, source file ($PLONKDIR) second
+- Follows standard diff conventions (current state vs. source of truth)
 - Processes all drifted files when no argument provided
 - Continues with remaining files if individual diff fails
 - GUI diff tools open in their own windows
@@ -58,7 +59,7 @@ Common configurations:
 - `diff_tool: "code --diff --wait"` - VS Code diff
 - `diff_tool: "meld"` - GUI diff tool
 
-The diff tool is executed as: `{tool} {source_path} {deployed_path}`
+The diff tool is executed as: `{tool} {deployed_path} {source_path}`
 
 ### Error Handling
 
@@ -86,8 +87,8 @@ plonk diff .vimrc
 ## Integration
 
 - Use `plonk status` to see which files have drifted
-- Use `plonk apply` to restore drifted files from source
-- Use `plonk add` to update source with current deployed version
+- Use `plonk apply` to restore drifted files from $PLONKDIR
+- Use `plonk add -y` to sync all drifted files from $HOME back to $PLONKDIR
 
 ## Notes
 

docs/cmds/dotfile-management.md

@@ -25,12 +25,13 @@ Copies dotfiles from their current location to `$PLONK_DIR` for management.
 ### Synopsis
 
 ```bash
-plonk add [options] <file>...
+plonk add [options] [files...]
 ```
 
 ### Options
 
 - `--dry-run, -n` - Preview changes without adding files
+- `--sync-drifted, -y` - Sync all drifted files from $HOME back to $PLONKDIR
 
 ### Behavior
 
@@ -62,6 +63,12 @@ plonk add ~/.zshrc ~/.gitconfig ~/.tmux.conf
 # Add entire directory
 plonk add ~/.config/nvim/
 
+# Sync all drifted files back to $PLONKDIR
+plonk add -y
+
+# Preview drift sync without making changes
+plonk add -y --dry-run
+
 # Preview changes
 plonk add --dry-run ~/.vimrc
 ```

docs/cmds/status.md

@@ -55,8 +55,8 @@ Using both `--packages` and `--dotfiles` together has the same effect as using n
 - STATUS: Current state with icon
 
 **Dotfiles Table** (managed/missing):
-- SOURCE: Path relative to `$PLONK_DIR`
-- TARGET: Full path in `$HOME`
+- $HOME: Full path in home directory (deployed location)
+- $PLONKDIR: Path relative to plonk configuration directory
 - STATUS: Current state with icon
 
 **Dotfiles List** (unmanaged):
@@ -108,7 +108,7 @@ plonk status -o json
 
 - Use before `plonk apply` to see what will be changed
 - Missing items can be resolved with `plonk apply`
-- Drifted dotfiles can be restored with `plonk apply` or updated with `plonk add`
+- Drifted dotfiles can be restored with `plonk apply` or synced back with `plonk add -y`
 - Unmanaged items can be added with `plonk install` or `plonk add`
 
 ## Notes

docs/plans/fixes-and-niceties.md

@@ -192,76 +192,88 @@ func KeyForPackage(managerName, packageName string) string {
 
 ## UX/Display Improvements
 
-### 8. Fix duplicate listing of drifted dotfiles
+### 8. ✅ Fix duplicate listing of drifted dotfiles (COMPLETED)
 **Priority**: Medium (UX bug)
 **Command**: `plonk status`
+**Status**: ✅ Completed (commit 55e9249)
 
 **Problem**: When a dotfile is in drifted status, it appears twice in the output.
 
-**Fix**: Ensure drifted files only appear once in the status output with their drift state clearly indicated.
+**Fix Applied**:
+- Removed misleading comment about handling drifted items separately
+- Drifted files (State==StateDegraded) already in Managed list now display once with "drifted" status
+- File: `internal/output/status_formatter.go`
 
-### 9. Improve dotfile column headers in status
+### 9. ✅ Improve dotfile column headers in status (COMPLETED)
 **Priority**: Medium (UX improvement)
 **Command**: `plonk status`
+**Status**: ✅ Completed (commit 55e9249)
 
 **Problem**: Column headers "source" and "target" are confusing for dotfiles.
 
-**Fix**:
-- Use actual expanded paths like `/Users/username` and `/Users/username/.config/plonk` instead of generic "source/target"
-- Reorder columns to: `$HOME`, `$PLONKDIR`, `STATUS`
-- Makes it immediately clear which file is where
+**Fix Applied**:
+- Changed headers from "SOURCE", "TARGET", "STATUS" to "$HOME", "$PLONKDIR", "STATUS"
+- Reordered columns: $HOME (deployed location), $PLONKDIR (source), STATUS
+- Updated all AddRow calls to match new column order
+- File: `internal/output/status_formatter.go`
 
-### 10. Fix diff output column ordering
+### 10. ✅ Fix diff output column ordering (COMPLETED)
 **Priority**: Medium (UX improvement)
 **Command**: `plonk diff`
+**Status**: ✅ Completed (commit 55e9249)
 
 **Problem**: Current ordering is inconsistent with user mental model.
 
-**Fix**: Display `$HOME` (deployed location) on the left and `$PLONKDIR` (source) on the right, matching standard diff conventions where "original" is on left and "modified" is on right.
+**Fix Applied**:
+- Swapped diff arguments from `source, dest` to `dest, source`
+- Now shows $HOME (deployed) on left and $PLONKDIR (source) on right
+- Matches standard diff conventions (current state vs. source)
+- File: `internal/commands/diff.go`
 
 ## Feature Additions
 
-### 11. Add `plonk add -y` to sync drifted files back to $PLONKDIR
+### 11. ✅ Add `plonk add -y` to sync drifted files back to $PLONKDIR (COMPLETED)
 **Priority**: Medium (Feature enhancement)
 **Command**: `plonk add`
+**Status**: ✅ Completed (commit 55e9249)
 
 **Feature**: Add a `-y` or `--sync-drifted` flag to automatically copy all drifted files from $HOME back to $PLONKDIR (reverse of `apply`).
 
-**Use case**: When you've edited dotfiles in $HOME and want to quickly capture all changes back to your managed config directory.
-
-**Behavior**:
+**Implementation**:
 ```bash
-plonk add -y
-# Finds all files with "drifted" status
-# Copies them from $HOME to $PLONKDIR
-# Updates timestamps/hashes
+plonk add -y                 # Sync all drifted files
+plonk add -y --dry-run       # Preview what would be synced
 ```
 
-**Implementation considerations**:
-- Should show which files will be synced before copying (or require `-y` for non-interactive)
-- Consider `--dry-run` option to preview changes
-- Respect `.plonkignore` or similar patterns if implemented
-
-### 12. Add selective file deployment to `plonk apply`
+**Changes Applied**:
+- Added `--sync-drifted` flag (short: `-y`) to add command
+- Finds all files with State==StateDegraded (drifted)
+- Copies them from $HOME back to $PLONKDIR
+- Shows summary of synced files
+- Works with `--dry-run` for preview
+- Shows appropriate message when no files are drifted
+- File: `internal/commands/add.go`
+
+### 12. ✅ Add selective file deployment to `plonk apply` (COMPLETED)
 **Priority**: Medium (Feature enhancement)
 **Command**: `plonk apply`
+**Status**: ✅ Completed (commit 55e9249)
 
 **Feature**: Allow `plonk apply <file1> <file2> ...` to selectively deploy only specified files from $PLONKDIR to $HOME.
 
-**Use case**: When you've updated specific dotfiles and only want to deploy those without touching others.
-
-**Behavior**:
+**Implementation**:
 ```bash
-plonk apply ~/.vimrc ~/.zshrc
-# Only deploys vimrc and zshrc from $PLONKDIR to $HOME
-# Leaves other managed dotfiles untouched
+plonk apply ~/.vimrc ~/.zshrc    # Apply only specified files
+plonk apply                       # Apply all (original behavior)
 ```
 
-**Implementation considerations**:
-- Accept both $HOME paths (`.vimrc`) and $PLONKDIR paths
-- Validate files are actually managed by plonk
-- Provide clear error if file not found or not managed
-- Still show before/after status for specified files
+**Changes Applied**:
+- Modified command to accept optional file arguments: `apply [files...]`
+- Validates that specified files are managed by plonk before proceeding
+- Shows clear error if file not found or not managed
+- Prevents combining file arguments with `--packages` or `--dotfiles` flags
+- Updated help text with examples
+- File: `internal/commands/apply.go`
 
 ## Nice-to-Haves
 
@@ -295,11 +307,19 @@ func NewIsolatedRegistry() *ManagerRegistry {
 }
 ```
 
-### 16. Add comprehensive tests
-**Recommended test additions**:
-1. Self-install path tests per manager (verify correct installer commands via mock executor)
-2. Concurrency smoke test for parallel manager reconciliation
-3. Symlink traversal tests for dotfile operations
+### 16. ✅ Add comprehensive tests (PARTIALLY COMPLETED)
+**Status**: ✅ Added drift and sync tests (commit 5800789, f2646a0)
+
+**Completed**:
+- ✅ Created `tests/bats/behavioral/10-drift-and-sync.bats` with 11 new tests
+- ✅ Tests for duplicate drifted dotfiles, column headers, diff ordering
+- ✅ Tests for `plonk add -y` sync functionality
+- ✅ Tests for selective `plonk apply <files>`
+- ✅ Integration test for complete drift workflow
+
+**Remaining**:
+1. Concurrency smoke test for parallel manager reconciliation
+2. Symlink traversal tests for dotfile operations
 
 ### 17. Documentation updates
 **Files**: README.md
@@ -332,12 +352,15 @@ func NewIsolatedRegistry() *ManagerRegistry {
 **Completed**: 2025-01-06 in commits 619924f, 10e9002
 **Results**: 3 critical fixes, 26 files changed, 1 file deleted, -293 LOC, all tests passing
 
-### Phase 2: UX Improvements
-4. Fix duplicate drifted dotfiles in status (#8)
-5. Improve dotfile column headers in status (#9)
-6. Fix diff output column ordering (#10)
-7. Add `plonk add -y` to sync drifted files (#11)
-8. Add selective file deployment to `plonk apply` (#12)
+### Phase 2: UX Improvements ✅ COMPLETED
+4. ✅ Fix duplicate drifted dotfiles in status (#8)
+5. ✅ Improve dotfile column headers in status (#9)
+6. ✅ Fix diff output column ordering (#10)
+7. ✅ Add `plonk add -y` to sync drifted files (#11)
+8. ✅ Add selective file deployment to `plonk apply` (#12)
+
+**Completed**: 2025-01-06 in commit 55e9249
+**Results**: 5 UX improvements, 4 files changed, +190 LOC, all tests passing
 
 ### Phase 3: Architecture & Performance
 9. Standardize V2 registration (#5)