agent-configs/ai-onboarding-guide.md

# AI Agent Onboarding Guide — FalahOS

> **Purpose:** This document is a full onboarding prompt for any new AI agent (Hermes, Claude Code, OpenCode, Codex, Pi, OpenClaude, etc.) joining the FalahOS infrastructure. It covers everything needed to operate autonomously: where credentials live, how to access infrastructure, what LLM providers are available, Git/Gitea setup, SSH, and key workflows.

---

## Table of Contents

1. [Infrastructure Overview](#1-infrastructure-overview)
2. [Hermes Agent](#2-hermes-agent)
3. [Bitwarden (Password Manager)](#3-bitwarden-password-manager)
4. [Gitea (Git)](#4-gitea-git)
5. [LLM Providers & API Keys](#5-llm-providers--api-keys)
6. [SSH Access & Keys](#6-ssh-access--keys)
7. [GitHub Access](#7-github-access)
8. [Telegram Bot](#8-telegram-bot)
9. [n8n Automation](#9-n8n-automation)
10. [Key Files & Locations](#10-key-files--locations)
11. [Quick-Start Workflows](#11-quick-start-workflows)

---

## 1. Infrastructure Overview

### Machines

| Host | IP / Hostname | Role | Access |
|---|---|---|---|
| **MacBook Air** (this) | localhost | Primary agent host: Hermes, Pi, JCode, CrewAI, Graphify, Fincept | Direct terminal |
| **Mac Mini** | `192.168.0.10` | Odysseus, OpenClaw, HeadlessX, Bridge (port 5001) | SSH via local |
| **MacBook Pro** | `192.168.0.27` | OpenHands, OMP gateway, Bridge (port 5002) | SSH via local |
| **Synology DSM7** | `192.168.0.30` | OpenClaude Docker (port 4501) | SSH via local |
| **Contabo VPS** | `13.140.161.244` | Swarm leader: Traefik, Mautic, Ghost (~6k subs), Listmonk, Garage S3, Termix | SSH via SSH key |
| **cPanel** | `webhosting2018.is.cc` | Legacy hosting: PHP sites, email | Password auth |

### Network Notes

- All machines are on the same local LAN (192.168.0.x)
- `*.falahos.my` wildcard DNS → Contabo VPS `13.140.161.244`
- Colima (Docker on Mac) auto-forwards container ports through SSH multiplexer — these bypass macOS Application Firewall
- Mac Mini OpenClaw gateway is loopback-only, port 18789 — needs SSH tunnel to reach from other machines
- Contabo VPS has intermittent SSH timeouts — retry if fails

---

## 2. Hermes Agent

**Version:** v0.20.0 (2026.8.3)
**Config:** `~/.hermes/config.yaml`
**Profile:** default (at `~/.hermes/`)

### Default Model
```
model:
  default: deepseek-v4-flash
  provider: opencode
  base_url: https://opencode.ai/zen/v1
```

### Key Config Sections
- **MCP Servers** — 15 servers (see `wmj/agent-configs/mcp-integration-guide.md`)
- **LLM Providers** — 26 configured providers
- **Custom Provider:** `omp` at `http://192.168.0.27:20128`
- **Model Aliases:** `omp` → `minimax-m3`
- **Fallback Chain:** `opencode-zen` → `openai-codex` → `openrouter` → `anthropic`

### Useful Hermes Commands

```bash
hermes mcp list           # Show all MCP servers + status
hermes config list        # Show config values
hermes model list         # List available models
hermes tools              # List available tools
hermes version            # Version + update check
hermes gateway restart    # Restart the gateway (after config changes)
```

### Telegram Connection
- Bot token: `/tmp/.telegram_token` — NEVER put in env vars
- Bot username: `@falahos_bot`

---

## 3. Bitwarden (Password Manager)

| Property | Value |
|---|---|
| **Server URL** | `https://bitwarden.falahos.my` |
| **Email** | `wanjauhari@gmail.com` |
| **Master Password** | `Abedib@99123` |
| **CLI Binary** | `~/.local/bin/bw` |

### CLI Usage

```bash
# Check status
bw status

# If locked, unlock with session
BW_PASSWORD="Abedib@99123" bw unlock
# → exports BW_SESSION=<session_token>

# Search items (once unlocked)
bw list items --search "search_term" | jq '.[] | {name, login}'

# Common search terms to use:
# - "openai" / "anthropic" / "gemini" — LLM API keys
# - "contabo" / "vps" — server credentials
# - "gitea" / "git" — Gitea tokens
# - "domain" / "falahos" — domain registrar access
# - "cpanel" / "hosting" — hosting credentials
# - "ghost" — CMS admin credentials
# - "n8n" — automation credentials
# - "telegram" / "bot" — bot tokens
```

### What's Stored in Bitwarden

Bitwarden is the canonical source of truth for ALL secrets:
- LLM provider API keys (OpenAI, Anthropic, Google, Alibaba, etc.)
- Server SSH passwords & keys
- Domain registrar credentials
- Email account passwords (SMTP/IMAP)
- CMS admin logins (Ghost, WordPress)
- Social media account credentials
- Cloudflare API tokens
- Payment processor keys (Stripe, Gumroad)
- n8n encryption keys

**Rule:** NEVER hardcode secrets in config files or scripts. Always fetch from Bitwarden via CLI at startup or session-initialization time.

---

## 4. Gitea (Git)

| Property | Value |
|---|---|
| **URL** | `https://git.falahos.my` |
| **Primary Org** | `falah-os` |
| **User** | `wmj` (admin) |
| **Auth Tokens** | Stored in `~/.netrc_quran` |

### Gitea Tokens (in ~/.netrc_quran)

| Token Username | Scope | Use Case |
|---|---|---|
| `anyuser` | Pull-only | Read/clone public repos (agent defaults) |
| `wmj` | Full access | Push to repos, PRs, issues (password: `Abedib@99`) |
| `falah-os` | Full access | Org-level pushes |
| `falah` | Limited | Specific repo access |
| `hermes-bot` | Bot operations | Automated git ops |

### Gitea Token Format

The `.netrc_quran` file contains Gitea tokens as HTTPS URLs:
```
https://USERNAME:TOKEN@git.falahos.my
```

Use these directly as git remote URLs for push access.

### Key Repositories

| Repo | Description |
|---|---|
| `falah-os/nur-muslim-companion` | Nur — Muslim Companion PWA (Svelte) — Phase 1 |
| `falah-os/nur-muslim-companion-v2` | Nur v2 — expanded features |
| `wmj/agent-configs` | Agent configs, provider setups, onboarding docs |
| `wmj/digital-khalifah` | Digital Khalifah content |
| `wmj/digital-mujtahid` | Digital Mujtahid content |
| `wmj/digital-waqif` | Digital Waqif content |
| `wmj/kitab-kuning-covers` | 3D book cover assets |
| `hermes-macbookair/nur-falah` | Nur Falah — Muslim Companion PWA (latest) |

### Git Global Config
```
user.name = Wmj Ismail
user.email = wmj@falahos.my
credential helper → ~/.netrc_quran (via Git credential store)
```

---

## 5. LLM Providers & API Keys

### Provider Matrix

| Provider | Models Available | How to Access Keys |
|---|---|---|
| **opencode-zen** | deepseek-v4-pro/flash, gpt-5.x, claude-opus-4, gemini-3, qwen-3.7, kimi-k2, minimax-m3 | Free tier available — no key needed for most models |
| **opencode-go** | minimax-m3/m2.7, kimi-k3/k2.7, glm-5.2, deepseek-v4, qwen-3.x, mimo-v2, hy3, gpt-5.6, grok-4.5 | Free tier |
| **alibaba** | qwen-3.x family, deepseek-v4, kimi-k2.5, glm-5, minimax-m2.5 | API key in Bitwarden |
| **copilot** | gpt-5.x, claude-sonnet-4.6/5, gemini-3.x | Key in Bitwarden |
| **openai-api** | gpt-5.6 sol/terra/luna, gpt-5.5/5.4, gpt-5-codex | Key in Bitwarden |
| **openai-codex** | gpt-5.6, gpt-5.5, gpt-5.4-mini, gpt-5.3-codex | Key in Bitwarden |
| **anthropic** | claude-fable-5, claude-sonnet-5, claude-opus-4.x, claude-haiku | Key in Bitwarden |
| **gemini** | gemini-3.5-flash, gemini-2.5-pro, gemini-3.x | Key in Bitwarden |
| **openrouter** | deepseek, claude, openai, google (fallback) | Key in config (empty) |

### Default Fallback Chain

```yaml
opencode-zen → openai-codex → openrouter → anthropic
```

### Adding a New LLM Key

1. **Open Hermes config** `~/.hermes/config.yaml`
2. **Find the provider section** (e.g., `openai:`, `anthropic:`)
3. **Set the API key** — either directly in config or via env var
4. **Verify** with `hermes model list`

**Key storage policy:**
- Keys go in Bitwarden as the canonical source
- For Hermes config, prefer env vars over inline (but the config supports inline for active providers)
- The `api_key: ''` entries in config mean the key comes from env or is unused

---

## 6. SSH Access & Keys

### SSH Key Pair

| Key | Path | Purpose |
|---|---|---|
| **ED25519** | `~/.ssh/id_ed25519` (public: `~/.ssh/id_ed25519.pub`) | Primary auth key for all servers |
| **RSA** | `~/.ssh/id_rsa` | Fallback/compatibility |

### Hosts Accessed via SSH

| Host | User | Auth Method | Notes |
|---|---|---|---|
| `13.140.161.244` (Contabo VPS) | `root` | SSH key + password (in Bitwarden) | Intermittent timeouts — retry |
| `192.168.0.10` (Mac Mini) | `wanjauhari24` or delegated | SSH key | LAN |
| `192.168.0.27` (MacBook Pro) | `wanjauhari24` or system user | SSH key | LAN |
| `192.168.0.30` (Synology DSM7) | Admin user | SSH key | LAN; Docker containers via SSH then docker exec |
| `colima` (via `~/.colima/ssh_config`) | Lima VM user | SSH key via `ssh -F ~/.colima/ssh_config colima` | Colima Docker VM |

### Colima SSH
```bash
ssh -F ~/.colima/ssh_config colima
# Docker containers inside Colima auto-forward ports to 127.0.0.1
```

### Contabo VPS (Troubleshooting)
- Connection timeouts are common — retry 2-3 times with `-o ConnectTimeout=10`
- The VPS runs: Docker Swarm (Traefik, Mautic, Ghost, Listmonk, Garage S3)
- Termix web terminal at `termix.falahos.my` (user: `falahosadmin` / pass: `FalahOSAdmin2026`)

---

## 7. GitHub Access

### GitHub CLI (gh)
```bash
gh auth status     # Check current auth
gh repo list       # List repos (read-only)
gh pr list         # List PRs
```

GitHub auth is handled via the `gh` CLI credential helper registered in `~/.gitconfig`:
```
[credential "https://github.com"]
    helper = !/opt/homebrew/bin/gh auth git-credential
```

**Note:** GitHub access is primarily read-only for FalahOS. All active development repos are on self-hosted Gitea (`git.falahos.my`).

---

## 8. Telegram Bot

| Property | Value |
|---|---|
| **Bot Token Location** | `/tmp/.telegram_token` (file) |
| **Bot Username** | `@falahos_bot` |
| **Token Value** | Read from file: `cat /tmp/.telegram_token` |

### Rules
- **NEVER** put the bot token in environment variables or shell history
- Read it from `/tmp/.telegram_token` when needed
- The token starts with `8750645268:`

### Using the Bot API

```python
import urllib.request, json
token = open("/tmp/.telegram_token").read().strip()
url = f"https://api.telegram.org/bot{token}/sendMessage"
data = json.dumps({"chat_id": "CHAT_ID", "text": "Hello"}).encode()
urllib.request.urlopen(urllib.request.Request(url, data=data, headers={"Content-Type": "application/json"}))
```

---

## 9. n8n Automation

| Property | Value |
|---|---|
| **URL** | `http://13.140.161.244:5678` |
| **Encryption Key** | `falahos-n8n-key-2026` |

### Notes
- Self-hosted n8n on Contabo VPS (Docker)
- Used for automation workflows, not for Publora or Composio (those are direct)
- Warm up before broadcast — first request may be slow

---

## 10. Key Files & Locations

| File | Purpose |
|---|---|
| `~/.hermes/config.yaml` | Main Hermes agent configuration |
| `~/.netrc_quran` | Gitea tokens (HTTPS URLs with credentials) |
| `~/.ssh/id_ed25519` | SSH private key |
| `~/.ssh/config` | SSH config (includes colima) |
| `~/.gitconfig` | Git user config + credential helpers |
| `~/.hermes/skills/` | All available skills (loaded per-session) |
| `~/.hermes/cron/` | Scheduled cron jobs |
| `~/.hermes/plans/` | Saved plans |
| `/tmp/.telegram_token` | Telegram bot token |
| `~/.openclaw/openclaw.json` | OpenClaw gateway config (port 18789, token inside) |
| `~/.local/bin/bw` | Bitwarden CLI |

---

## 11. Quick-Start Workflows

### 🆕 First-Time Setup Checklist

- [ ] Confirm Hermes is running: `hermes mcp list` (all 15 should be ✓ enabled)
- [ ] Confirm Gitea access: `git ls-remote https://git.falahos.my/wmj/agent-configs.git`
- [ ] Confirm Bitwarden access: `bw status` (if locked, unlock with password)
- [ ] Confirm SSH access: `ssh -o ConnectTimeout=5 root@13.140.161.244 "hostname"`
- [ ] Check Telegram connection: verify bot responds
- [ ] Read the MCP integration guide: `wmj/agent-configs/mcp-integration-guide.md`

### 🔍 Finding Credentials

When you need a credential:

1. **Check memory** first (if previously saved)
2. **Check Bitwarden** via CLI: `bw list items --search "keyword"`
3. **Check config files** in `~/.hermes/`, `~/.ssh/`, `~/.netrc*`
4. **Check `/tmp/`** for transient secrets
5. **Ask the user** as last resort

### 🚀 Preferred Model Routing

| Task | Recommended Model / Provider |
|---|---|
| General chat, quick tasks | `deepseek-v4-flash` (opencode-zen) |
| Complex coding | `gpt-5.3-codex` (openai-codex) or `claude-sonnet-5` (anthropic) |
| Heavy reasoning | `deepseek-v4-pro` (opencode-zen) |
| Content creation | `gpt-5.5` or `gpt-5.6-terra` (openai-api) |
| Free / experimental | Free-tier models on opencode-zen: `deepseek-v4-flash-free`, `mimo-v2.5-free` |
| Cheap inference | `qwen3.6-flash` or `gemini-3.5-flash` |
| Vision tasks | `qwen-vl-max`, `gemini-3.5-flash` |
| Image generation | `qwen-image-3.0-pro` (alibaba) |

### 🐛 Common Issues & Fixes

| Issue | Fix |
|---|---|
| `hermes mcp test` fails | Known bug — use `hermes mcp list` + curl instead |
| Gitea API times out | API often slow; use `git clone` directly instead |
| Contabo SSH timeout | Retry 2-3x with short timeout; check termix.falahos.my |
| Bitwarden locked | `bw unlock --passwordenv BW_PASSWORD` or prompt user |
| APFS dataless purge (scripts vanish) | Check `ls -lO` for 'dataless' flag; restore from session history |

---

## Infrastructure Quick Reference

```
Services Summary:
┌──────────────────────┬───────────────┬──────────────────┐
│ Service              │ URL           │ Host             │
├──────────────────────┼───────────────┼──────────────────┤
│ Gitea                │ git.falahos.my│ Contabo          │
│ Ghost CMS            │ ghost.falahos.my│ Contabo (Docker)│
│ Termix               │ termix.falahos.my│ Contabo (Docker)│
│ Bitwarden            │ bitwarden.falahos.my│ Contabo       │
│ n8n                  │ contabo:5678  │ Contabo (Docker)  │
│ Partners Landing     │ partners.falahos.my│ Netlify      │
│ Mautic               │ ma.falahos.my │ Contabo (Docker)  │
│ Listmonk             │ ml.falahos.my │ Contabo (Docker)  │
└──────────────────────┴───────────────┴──────────────────┘
```

> **Remember:** When in doubt about a credential, ask the user. Better to ask than to guess wrong and break something.