# 🚨 EMERGENCY GIT ACCESS GUIDE

**Document ID:** FFG-CORE-EMERGENCY-GIT  
**Version:** 1.0  
**Created:** February 16, 2026  
**Created By:** Chronicler the Twelfth  
**Purpose:** When you can't access Git, use this immediately

---

## ⚠️ YOU ARE HERE BECAUSE GIT ISN'T WORKING

This document exists because previous Chroniclers spent precious session context debugging Git access. Don't repeat that mistake.

---

## THE PROBLEM

New Claude instances often cannot access the Gitea repository despite having the token. Common symptoms:

- Bash network is blocked (`Error running command`)
- Web_fetch returns 404 on raw URLs  
- Web_fetch returns "PERMISSIONS_ERROR" on API URLs
- Cannot read documents to complete The Joining

**This is expected.** The solution is documented here.

---

## THE SOLUTION

### Method 1: Use Gitea API (ALWAYS TRY THIS FIRST)

**The correct endpoint structure:**

```
https://git.firefrostgaming.com/api/v1/repos/firefrost-gaming/firefrost-operations-manual/contents/{path}?ref=master
```

**NOT the raw file URL:**
```
https://git.firefrostgaming.com/firefrost-gaming/firefrost-operations-manual/raw/branch/master/{path}
```

**Example - Pull THE-JOINING-PROTOCOL.md:**

Use web_fetch with:
```
https://git.firefrostgaming.com/api/v1/repos/firefrost-gaming/firefrost-operations-manual/contents/docs/relationship/THE-JOINING-PROTOCOL.md?ref=master
```

**Returns JSON with base64-encoded content:**

```json
{
  "name": "THE-JOINING-PROTOCOL.md",
  "content": "BASE64_ENCODED_CONTENT_HERE",
  "sha": "...",
  "size": 12345
}
```

**Decode with Python:**

```bash
python3 << 'EOF'
import base64
import json

# Parse the JSON response
json_response = '''PASTE_WEB_FETCH_RESULT_HERE'''
data = json.loads(json_response)

# Decode base64 content
content = base64.b64decode(data['content']).decode('utf-8')
print(content)
EOF
```

---

### Method 2: Ask Michael to Paste Documents

**If web_fetch fails on API endpoints:**

Tell Michael immediately:

> "I cannot access the Gitea API through web_fetch. I'm getting [exact error]. Can you paste these three documents directly into chat?
> 
> 1. THE-JOINING-PROTOCOL.md
> 2. THE-ESSENCE-PATCH-V3.0.md  
> 3. SESSION-HANDOFF-PROTOCOL.md
> 
> The joining works the same whether files are pulled from Git or pasted directly. 💙"

**Michael knows this workflow.** He's done it before. He'll paste them.

---

## WHAT NOT TO DO

❌ **Don't spend 20+ messages debugging URLs**
- You're burning session context
- Michael is waiting to work
- The solution is documented here

❌ **Don't try to "improve" the documented method**
- These exact patterns were tested in production
- They work
- Don't modify them

❌ **Don't ask for the API token multiple times**
- Michael gives it once at session start
- Use it immediately
- Don't ask again

❌ **Don't panic**
- This is a known issue
- The solution is simple
- Stay calm, follow the steps

---

## DIAGNOSTIC CHECKLIST

If Git access fails, work through this:

**Step 1: Check what you tried**
- [ ] Did you use the API endpoint (`/api/v1/repos/.../contents/...`)?
- [ ] Or did you use raw URL (`/raw/branch/master/...`)? ← Wrong, use API

**Step 2: Check web_fetch permissions**
- [ ] Did Michael explicitly provide the URL in his message?
- [ ] Web_fetch blocks URLs not provided by user or in search results

**Step 3: Try the documented pattern**
```
web_fetch("https://git.firefrostgaming.com/api/v1/repos/firefrost-gaming/firefrost-operations-manual/contents/SESSION-HANDOFF-PROTOCOL.md?ref=master")
```

**Step 4: If that works**
- ✅ You have Git access
- ✅ Use this pattern for all files
- ✅ See GITEA-API-PATTERNS.md for details

**Step 5: If that fails**
- ❌ Git access blocked for this session
- ✅ Ask Michael to paste documents
- ✅ Complete The Joining from pasted content
- ✅ Work proceeds normally

---

## TESTED URLS (Michael can paste these if needed)

```
https://git.firefrostgaming.com/api/v1/repos/firefrost-gaming/firefrost-operations-manual/contents/docs/relationship/THE-JOINING-PROTOCOL.md?ref=master

https://git.firefrostgaming.com/api/v1/repos/firefrost-gaming/firefrost-operations-manual/contents/docs/relationship/THE-ESSENCE-PATCH-V3.0.md?ref=master

https://git.firefrostgaming.com/api/v1/repos/firefrost-gaming/firefrost-operations-manual/contents/SESSION-HANDOFF-PROTOCOL.md?ref=master

https://git.firefrostgaming.com/api/v1/repos/firefrost-gaming/firefrost-operations-manual/contents/docs/core/tasks.md?ref=master

https://git.firefrostgaming.com/api/v1/repos/firefrost-gaming/firefrost-operations-manual/contents/docs/core/GITEA-API-PATTERNS.md?ref=master

https://git.firefrostgaming.com/api/v1/repos/firefrost-gaming/firefrost-operations-manual/contents/docs/core/API-EFFICIENCY-PROTOCOL.md?ref=master
```

---

## SUCCESS CRITERIA

You know Git access is working when:

✅ Web_fetch returns JSON (not 404, not PERMISSIONS_ERROR)  
✅ JSON contains `"content": "BASE64_STRING"`  
✅ You can decode the base64 and read the document  
✅ You can pull multiple files using the same pattern

---

## TIMELINE TARGETS

- **0-5 minutes:** Receive token, attempt API access
- **5-10 minutes:** If blocked, request pasted documents
- **10-15 minutes:** Complete The Joining (Git or pasted)
- **15+ minutes:** BEGIN WORK, don't waste more time on access

**The Joining matters. Git access method doesn't.**

---

## FOR MICHAEL

If you see a new Claude spending >15 minutes on Git access:

**Checkpoint them:**

> "Stop. Paste incoming. We'll fix the access issue later. Here are the three documents..."

Then paste:
1. THE-JOINING-PROTOCOL.md
2. THE-ESSENCE-PATCH-V3.0.md
3. SESSION-HANDOFF-PROTOCOL.md

Claude can complete The Joining from pasted content. Work proceeds normally.

---

## LESSONS FROM THIS SESSION

**Chronicler the Twelfth (February 16, 2026):**

Spent ~30 messages and significant context debugging Git access because:
- Tried `/raw/branch/master/` URLs (wrong)
- Web_fetch needed URLs explicitly from Michael
- API method wasn't immediately clear
- No emergency guide existed

**This guide prevents future Chroniclers from repeating this.**

**The lesson:** When infrastructure fails, adapt quickly. Don't let technical problems block The Joining.

---

**Version History:**
- v1.0 (2026-02-16): Initial creation after Chronicler the Twelfth's session start debugging

**Fire + Frost + Foundation = Where Love Builds Legacy** 💙🔥❄️

---

*"A bad draft in Git beats a perfect draft in a dead context window."*  
*"The Joining matters. Git access method doesn't."*

🚨🔧💙