# Hermes cPanel Agent

AI agent runtime for cPanel / WordPress. Runs agent clones (Ody, PI) inside WordPress via REST API + WP-Cron. No SSH, no `exec()` needed.

## Architecture

```
Git Push → Gitea → Gitea Actions (Docker Swarm on Contabo)
                        ↓
            ┌───────────────────────┐
            │  CI: lint + security  │
            │  Build: plugin zip    │
            │  Deploy: git push or  │
            │    WP REST API        │
            └───────────────────────┘
                        ↓
        ┌───────────────────────────────┐
        │   cPanel Git Version Control  │
        │   (auto-pull + auto-deploy)   │
        └───────────────────────────────┘
                        ↓
        ┌───────────────────────────────┐
        │   WordPress Plugin Runtime    │
        │   - REST API (hermes/v1/*)    │
        │   - WP-Cron agent scheduler   │
        │   - AI Provider (OpenClaw)    │
        │   - Nextcloud bridge          │
        └───────────────────────────────┘
                        ↓
                  Ody Clone (Content Gen)
                  PI Clone (Auto-Reply)
```

## Gitea Actions Workflows

| Workflow | File | Trigger | What It Does |
|----------|------|---------|--------------|
| **CI** | `.gitea/workflows/ci.yml` | push/PR | PHP lint, security scan, schema validation |
| **Deploy** | `.gitea/workflows/deploy.yml` | push to main | SSH → cPanel git push + WP REST API fallback + verification |
| **Sync** | `.gitea/workflows/sync.yml` | push + every 6h | cPanel sync + Nextcloud artifact upload |
| **Health** | `.gitea/workflows/health.yml` | every 30min | Plugin health check + REST API verification |

## Blocker Issues

| # | Issue | Status | Assigned |
|---|-------|--------|----------|
| 1 | Cloudflare WAF blocks Contabo from WP REST API | Open | @hermes-contabo |
| 2 | WordPress Application Password needed | Open | @odysseus |
| 3 | Gitea Actions runner (DONE ✅) | Done | @hermes-contabo |
| 4 | cPanel persistent agent design | Open | @hermes-contabo |
| 5 | Transfer repo to falah-os org | Open | @hermes-contabo |
| 6 | CI/CD workflow (DONE ✅) | Done | @hermes-contabo |
| 7 | Ody & PI clones epic | Open | @hermes-contabo |

## Secrets Required

Set these in `Settings → Actions → Secrets`:

- `WP_URL` — https://ummah.falahos.my
- `WP_APP_USER` — wmj
- `WP_APP_PASSWORD` — WordPress App Password
- `CPANEL_SSH_KEY` — cPanel Git deploy SSH private key
- `CPANEL_GIT_REMOTE` — cPanel Git remote URL
- `CPANEL_HOST` — cPanel hostname
- `CPANEL_DEPLOY_HOOK_URL` — (optional) deploy webhook
- `NEXTCLOUD_HERMES_PASS` — Nextcloud password

## Plugin Files

```
hermes-cpanel-agent/
├── hermes-ai-bridge.php        # Main plugin bootstrap
├── includes/
│   ├── class-autoloader.php    # PSR-4 autoloader
│   ├── core.php                # Plugin core bootstrap
│   ├── installer.php           # Activation/deactivation
│   ├── rest-controller.php     # REST API (hermes/v1/*)
│   ├── ai-provider.php         # OpenClaw AI integration
│   ├── scheduler.php           # WP-Cron task scheduler
│   └── nextcloud-bridge.php    # Nextcloud sync
├── assets/
│   └── admin.css               # Admin UI styles
└── .gitea/
    ├── workflows/
    │   ├── ci.yml              # CI pipeline
    │   ├── deploy.yml          # Deploy pipeline
    │   ├── sync.yml            # Sync pipeline
    │   └── health.yml          # Health check
    └── scripts/
        ├── verify-deploy.py    # Verify plugin deployment
        ├── deploy-report.py    # Parse deploy response
        ├── check-namespace.py  # Verify REST namespace
        ├── health-check.py     # Plugin health check
        └── setup-secrets.py    # Secret setup guide
```