AkurAI-Mail / AGENTS.md

Latest change 66e3647948f2e277afdd6ecd16939de8b6ad525f - Initial commit: AkurAI Mail UI (SvelteKit+Bun) by Ólafur Búi Ólafsson

# AkurAI Mail Agent Memory

## Operating Rules

- Work directly on the VM repository at `/opt/akurai-mail-ui`.
- Keep `VERSION`, `CHANGELOG.md`, git history, and `deploy.sh` current for every deployed change.
- Run `./deploy.sh` for final verification after UI, CLI, service, backup, or deployment changes.
- `deploy.sh` must create a backup first through `backup.sh`.
- Keep only the 10 newest backups under `/opt/akurai-mail-ui-backups`.
- Use `rollback.sh latest` or `/usr/local/sbin/akurai-mail-rollback latest` to restore the newest backup.

## Product Context

- Product register: authenticated product/admin UI.
- Primary surfaces: admin console at `/`, webmail shell at `/webmail`, admin login at `/login`, mailbox login at `/webmail/login`.
- Design language: restrained operational UI, dark rail, light workspace, green primary action, dense readable panels.
- Webmail should read as a familiar mail client: top search, folder column, message list, reading pane, floating compose window, and a mobile list/detail flow.
- Avoid marketing hero layouts, decorative gradients, glassmorphism, nested cards, and placeholder-only operational data.

## Server Context

- VM: `mail.olibuijr.com` / `3.94.46.219`.
- App directory: `/opt/akurai-mail-ui`.
- Runtime: Bun with SvelteKit.
- Mail stack: Postfix, Dovecot, OpenDKIM, Nginx, AkurAI UI, Fail2ban.
- Expected public mail ports include SMTP `25/tcp`, submission `587/tcp`, SMTPS `465/tcp` at the AWS security group, and IMAPS `993/tcp`; UFW explicitly allows `587/tcp` and `993/tcp`.
- Dovecot IMAPS and Postfix submission use the Let's Encrypt certificate at `/etc/letsencrypt/live/mail.olibuijr.com/`; it was issued with a manual DNS-01 challenge and expires on September 22, 2026.
- Runtime status comes from `/usr/local/sbin/akurai-mail-server`.
- Real mailbox source: `/etc/dovecot/users`.
- Mailbox webmail login validates against `/etc/dovecot/users` through `akurai-mail-server validate-login`.
- Admin sessions can operate all mailboxes; mailbox sessions are scoped to `/webmail` and the signed-in mailbox only.
- Real alias source: `/etc/postfix/virtual`.
- Webmail reads local Maildir folders under `/var/vmail/<domain>/<user>/Maildir`.
- Webmail state for contacts, signatures, vacation settings, rules, and preferences lives in `/var/lib/akurai-mail/webmail.json`.
- Outgoing webmail sends through `/usr/sbin/sendmail` and stores sent messages in the selected mailbox `Sent` Maildir.
- Webmail supports attachment download through `/webmail/api`, settings import/export, dark mode preference, keyboard shortcuts, automatic Inbox rules, and vacation auto-replies when Inbox is processed.
- Anti-spam policy lives in `/var/lib/akurai-mail/state.json` under `spamPolicy`; use `akurai-mail-server anti-spam-config` and `akurai-mail-server anti-spam-scan` for one-shot management.
- Inbox processing scores spam before vacation replies and user rules, then moves messages over threshold to the Spam folder when automatic quarantine is enabled.
- Admin status includes Postfix queue summary, recent delivery errors, DNS health, anti-spam policy, quarantine counts, mailbox usage, and last delivery time.

## Verification

- Expected active services: `postfix`, `dovecot`, `opendkim`, `nginx`, `akurai-mail-ui`, `fail2ban`.
- Deployment checks must verify `/`, `/login`, `/webmail`, `/api/actions`, Nginx syntax, and service health.