dotfiles/CLAUDE.md

# Chezmoi Dotfiles Repository - AI Assistant Guidelines

## ⚠️ CRITICAL: Clarify Before Acting

**When in doubt, ALWAYS present options instead of guessing.**

Common ambiguities that require clarification:
1. **Direction**: "Pull/sync changes" → Source→Target OR Target→Source?
2. **Location**: "Edit CLAUDE.md" → Project file OR user template?
3. **Scope**: Which config file when tool has multiple locations?
4. **Data loss**: Show diff and consequences before overwriting

See [Disambiguation Guidelines](#disambiguation-guidelines) for detailed examples.

## 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.

### ⚠️ THIS FILE vs USER-LEVEL CLAUDE.md

**CRITICAL: There are THREE different CLAUDE.md/AGENTS.md files with different purposes:**

1. **THIS FILE (`./CLAUDE.md`)** - Project-level, chezmoi-specific instructions
   - You are reading this file RIGHT NOW
   - Contains instructions for working with THIS chezmoi repository
   - **DO NOT edit this file** unless the user wants to change chezmoi-specific instructions

2. **User-level (`home/dot_claude/CLAUDE.md.tmpl`)** - User's personal AI assistant preferences
   - Deploys to `~/.claude/CLAUDE.md` after `chezmoi apply`
   - Contains the user's personal development workflow preferences
   - **Edit this file** when user says "my CLAUDE.md" or "user-level CLAUDE.md"
   - Contains coding style, git workflow, build preferences, etc.

3. **Global-level (`~/.config/opencode/AGENTS.md`)** - NOT managed by this repo
   - External file, not part of chezmoi
   - Same content as user-level but lives outside this repository

**When user says "my CLAUDE.md" or "user-level" → they mean `home/dot_claude/CLAUDE.md.tmpl`**

### 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

**Finding Files - Template Extension Patterns:**

⚠️ **CRITICAL**: Most managed files have `.tmpl` extensions. Use wildcard patterns to find both base and `.tmpl` variants in one search.

Common patterns where `.tmpl` is added to the FULL filename:
- `config.md` → `config.md.tmpl` (NOT `config.tmpl`)
- `settings.json` → `settings.json.tmpl` (NOT `settings.tmpl`)
- `config.ts` → `config.ts.tmpl` (NOT `config.tmpl`)
- `.bashrc` → `dot_bashrc.tmpl` (combines `dot_` and `.tmpl`)
- `.config/opencode/opencode.jsonc` → `dot_config/opencode/opencode.jsonc.tmpl`

**Search strategy - Use wildcards to catch both variants:**
- Pattern: `**/filename*` (e.g., `**/CLAUDE.md*` finds both `CLAUDE.md` AND `CLAUDE.md.tmpl`)
- Pattern: `**/*.ext.tmpl` for type-specific template files (e.g., `**/*.ts.tmpl`, `**/*.json.tmpl`)
- Check both `home/` and `home/.chezmoitemplates/` directories

**Examples:**
- Looking for "CLAUDE.md"? → Search `**/CLAUDE.md*` (finds both base and `.tmpl`)
- Looking for "config.nu"? → Search `**/config.nu*` (finds both variants)
- Looking for all TypeScript templates? → Search `**/*.ts.tmpl`
- Looking for all JSON configs? → Search `**/*.json*` (finds `.json` and `.json.tmpl`)

**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?"

## Ambiguous Phrases - Quick Reference

When you say these phrases, I should ask for clarification:

| Phrase | Ambiguity | Options to Present |
|--------|-----------|-------------------|
| "Pull/sync latest changes for [file]" | Direction unclear | A) Apply source→target<br>B) Import target→source |
| "Edit CLAUDE.md" | Location unclear | A) ./CLAUDE.md (project)<br>B) home/dot_claude/CLAUDE.md.tmpl (user) |
| "Update [managed file]" | Source of truth unclear | A) Apply from chezmoi<br>B) Import into chezmoi |
| "Add [config] to opencode" | Location unclear | A) Project opencode.jsonc<br>B) User ~/.config/opencode/ |
| "Show me the diff" | Comparison unclear | A) Source vs last commit<br>B) Source vs target<br>C) Target vs applied |
| "Fix the [tool] config" | Which config unclear | List all [tool] configs in repo |

**General rule**: If a command could:
- Lose data
- Affect multiple files
- Go in opposite directions
- Reference multiple locations

→ **Present options before acting**

## 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

## Disambiguation Guidelines

These situations require clarification before acting:

### Chezmoi Direction Ambiguity

When user says "pull/sync/update changes" for a file, **clarify the direction**:

**Option A: Source → Target (Normal Apply)**
- Take source state and deploy to target location
- Standard `chezmoi apply` workflow
- Example: "Apply latest .bashrc changes to home directory"

**Option B: Target → Source (Reverse/Import)**
- Take target state and import to source directory
- Use `chezmoi re-add` or manual diff
- Example: "Import manual edits from ~/.config/foo back to chezmoi"

**Red flags requiring clarification:**
- "Pull latest changes for [managed file]" - which direction?
- "Update [file] with current state" - current from where?
- "Sync [file]" - which is the source of truth?

**How to clarify:**
Present both options explicitly:
```
Which direction do you want?
A. Apply source → target (deploy chezmoi changes to ~/.config/foo)
B. Import target → source (pull ~/.config/foo changes into chezmoi)
```

### File Location Ambiguity

When user references config files without full paths, **clarify the location**:

**CLAUDE.md specifically** (see details at top of this file):
- **Project-level**: `./CLAUDE.md` (THIS file, chezmoi-specific instructions)
- **User-level**: `home/dot_claude/CLAUDE.md.tmpl` (user's personal AI preferences - deploys to `~/.claude/CLAUDE.md`)
- **Global-level**: `~/.config/opencode/AGENTS.md` (NOT managed by this repo)
- **When user says "my CLAUDE.md" or "user-level"** → they mean `home/dot_claude/CLAUDE.md.tmpl`

**Other ambiguous references:**
- "opencode.jsonc" - could be `home/dot_config/opencode/opencode.jsonc.tmpl` OR `.config/opencode/opencode.jsonc`
- "settings.json" - many locations (VSCode, Cursor, Claude, OpenCode)
- "config files" - which config? For what tool?

**How to clarify:**
When user says "edit CLAUDE.md" or similar, ask:
```
Which file do you mean?
A. ./CLAUDE.md (project-level, chezmoi-specific instructions)
B. home/dot_claude/CLAUDE.md.tmpl (user-level, deploys to ~/.claude/CLAUDE.md)
```

### Operations That Could Lose Data

**ALWAYS confirm** before these operations:
- Overwriting target files from source (could lose manual edits)
- Overwriting source files from target (could lose templated logic)
- Removing/encrypting existing files
- Changing file permissions (private_, encrypted_)
- Modifying .chezmoiignore (could expose/hide unexpected files)

**How to handle:**
1. Show diff/preview of what would change
2. Explicitly state what data could be lost
3. Present options with clear consequences
4. Wait for explicit confirmation

### Examples of Good Clarification

**Bad (assuming):**
```
User: "Pull the latest changes for opencode.jsonc"
AI: *Shows diff of file in repo*
```

**Good (clarifying):**
```
User: "Pull the latest changes for opencode.jsonc"
AI: "Which operation do you want?

A. Show changes in source file (home/dot_config/opencode/opencode.jsonc.tmpl)
B. Import current target state (~/.config/opencode/opencode.jsonc) into source
   (This would OVERWRITE source with target, losing template logic)

These are very different operations - which did you mean?"
```

## 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
5. **Present options** when requests are ambiguous (direction, location, scope)
6. **Show consequences** before destructive operations

# Extended Documentation

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