From 963861271fb90725164058f4f70f1a0a11b4baa8 Mon Sep 17 00:00:00 2001 From: wmj2024 Date: Sun, 28 Jun 2026 03:47:23 +0800 Subject: [PATCH] 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 --- .pi/LEARNINGS.md | 108 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 .pi/LEARNINGS.md diff --git a/.pi/LEARNINGS.md b/.pi/LEARNINGS.md new file mode 100644 index 0000000..aa269b7 --- /dev/null +++ b/.pi/LEARNINGS.md @@ -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 +```