# 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
```