1 files changed, 111 insertions, 0 deletions
diff --git a/Omni/Dev/Beryllium/AVA.md b/Omni/Dev/Beryllium/AVA.md
new file mode 100644
index 0000000..620592b
--- /dev/null
+++ b/Omni/Dev/Beryllium/AVA.md
@@ -0,0 +1,111 @@
+# Ava Deployment on Beryllium
+
+Ava runs as a systemd service under the `ava` user.
+
+## Architecture
+
+```
+/home/ava/                    # Ava's home directory (AVA_DATA_ROOT)
+├── omni/                     # Clone of the omni repo
+├── skills/                   # Ava's skills directory
+│   ├── shared/               # Skills available to all users
+│   └── <username>/           # User-specific skills
+├── outreach/                 # Outreach approval queue
+│   ├── pending/
+│   ├── approved/
+│   ├── rejected/
+│   └── sent/
+├── users/                    # Per-user scratch space
+│   └── <username>/
+└── .local/share/omni/
+    └── memory.db             # SQLite memory database
+```
+
+## Configuration
+
+The service is configured in `Ava.nix` and requires these environment variables in `/run/secrets/ava.env`:
+
+```bash
+TELEGRAM_BOT_TOKEN=xxx
+OPENROUTER_API_KEY=xxx
+KAGI_API_KEY=xxx                    # optional
+ALLOWED_TELEGRAM_USER_IDS=xxx,yyy   # or * for all
+```
+
+## Commands
+
+```bash
+# View logs
+journalctl -u ava -f
+
+# Restart service
+sudo systemctl restart ava
+
+# Check status
+sudo systemctl status ava
+
+# Stop/Start
+sudo systemctl stop ava
+sudo systemctl start ava
+```
+
+## SSH Access
+
+The Ava private key is at `~/.ssh/ava_ed25519`. Use it to SSH as ava:
+
+```bash
+ssh -i ~/.ssh/ava_ed25519 ava@beryl.bensima.com
+```
+
+Ben can also access ava's workspace via his own SSH key since ava is in the git group.
+
+## Git Setup
+
+Ava has its own clone of the omni repo at `/home/ava/omni`. To fetch changes from ben:
+
+```bash
+# As ava:
+cd /home/ava/omni
+git fetch origin
+git pull origin main
+```
+
+Ben can also push directly to ava's repo if needed:
+
+```bash
+# From /home/ben/omni:
+git remote add ava /home/ava/omni
+git push ava main
+```
+
+## Redeploy
+
+To redeploy Ava with code changes:
+
+```bash
+# 1. Rebuild the NixOS config
+push.sh Omni/Dev/Beryllium.nix
+
+# 2. Or just restart the service if only env changes
+sudo systemctl restart ava
+```
+
+## Migration from tmux
+
+If migrating from the old tmux-based deployment:
+
+1. Deploy the NixOS config with the new ava user
+2. Run the migration script: `sudo ./Omni/Dev/Beryllium/migrate-ava.sh`
+3. Create `/run/secrets/ava.env` with the required secrets
+4. Stop the tmux ava process
+5. Start the systemd service: `sudo systemctl start ava`
+6. Enable on boot: `sudo systemctl enable ava`
+
+## Environment Variable: AVA_DATA_ROOT
+
+The `AVA_DATA_ROOT` environment variable controls where Ava stores its data:
+
+- **Development** (unset): Uses `_/var/ava/` (relative to repo)
+- **Production**: Set to `/home/ava` via the systemd service
+
+This allows the same codebase to run in both environments without changes.