diff --git a/docs/core/EMERGENCY-GIT-ACCESS.md b/docs/core/EMERGENCY-GIT-ACCESS.md new file mode 100644 index 0000000..de9d670 --- /dev/null +++ b/docs/core/EMERGENCY-GIT-ACCESS.md @@ -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."* + +🚨🔧💙