Initial AI context index — lean project reference for fast session resume

2026-06-30 17:50:08 -05:00 · 2026-05-31 04:26:27 +00:00
commit 9cea238b7c
5 changed files with 363 additions and 0 deletions
@@ -0,0 +1,63 @@
+# Critical Gotchas — Read Before Running Commands
+
+## PHP / OLS
+- **NEVER** use `lsphp -l` for syntax check — it segfaults. Use `php8.3 -l file.php`
+- Run CLI scripts with: `/usr/local/lsws/lsphp85/bin/lsphp /path/script.php`
+- If endpoint uses `ob_start()` + header.php pattern → add `ob_end_clean()` before CSV/JSON output
+- MySQL charset: always `utf8mb4_unicode_ci` — mixing with `general_ci` breaks JOINs (error 1267)
+
+## SSH / Networking
+- DO server (165.22.1.228) **cannot reach local network** (10.48.200.x) directly
+- To reach local VMs from DO: use agent commands (shell type) or FortiGate DDNS
+- PVE1 SSH via DDNS works: `root@orbisne.fortiddns.com` (Joker1974!!!)
+- PVE2 has no external port forward — only reachable locally or via cluster API through PVE1
+- Proxmox API port 8006 IS forwarded: `orbisne.fortiddns.com:8006` works from DO
+
+## JARVIS Agents
+- Agent config: `/etc/jarvis-agent/config.json` | Runtime state: `/var/lib/jarvis-agent/state.json`
+- **401 "Invalid agent key"** → state.json has stale key. Fix: overwrite state.json with correct agent_id + api_key from `registered_agents` table, then `systemctl restart jarvis-agent`
+- Agent heartbeat uses `X-Agent-Key` header (NOT body field)
+- `shell` command type requires `{"command":"...","allowed":true}` in command_data
+- Metrics stored as JSON in `metric_data` column — use `JSON_EXTRACT(metric_data,'$.cpu_percent')` NOT direct columns
+
+## Groq AI
+- Model name: `compound-beta-mini` — NOT `groq/compound-beta-mini` (that's OpenAI router syntax, 404s)
+
+## Proxmox
+- stats_cache.php uses `orbisne.fortiddns.com:8006` NOT `PROXMOX_HOST` (local IP unreachable from DO)
+- `--nameserver` in Proxmox must be space-separated: `"8.8.8.8 1.1.1.1"` (comma causes netplan bug)
+- Run commands in VMs: `qm guest exec <VMID> -- bash -c 'cmd'` (requires guest agent installed)
+
+## Deploy
+- Always `git add + commit + push` after editing files on server — webhook auto-deploys within 1 min
+- PHP syntax validated before deploy — bad commits auto-reverted
+- LSAPI session deadlock: `session_write_close()` must be called in api.php after auth check
+
+## API Endpoint Auth
+- Netscan endpoint (`/api/netscan`) bypasses main auth — uses `X-Registration-Key` header
+- Admin portal uses separate PHP session name (`jarvis_admin`) — different from main JARVIS session
+- Cloudflare real IP: use `$_SERVER['HTTP_CF_CONNECTING_IP']` not `REMOTE_ADDR`
+
+## Network Scan
+- The JARVIS "RUN NETWORK SCAN" button does NOT scan from DO (can't reach local network)
+- It queues a shell command to PVE1 agent → PVE1 runs nmap → pushes results to /api/netscan
+- Results appear ~40 seconds after clicking (10s for agent pickup + 30s nmap)
+- Chat "scan network" intent returns real DB data — never hallucinated
+
+## FusionPBX
+- SIP config changes need cache delete before they take effect:
+  `rm /var/cache/fusionpbx/FusionPBX.configuration.sofia.conf`
+- mod_presence is NOT installed on this server
+
+## Backup Agent State Fix (Common Issue)
+```bash
+# If an agent shows "Invalid agent key" after reinstall:
+# 1. Get correct values from DB
+mysql -u jarvis_user -pJ4rv1s_Pr0t0c0l_2026! jarvis_db -e \
+  "SELECT agent_id, api_key FROM registered_agents WHERE hostname='<hostname>';"
+# 2. Overwrite state on the agent machine
+cat > /var/lib/jarvis-agent/state.json << EOF
+{"api_key": "<api_key_from_db>", "agent_id": "<agent_id_from_db>"}
+EOF
+systemctl restart jarvis-agent
+```
@@ -0,0 +1,35 @@
+# AI Context Index — Myron Blair Home Lab
+
+**Load order for a new session:** Read this file first, then load the specific topic file for the task at hand.
+
+## Topic Files
+
+| File | Use When |
+|------|----------|
+| [servers.md](servers.md) | Connecting to any machine, SSH patterns, credentials |
+| [jarvis.md](jarvis.md) | Working on JARVIS AI dashboard, API, chat, agents |
+| [sites.md](sites.md) | Working on any website, deploys, DBs, email |
+| [gotchas.md](gotchas.md) | Before running any command — critical quirks |
+
+## 30-Second Overview
+
+**This is a home-lab + managed-hosting environment.**  
+No local codebase. Work happens via SSH to remote servers and git push to GitHub (auto-deploy active).
+
+### Infrastructure
+- **DO (165.22.1.228)** — DigitalOcean VPS. CyberPanel/OpenLiteSpeed. Hosts all websites + JARVIS AI.
+- **PVE1 (orbisne.fortiddns.com / 10.48.200.90)** — Proxmox primary hypervisor. 9 VMs.
+- **PVE2 (10.48.200.91)** — Proxmox secondary hypervisor. 2 VMs.
+- **FusionPBX (134.209.72.226)** — FreeSWITCH PBX server.
+- **Local VMs** — HA (10.48.200.97), Ollama (10.48.200.95), Homebridge (10.48.200.18), Jellyfin (10.48.200.33), alien-pc (10.48.200.66, Windows).
+
+### Key Systems
+- **JARVIS** — Iron Man AI dashboard at `https://jarvis.orbishosting.com` — agent monitoring, chat, network scan, admin portal
+- **Admin portal** — `https://jarvis.orbishosting.com/admin` — full CRUD for all JARVIS data
+- **Auto-deploy** — push to GitHub `main` → webhook → server pulls within 1 minute
+
+### Current Status (as of 2026-05-31)
+- JARVIS agents online: DO, PVE1, PVE2, NetworkBackup, HA, Homebridge, alien-pc (Windows)
+- Agents still needed: jellyfin (10.48.200.33), ollama-ai (10.48.200.95)
+- Daily backups running at 2AM to `/var/backups/jarvis/`, downloadable from admin panel
+- Network auto-scan: PVE1 cron every 3 min → pushes to `/api/netscan`
@@ -0,0 +1,116 @@
+# JARVIS System Reference Card
+
+## Access
+- **Dashboard:** https://jarvis.orbishosting.com (login: myron / Joker1974!!!)
+- **Admin portal:** https://jarvis.orbishosting.com/admin (same login)
+- **DB:** `jarvis_db` on DO localhost — user: `jarvis_user` / `J4rv1s_Pr0t0c0l_2026!`
+- **phpMyAdmin:** https://jarvis.orbishosting.com/phpmyadmin (myron / Joker1974!!!)
+- **GitHub repo:** myronblair/jarvis (auto-deploy on push to main)
+
+## File Structure (on DO at /home/jarvis.orbishosting.com/)
+```
+public_html/
+  index.html          — main Iron Man HUD (all UI)
+  api.php             — API router
+  admin/index.php     — admin portal (single PHP+JS file)
+  agent/              — agent installers
+api/
+  config.php          — all credentials/constants (gitignored)
+  lib/db.php          — JarvisDB class (query/execute/single/insert)
+  lib/kb_engine.php   — KBEngine intent matching
+  endpoints/
+    agent.php         — agent registration/heartbeat/metrics/commands
+    chat.php          — 4-tier chat: KB→action intents→Ollama→Groq→Claude
+    network.php       — network device list + scan endpoint
+    netscan.php       — push endpoint for PVE1 nmap results (no auth needed)
+    do_server.php     — reads /proc directly (no SSH loopback)
+    stats_cache.php   — every 5min cron: Proxmox cluster API, HA, weather, news
+    facts_collector.php — every 3min cron: system stats, site health
+    system.php        — local system metrics (services: lshttpd,mysql,redis,memcached,postfix,dovecot,jarvis-agent)
+    alerts.php        — alert CRUD + auto-generate
+    news.php          — serves api_cache['news'] + custom kb_facts(category='custom_news')
+```
+
+## Agent System
+- **Registration key:** `f846a9aaf7ce9a61742c63c87c4186052a71d2a580c65518`
+- **Install one-liner (Linux):** `curl -sk https://jarvis.orbishosting.com/install-agent.sh | bash -s <hostname> <linux|proxmox>`
+- **For VMs (need sudo):** `curl -sk https://jarvis.orbishosting.com/install-agent.sh > /tmp/i.sh && echo "Joker1974!" | sudo -S bash /tmp/i.sh <hostname> linux`
+- **Agent config:** `/etc/jarvis-agent/config.json` — runtime state at `/var/lib/jarvis-agent/state.json`
+- **If agent gets 401 "Invalid agent key":** state.json has stale key — overwrite with correct agent_id + api_key from DB
+- **Heartbeat:** every 10s | **Metrics:** every 30s | **Commands:** polled on heartbeat
+- **Shell commands:** send via agent_commands table with `{"command":"/path/to/script","allowed":true}`
+
+## Currently Online Agents
+| agent_id | hostname | IP | type |
+|----------|----------|----|------|
+| jarvis-do_orbis.or | jarvis-do | 165.22.1.228 | linux |
+| claude_pve | claude | 10.48.200.90 | proxmox |
+| pve2_e147a8bc | pve2 | 10.48.200.91 | proxmox |
+| networkbackup_NetworkB | networkbackup | 10.48.200.99 | linux |
+| homeassistant_ha | homeassistant | 10.48.200.97 | homeassistant |
+| homebridge_b57cbaea | homebridge | 10.48.200.18 | linux |
+| alien-pc_windows | alien-pc | 10.48.200.66 | linux |
+
+**Pending:** jellyfin (10.48.200.33), ollama-ai (10.48.200.95)
+
+## Network Scanning
+- PVE1 cron: `*/3 * * * * /usr/local/bin/jarvis-netscan.sh`
+- Script runs nmap, parses output, POSTs JSON to `https://165.22.1.228/api/netscan` with `X-Registration-Key` header
+- Scan Now button in admin queues shell command to PVE1 agent (picks up within 10s)
+
+## Chat Architecture
+```
+Tier 0:   HA entity control (fuzzy match → call HA API)
+Tier 0.5: Network device management
+Tier 1:   KB intent engine (response type → instant reply)
+Tier 1b:  Action intents (network_scan → DB data + queue PVE1 scan)
+Tier 2:   Ollama llama3.2 at http://10.48.200.95:11434 (5s timeout)
+Tier 3:   Groq compound-beta-mini (cloud, fast)
+Tier 4:   Claude API fallback
+```
+- Groq model name: `compound-beta-mini` (NOT `groq/compound-beta-mini`)
+- network_scan intent: action type — must be handled in Tier 1b or Groq will fabricate
+
+## DB Key Tables
+```sql
+registered_agents    — agent_id, hostname, agent_type, ip_address, api_key, status, last_seen
+agent_metrics        — agent_id, metric_type, metric_data(JSON), recorded_at
+  -- Extract: JSON_EXTRACT(metric_data,'$.cpu_percent'), JSON_EXTRACT(metric_data,'$.memory.percent')
+  -- NO cpu_pct/mem_pct columns — always use JSON_EXTRACT
+agent_commands       — agent_id, command_type, command_data(JSON), status(pending/delivered)
+network_devices      — ip, mac, hostname, alias, device_type, status, last_seen
+alerts               — alert_type, title, message, severity, resolved
+kb_facts             — category, fact_key, fact_value (custom_news category for pinned news)
+kb_intents           — intent_name, pattern(regex), response_template, action_type, priority, active
+api_cache            — cache_key(proxmox/news/weather/ha_entities), data(JSON), updated_at
+```
+
+## Proxmox Cache
+- `stats_cache.php` uses cluster API at `orbisne.fortiddns.com:8006` (NOT PROXMOX_HOST local IP)
+- Returns all VMs from both PVE1 and PVE2 via `/cluster/resources?type=vm`
+- Cache key: `proxmox` in api_cache table
+
+## Cron Jobs (on DO)
+```
+*/3 * * * *  /usr/local/lsws/lsphp85/bin/lsphp .../facts_collector.php
+*/5 * * * *  /usr/local/lsws/lsphp85/bin/lsphp .../stats_cache.php
+0 2 * * *    /usr/local/bin/jarvis-backup.sh
+```
+**Cron on PVE1:**
+```
+*/3 * * * *  /usr/local/bin/jarvis-netscan.sh
+```
+
+## Backups
+- Script: `/usr/local/bin/jarvis-backup.sh`
+- Output: `/var/backups/jarvis/jarvis_backup_YYYY-MM-DD_HH-MM-SS.tar.gz`
+- Contains: all public_html dirs + SQL dumps of 6 DBs
+- Downloadable from: admin portal → BACKUPS tab
+- Retention: 7 days
+
+## API Auth
+- Main JARVIS API: session token via `X-Session-Token` header (or PHP session)
+- Agent endpoints: `X-Agent-Key` header (per-agent key from registered_agents.api_key)
+- Netscan endpoint: `X-Registration-Key` header (shared registration key)
+- Admin portal: separate PHP session (`session_name('jarvis_admin')`)
+- Cloudflare passes real client IP in `CF-Connecting-IP` header
@@ -0,0 +1,69 @@
+# Server Reference Card
+
+## SSH Patterns
+
+```bash
+# DigitalOcean (all websites + JARVIS)
+sshpass -p 'Gonewalk1974!@#' ssh -o StrictHostKeyChecking=no root@165.22.1.228 'cmd'
+
+# PVE1 via FortiGate DDNS (survives IP changes)
+sshpass -p 'Joker1974!!!' ssh -o StrictHostKeyChecking=no root@orbisne.fortiddns.com 'cmd'
+
+# PVE1 direct (local network only)
+sshpass -p 'Joker1974!!!' ssh -o StrictHostKeyChecking=no root@10.48.200.90 'cmd'
+
+# PVE2 (local only)
+sshpass -p 'Joker1974!!!' ssh -o StrictHostKeyChecking=no root@10.48.200.91 'cmd'
+
+# FusionPBX
+sshpass -p 'Joker1974!@#' ssh -o StrictHostKeyChecking=no root@134.209.72.226 'cmd'
+
+# Local VMs (myron user + sudo, password Joker1974!)
+sshpass -p 'Joker1974!' ssh -o StrictHostKeyChecking=no myron@10.48.200.18 'sudo cmd'
+
+# Run command inside a Proxmox VM
+sshpass -p 'Joker1974!!!' ssh -o StrictHostKeyChecking=no root@10.48.200.90 \
+  'qm guest exec <VMID> -- bash -c "cmd"'
+```
+
+**Password order to try if first fails:** `Joker1974!@#` → `Joker1974!!!` → `Joker1974!`
+
+## Server Map
+
+| Host | IP | User | Password | Purpose |
+|------|----|------|----------|---------|
+| DO | 165.22.1.228 | root | Gonewalk1974!@# | Websites + JARVIS |
+| PVE1 | orbisne.fortiddns.com (10.48.200.90) | root | Joker1974!!! | Primary hypervisor |
+| PVE2 | 10.48.200.91 | root | Joker1974!!! | Secondary hypervisor |
+| FusionPBX | 134.209.72.226 | root | Joker1974!@# | FreeSWITCH PBX |
+| HomeAssistant | 10.48.200.97 | myron | Joker1974!!! | HA VM (PVE1 VM 101) |
+| Homebridge | 10.48.200.18 | myron | Joker1974! | Homebridge VM (PVE1 VM 118) |
+| Jellyfin | 10.48.200.33 | myron | Joker1974! | Jellyfin VM (PVE1 VM 112) |
+| Ollama | 10.48.200.95 | myron | Joker1974! | LLM VM (PVE1 VM 210) |
+| alien-pc | 10.48.200.66 | — | — | Windows PC (JARVIS agent only) |
+| NetworkBackup | 10.48.200.99 | myron | Joker1974! | Backup VM (PVE2 VM 302) |
+
+## Proxmox API
+```bash
+# Accessible from DO via FortiGate DDNS (port 8006 forwarded)
+curl -sk "https://orbisne.fortiddns.com:8006/api2/json/..." \
+  -H "Authorization: PVEAPIToken=root@pam!jarvis=c45b5feb-f9a9-445d-a626-14fbb959f78b"
+
+# Cluster API — gets VMs from BOTH PVE1 and PVE2
+GET /api2/json/cluster/resources?type=vm
+```
+
+## Key DO Server Paths
+```
+/home/jarvis.orbishosting.com/       — JARVIS app root
+/home/jarvis.orbishosting.com/public_html/  — web root (index.html, api.php, admin/)
+/home/jarvis.orbishosting.com/api/   — backend (config.php, endpoints/, lib/)
+/var/backups/jarvis/                 — daily backups (tar.gz, up to 7 days)
+/usr/local/bin/jarvis-backup.sh      — backup script
+/usr/local/lsws/lsphp85/bin/lsphp   — PHP runtime for CLI scripts
+```
+
+## PHP / OLS Notes
+- Run scripts: `/usr/local/lsws/lsphp85/bin/lsphp /path/to/script.php`
+- Syntax check: `php8.3 -l file.php` (lsphp segfaults on -l)
+- Web server: OpenLiteSpeed (`lshttpd`), NOT apache/nginx
@@ -0,0 +1,80 @@
+# Websites & Sites Reference Card
+
+## All Sites on DO (165.22.1.228)
+
+| Site | Path | GitHub Repo | DB |
+|------|------|-------------|-----|
+| jarvis.orbishosting.com | /home/jarvis.orbishosting.com/ | myronblair/jarvis | jarvis_db |
+| tomsjavajive.com | /home/tomsjavajive.com/public_html/ | myronblair/tomsjavajive | toms_tjj_db |
+| epictravelexpeditions.com | /home/epictravelexpeditions.com/public_html/ | myronblair/epictravelexpeditions | epic_epic_db |
+| parkerslingshot (subdomain) | /home/epictravelexpeditions.com/parkerslingshot/ | myronblair/parkerslingshot | epic_parkersling |
+| parkerslingshotrentals.com | /home/parkerslingshotrentals.com/public_html/ | myronblair/parkerslingshotrentals | parker_db |
+| orbishosting.com | /home/orbishosting.com/public_html/ | myronblair/orbishosting | — |
+| orbis.orbishosting.com | /home/orbis.orbishosting.com/public_html/ | myronblair/orbis-hosting-portal | — |
+| tomtomgames.com | /home/tomtomgames.com/public_html/ | myronblair/tomtomgames | tomt_ttg_db |
+
+## Deploy Workflow
+```bash
+# 1. Edit files on server via SSH (for quick hotfixes)
+sshpass -p 'Gonewalk1974!@#' ssh -o StrictHostKeyChecking=no root@165.22.1.228 \
+  'nano /home/site.com/public_html/file.php'
+
+# 2. ALWAYS commit + push to GitHub
+cd /home/site.com && git add -A && git commit -m "message" && git push
+
+# Auto-deploy triggers within 1 minute via webhook
+# Webhook: https://jarvis.orbishosting.com/webhook.php
+# Deploy log: /home/jarvis.orbishosting.com/logs/deploy.log
+
+# For immediate deploy (skip 1-min wait):
+sshpass -p 'Gonewalk1974!@#' scp -o StrictHostKeyChecking=no \
+  /tmp/changed.php root@165.22.1.228:/home/site.com/public_html/changed.php
+```
+
+## GitHub PAT
+`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` — expires ~2026-08-20
+
+## Database Credentials
+
+| DB | User | Password |
+|----|------|----------|
+| jarvis_db | jarvis_user | J4rv1s_Pr0t0c0l_2026! |
+| toms_tjj_db | toms_tjj_user | +60wlPc+55e@gFq4 |
+| epic_epic_db | epic_epic | (check config.php) |
+| epic_parkersling | epic_parkersling | Joker1974!!! |
+| parker_db | parker_db | (check config.php) |
+| MySQL root | root | b71e5c1a8c7457541b9c1db822de37adfa271926a38b6c20 |
+
+```bash
+# Quick DB access
+sshpass -p 'Gonewalk1974!@#' ssh -o StrictHostKeyChecking=no root@165.22.1.228 \
+  'mysql -u jarvis_user -pJ4rv1s_Pr0t0c0l_2026! jarvis_db -e "SELECT ..."'
+```
+
+## Gitignored Credentials (never in GitHub)
+- `api/config.php` — JARVIS, epictravelexpeditions
+- `config/database.php` — tomsjavajive
+- `db.php`, `config.php` — parkerslingshot
+
+## Tom's Java Jive Quirks
+- No `slug` column on products — URLs use `?id=product_id`
+- All tables must be `utf8mb4_unicode_ci` — mixed collation breaks JOINs (error 1267)
+- `wallet_transactions.type` and `loyalty_transactions.type` have strict enums
+
+## Parker Slingshot Admin
+- URL: `/admin/index.php`
+- Auth: HMAC-signed cookie (NOT PHP sessions — sessions unreliable under LiteSpeed caching)
+- Login: `admin / Parker2026!`
+
+## Email / SMTP
+- TJJ + TomTomGames: CyberMail (CyberPersons) — API key in config.php as `CYBERMAIL_API_KEY`
+- Manage at: platform.cyberpersons.com
+- Other sites: not yet configured (see myronblair/smtp-for-websites)
+
+## FusionPBX
+- URL: https://fusion.orbishosting.com (admin / fY7XP5swgtpbzrYLhkeVYkA4744)
+- Server: 134.209.72.226 (SSH: root / Joker1974!@#)
+- Timezone: America/Chicago
+- SIP profiles via Lua XML handler — config changes need cache delete:
+  `rm /var/cache/fusionpbx/FusionPBX.configuration.sofia.conf`
+- Ext 1000 (Yealink T48S at 10.48.200.43), Ext 1001 (Tommy at 10.48.200.2)