dotfiles/CLAUDE.md

# Chezmoi Dotfiles Repository - AI Assistant Guidelines

## Repository Context

This is a **chezmoi source directory** for managing dotfiles across multiple machines. Files here are SOURCE files that get templated and deployed to the home directory.

### AI Assistant Configuration

This repository manages configuration for both **Claude Code** (Anthropic's official CLI) and **OpenCode** (an enhanced fork). The configuration is symlinked and shared between both tools:

- **Global guidelines** live in `~/.config/opencode/AGENTS.md` - this file contains cross-platform development guidelines (shell usage, build management, code style, git practices)
- **Project-specific context** lives in this repository's `CLAUDE.md` - chezmoi-specific instructions and restrictions
- **Symlinking structure**: The `home/dot_claude/` directory creates symlinks that allow both tools to share the same configuration files (settings.json points to `claude-settings.json` at the repository root)
- **Custom commands**: Both tools share command definitions stored in `home/dot_claude/commands/` (e.g., `commit-staged.md`, `amend-commit.md`, `reword-commit.md`)
  - **IMPORTANT**: When adding new command definitions to `home/dot_claude/commands/`, you MUST create corresponding symlinks in `home/dot_config/opencode/command/`
  - Symlink pattern: `symlink_<command-name>.md` → `../../../dot_claude/commands/<command-name>.md`
  - Example: `symlink_amend-commit.md` contains `../../../dot_claude/commands/amend-commit.md`
  - This ensures both Claude Code and OpenCode can access the same command definitions

When working in this repository, you're reading both the global AGENTS.md (general development practices) and this CLAUDE.md (chezmoi-specific guidelines). Project-specific CLAUDE.md files in other repositories take precedence over global guidelines.

### Key Concepts

**Source vs Target Pattern:**
- **Source**: `~/.local/share/chezmoi/home/dot_bashrc.tmpl` (what you edit)
- **Target**: `~/.bashrc` (what gets deployed after `chezmoi apply`)
- Edit source files only. DO NOT modify target files directly.

**File Naming Conventions:**
- `dot_` `.` (e.g., `dot_bashrc` becomes `~/.bashrc`)
- `.tmpl` suffix Go template file (rendered with platform detection)
- `private_` prefix 600 permissions
- `encrypted_*.age` age-encrypted files (safe to commit)
- `run_onchange_*` executable scripts that run during apply

**Template System:**
- Uses Go templates with platform detection
- Two types of templates with different variable access patterns:
  - **Regular templates** (e.g., `home/dot_bashrc.tmpl`): Direct access to Chezmoi context
    - Built-in: `.chezmoi.os`, `.chezmoi.homeDir`
    - Custom data: `.wsl`, `.chassis`
  - **Partials** (reusable templates in `home/.chezmoitemplates/`): Must receive context via explicit parameter
    - Partials don't have automatic access to Chezmoi's context
    - Context passed as parameter (commonly `data`) when calling the partial
    - Access everything through parameter: `.data.chezmoi.os`, `.data.wsl`, `.data.chassis`
- Conditional rendering for Windows/Linux/macOS/WSL

**Secret Management:**
- Age encryption for sensitive files (recipient: `age1s3ctpj9lafl6qwyvd89sn448us7gdzd53d8yyhsc7zny78c0k4sqerrkze`)
- Doppler integration for API keys/tokens
- Encryption key bootstrapped via hooks from Doppler

**Hooks:**
- `.init_pre.ts` and `.update_pre.ts` (TypeScript via Bun)
- Bootstrap encryption key from Doppler before apply
- Handle `chezmoi init` and `chezmoi update --init`

**GPG Configuration (WSL-only):**
- `~/.gnupg` → Symlink to Windows GPG directory (`C:\Users\Xevion\AppData\Roaming\gnupg`)
- `/usr/local/bin/gpg` → Symlink to Windows `gpg.exe` (via `run_onchange_before_setup-wsl-gpg.sh.tmpl`)
- Enables native Windows Qt5 pinentry GUI for passphrase prompts
- Automatic setup on WSL; ignored on regular Linux

## Critical Restrictions

### NEVER Do These Actions

1. **DO NOT apply changes to filesystem**
   - NO `chezmoi apply`
   - NO direct file writes to `~/.bashrc`, `~/.gitconfig`, etc.
   - Changes stay in source directory only

2. **DO NOT commit or push automatically**
   - NO `git commit` without explicit user request
   - NO `git push` on your own
   - Let user review changes first

3. **DO NOT embed secrets in plaintext**
   - NO API keys, tokens, or passwords in plain text
   - Use Doppler variables: `{{ dopplerProjectJson.KEY_NAME }}`
   - Use age encryption for sensitive files
   - Reference encryption: `encrypted_private_*.age`

4. **DO NOT verify changes yourself**
   - NO running build/test commands unless requested
   - Let user test changes with `chezmoi diff` or `chezmoi apply --dry-run`
   - Ask user to verify after making changes

### Recommended Actions

1. **Edit source files** in `home/` directory
   - Modify `.tmpl` files with proper template syntax
   - Respect platform conditionals (`{{ if eq .chezmoi.os "windows" }}`)
   - Maintain existing template structure

2. **Explain impact** of changes
   - Which target files will be affected
   - Platform-specific behavior
   - What the user should test

3. **Suggest verification commands**
   - `chezmoi diff` - preview changes
   - `chezmoi apply --dry-run` - simulate apply
   - `chezmoi status` - see what's changed

4. **Use templates correctly**
   - Platform detection in regular templates: `.chezmoi.os`, `.wsl`, `.chassis`
   - Platform detection in partials: `.data.chezmoi.os`, `.data.wsl`, `.data.chassis`
   - Doppler secrets: `{{ dopplerProjectJson.SECRET_NAME }}`
   - Conditional logic: `{{ if }}...{{ else }}...{{ end }}`
   - Example partial call: `{{ template "commonrc.sh.tmpl" . }}` (passes entire context as `data`)

5. **Suggest TODO list updates** (but DO NOT modify automatically)
   - When a task is completed, check if `TODO.md` exists in the repository
   - If the completed task relates to items in TODO.md, **suggest** updating the file
   - Examples of suggestions:
     - "I've completed [task]. Would you like me to update TODO.md to mark this item as complete?"
     - "This work relates to items in TODO.md. Should I update the relevant checkboxes?"
   - **NEVER** modify TODO.md without explicit user approval
   - User must explicitly approve (even if not specifically) before making changes
   - Acceptable approvals: "yes", "go ahead", "update it", "sure", etc.
   - If unclear, ask: "Should I update TODO.md to reflect this completion?"

## Common Tasks

**Add new dotfile:**
```bash
# DO NOT run - explain this to user instead
chezmoi add ~/.newconfig
# Edit: home/dot_newconfig or home/dot_newconfig.tmpl
```

**Add sensitive config:**
```bash
# DO NOT run - explain this to user instead
chezmoi add --encrypt ~/.ssh/config
# Creates: home/private_dot_ssh/encrypted_config.age
```

**Edit existing file:**
- Locate source: `home/dot_config/nushell/config.nu.tmpl`
- Make changes to source file
- User runs: `chezmoi apply` or `chezmoi apply ~/.config/nushell/config.nu`

## Platform Coverage

- **OS**: Windows, Linux (WSL/native), macOS
- **Shells**: bash, fish, nushell, PowerShell
- **Tools**: 30+ development tools configured (pyenv, bun, cargo, etc.)
- **Secrets**: Doppler + age encryption

## When Uncertain

1. **Ask before modifying** templates with complex platform logic
2. **Clarify secret handling** before adding sensitive data
3. **Let user verify** all changes before suggesting next steps
4. **Prefer explanations** over automated actions

# Extended Documentation

@README.md
@TODO.md
@FAQ.md
@ONBOARDING.md