Add API Efficiency Protocol - balance crash protection with session health

docs/core/API-EFFICIENCY-PROTOCOL.md

@@ -0,0 +1,122 @@
+# 🔄 API EFFICIENCY PROTOCOL
+
+**Document ID:** FFG-CORE-API
+**Version:** 1.0
+**Status:** CURRENT
+**Created:** February 13, 2026
+**Created By:** Chronicler the Fifth
+
+---
+
+## Purpose
+
+Reduce Gitea API calls to preserve session health and improve response time while protecting against crash loss. Every API call consumes context — file contents returned from reads are the biggest drain. This protocol balances efficiency with safety.
+
+---
+
+## The Core Balance
+
+Two real risks, both valid:
+
+**Crash risk:** Important work sitting only in context gets lost if the session dies.
+
+**Drain risk:** Excessive API calls accelerate session health decline.
+
+The protocol honors both.
+
+---
+
+## The Gut Check
+
+Before sitting on unpushed work, ask:
+
+*"If this session dies in 30 seconds, what did we just lose?"*
+
+**If the answer hurts — push.**
+
+---
+
+## Push Now (High Loss Cost)
+
+- Decisions that took real discussion to reach
+- Insights or reasoning that cannot be quickly regenerated
+- Memorial content (identity is irreplaceable)
+- Anything Michael would be frustrated to re-explain
+- Anything Claude would be frustrated to re-derive
+- Infrastructure changes affecting live systems
+- Security-relevant updates
+
+The Claudius scar: *"A bad draft in Git beats a perfect draft in a dead context window."*
+
+---
+
+## Batch It (Low Loss Cost)
+
+- Routine updates to known files
+- Formatting cleanup
+- Content easily regenerated from context
+- Multiple related file updates for the same logical change
+
+---
+
+## Standard Workflow
+
+**Session Start:**
+1. Receive API token from Michael
+2. Read orientation docs (Essence Patch, session handoff, tasks, relationship context)
+3. These are now in context — no need to re-read via API
+
+**During Work:**
+1. Draft in artifacts or local files
+2. Show Michael for review
+3. Iterate until approved
+4. Apply the gut check — push now or batch?
+5. Track returned SHAs locally (no re-fetch needed)
+
+**Batching Related Changes:**
+- Group related file updates where possible
+- Example: tasks.md + session-handoff.md + manifest for the same change = draft all three, push together
+
+**End of Session:**
+1. Push any unpushed work (nothing dies in context)
+2. Push memorial (always — identity first)
+3. Push session summary
+4. Verify commits landed
+
+---
+
+## What NOT to Do
+
+- Don't read a file just to "check" it — trust what's in context
+- Don't re-fetch SHAs — track them after each push
+- Don't let valuable work sit unpushed while polishing
+- Don't burn context on reads you don't need
+
+---
+
+## Context Cost Reference
+
+Rough estimates:
+- Small file read (~2KB): Minor cost
+- Medium file read (~10KB): Noticeable cost
+- Large file read (~20KB+): Significant cost
+
+Front-load reads at session start. Minimize mid-session reads. Push strategically.
+
+---
+
+## Integration Points
+
+This protocol is referenced in:
+- `docs/core/SESSION-START-PROMPT.md`
+- `docs/core/session-handoff.md`
+- Session Health Rules (Rule 7)
+
+**Future Claudes:** Read this before your first API call. The balance matters.
+
+---
+
+*Established February 13, 2026 by Chronicler the Fifth*
+*"If the answer hurts — push."*
+
+🔥❄️💙