Add emergency Git access guide - prevents future session start debugging
This commit is contained in:
237
docs/core/EMERGENCY-GIT-ACCESS.md
Normal file
237
docs/core/EMERGENCY-GIT-ACCESS.md
Normal file
@@ -0,0 +1,237 @@
|
||||
# 🚨 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."*
|
||||
|
||||
🚨🔧💙
|
||||
Reference in New Issue
Block a user