sysadmin-chronicles/PROJECT_MAP.md

# PROJECT_MAP.md

# Auto-generated / agent-maintained project index.
# Purpose: help future agents quickly select the right context and files.
# Last updated: 2026-04-30 - Initial root map created from current repo and docs.

---

## 1. Project Snapshot

Sysadmin Chronicles is a Linux sysadmin game where players resolve tickets inside real libvirt/QEMU VMs. The host Node.js/Express server owns state, validation, VM control, APIs, and static sites; the Svelte/Vite HUD runs in Chromium inside the workstation VM.

---

## 2. Context Budget Rules

1. Read this `PROJECT_MAP.md` first.
2. Identify the relevant hot path or feature area.
3. Load only directly relevant files.
4. Load one dependency layer outward only if needed.
5. Avoid loading whole directories unless the map says the area is tightly coupled.
6. Prefer tests and public interfaces over implementation details when scoping behavior.
7. Update this map after meaningful structural or user-facing changes.

Do not paste large files into context when a targeted excerpt, `rg`, `rtk`, or symbol search is enough.

---

## 3. Architecture Summary

The game is host-authoritative: frontend actions call server APIs, services update save/game state, and validation checks real VM state over SSH/libvirt instead of trusting typed commands.

Runtime flow:

`scripts/start-game.sh -> server/src/index.js -> ContentLoader/SaveState/services -> VMManager.ensureWorkstationLive() -> Express/WebSocket on port 3000 -> remote-viewer opens sc-workstation -> Chromium HUD`

VMs:

- `sc-workstation` / `ares`: player workstation, XFCE, Chromium HUD, Tilix.
- `sc-web-server` / `hermes`: web/server target.
- `sc-build-machine` / `vulcan`: build/package target.

---

## 4. File Priority Map

### Tier 1 - Critical / frequently needed

| Path | Role | When to load |
|------|------|--------------|
| `server/src/index.js` | Server bootstrap, routes, static serving, WebSocket events | Runtime/API/static route changes |
| `server/src/services/ContentLoader.js` | Loads authored content collections | Content schema/loading changes |
| `server/src/services/SaveState.js` | Save persistence and state shape | Save/progression compatibility changes |
| `server/src/services/QuestEngine.js` | Quest lifecycle and completion | Quest activation/completion changes |
| `server/src/services/TicketService.js` | Ticket state and resolution | Ticket workflow changes |
| `server/src/services/ValidationEngine.js` | Real VM rule evaluation | Objective/validation rule changes |
| `server/src/services/VMManager.js` | libvirt state, startup, IP discovery | VM runtime/control changes |
| `frontend/src/App.svelte` | Main HUD orchestration | Tab/workflow/UI state changes |
| `frontend/src/lib/api.js` | Browser API client/session handling | API contract changes |
| `tools/vm/build-vm.sh` | Common VM build driver | VM build behavior changes |
| `tools/vm/profiles/workstation.sh` | Ares workstation image profile | Desktop/provisioning changes |
| `scripts/start-game.sh`, `start-game.sh` | End-to-end launchers | Startup/viewer/server launch changes |
| `tools/lib/internal-https.sh` | Shared internal HTTPS cert/env/URL helpers | Portal/Sage/company URL or TLS startup changes |
| `content/quests/`, `content/tickets/`, `content/vm_profiles/` | Authored gameplay data | Quest, ticket, or VM identity changes |

### Tier 2 - Supporting / sometimes needed

| Path | Role | When to load |
|------|------|--------------|
| `server/src/routes/` | API route modules | Endpoint behavior changes |
| `server/src/services/TrustSystem.js` | Trust score and unlocks | Access/progression tuning |
| `server/src/services/ProgressionSystem.js` | Unlock/progression rules | Unlock state changes |
| `server/src/services/EmailService.js` | Mail/read/reply state | Mail workflow changes |
| `server/src/services/SageService.js` | Sage API behavior | Knowledge-base changes |
| `server/src/services/IncidentScheduler.js` | Timed incident pressure | Incident/shift pacing |
| `server/src/services/ShiftReviewService.js` | End-shift review data | Profile/review changes |
| `frontend/src/components/` | HUD panels/components | Focused UI changes |
| `tools/content/validate-content.js` | Content validator | Any content schema/rule change |
| `tools/setup/*.sh` | Host setup/seed/uninstall | Installer/setup flow changes |
| `tools/vm/profiles/*.sh` | Target VM profiles | Hermes/vulcan/workstation provisioning changes |
| `tools/vm/repair-workstation-launchers.sh` | Live workstation desktop launcher trust repair | Existing Ares desktop launcher prompt fixes |
| `tools/vm/quest-prep/` | Baseline quest state authorship | VM baseline quest setup |
| `sage/`, `company-website/` | Static web surfaces | Sage/company site changes |
| `docs/ARCHITECTURE.md`, `docs/SAVE_SYSTEM.md`, `docs/VM_BUILD_SYSTEM.md` | Deep design docs | Architecture/save/build questions |

### Tier 3 - Peripheral / rarely needed

| Path | Role | When to load |
|------|------|--------------|
| `frontend/dist/` | Generated frontend build | Only to verify served assets |
| `node_modules/` | Installed dependencies | Avoid; use manifests instead |
| `ruvector.db` | Local RTK/vector data | Do not inspect for normal work |
| `vm/images/`, `vm/snapshots/` | Large/live VM data | Only for explicit VM storage tasks |
| Static assets | Images/icons/fonts | Only for visual asset changes |

---

## 5. Hot Paths

- Change server API route:
  - Load: `server/src/index.js`, relevant `server/src/routes/*`, relevant service, `frontend/src/lib/api.js`
  - Usually update: server tests and frontend caller
  - Watch out for: session middleware and WebSocket refresh expectations

- Change quest/ticket behavior:
  - Load: `content/quests/`, `content/tickets/`, `ContentLoader.js`, `QuestEngine.js`, `TicketService.js`, `ValidationEngine.js`
  - Usually update: `tools/content/validate-content.js`, docs if schema changes
  - Watch out for: world flag and dialogue ID references

- Change validation rule:
  - Load: `ValidationEngine.js`, tests, representative quest JSON
  - Usually update: `docs/QUEST_AUTHORING.md`
  - Watch out for: validation must observe real VM state, not commands typed

- Change VM build/provisioning:
  - Load: `docs/VM_BUILD_SYSTEM.md`, `tools/vm/build-vm.sh`, relevant `tools/vm/profiles/*.sh`, `tools/setup/seed-vms.sh`
  - Usually update: setup docs and dependency/version tracking
  - Watch out for: destructive `--force`, cloud-init quoting, readiness gates

- Change workstation desktop UX:
  - Load: `tools/vm/profiles/workstation.sh`, `scripts/start-game.sh`, `runtime/viewer/*`
  - Usually update: rebuild/patch instructions
  - Watch out for: RAM pressure, browser launch, desktop icon permissions

- Change frontend HUD workflow:
  - Load: `frontend/src/App.svelte`, relevant component, `frontend/src/lib/api.js`
  - Usually update: `cd frontend && npm run build`
  - Watch out for: generated `frontend/dist` is what the server serves

- Change save/progression/trust:
  - Load: `SaveState.js`, `TrustSystem.js`, `ProgressionSystem.js`, `QuestEngine.js`, content progression JSON
  - Usually update: migration/default handling and tests
  - Watch out for: no-auto-restore and backward compatibility

- Change Sage/company web surface:
  - Load: `server/src/index.js`, `sage/` or `company-website/`, workstation profile bookmarks/proxy config
  - Usually update: browser smoke test inside ares
  - Watch out for: `/sage/` route and guest bookmark expectations

---

## 6. Change Impact Map

| Change type | Also check/update |
|-------------|-------------------|
| API contract | route, service, `frontend/src/lib/api.js`, HUD state handling, tests |
| Content schema or IDs | validator, ContentLoader, quests/tickets/dialogue/world flags, docs |
| Validation rule | `ValidationEngine.js`, representative content, tests, authoring docs |
| Persistence format | `SaveState.js`, migrations/defaults, load/save compatibility tests |
| VM profile/domain | setup scripts, start script, content VM profiles, docs, live libvirt state |
| Workstation desktop | profile packages, cloud-init user-data, browser/shortcut config, RAM/performance |
| Frontend UI workflow | `App.svelte`, component state, API client, WebSocket refresh behavior |
| Build/dev tooling | README/dev docs, `AGENTS.md`, scripts, dependency/version manifest |

---

## 7. Key Concepts & Domain Terms

- **Ares**: player workstation VM; libvirt domain `sc-workstation`.
- **Hermes**: web server target VM; libvirt domain `sc-web-server`.
- **Vulcan**: build machine target VM; libvirt domain `sc-build-machine`.
- **opsbridge**: management user for host-driven SSH validation/control.
- **player**: in-world workstation user.
- **world_flags**: durable flags for quest/narrative branching.
- **trust/unlocks**: score and capability gate system.
- **solution_branches**: authored ticket outcomes.
- **pressure_profiles**: incident/timer pressure configuration.
- **baseline/recovery/checkpoint/live**: VM state tiers described in save/snapshot docs.
- **Sage**: knowledge-base/help system.

---

## 8. User-Facing Surface

- Launch: `bash scripts/start-game.sh`.
- HUD tabs: Tickets, Mail, Docs, Sage, VMs, Profile.
- Server APIs: `/api/session`, `/api/state`, `/api/tickets`, `/api/mail`, `/api/docs`, `/api/vms`, `/api/sage`, `/api/profile`.
- Static sites: `/sage`, `/company`, `/public`; intended in-VM browser URLs use HTTPS (`portal.axiomworks.internal:3000`, `sage.axiomworks.internal:3000/sage/`, `www.axiomworks.corp/`).
- Workstation desktop: Chromium HUD, terminal, desktop shortcuts, remote-viewer session.
- Save path: `~/.local/share/sysadmin-chronicles/save.json`.

---

## 9. Persistence / Data Contracts

| Contract | Defined in | Compatibility notes |
|----------|------------|---------------------|
| Save file | `SaveState.js`, docs `SAVE_SYSTEM.md` | Preserve load defaults and migration behavior |
| Authored content JSON | `content/`, `ContentLoader.js`, validator | Treat as read-only runtime input; keep IDs stable |
| VM profiles | `content/vm_profiles/`, `tools/vm/profiles/*.sh` | Domain/hostname/user changes affect scripts and docs |
| Frontend session token | `frontend/src/lib/api.js` | Stored in browser local storage; API retries on invalid session |
| VM disks/snapshots | libvirt/qcow2, docs | Save/load must handle missing domains/snapshots gracefully |
| Static route prefixes | `server/src/index.js` | Guest bookmarks/proxies may depend on `/sage` and `/company` |

---

## 10. Test & Validation Map

| Change area | Validation |
|-------------|------------|
| Content changes | `node tools/content/validate-content.js --verbose` |
| Server services/routes | `cd server && npm test` |
| Frontend HUD | `cd frontend && npm run build` |
| Host setup | `bash tools/setup/check-host.sh` |
| VM profile/build logic | `bash tools/vm/build-workstation.sh --dry-run` when available; otherwise inspect generated command/output |
| Live VM runtime | `virsh --connect qemu:///system list --all`; targeted SSH/HTTP checks |
| Full smoke test | `bash scripts/start-game.sh`, then use HUD in ares workstation |

---

## 11. Known Risk Areas / Tech Debt

- **VM rebuilds**: build scripts can destroy/recreate `sc-` domains; confirm intent before force paths.
- **Cloud-init profiles**: YAML and shell quoting are fragile in `tools/vm/profiles/*.sh`.
- **Readiness checks**: networking, cloud-init, LightDM, and SSH can hang builds if guest state drifts.
- **Save/snapshot drift**: save refs can point at missing domains or snapshots; recovery handling matters.
- **Real VM validation**: many behaviors need live libvirt smoke tests beyond unit tests.
- **Content cross-references**: IDs, world flags, dialogue, branches, and tickets can silently desync.
- **Generated frontend**: server serves `frontend/dist` when present, so rebuild after UI changes.
- **Workstation performance**: Chromium/XFCE can cause RAM pressure and perceived hangs.
- **Internal HTTPS**: `tools/lib/internal-https.sh` is the shared source for launcher TLS env and in-VM Portal/Sage/company URLs; avoid reintroducing per-script HTTP fallbacks.
- **Desktop launcher trust**: Trust all `/home/player/Desktop/*.desktop` files through the real player DBus session via `/usr/local/bin/trust-desktop-launchers`; use `tools/vm/repair-workstation-launchers.sh` for live VMs.
- **Docs drift**: some older roadmap/status docs may lag active implementation.

---

## 12. Anti-Patterns

- Do not fake SSH, terminals, or validation results for core gameplay.
- Do not validate quests by matching commands the player typed.
- Do not operate on non-`sc-` libvirt domains from game scripts.
- Do not mutate `content/` as runtime save state.
- Do not run quest-prep scripts against live player VMs unless explicitly intended.
- Do not write save JSON ad hoc; go through `SaveState.js`.
- Do not rely only on QEMU guest agent IP discovery.
- Do not place scratch files in the repo root.
- Do not turn this map into a changelog or README replacement.

---

## 13. Agent Workflow Notes

1. Start with this map.
2. Use hot paths to choose files.
3. Prefer symbol/search-based context over broad file loading.
4. Keep edits narrow.
5. Update this map only when structure, ownership, contracts, workflows, or known risk areas change.
6. Append a one-line changelog entry for meaningful updates.

---

## 14. Change Log

- 2026-04-30 Initial root map created; updated VM tooling notes for seed ISO detach and installer/rebuild image path normalization.
- 2026-05-02 Centralized internal HTTPS launch URLs/TLS env and workstation desktop launcher trust repair paths.