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:**

```bash
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:**
```bash
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:**
```json
{
  "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:**
```bash
# 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:**
```bash
# 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:**
```bash
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:

```bash
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:**

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

**To update API token:**

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

---

## Manual API Calls (Without Script)

**If you want to fetch a single file manually:**

```bash
# 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:**

```bash
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:**

```bash
# 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:**
```bash
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.** 🏛️