From 03d1db34180da7b7e5a5ce45cc62d697c22f9a08 Mon Sep 17 00:00:00 2001
From: jp <jp@txt3.com>
Date: Thu, 13 Aug 2026 19:57:36 +0100
Subject: [PATCH] Add AGENTS.md project instructions

---
 AGENTS.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..2ed5c58
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,78 @@
+# AGENTS.md — Asterisk Voicemail Portal
+
+Project: mail.txt3.net Asterisk PBX + MySQL voicemail store + React portal (vm.txt3.net)
+Backend repo: `/home/jp/Work/asterisk-voicemail` (this repo)
+Frontend repo: `/home/jp/Work/voicemail-ui`
+Deployed frontend: `/home/txt3/domains/vm.txt3.net/public_html/`
+Deployed backend: `/opt/vm-transcribe/`
+
+---
+
+## Directory layout
+
+- `src/vm_api.py` — FastAPI JSON API (:8098). Apache proxies `/api/` → :8098.
+- `src/vm_web.py` — Original FastAPI HTML portal (:8099).
+- `src/vm_store.py` — MySQL-backed voicemail store.
+- `src/vm_contacts.py` — MySQL-only contact backend (no CardDAV/Google).
+- `frontend/` — React frontend synced from `/home/jp/Work/voicemail-ui`.
+- `apache/vm.txt3.net.conf` — Apache vhost (CSP relaxed, Let's Encrypt cert).
+
+---
+
+## Services
+
+- `vm-api.service` → :8098 (JSON API). Active unit.
+- `vm-portal.service` → :8099 (HTML portal).
+- `apache2` → :443 with per-subdomain cert for vm.txt3.net.
+
+Auth: voicemail `pin` from `voicemail.conf`. No separate portal passwords.
+
+---
+
+## Frontend stack
+
+- React + react-router-dom (createBrowserRouter + RouterProvider).
+- TanStack Query for data fetching/mutations.
+- Vite build → `dist/` → rsync to `/home/txt3/domains/vm.txt3.net/public_html/`.
+- Dark cyber theme in `src/index.css` with neon accents.
+
+---
+
+## Backend conventions
+
+- Use `_fmt_time()` for timestamps; it must handle both `datetime.datetime` and unix timestamps.
+- SQL queries via PyMySQL `%s` placeholders; always use `con.execute()` and `con.commit()`.
+- Callerid matching: strip spaces/quotes with `REPLACE(REPLACE(callerid, ' ', ''), '"', '')` before LIKE comparison.
+- Normalize UK numbers to E.164 in backend; 0-prefix fallback in queries.
+
+---
+
+## Sudo / deployment
+
+- Sudo requires password. Use `SUDO_ASKPASS=/home/jp/.hermes/askpass.sh` with `sudo -A <cmd>`.
+- `sudo bash <script>` is blocked (nested root shell). Run privileged steps as individual `sudo -A <cmd>` calls.
+- Deploy backend: `sudo -A cp /home/jp/asterisk-vm/vm_api.py /opt/vm-transcribe/vm_api.py && sudo -A systemctl restart vm-api`.
+- Deploy frontend: `sudo -A rsync -a --exclude 'node_modules' --exclude 'dist' /home/jp/Work/voicemail-ui/ /home/txt3/domains/vm.txt3.net/public_html/`.
+
+---
+
+## Git
+
+- Remote: Gitea self-hosted. Push needs `jp-account` Gitea PAT with `repo` scope.
+- Frontend sync: `rsync -a /home/jp/Work/voicemail-ui/ frontend/` then commit under `frontend/`.
+
+---
+
+## Contacts & matching
+
+- Contacts live in MySQL `contacts` table.
+- E.164 is canonical; UK storage often 0-prefixed.
+- Creating/updating a contact backfills `messages.contact_name`/`contact_email` for matching callerids.
+
+---
+
+## Known gotchas
+
+- Chrome overrides dark inputs: use bare `input` selector, hardcode `background: #0a0e17`, reset `appearance`, set `-webkit-text-fill-color`.
+- React hook rules: no `useMemo`/`useState` inside `.map()`. Hooks must be at component top level.
+- Do NOT push to origin from this session unless explicitly asked; push is currently blocked by Gitea 401 (uid 0).