Add infrastructure documentation and project setup

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-25 10:48:33 +00:00
parent 02e3109a28
commit c0f5aebc44
4 changed files with 737 additions and 1 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,121 @@
+# 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*