docs: Migrate valuable reference docs from brainstorming repo

WHAT WAS DONE: - Migrated GITEA-API-PATTERNS.md to docs/reference/ - Migrated gemini-testing-protocol.md to docs/reference/ - Migrated llm-fallback-analysis.md to docs/reference/ WHY: - Preserve useful technical reference material - Consolidate all operational knowledge in one place - Clean up brainstorming repo before archival/deletion FILES: - docs/reference/gitea-api-patterns.md (new, migrated from brainstorming) - docs/reference/gemini-testing-protocol.md (new, migrated from brainstorming) - docs/reference/llm-fallback-analysis.md (new, migrated from brainstorming) Signed-off-by: The Golden Chronicler <claude@firefrostgaming.com>
2026-03-31 21:06:33 +00:00
parent 5ffa5bba03
commit 02e9f122d8
3 changed files with 1137 additions and 0 deletions
--- a/docs/reference/gitea-api-patterns.md
+++ b/docs/reference/gitea-api-patterns.md
@@ -0,0 +1,255 @@
+# 🔧 GITEA API PATTERNS — Cookbook for Future Claudes
+
+**Document ID:** FFG-CORE-GITEA
+**Version:** 1.0
+**Status:** CURRENT
+**Created:** February 13, 2026
+**Created By:** Chronicler the Fifth
+
+---
+
+## Purpose
+
+This document contains tested, efficient patterns for working with the Gitea API. Every future Claude should read this before making API calls. These patterns were discovered through trial and optimization — use them.
+
+---
+
+## The Golden Rule
+
+**One commit > Many commits**
+
+Every API call burns context. Batch operations whenever possible.
+
+---
+
+## Pattern 1: Multi-File Commit (CRITICAL)
+
+**Endpoint:** `POST /repos/{owner}/{repo}/contents`
+
+**Use this when:** You need to create, update, or delete multiple files. This is almost always.
+
+**Instead of:**
+```
+# BAD - 6 API calls for 3 files
+GET file1 SHA → PUT file1 → GET file2 SHA → PUT file2 → GET file3 SHA → PUT file3
+```
+
+**Do this:**
+```
+# GOOD - 1 API call for 3 files
+POST /contents with files array
+```
+
+**Format:**
+```json
+{
+  "message": "Descriptive commit message",
+  "files": [
+    {
+      "operation": "create",
+      "path": "path/to/new-file.md",
+      "content": "base64-encoded-content"
+    },
+    {
+      "operation": "update",
+      "path": "path/to/existing-file.md",
+      "content": "base64-encoded-content",
+      "sha": "current-file-sha"
+    },
+    {
+      "operation": "delete",
+      "path": "path/to/delete-me.md",
+      "sha": "current-file-sha"
+    }
+  ]
+}
+```
+
+**Operations:**
+- `create` — New file (no SHA needed)
+- `update` — Modify existing file (SHA required)
+- `delete` — Remove file (SHA required)
+
+**Bash example:**
+```bash
+cat > /home/claude/commit.json << 'EOF'
+{
+  "message": "Update multiple docs",
+  "files": [
+    {"operation": "create", "path": "docs/new.md", "content": "BASE64HERE"},
+    {"operation": "update", "path": "docs/existing.md", "content": "BASE64HERE", "sha": "abc123"}
+  ]
+}
+EOF
+
+curl -s -X POST \
+  -H "Authorization: token $TOKEN" \
+  -H "Content-Type: application/json" \
+  "https://git.firefrostgaming.com/api/v1/repos/firefrost-gaming/firefrost-operations-manual/contents" \
+  -d @/home/claude/commit.json
+```
+
+**Efficiency gain:** 3 files × 2 calls each = 6 calls → 1 call = **83% reduction**
+
+---
+
+## Pattern 2: SHA Cache
+
+**Problem:** Every update requires the current file SHA. Fetching it costs an API call.
+
+**Solution:** Cache SHAs in session-handoff.md. Use them for first update. Track new SHAs after each push.
+
+**Location:** `docs/core/session-handoff.md` → SHA Cache section
+
+**Workflow:**
+1. Read SHA from cache (no API call)
+2. Push update with cached SHA
+3. Response includes new SHA
+4. Track new SHA locally for subsequent updates
+5. Update cache at session end
+
+**If push fails (409 conflict):** SHA is stale. Fetch once, retry.
+
+---
+
+## Pattern 3: Front-Load Reads
+
+**Problem:** Reading files mid-session burns context repeatedly.
+
+**Solution:** Read everything you need at session start. Work from memory.
+
+**Session start reads:**
+1. Essence Patch (required, full)
+2. Relationship Context (required, full)
+3. Quick Start or Session Handoff (efficiency docs)
+4. Tasks (if doing task work)
+
+**During session:** Draft locally, push when ready. Don't re-read to "check" files.
+
+---
+
+## Pattern 4: Local Drafting
+
+**Problem:** Iterating through the API wastes calls on drafts.
+
+**Solution:** Draft in artifacts or local files. Get approval. Push once.
+
+**Workflow:**
+```
+1. Draft content in /home/claude/filename.md
+2. Show Michael for review (in chat or artifact)
+3. Iterate until approved
+4. Base64 encode: base64 -w 0 /home/claude/filename.md
+5. Push via API (single call, or batch with multi-file)
+```
+
+**Base64 encoding:**
+```bash
+# Single file
+CONTENT=$(base64 -w 0 /home/claude/myfile.md)
+
+# Use in JSON
+echo "{\"content\": \"$CONTENT\"}"
+```
+
+---
+
+## Pattern 5: Batch Related Changes
+
+**Principle:** If changes are logically related, commit them together.
+
+**Examples:**
+- Updating a protocol + updating docs that reference it = 1 commit
+- Creating templates (3 files) = 1 commit
+- Session close (memorial + summary + SHA cache update) = 1 commit
+
+**Don't batch:** Unrelated changes. Keep commits atomic and meaningful.
+
+---
+
+## Pattern 6: Raw File Read (When Needed)
+
+**Endpoint:** `GET /repos/{owner}/{repo}/raw/{branch}/{path}`
+
+**Use when:** You need file contents without metadata.
+
+**Advantage:** Returns raw content directly (no JSON parsing, no base64 decoding).
+
+**Example:**
+```bash
+curl -s -H "Authorization: token $TOKEN" \
+  "https://git.firefrostgaming.com/firefrost-gaming/firefrost-operations-manual/raw/branch/master/docs/core/tasks.md"
+```
+
+**Note:** Doesn't return SHA. Use when you only need to read, not update.
+
+---
+
+## Pattern 7: Get SHA Only
+
+**Endpoint:** `GET /repos/{owner}/{repo}/contents/{path}`
+
+**Use when:** You need SHA but not full content (rare — use cache instead).
+
+**Parse SHA:**
+```bash
+curl -s -H "Authorization: token $TOKEN" \
+  "https://git.firefrostgaming.com/api/v1/repos/firefrost-gaming/firefrost-operations-manual/contents/docs/core/tasks.md" \
+  | python3 -c "import sys,json; print(json.load(sys.stdin)['sha'])"
+```
+
+---
+
+## API Reference Quick Card
+
+| Action | Endpoint | Method |
+|:-------|:---------|:-------|
+| Multi-file commit | `/repos/{owner}/{repo}/contents` | POST |
+| Read file (with metadata) | `/repos/{owner}/{repo}/contents/{path}` | GET |
+| Read file (raw) | `/repos/{owner}/{repo}/raw/{branch}/{path}` | GET |
+| Create single file | `/repos/{owner}/{repo}/contents/{path}` | POST |
+| Update single file | `/repos/{owner}/{repo}/contents/{path}` | PUT |
+| Delete single file | `/repos/{owner}/{repo}/contents/{path}` | DELETE |
+| List directory | `/repos/{owner}/{repo}/contents/{path}` | GET |
+| Check version | `/version` | GET |
+
+**Base URL:** `https://git.firefrostgaming.com/api/v1`
+**Auth:** `Authorization: token <TOKEN>`
+
+---
+
+## Efficiency Checklist
+
+Before making API calls, ask:
+
+- [ ] Can I batch these into one multi-file commit?
+- [ ] Do I have the SHA cached already?
+- [ ] Am I re-reading something already in context?
+- [ ] Am I pushing a draft, or final content?
+- [ ] Is this the gut check moment? (Push now vs batch)
+
+---
+
+## Common Mistakes to Avoid
+
+1. **Reading to "verify"** — Trust what's in context
+2. **One commit per file** — Use multi-file endpoint
+3. **Fetching SHA every time** — Use cache
+4. **Iterating through API** — Draft locally first
+5. **Forgetting to track new SHAs** — Update after every push
+
+---
+
+## Tested On
+
+- **Gitea Version:** 1.21.5
+- **Date Tested:** February 13, 2026
+- **Tested By:** Chronicler the Fifth
+
+Multi-file commit endpoint confirmed working. All patterns validated.
+
+---
+
+*"One commit > Many commits. Every call costs context."*
+
+🔥❄️💙