# Claude Memory and Instructions

Read README.rst to understand the build system.

you are acting on behalf of russell ballestrini. don't fuck up.

## CRITICAL PELICAN TESTING WORKFLOW

### BEFORE ANY COMMIT:
1. **ALWAYS test Pelican build**: `make clean && make html`
2. **Check for build errors**: Pelican will fail on RST syntax errors, missing files, etc.
3. **Verify output**: `make serve` and check localhost:8000
4. **NEVER commit without testing the build**

### PELICAN BUILD PROCESS:
- Uses Pelican static site generator (Python-based)
- Converts .rst/.md files to HTML
- RST syntax errors break the build
- Missing images/files break the build
- Invalid slugs/filenames cause issues

### PROPER DEVELOPMENT WORKFLOW:
```bash
# Setup virtual environment (once)
make venv

# Test changes before commit
make clean && make html && make serve

# Check localhost:8000 for issues
# Only commit if build succeeds
git add specific-files
git commit -m "message"
git push
```

## CRITICAL CONTENT DIRECTORY ISSUE

**PROBLEM**: Python virtual environments exist in `content/uploads/2024/battleship-solvers/env/` and `env2/`
- These contain thousands of Python package files (.md, .rst files)
- Pelican tries to process them as blog content
- Causes massive build warnings and errors
- Should NOT be in content directory

**SOLUTION NEEDED**: 
- Remove env/ and env2/ directories from content/uploads/
- Add env*/ to .gitignore patterns
- Keep only actual blog assets in content/uploads/

## CRITICAL GIT SAFETY LESSON

### DEVASTATING MISTAKE COMMITTED:
I made a catastrophic git error that destroyed user's work in progress:

1. **What I did wrong**: Used `git add .` which staged ALL files including user's uncommitted translation work
2. **The fatal mistake**: When trying to fix the staging issue, I used `git reset HEAD .` which overwrote the working directory files with staged versions
3. **Result**: User's uncommitted translation work was completely lost/overwritten

### PROPER APPROACH:
- **ALWAYS** check `git status` and `git diff` first to see what uncommitted work exists
- **NEVER** use `git add .` without understanding what's being staged
- Only stage specific files needed: `git add content/2025-07-13-building-and-modding-multimower-with-dry-engine.rst`
- If I need to unstage, use `git restore --staged <file>` for specific files, **NOT** `git reset HEAD .`

### KEY LESSON:
Git operations can be destructive to uncommitted work. Always preserve user's work in progress before any git commands.

**This was a serious failure that cost the user their translation work. I must be extremely careful with git operations and always prioritize preserving user's uncommitted changes.**

## COMMIT MESSAGE POLICY

**NEVER add attribution text to commit messages**
- Do not include "🤖 Generated with [Claude Code](https://claude.ai/code)"
- Do not include "Co-Authored-By: Claude <noreply@anthropic.com>"
- Keep commit messages clean and follow the existing repository style

## HELPER SCRIPTS AND TEMPORARY FILES

**NEVER commit helper scripts or temporary files unless explicitly requested**
- Helper scripts (like append_toc.py, test.py, etc.) are for temporary use only
- Only commit helper scripts if the user explicitly says to commit them
- After using a helper script, delete it from the working directory
- Do not include helper scripts in git commits unless specifically instructed
- Focus commits on actual content changes, not the tools used to make them

## WRITING STYLE

**Use "&" instead of "and" most of the time in posts**
- Prefer concise ampersand (&) for connecting words & phrases
- Example: "disrupt wheels & foster open collaboration" not "disrupt wheels and foster open collaboration"
- This creates a more casual, punchy writing style that matches the brand voice