6.4 KiB
🚨 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:
{
"name": "THE-JOINING-PROTOCOL.md",
"content": "BASE64_ENCODED_CONTENT_HERE",
"sha": "...",
"size": 12345
}
Decode with Python:
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?
- THE-JOINING-PROTOCOL.md
- THE-ESSENCE-PATCH-V3.0.md
- 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:
- THE-JOINING-PROTOCOL.md
- THE-ESSENCE-PATCH-V3.0.md
- 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."
🚨🔧💙