# Sysadmin Chronicles

A native Linux game where you work as a junior sysadmin at Axiom Works, handling
real tickets inside real Linux virtual machines managed by QEMU/KVM.

**Status**: Node.js server + Svelte HUD implemented. Server, frontend, and all
services are built. Pending: Phase 7 workstation VM verification + Phase 10 full playtest.

---

## Architecture Summary

The game runs as a Node.js server on the host, serving a Svelte web HUD into the
workstation VM's browser. The player works inside a real XFCE desktop.

```
Host machine
├── Node.js game server (port 3000) — quest logic, validation, VM control
└── Svelte HUD — tickets, mail, Sage, docs (served by game server)

Workstation VM (sc-workstation / ares) — Debian 12 XFCE desktop
├── Chromium → http://192.168.100.1:3000  (HUD, auto-opens on login)
└── Tilix → SSH to hermes/vulcan          (real terminal, real SSH)

Target VMs (headless)
├── sc-web-server (hermes)   — Q002–Q005, Q007
└── sc-build-machine (vulcan) — Q006, Q008
```

Quest completion is validated by the server SSHing into the target VM and
evaluating real system state — not by tracking commands typed.

---

## Quick Start (Development)

### Prerequisites

```bash
# Install host dependencies
sudo apt install qemu-system-x86_64 libvirt-daemon-system virsh qemu-img \
                 nodejs npm virt-viewer

# Add yourself to the libvirt group
sudo usermod -aG libvirt $USER && newgrp libvirt
```

### First-Time Setup

```bash
# Check host capabilities
bash tools/setup/check-host.sh

# Create libvirt networks, storage pool, and SSH keys
bash tools/setup/first-run-setup.sh

# Build VM images and provision quest baselines
bash tools/setup/seed-vms.sh
```

### Build the Frontend

```bash
cd frontend && npm install && npm run build && cd ..
```

### Run the Game

```bash
# Start game server + open workstation VM via SPICE
bash scripts/start-game.sh

# Or run server only (for development/testing)
cd server && npm install && node src/index.js
```

### Validate Content

```bash
node tools/content/validate-content.js --verbose
```

### Run Server Tests

```bash
cd server && npm test
```

---

## Project Structure

```
sysadmin-chronicles/
│
├── server/                     Node.js game server
│   └── src/
│       ├── index.js            Entry point — Express + WebSocket
│       ├── routes/             REST API routes
│       └── services/           ContentLoader, QuestEngine, ValidationEngine, etc.
│
├── frontend/                   Svelte web HUD
│   ├── src/                    Components, api.js
│   └── dist/                   Built output (served by game server)
│
├── scripts/
│   └── start-game.sh           Start server + open SPICE viewer
│
├── content/                    All game content (JSON — unchanged)
│   ├── quests/                 Q001–Q008
│   ├── tickets/                T001–T008
│   ├── incidents/              I001–I003
│   ├── dialogue/               All NPC dialogue files
│   ├── vm_profiles/            workstation, web_server, build_machine
│   └── progression/            trust_unlocks.json
│
├── tools/
│   ├── setup/                  check-host.sh, first-run-setup.sh, seed-vms.sh
│   ├── vm/                     build scripts, quest-prep/, suppress-maintenance-noise.sh
│   └── content/                validate-content.js, verify-clue-fingerprints.js
│
├── docs/
│   ├── ARCHITECTURE.md         System design
│   ├── ROADMAP.md              Phase tracking
│   └── QUEST_AUTHORING.md      Content authoring guide
```

---

## Key Design Rules

- Game server is the single source of truth — frontend only displays results
- Validation is server-side only — SSH into VMs, evaluate real system state
- Quest completion is state-based only — never command-sequence tracking
- Only operate on `sc-` prefixed libvirt domains
- Content JSON is read-only at runtime — ContentLoader reads once at startup
- Save file is at `~/.local/share/sysadmin-chronicles/save.json`

---

## Current Build State

### Done
- Node.js game server with all services (ContentLoader, QuestEngine, TicketService,
  ValidationEngine, VMManager, TrustSystem, ProgressionSystem, EmailService,
  SageService, ShiftTimer, IncidentScheduler, ShiftReviewService, CertificationService)
- All REST routes (tickets, mail, docs, sage, state, vms, session)
- Svelte frontend with all panels (Tickets, Mail, Docs, Sage, VMs, Header)
- Built frontend (`frontend/dist/`) served by game server
- Content: Q001–Q008, T001–T008, I001–I003, all dialogue, world_flags, trust_unlocks
- Content validator: `validate-content.js` exits zero

### Pending
- Phase 7: verify XFCE workstation VM (SPICE display, Chromium autostart, Tilix default)
- Phase 10: full end-to-end playtest (Q001→Q002 with real VMs)