chore: bootstrap lean sysadmin-chronicles repo

Import the runnable game code, content, docs, scripts, and repo guidance while leaving local agent state, dependency installs, build output, and backup copies out of the published tree.
2026-05-02 11:49:07 -04:00
commit 0265afa054
252 changed files with 37574 additions and 0 deletions
@@ -0,0 +1,155 @@
+# 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)