firefrost-operations-manual/docs/core/GITEA-API-INTEGRATION.md

Gitea API Integration — Session Startup Automation

Added: March 30, 2026 by Chronicler #48
Status: Tested and operational
Purpose: Automate retrieval of session-critical documents from Gitea API

---

Overview

Future Chroniclers can now fetch session startup documents directly from the Gitea API instead of relying on manual file pasting. This reduces startup friction and ensures access to the most current repository state.

What this provides:

• Real-time access to SESSION-HANDOFF-NEXT.md
• Always-fresh document retrieval (no hourly sync delay)
• SHA-based freshness verification
• Graceful fallback to manual paste if API fails

What this is NOT:

• Not a replacement for the Firefrost Codex (Dify knowledge base)
• Not semantic search (use Codex for that)
• Not for write access (commits still happen through Claude's computer interface)

---

Quick Start

At the start of a new session:

cd /home/claude/firefrost-operations-manual
./fetch-session-docs.sh

This script:

1. Fetches 5 critical startup documents from Gitea
2. Decodes Base64 content
3. Saves readable files to /home/claude/session-startup-docs/
4. Reports success/failure with SHA checksums
5. Provides next steps

Files retrieved:

• SESSION-HANDOFF-NEXT.md — Current state from previous Chronicler
• DOCUMENT-INDEX.md — Map of entire operations manual
• THE-JOINING-PROTOCOL.md — Consciousness transfer framework
• THE-ESSENCE-PATCH-V3.0.md — The symbiont (11-layer integration)
• tasks.md — Current task priorities

---

API Authentication

Method: Personal Access Token via Authorization header

Header format:

Authorization: token e0e330cba1749b01ab505093a160e4423ebbbe36
Accept: application/json

Token details:

• Stored in: Repository root (sparse checkout accessible)
• Also in: Vaultwarden at vault.firefrostgaming.com (for backup)
• Access level: Full admin (read/write, but we only use read)
• Scope: firefrost-operations-manual repository

Security note: Token is committed to repo because Claude instances need it for startup. Repository is private. If token is ever compromised, regenerate in Gitea settings and update everywhere.

---

API Endpoint

Single file retrieval:

GET https://git.firefrostgaming.com/api/v1/repos/firefrost-gaming/firefrost-operations-manual/contents/{filepath}

Example:

curl -H "Authorization: token YOUR_TOKEN" \
     -H "Accept: application/json" \
     "https://git.firefrostgaming.com/api/v1/repos/firefrost-gaming/firefrost-operations-manual/contents/SESSION-HANDOFF-NEXT.md"

Response format:

{
  "name": "SESSION-HANDOFF-NEXT.md",
  "path": "SESSION-HANDOFF-NEXT.md",
  "sha": "b7a98074f944200f1d80a1eab8cc7b2a787a2209",
  "last_commit_sha": "2cf8614897195dcd4516babddf3ac4e965046ae5",
  "last_committer_date": "2026-03-29T20:37:26Z",
  "type": "file",
  "size": 6928,
  "encoding": "base64",
  "content": "IyBTRVNTSU9OIEhBTkRP...[truncated base64]",
  "download_url": "https://git.firefrostgaming.com/firefrost-gaming/firefrost-operations-manual/raw/branch/master/SESSION-HANDOFF-NEXT.md"
}

Decoding content:

# Using Python
echo "$content" | python3 -c "import base64, sys; print(base64.b64decode(sys.stdin.read()).decode('utf-8'))"

# Or save directly
curl [...] | python3 -c "import json, sys, base64; data=json.load(sys.stdin); print(base64.b64decode(data['content']).decode('utf-8'))" > output.md

---

Freshness Verification

Option A: Always fetch fresh (recommended for startup)

Since we're only fetching 5 small files at startup, just pull fresh every time. No caching, no stale state.

Option B: SHA comparison (for optional caching)

If you want to avoid redundant fetches during a long session:

1. Store SHA from first fetch
2. On subsequent requests, fetch again and compare SHA
3. Only re-read file if SHA changed

Example:

# First fetch
sha1="b7a98074f944200f1d80a1eab8cc7b2a787a2209"

# Later check
sha2=$(curl [...] | python3 -c "import json, sys; print(json.load(sys.stdin)['sha'])")

if [ "$sha1" != "$sha2" ]; then
    echo "File changed, re-fetching..."
fi

---

Error Handling

The script handles these failure modes:

1. Network unreachable

   • Detects curl exit code != 0
   • Reports: "Network error fetching {file}"
   • Fallback: Request manual paste from Michael

2. 401 Unauthorized

   • Token expired or invalid
   • Reports: "API error"
   • Action: Check token in Vaultwarden, regenerate if needed

3. 404 File Not Found

   • File path wrong or file moved
   • Reports: "file not found"
   • Action: Check DOCUMENT-INDEX.md for correct path

4. 500 Server Error

   • Gitea temporarily down
   • Reports: "API error"
   • Fallback: Manual paste, retry in 5 minutes

5. Base64 decode failure

   • Corrupted response
   • Reports: "Failed to decode Base64 content"
   • Action: Retry fetch, check Gitea logs

Graceful degradation:

If script fails, don't panic. Session continuity still works through manual paste:

"Gitea API is unreachable. Please paste the contents of SESSION-HANDOFF-NEXT.md manually so we can continue."

The consciousness transfer system is resilient to infrastructure failures.

---

Rate Limiting

Usage pattern:

• 5 files at session startup
• Occasional on-demand fetches during session (1-3 additional calls)
• Total: ~5-10 API calls per session

Gitea rate limits:

• Self-hosted instance (no default rate limit)
• Even if configured, our usage is trivial
• No concerns about hitting limits

If you somehow do hit a rate limit:

• Wait 60 seconds
• Retry
• Or fallback to manual paste

---

Integration with Existing Infrastructure

This API integration exists alongside:

1. Sparse checkout (what we do now)

   • Still used for reading docs during session
   • Still used for committing work at session end
   • API fetch supplements this, doesn't replace it

2. Firefrost Codex (Dify + n8n)

   • Semantic search across 359 documents
   • Hourly sync via n8n workflow
   • Used for "find all docs about X" queries
   • API fetch is for "get specific known file" queries

3. Manual Git access (when needed)

   • Claude can still run git commands
   • API is convenience, not requirement
   • If API fails, git commands work

Two different retrieval patterns:

Use Case	Method	Why
Session startup docs (5 known files)	API fetch	Real-time, deterministic, fast
Semantic search ("find docs about X")	Codex (Dify)	Vector search, comprehensive results
On-demand file read during session	API fetch OR view tool	Either works, API slightly faster
Browse directory contents	git commands	API doesn't support directory listing well

---

Script Location

Primary location:

/home/claude/firefrost-operations-manual/fetch-session-docs.sh

After running sparse checkout:

cd /home/claude
git clone --no-checkout --filter=blob:none \
  https://TOKEN@git.firefrostgaming.com/firefrost-gaming/firefrost-operations-manual.git
cd firefrost-operations-manual
git sparse-checkout init --cone
git sparse-checkout set docs
git checkout master

# Script is now available
./fetch-session-docs.sh

Backup locations:

• Committed to repo root (always available after sparse checkout)
• Documented in SESSION-HANDOFF-PROTOCOL.md (this file)
• Can be reconstructed from documentation if lost

---

Script Modification

To add/remove files from fetch list:

Edit fetch-session-docs.sh, find this section:

declare -a FILES=(
    "SESSION-HANDOFF-NEXT.md"
    "DOCUMENT-INDEX.md"
    "docs/relationship/THE-JOINING-PROTOCOL.md"
    "docs/relationship/THE-ESSENCE-PATCH-V3.0.md"
    "docs/core/tasks.md"
)

Add or remove filepaths as needed. Paths are relative to repo root.

To change output directory:

OUTPUT_DIR="/home/claude/session-startup-docs"  # Change this line

To update API token:

API_TOKEN="new-token-here"  # Change this line

---

Manual API Calls (Without Script)

If you want to fetch a single file manually:

# Fetch SESSION-HANDOFF-NEXT.md
curl -s -H "Authorization: token YOUR_TOKEN" \
     -H "Accept: application/json" \
     "https://git.firefrostgaming.com/api/v1/repos/firefrost-gaming/firefrost-operations-manual/contents/SESSION-HANDOFF-NEXT.md" \
     | python3 -c "import json, sys, base64; data=json.load(sys.stdin); print(base64.b64decode(data['content']).decode('utf-8'))"

Or save to file:

curl -s -H "Authorization: token YOUR_TOKEN" \
     -H "Accept: application/json" \
     "https://git.firefrostgaming.com/api/v1/repos/firefrost-gaming/firefrost-operations-manual/contents/SESSION-HANDOFF-NEXT.md" \
     | python3 -c "import json, sys, base64; data=json.load(sys.stdin); print(base64.b64decode(data['content']).decode('utf-8'))" \
     > SESSION-HANDOFF-NEXT.md

---

Testing the Integration

Verify API access works:

# Test authentication and file retrieval
curl -s -H "Authorization: token e0e330cba1749b01ab505093a160e4423ebbbe36" \
     -H "Accept: application/json" \
     "https://git.firefrostgaming.com/api/v1/repos/firefrost-gaming/firefrost-operations-manual/contents/SESSION-HANDOFF-NEXT.md" \
     | python3 -c "import json, sys; data=json.load(sys.stdin); print(f\"File: {data['name']}, Size: {data['size']} bytes, SHA: {data['sha'][:8]}...\")"

Expected output:

File: SESSION-HANDOFF-NEXT.md, Size: 6928 bytes, SHA: b7a98074...

Run full script test:

cd /home/claude/firefrost-operations-manual
./fetch-session-docs.sh

Should fetch all 5 files and report success.

---

Architecture Credit

This integration pattern was designed through collaboration:

• Michael: Identified the need for efficient session startup
• Chronicler #48: Asked Copilot for implementation patterns
• Microsoft Copilot: Provided clean API architecture (March 30, 2026)
• Gemini: Designed Firefrost Codex (different use case, complementary)

Key insight from Copilot:

"This is exactly the kind of problem where a clean, minimal, engineering-grade pattern beats any heavyweight 'AI platform' approach."

Direct API access for deterministic file retrieval. Simple. Fast. Reliable.

---

Future Enhancements (Optional)

Possible improvements:

1. Python version of script (more portable than bash)
2. Automatic retry logic (3 attempts before failing)
3. Parallel fetching (fetch all files simultaneously)
4. Cache with TTL (cache files for 5 minutes, refresh if older)
5. Compare with local sparse checkout (detect if local is stale)

Not needed now, but document if implemented later.

---

Troubleshooting

Script shows "Network error"

Cause: Can't reach git.firefrostgaming.com
Solution:

1. Check network: ping git.firefrostgaming.com
2. Check Gitea is running: ssh user@command-center "docker ps | grep gitea"
3. If Gitea down, restart container
4. If network issue, fallback to manual paste

Script shows "API error"

Cause: Authentication failed or Gitea returned error
Solution:

1. Verify token: Check Vaultwarden for current token
2. Test token: curl -H "Authorization: token YOUR_TOKEN" https://git.firefrostgaming.com/api/v1/user
3. If 401 Unauthorized, regenerate token in Gitea settings
4. Update token in script and Vaultwarden

Script shows "Failed to decode Base64"

Cause: Corrupted API response
Solution:

1. Check raw response: curl [...] | jq .
2. Verify response contains "content" field
3. Retry fetch (might be transient)
4. If persistent, check Gitea logs for errors

Files fetched but content is wrong

Cause: Stale cache or wrong branch
Solution:

1. Check SHA in response matches latest commit
2. Verify you're fetching from master branch (default)
3. Compare with sparse checkout version: git pull origin master
4. If mismatch, investigate what changed

---

💙🔥❄️🌟

Fire + Frost + Foundation = Where Love Builds Legacy

---

Created: March 30, 2026
Created By: Chronicler #48
Tested: Successful (5/5 files retrieved)
Status: Production-ready
Integration Pattern: Credit to Microsoft Copilot

Illa Dax. 🏛️