cpplain · cpplain · Feb 21, 2026 · Feb 21, 2026 · Feb 21, 2026 · Feb 21, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,175 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+`lnk` is an opinionated symlink manager for dotfiles written in Go. It recursively traverses source directories and creates individual symlinks for each file (not directories), allowing mixed file sources in the same target directory.
+
+## Development Commands
+
+```bash
+# Build
+make build                  # Build binary to bin/lnk with version from git tags
+
+# Testing
+make test                   # Run all tests (unit + e2e)
+make test-unit              # Run unit tests only (lnk/)
+make test-e2e               # Run e2e tests only (test/)
+make test-coverage          # Generate coverage report (coverage.html)
+
+# Code Quality
+make fmt                    # Format code (prefers goimports, falls back to gofmt)
+make lint                   # Run go vet
+make check                  # Run fmt, test, and lint in sequence
+```
+
+## Architecture
+
+### Core Components
+
+- **main.go**: CLI entry point with POSIX-style flag parsing. Action flags (-C/--create, -R/--remove, -S/--status, -P/--prune, -A/--adopt, -O/--orphan) determine the operation. For C/R/S operations, the positional argument specifies the source directory. For A/O operations, positional arguments specify files to manage.
+
+- **lnk/config.go**: Configuration system with `.lnkconfig` file support. Config files can specify target directory and ignore patterns using stow-style format (one flag per line). CLI flags override config file values. Config file search locations:
+  1. `.lnkconfig` in source directory
+  2. `.lnkconfig` in home directory (~/.lnkconfig)
+  3. Built-in defaults if no config found
+
+- **lnk/create.go, lnk/remove.go**: Symlink operations with 3-phase execution:
+  1. Collect planned links (recursive file traversal)
+  2. Validate all targets
+  3. Execute or show dry-run
+
+- **lnk/adopt.go**: Moves files from target to source directory and creates symlinks
+
+- **lnk/orphan.go**: Removes symlinks and restores actual files to target locations
+
+### Key Design Patterns
+
+**Recursive File Linking**: lnk creates symlinks for individual files, NOT directories. This allows:
+
+- Multiple source directories can map to the same target
+- Local-only files can coexist with managed configs
+- Parent directories are created as regular directories, never symlinks
+
+**Error Handling**: Uses custom error types in `errors.go`:
+
+- `PathError`: for file operation errors
+- `ValidationError`: for validation failures
+- `WithHint()`: adds actionable hints to errors
+
+**Output System**: Centralized in `output.go` with support for:
+
+- Text format (default, colorized)
+- Verbosity levels: quiet, normal, verbose
+
+**Terminal Detection**: `terminal.go` detects TTY for conditional formatting (colors, progress bars)
+
+### Configuration Structure
+
+```go
+// Config loaded from .lnkconfig file
+type FileConfig struct {
+    Target         string   // Target directory (default: ~)
+    IgnorePatterns []string // Ignore patterns from config file
+}
+
+// Final resolved configuration
+type Config struct {
+    SourceDir      string   // Source directory (from CLI)
+    TargetDir      string   // Target directory (CLI > config > default)
+    IgnorePatterns []string // Combined ignore patterns from all sources
+}
+
+// Options for linking operations
+type LinkOptions struct {
+    SourceDir      string   // source directory - what to link from (e.g., ~/git/dotfiles)
+    TargetDir      string   // where to create links (default: ~)
+    IgnorePatterns []string // combined ignore patterns from all sources
+    DryRun         bool     // preview mode without making changes
+}
+
+// Options for adopt operations
+type AdoptOptions struct {
+    SourceDir string   // base directory for dotfiles (e.g., ~/git/dotfiles)
+    TargetDir string   // where files currently are (default: ~)
+    Paths     []string // files to adopt (e.g., ["~/.bashrc", "~/.vimrc"])
+    DryRun    bool     // preview mode
+}
+
+// Options for orphan operations
+type OrphanOptions struct {
+    SourceDir string   // base directory for dotfiles (e.g., ~/git/dotfiles)
+    TargetDir string   // where symlinks are (default: ~)
+    Paths     []string // symlink paths to orphan (e.g., ["~/.bashrc", "~/.vimrc"])
+    DryRun    bool     // preview mode
+}
+```
+
+### Testing Structure
+
+- **Unit tests**: `lnk/*_test.go` - use `testutil_test.go` helpers for temp dirs
+- **E2E tests**: `test/e2e_test.go` - full workflow testing
+- Test data: Use `test/helpers_test.go` for creating test repositories
+
+## Development Guidelines
+
+### Commit Messages
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+- `feat:` - new feature
+- `fix:` - bug fix
+- `docs:` - documentation only
+- `refactor:` - code restructuring
+- `test:` - adding/updating tests
+- `chore:` - build/tooling changes
+
+Breaking changes use `!` suffix: `feat!:` or `BREAKING CHANGE:` in footer.
+
+### CLI Design Principles
+
+From [cpplain/cli-design](https://github.com/cpplain/cli-design):
+
+- **Obvious Over Clever**: Make intuitive paths easiest
+- **Helpful Over Minimal**: Provide clear guidance and error messages
+- **Consistent Over Special**: Follow CLI conventions
+- All destructive operations support `--dry-run`
+
+### Code Standards
+
+- Use `PrintVerbose()` for debug output (hidden unless --verbose)
+- Use `PrintErrorWithHint()` for user-facing errors with actionable hints
+- Expand paths with `ExpandPath()` to handle `~/` notation
+- Validate paths early using `validation.go` functions
+
+## Common Tasks
+
+### Adding a New Operation
+
+1. Add new action flag to `main.go` (e.g., `-X/--new-operation`)
+2. Create options struct in `lnk/` following the pattern (e.g., `NewOperationOptions`)
+3. Implement operation function in `lnk/` (e.g., `func NewOperation(opts NewOperationOptions) error`)
+4. Add case in `main.go` to handle the new flag and construct options
+5. Add tests in `lnk/xxx_test.go`
+6. Add e2e test if appropriate
+
+### Modifying Configuration
+
+- Config types in `config.go` are simple structs for holding configuration
+- Add validation with helpful hints using `NewValidationErrorWithHint()`
+- Config files use stow-style format: one flag per line (e.g., `--target=~`)
+
+### Running Single Test
+
+```bash
+go test -v ./lnk -run TestFunctionName
+go test -v ./test -run TestE2EName
+```
+
+## Technical Notes
+
+- Version info injected via ldflags during build (version, commit, date)
+- No external dependencies - stdlib only
+- Git operations are optional (detected at runtime)
+- Uses stdlib `flag` package for command-line parsing
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -38,7 +38,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Comprehensive end-to-end testing suite
-- Zero-configuration defaults with flexible config discovery (`~/.config/lnk/config.json`, `~/.lnk.json`)
+- Zero-configuration defaults with flexible config discovery (`.lnkconfig` in source dir, `~/.config/lnk/config`, `~/.lnkconfig`)
 - Global flags: `--verbose`, `--quiet`, `--yes`, `--no-color`, `--output`
 - Command suggestions for typos, progress indicators, confirmation prompts
 - JSON output and specific exit codes for scripting

diff --git a/CLAUDE.md b/CLAUDE.md
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -44,17 +44,17 @@ type[(optional scope)]: description
 #### Examples
 
 ```
-feat: add support for multiple link mappings
+feat: add support for multiple packages
 
 fix: prevent race condition during link creation
 
 docs: add examples to README
 
 feat(adopt): allow adopting entire directories
 
-fix!: change config file format to JSON
+fix!: change default target directory
 
-BREAKING CHANGE: config files must now use .lnk.json extension
+BREAKING CHANGE: target directory now defaults to home instead of current directory
 ```
 
 ### CLI Design Guidelines

diff --git a/Makefile b/Makefile
@@ -25,7 +25,7 @@ build:
 	@# Generate dev+timestamp for local builds (releases override via ldflags)
 	@VERSION=$$(date -u '+dev+%Y%m%d%H%M%S'); \
 	echo "Building lnk $$VERSION..."; \
-	go build -ldflags "-X 'main.version=$$VERSION'" -o bin/lnk cmd/lnk/main.go
+	go build -ldflags "-X 'main.version=$$VERSION'" -o bin/lnk .
 
 # Clean build artifacts
 clean:
@@ -34,7 +34,7 @@ clean:
 
 # Clean test artifacts
 clean-test:
-	rm -rf e2e/testdata/
+	rm -rf test/testdata/
 	@echo "Test data cleaned. Run 'scripts/setup-testdata.sh' to recreate."
 
 # Run tests
@@ -43,11 +43,11 @@ test:
 
 # Run unit tests only
 test-unit:
-	go test -v ./internal/...
+	go test -v ./lnk/...
 
 # Run E2E tests only
 test-e2e:
-	go test -v ./e2e/...
+	go test -v ./test/...
 
 # Run tests with coverage
 test-coverage: