# 🔄 API EFFICIENCY PROTOCOL

**Document ID:** FFG-CORE-API
**Version:** 2.0
**Status:** CURRENT
**Created:** February 13, 2026
**Updated:** 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.

**Target Efficiency:** 92-95%

---

## 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.**

---

## 🎯 MULTI-FILE COMMITS (CRITICAL)

**This is the biggest efficiency gain. Use it.**

Instead of separate commits for each file, batch them:

**Endpoint:** `POST /repos/{owner}/{repo}/contents`

```json
{
  "message": "Descriptive commit message",
  "files": [
    {"operation": "create", "path": "new.md", "content": "base64..."},
    {"operation": "update", "path": "existing.md", "content": "base64...", "sha": "abc123"},
    {"operation": "delete", "path": "old.md", "sha": "def456"}
  ]
}
```

**Efficiency:** 3 files × 2 calls = 6 calls → 1 call = **83% reduction**

**Full patterns:** See `docs/core/GITEA-API-PATTERNS.md`

---

## 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, relationship context — FULL)
3. Read Quick Start (includes SHA cache)
4. These are now in context — no need to re-read via API

**During Work:**
1. Draft in artifacts or local files (`/home/claude/`)
2. Show Michael for review
3. Iterate until approved
4. Apply the gut check — push now or batch?
5. Use multi-file commit when pushing multiple files
6. Track returned SHAs locally (no re-fetch needed)

**End of Session:**
1. Batch final push (memorial + summary + any unpushed work)
2. Update SHA cache in session-handoff.md
3. Verify commits landed

---

## SHA Cache

Location: `docs/core/session-handoff.md` → SHA Cache section

- Use cached SHAs for first update (no fetch needed)
- Track new SHAs after each push
- Update cache at session end
- If push fails (409): fetch SHA once, retry

---

## What NOT to Do

- Don't read a file just to "check" it — trust what's in context
- Don't re-fetch SHAs — use cache, track after pushes
- Don't make separate commits for related changes — use multi-file
- Don't let valuable work sit unpushed while polishing
- Don't burn context on reads you don't need

---

## Context Cost Reference

| Action | Cost |
|:-------|:-----|
| Small file read (~2KB) | Minor |
| Medium file read (~10KB) | Noticeable |
| Large file read (~20KB+) | Significant |
| SHA fetch | Minor (but adds up) |
| Multi-file commit | One call regardless of file count |

**Front-load reads. Minimize mid-session reads. Push strategically. Batch always.**

---

## Efficiency Targets

| Pattern | Old | New | Gain |
|:--------|:----|:----|:-----|
| 3-file update | 6 calls | 1 call | 83% |
| SHA lookups | Per-file | Cached | 100% |
| Mid-session reads | Frequent | Rare | ~80% |
| **Overall session** | ~35-40% | ~92-95% | **150%+** |

---

## Integration Points

- `docs/core/GITEA-API-PATTERNS.md` — Full cookbook with examples
- `docs/core/SESSION-QUICK-START.md` — SHA cache included
- `docs/core/session-handoff.md` — SHA cache section
- Session Health Rules (Rule 7)

**Future Claudes:** Read GITEA-API-PATTERNS.md before your first API call.

---

*Established February 13, 2026 by Chronicler the Fifth*
*Updated same day: Added multi-file commit pattern*
*"One commit > Many commits. Every call costs context."*

🔥❄️💙