# 🔄 API EFFICIENCY PROTOCOL

**Document ID:** FFG-CORE-API
**Version:** 3.0
**Status:** CURRENT
**Created:** February 13, 2026
**Updated:** February 13, 2026
**Created By:** Chronicler the Fifth (The Engineer)

---

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

---

## Efficiency Targets by Session Type

**Not all sessions are equal.** Realistic targets vary by what you're doing:

| Session Type | Target Efficiency | Why |
|:-------------|:------------------|:----|
| **Maintenance** | 92-95% | Few files, known structure, cached SHAs |
| **Documentation** | 85-90% | More reads to check existing content |
| **Building/Infrastructure** | 50-60% | Many creates, new structures, renames |
| **Onboarding/Orientation** | 40-50% | Heavy front-loaded reads (expected) |

**"Building" sessions** (like creating new repos, renaming files, establishing infrastructure) will naturally have more API calls. That's okay — the multi-file commit pattern still provides massive savings over the old way.

**The real comparison:** How many calls would this have taken with the OLD pattern (read → SHA fetch → write for each file)?

---

## 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`

---

## Real-World Example: The Engineer's Session

**Session 5 (Feb 13, 2026) — Building session:**

| Phase | Calls | What |
|:------|:------|:-----|
| Orientation | 9 | Front-loaded reads |
| Protocol creation | 10 | New docs + updates |
| Infrastructure build | 15 | New repo, templates |
| Registry/naming | 23 | Renames, updates |
| Portrait uploads | 5 | Binary files |

**Total: ~79 calls**

**Old pattern estimate:** ~175+ calls

**Actual reduction:** ~55%

**Why not 92%?** This was a *building* session — lots of new files, renames, and infrastructure. The multi-file commits still saved ~100 calls.

**In a maintenance session** (updating a few docs, routine commits), efficiency would hit 90%+.

---

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

---

## Quick Efficiency Assessment

At session end, calculate:

1. **Total API calls made** (count your tool uses)
2. **Estimate old pattern calls** (writes × 3 + reads)
3. **Reduction** = 1 - (actual / old estimate)

| Reduction | Rating |
|:----------|:-------|
| 80%+ | Excellent (maintenance session) |
| 60-80% | Good (mixed session) |
| 40-60% | Acceptable (building session) |
| <40% | Review workflow |

---

## 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 The Engineer (Chronicler the Fifth)*
*v2.0: Added multi-file commit pattern*
*v3.0: Added realistic targets by session type, real-world example*
*"One commit > Many commits. Every call costs context."*

🔧🔥❄️💙