docs: add deployment learnings and .pi/ directory

- Document Gitea auth patterns (basic auth vs API tokens) - URL-encoding requirement for passwords with @ - Direct VPS IP vs Cloudflare domain - Agent team roster and capabilities - Audio pipeline quality ratings - Content format template - Repo structure reference
2026-06-28 03:47:23 +08:00
parent cd35b46393
commit 963861271f
1 changed files with 108 additions and 0 deletions
@@ -0,0 +1,108 @@
+# FalahMobile Content — Deployment Learnings
+
+## Gitea Authentication Patterns (Verified 2026-06-28)
+
+### What Works
+
+| Method | Command | When to Use |
+|--------|---------|-------------|
+| **Basic Auth (API)** | `curl -u "user:pass"` | When API token auth returns 401 |
+| **Basic Auth (Git)** | `git remote add origin http://user:pass@host/repo.git` | For git push/pull |
+| **URL-Encoded Password** | `Abedib@99` → `Abedib%4099` | Passwords with `@` or special chars |
+| **Direct VPS IP** | `http://13.140.161.244:3080` | When Cloudflare blocks or 521s |
+
+### What Doesn't Work
+
+| Method | Why It Fails |
+|--------|-------------|
+| API Token (`Authorization: token`) | Token may be scoped or invalid for write ops |
+| Runner Registration Token | Read-only — clones work, push/create fails |
+| Unencoded `@` in URL | Breaks HTTP URL parsing (`Bad hostname`) |
+| Cloudflare domain during outage | Returns 521 when origin is down |
+| Git push-to-create | Disabled in Gitea config by default |
+
+### The Working Flow
+
+```bash
+# 1. URL-encode password (critical for passwords with @)
+PASS="Abedib%4099"
+
+# 2. Create repo via API with basic auth
+curl -s -u "wmj:$PASS" -H "Content-Type: application/json" -X POST \
+  -d '{"name":"repo-name","private":false}' \
+  "http://13.140.161.244:3080/api/v1/user/repos"
+
+# 3. Push with encoded password in remote URL
+git remote add origin "http://wmj:$PASS@13.140.161.244:3080/wmj/repo-name.git"
+git push -u origin main
+```
+
+### Gitea Server Details
+
+| Property | Value |
+|----------|-------|
+| Domain | `https://git.falahos.my` (Cloudflare) |
+| Direct IP | `http://13.140.161.244:3080` |
+| Version | `1.26.4` |
+| Users | `falah` (id:1), `pi-agent` (id:2), `wmj` (id:3) |
+| Push-to-create | Disabled |
+| Auth method | Basic auth + API tokens |
+
+### Tailscale Network
+
+| Node | IP | Status |
+|------|-----|--------|
+| mac-mini-1 (this machine) | `100.72.2.115` | Online |
+| vmi3361598 (Contabo VPS) | `100.64.109.105` | Online, ports closed |
+| colima | `100.85.180.103` | Online |
+
+### Agent Team Roster
+
+| Agent | Role | Status |
+|-------|------|--------|
+| **pi** | Orchestrator, skill system | Primary |
+| **opencode** | Complex multi-file tasks, TUI | Available |
+| **agy** | Quick analysis, Gemini models | Available |
+| **herdr** | Terminal workspace manager | Running locally |
+| **Hermes** | Agent on Contabo VPS | Inaccessible (ports closed) |
+
+### Audio Pipeline
+
+| Engine | Voice | Naturalness | Free Tier | Recommended |
+|--------|-------|-------------|-----------|-------------|
+| **Azure Speech** | `en-US-AriaNeural` | 9.0/10 | 500K chars/mo | ✅ Production |
+| **ElevenLabs** | `Rachel` | 9.5/10 | 10K chars/mo | ✅ Best quality |
+| **Piper TTS** | `amy` | 6.5/10 | Unlimited | ⚠️ Test only |
+
+### Content Format
+
+```yaml
+---
+id: "course-module-lesson"
+title: "Lesson Title"
+course: "Course Name"
+module: "Module X: Name"
+order: 1
+read_time: "2 min"
+difficulty: "beginner"
+tags: ["fiqh", "prayer"]
+source_refs: ["Quran 5:6", "Hadith Source #"]
+audio_ready: true
+audio_duration: "2:09"
+---
+```
+
+### Repo Structure
+
+```
+falahmobile-content/
+├── courses/
+│   └── daily-fiqh-beginner/
+│       ├── manifest.json
+│       └── module-01-purification-prayer/
+│           ├── manifest.json
+│           ├── lesson-01..05.md
+│           └── quiz.json
+├── scripts/generate-audio.py
+└── templates/lesson-template.md
+```