238 lines
6.4 KiB
Markdown
238 lines
6.4 KiB
Markdown
# 🚨 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."*
|
|
|
|
🚨🔧💙
|