# CLAUDE.md — OTIVM Project

This file is read automatically by Claude Code at the start of every session.
Read it completely before doing anything else.

---

## What OTIVM Is

A browser-based Roman merchant idle game. One screen, one resource loop.
The narrative unfolds through trade goods and journal entries.
It is a standalone light-hearted project — not part of CIVICVS or TESSERA infrastructure.

**Live URL:** https://otium.civicus.us
**Repo:** https://gitea.barternetwork.us/TheRON/OTIVM (branch: main)

---

## Stack

- React 19 + Vite frontend
- Node.js v22
- PM2 under otivm user (never root)
- Python venv at /home/otivm/venv (never run Python outside venv)
- No database — JSON flat files for any local state

---

## Ground Rules — Do Not Violate

- **Never run PM2 as root** — always as otivm user
- **Never run Python outside the venv** — /home/otivm/venv always
- **Never commit secrets** — no tokens, no keys, no passwords in any file
- **Never push to main without testing** — test locally on port 3000 first
- **One screen, one loop** — do not add complexity without explicit instruction
- **No database** — JSON flat files only, consistent with TheRON design principles

---

## Container Facts

| Property | Value |
|----------|-------|
| Hostname | otivm-dev |
| LAN IP | 10.0.0.23 |
| WireGuard | 10.110.0.18 |
| App user | otivm |
| App port | 3000 |
| Python venv | /home/otivm/venv |
| PM2 home | /home/otivm/.pm2 |
| Repo path | /home/otivm/OTIVM |

---

## PM2 Commands

```bash
# Always as otivm user
pm2 start ecosystem.config.js
pm2 restart otivm
pm2 logs otivm
pm2 save
```

---

## Git Workflow

```bash
git add <files>
git commit -m "imperative mood, under 72 chars"
git push origin main
```

Commit messages: imperative mood, present tense, under 72 characters.
Example: `Add trade route unlock mechanic` not `Added trade routes`.

---

## TheRON Infrastructure Context

- **wg-pk** (198.58.111.109) — Linode hub, Nginx proxy, WireGuard hub
- **srv-a** (10.0.0.11) — dev Proxmox host, runs this container
- **mcp.civicus.us** — gitea-mcp server, gives Claude chat read access to this repo
- **Gitea** — https://gitea.barternetwork.us (owner: TheRON)

---

## Design Notes

The game carries quiet atmospheric references to Mesolithic cultures
(Maglemosian, Ertebølle, Sauveterrian, Azilian) through trade goods,
place names, and merchant journal entries. These are never labelled
academically — they are atmosphere only. The amber road, the northern
forests, the flint from the Pyrenean foothills.

The Roman merchant's journey: Ostia → Capua → Brundisium → Carthago → Alexandria.
Five chapters. Five trade routes. Five journal entries.

---

## Session Start Checklist

1. Read this file ✓
2. Check `git status` and `git log --oneline -5`
3. Check `pm2 list` (as otivm user)
4. Proceed with the task

---

## Aliases

| Location | Alias | Effect |
|----------|-------|--------|
| root@otivm-dev ~/.bashrc | webmin-on | systemctl start webmin |
| root@otivm-dev ~/.bashrc | webmin-off | systemctl stop webmin |
| otivm@otivm-dev ~/.bashrc | work | cd ~/OTIVM && claude |

---

*CLAUDE.md — OTIVM — TheRON*