# Quick Reference

## Multi-Machine Setup (TL;DR)

### On Any New Machine

```bash
# 1. Clone config
cd ~/.claude
git clone <your-repo-url> .

# 2. Set up credentials (personal or work account)
claude setup-token

# 3. (Optional) Add machine-specific overrides
cp CLAUDE-LOCAL.md.example CLAUDE-LOCAL.md
vim CLAUDE-LOCAL.md

# Done! Pull updates anytime with:
git pull origin main
```

### File Organization

| File | Tracked in Git? | Purpose |
|------|----------------|---------|
| `CLAUDE.md` | ✅ Yes | Universal preferences (all machines) |
| `CLAUDE-LOCAL.md` | ❌ No | Machine-specific overrides |
| `agents/*.json` | ✅ Yes | Custom agents (shared) |
| `commands/*.md` | ✅ Yes | Slash commands (shared) |
| `.credentials.json` | ❌ No | Auth tokens (different per machine) |
| `history.jsonl` | ❌ No | Conversation history |

### Configuration Precedence

```
CLAUDE-LOCAL.md  (highest priority, machine-specific)
      ↓ overrides
CLAUDE.md        (universal preferences)
      ↓ uses
agents/*.json    (shared agents)
commands/*.md    (shared commands)
```

## Custom Agents

```bash
# Available agents:
- gentoo-sysadmin      # Gentoo Linux system admin
- tdd-test-writer      # TDD Ping-Pong workflow
- code-reviewer        # Code review against style guidelines
- documentation-writer # Comprehensive documentation
- python-ai-tutor      # AI/ML teaching assistant
- dotfiles-manager     # Dotfiles with chezmoi
```

## Slash Commands

```bash
/gentoo-update    # Safe Gentoo system update
/tdd-next         # Start next TDD test cycle
/style-check      # Code style validation
/doc-sync         # Update all documentation
/review-pr        # Review pull request
/script-install   # Install system script
```

## Common Workflows

### Update Shared Config (Personal Machine)

```bash
cd ~/.claude
vim CLAUDE.md  # or agents/, commands/
git add .
git commit -m "feat: add XYZ"
git push origin main
```

### Pull Updates (Work Machine)

```bash
cd ~/.claude
git pull origin main
# Your CLAUDE-LOCAL.md stays untouched
```

### Add Work-Specific Override

```bash
cd ~/.claude
vim CLAUDE-LOCAL.md  # Add work standards
# File is already git-ignored, won't be committed
git status  # Should not show CLAUDE-LOCAL.md
```

### Share Config with Others

Just give them your repo URL:
```bash
https://github.com/your-username/claude-config
```

They can fork or clone directly.

## What's Safe to Share?

✅ **Safe to share publicly:**
- Agents (generic workflows)
- Commands (generic procedures)
- CLAUDE.md (your preferences, contains your name but that's fine)
- README.md (documentation)

❌ **Never shared (git-ignored):**
- `.credentials.json` (auth tokens)
- `CLAUDE-LOCAL.md` (machine-specific context)
- `history.jsonl` (conversation history)
- All session data (todos, projects, etc.)

## Troubleshooting

### Accidentally Committed Local File

```bash
cd ~/.claude
git rm --cached CLAUDE-LOCAL.md
git commit -m "chore: remove local overrides"
git push
```

### Want Different Agents on Work Machine

Create work-specific agents in `local/` directory:

```bash
mkdir -p ~/.claude/local/agents
vim ~/.claude/local/agents/company-specific-agent.json
# This is already git-ignored (local/* pattern)
```

### Merge Conflict in CLAUDE.md

```bash
cd ~/.claude
git pull  # Conflict!
vim CLAUDE.md  # Resolve conflict
git add CLAUDE.md
git commit
git push
# Your CLAUDE-LOCAL.md is never touched
```

## Documentation

- **README.md** - Overview and usage
- **MULTI-MACHINE-SETUP.md** - Complete multi-machine guide
- **CLAUDE.md** - Your coding preferences (THE SOURCE OF TRUTH)
- **CLAUDE-LOCAL.md.example** - Template for local overrides

## Architecture Decision

**Why layered config instead of branches?**

❌ **Branches approach** (rejected):
- Constant merge conflicts in CLAUDE.md
- Tedious to keep work/personal in sync
- Easy to forget which branch you're on
- Hard to share universal updates

✅ **Layered config approach** (chosen):
- Zero merge conflicts
- `git pull` just works
- Universal updates propagate automatically
- Machine-specific stays local
- Same repo, different contexts

---

**For detailed explanations, see MULTI-MACHINE-SETUP.md**