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.