# MyBurn — Claude Code Instructions

## MANDATORY RULES

### 1. PLAN before implementing
For any change touching more than 2 files, or any new feature/refactor:
- Describe the approach (which files, what changes, what order)
- Get explicit user approval BEFORE writing any code
- Use plan mode for non-trivial work

### 2. NEVER act without being asked
- **Don't commit** unless the user says "commit"
- **Don't deploy** unless the user says "deploy"
- **Don't refactor** surrounding code while fixing a bug
- **Don't add features** that weren't requested
- **Suggest**, don't do. Say "queres que eu faça X?" instead of just doing X.

### 3. Verify before saying "done"
After ANY code change:
- Restart the server (see Environment below)
- Run smoke tests — unit tests alone are NOT sufficient:
  ```bash
  curl -s localhost:7734/api/health | python3 -m json.tool
  curl -s localhost:7734/api/monthly | head -c 200
  curl -s localhost:7734/api/daily | head -c 200
  ```
- If UI changed: take a screenshot or describe what you see
- NEVER say "done" or "ready" without having verified

### 4. Session-end protocol
Before ending ANY session:
1. Update `MEMORY.md` — current state, what was done
2. Update `roadmap.md` — mark completed items, add new ones
3. Cross-check: no item marked TODO in one file if DONE in another
4. Report to user what was accomplished

## OPERATING DISCIPLINE

- **Investigate before acting** — read memory files, grep codebase, check DB state BEFORE writing anything
- **No trial-and-error** — if you don't know how something works, READ the code first
- **Verify assumptions** — check the DB, check the logs, check actual state before claiming correctness
- This project has real infra (sync pipelines, trust validation, cloud services) — blind changes cascade
- **"246 tests passing" does NOT mean production works** — always smoke-test the running server

## KNOWN LANDMINES

### datetime migrations
Changing `datetime.utcnow()` to `datetime.now(timezone.utc)` makes ALL downstream comparisons fail if any datetime in the chain is still naive. Before touching any datetime:
```bash
grep -rn "datetime(" myburn/ --include="*.py"
```
Fix ALL constructors in the chain, not just the one you're looking at.

### CSP (Content Security Policy)
Before changing `script-src` or any CSP directive, check what the HTML actually loads:
```bash
grep -n "script src=" static/index.html static/wrapped.html
```
Dashboard uses `cdn.jsdelivr.net` for Chart.js and html2canvas.

### Server restart required after changes
The FastAPI server does NOT hot-reload in production mode. After code changes:
```bash
# Kill existing
pkill -f "python3 app.py" 2>/dev/null
# Restart
MYBURN_DATA_DIR=/home/gekko/projects/ccusage-dashboard/data MYBURN_HOST=0.0.0.0 nohup python3 app.py > /tmp/myburn.log 2>&1 &
# Verify
sleep 2 && curl -s localhost:7734/api/health
```

### Schema changes
After any SQLite schema change, restart the server AND verify existing data wasn't corrupted:
```bash
curl -s localhost:7734/api/health | python3 -m json.tool
```

## COMMIT STYLE
- Feature-based commits (not WIP)
- Always suggest before committing — never auto-commit
- Format: `feat:`, `fix:`, `refactor:`, `docs:`, `test:`
- Include `Co-Authored-By: Claude <noreply@anthropic.com>`

## ENVIRONMENT
- **Server port**: 7734
- **Restart command**: `MYBURN_DATA_DIR=/home/gekko/projects/ccusage-dashboard/data MYBURN_HOST=0.0.0.0 nohup python3 app.py > /tmp/myburn.log 2>&1 &`
- **Health check**: `curl localhost:7734/api/health`
- **Required env vars**: `MYBURN_DATA_DIR`, `MYBURN_HOST=0.0.0.0`, `GITHUB_CLIENT_ID` (for cloud features)
- **Tests**: `python3 -m pytest tests/ -q`

## USER PREFERENCES
- Portuguese for conversation, English for code
- Quality over speed — ship when ready, not when fast
- Suggest approach before implementing
- Likes meme energy and viral-ready design, but correctness comes first
