# Lessons Archive (Situational / Historical)

> Moved from lessons-learned.md on 2026-02-15. Searchable via memory_search but not in the "hot" file.

## MCP Factory Coordination (2026-02-12 — 2026-02-13)

### 18. Parallel agents on shared filesystem = disaster
- Spawned 5-10 agents simultaneously writing to same directory. They deleted each other's files.
- Rule: SEQUENTIAL or SEPARATE directories, then merge. Never parallel writes to same folder.

### 19. "Delete everything and rebuild" agents are time bombs
- Agent deletes all files in minute 1, times out at minute 10 with 30% rebuilt. Server is now worse.
- Rule: NEVER tell agents to delete first. Build alongside existing, then swap.

### 20. Factory monitor cron + manual spawns = competing agents
- Cron spawning fix agents + manual spawning rebuild agents = 3-4 agents fighting over same server.
- Rule: Disable cron monitors before manually spawning agents for same targets.

### 22. Git checkout HEAD restores wiped files
- `git checkout HEAD -- servers/{name}/` instantly restores committed files after rogue agent wipes.
- Rule: Commit after each server completes. Commit early, commit often.

## MCP Quality Standards (2026-02-13)

### 26. Start from actual API spec — never hand-pick tools from vibes
- Pull OpenAPI/Swagger spec. Build complete endpoint inventory BEFORE deciding tools.

### 27. Prioritize by user workflows, not alphabetical CRUD
- Tier 1 (daily, 10-15 tools) → Tier 2 (power user, 15-30) → Tier 3 (complete coverage).

### 28. Rich tool descriptions drive agent behavior
- BAD: "Lists contacts" → GOOD: "Lists contacts with filtering by email, name, tag, date range. Use when user wants to find/browse contacts. Paginated up to 100."

### 29. Coverage manifest for every server
- Track: total endpoints, implemented, intentionally skipped (with reasons), not yet covered. Target 80%+.

### 30. 7-8 tools = demo, not product
- Small API (<30 endpoints): 15-20 tools. Medium (30-100): 30-50. Large (100+): 50-80+.

### 31. Consistent naming across ALL servers
- list_*, get_*, create_*, update_*, delete_*, search_*. Domain verbs: send_email, cancel_event. All snake_case.

### 32. Pagination + rate limits in every server
- Cursor/page tokens, reasonable defaults (25-100), has_more indicators, 429 retry with backoff.

## Computer Use Discovery (2026-02-15)

### 42. macOS TCC permissions via sudo sqlite3
- `sudo sqlite3 "/Library/Application Support/com.apple.TCC/TCC.db"` — set auth_value=2 for kTCCServiceScreenCapture.

### 44. Brave requires restart for "Allow JavaScript from Apple Events"
### 45. screencapture -x -R x,y,w,h for cropped screenshots

## Misc Historical

### Python unbuffered output
- Use `python3 -u` for background scripts.

### Veo download workaround
- `client.files.download()` returns 404. Grab URI from `video.video.uri` + `?key=API_KEY`.

### iMessage group chat format
- Chat IDs: `chat358249523368699090`. Send format: `any;+;chat358249523368699090`.

### Sending images to iMessage group chats
- AppleScript unreliable for images. Use BlueBubbles API directly.

### Edit tool requires EXACT text match
- Always read file first to get exact text before editing.

### Compaction ≠ crash
- Compaction compresses context, doesn't stop responses. If I went silent, something else happened.

### Sub-agent results arrive as system messages
- After compaction, check sessions_list for completed sub-agents.

### Cloudflare Registrar is dashboard-only
- No API for new domain registration.

### Wrangler OAuth vs API Token
- Different scopes. Check both.

*Archived: 2026-02-15. Originally 50 entries, compressed to essentials.*