175 lines
5.2 KiB
Markdown
175 lines
5.2 KiB
Markdown
# 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 |
|
|
| Cores | 4 |
|
|
| RAM | 2048 MB |
|
|
| 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*
|
|
|
|
---
|
|
|
|
## Session workflow — paste-and-commit
|
|
|
|
Each development step follows this exact sequence:
|
|
|
|
1. The design discussion happens in Claude chat (not here)
|
|
2. Claude chat produces one file or one change at a time
|
|
3. That content is pasted into this Claude Code session as a prompt
|
|
4. Claude Code writes the file to disk exactly as given, then commits and pushes
|
|
5. The human confirms it works before the next step begins
|
|
|
|
**When a file is pasted into this prompt**, the instruction will say:
|
|
|
|
> Write this to `<path>` exactly as given, then commit with message `<message>` and push to main.
|
|
|
|
Do not modify the content. Do not reformat. Do not add imports or change structure. Write it exactly as given.
|
|
|
|
**When a shell command result is pasted**, it is for context only — no action unless explicitly instructed.
|
|
|
|
## Current development state — updated 2026-04-25
|
|
|
|
### OTIVM-I — complete
|
|
- Fastify backend serving dist/ and save API on port 3000
|
|
- Five trade routes, Ostia → Alexandria, all working
|
|
- Journal entries firing on dispatch milestones
|
|
- Otium/negotium mechanic working
|
|
- Per-player save files in data/saves/ via 8-char hex token
|
|
- Token displayed in UI — player can record it to resume on another device
|
|
- 128 concurrent players supported
|
|
|
|
### Navigation scaffold — complete
|
|
- src/screens/ directory established
|
|
- Game.jsx renamed to src/screens/Ledger.jsx
|
|
- App.jsx manages screen state — ledger and map
|
|
- Both screens stay mounted — no state lost on switch
|
|
- Map screen shows placeholder — ready for OTIVM-II work
|
|
|
|
### OTIVM-II — next
|
|
- src/screens/Map.jsx to be created
|
|
- Mediterranean rendered using H3 geometry
|
|
- Five waypoints plotted using confirmed H3 res-5 IDs
|
|
- Route lines drawn between waypoints
|
|
- No interactivity required in first Map commit — visual only
|
|
|
|
### Architecture decisions locked
|
|
- H3 IDs on all waypoints — permanent, TESSERA-compatible
|
|
- constants.js / gameState.js / api.js separation — permanent
|
|
- Virtual screens via display:none — state preserved in browser
|
|
- Save on meaningful events only — not on every tick
|