Codex documentstion created

2026-06-05 11:07:47 -05:00 · 2026-06-05 11:07:47 -05:00 · b5dcf01a8c
commit b5dcf01a8c
parent 3dc017421e
27 changed files with 6648 additions and 1069 deletions
--- a/docs/agents/LINUX_AGENT.md
+++ b/docs/agents/LINUX_AGENT.md
@ -0,0 +1,109 @@
+# Linux Agent
+
+## Role
+
+`Agent_Linux/ogp_agent.pl` is the Linux execution agent for GSP. It is responsible for:
+
+- starting and stopping game servers
+- managing `screen` sessions
+- reading logs
+- running update/install tasks
+- handling scheduler jobs
+- performing query checks and status checks
+
+## Important Files
+
+- `Agent_Linux/ogp_agent.pl`
+- `Agent_Linux/startups/`
+- `Agent_Linux/includes/`
+- `Agent_Linux/php-query/`
+- `Agent_Linux/Cfg/`
+- `Agent_Linux/Schedule/`
+- `Agent_Linux/steamcmd/`
+- `Agent_Linux/systemd/`
+
+## Startup Logic
+
+The Linux agent creates a managed `screen` session per server.
+
+Key flow in `ogp_agent.pl`:
+
+- `universal_start_without_decrypt`
+- `create_screen_cmd`
+- `create_screen_cmd_loop`
+- `replace_OGP_Env_Vars`
+
+The agent builds the startup command from:
+
+- the game XML template
+- server parameters
+- mod data
+- control password
+- path variables
+
+The session name follows the OGP naming convention, for example:
+
+```text
+OGP_HOME_000000123
+```
+
+## Status Logic
+
+Relevant functions:
+
+- `is_screen_running_without_decrypt`
+- `get_screen_pid_without_decrypt`
+- `server_status_without_decrypt`
+- `verify_server_stopped_without_decrypt`
+
+The status implementation should check:
+
+- screen/session existence
+- PID or child process information when available
+- whether the game port is listening
+- whether query metadata can be fetched
+
+Marker files such as `SERVER_STOPPED` should not be treated as the final source of truth.
+
+## Logging
+
+Relevant function:
+
+- `get_log`
+
+The agent reads screen logs and may also copy a local log file into the game home. Logs should be treated as runtime output, not as a state store.
+
+## Scheduler
+
+Linux scheduler functions live in `ogp_agent.pl`:
+
+- `scheduler_dispatcher`
+- `scheduler_server_action`
+- `scheduler_log_events`
+- `scheduler_add_task`
+- `scheduler_del_task`
+- `scheduler_edit_task`
+- `scheduler_read_tasks`
+- `scheduler_stop`
+- `scheduler_list_tasks`
+
+The scheduler is agent-driven. Panel pages create or edit jobs, but the agent executes them.
+
+## Configuration Files
+
+Useful configuration and runtime areas:
+
+- `Agent_Linux/Cfg/`
+- `Agent_Linux/startups/`
+- `Agent_Linux/steamcmd/`
+- `Agent_Linux/systemd/`
+
+The agent also maintains screen logs and helper scripts inside its runtime area.
+
+## Linux-Specific Notes
+
+- The Linux agent uses `screen` and `sudo_exec_without_decrypt`.
+- It can resolve server ownership and screen users via helper functions such as `find_user_by_screen_id`.
+- It must remain portable across distro variants, so avoid assuming one exact init system or one exact binary path.
+- For Windows-targeted games running under Linux, Wine-related path conversion appears in startup path handling.
+
--- a/docs/agents/WINDOWS_AGENT.md
+++ b/docs/agents/WINDOWS_AGENT.md
@ -0,0 +1,94 @@
+# Windows Agent
+
+## Role
+
+`Agent-Windows/ogp_agent.pl` is the Windows/Cygwin execution agent for GSP. It mirrors the Linux agent as closely as practical, while using Windows-compatible paths, processes, and wrappers.
+
+## Important Files
+
+- `Agent-Windows/ogp_agent.pl`
+- `Agent-Windows/php-query/`
+- `Agent-Windows/ArmaBE/`
+- `Agent-Windows/Cfg/`
+- `Agent-Windows/Install/`
+- `Agent-Windows/ServerFiles/`
+- `Agent-Windows/Schedule/`
+
+## Cygwin Requirements
+
+The Windows agent assumes a Cygwin-style environment that can provide:
+
+- `screen`
+- Perl
+- shell utilities such as `ps`, `grep`, `cut`, `awk`, `sed`
+- `cygpath`
+- a usable `bash`
+
+The goal is to keep the Windows agent behavior close to the Linux agent so the Panel does not need separate semantics for basic lifecycle operations.
+
+## Startup Logic
+
+Relevant functions:
+
+- `universal_start_without_decrypt`
+- `create_screen_cmd`
+- `create_screen_cmd_loop`
+- `replace_OGP_Env_Vars`
+
+The Windows agent also uses `screen` sessions for managed server execution. Depending on the game and binary type, it may wrap commands in `cmd /Q /C start` or run a batch file wrapper.
+
+The session naming scheme also follows the OGP convention:
+
+```text
+OGP_HOME_000000123
+```
+
+## Status Logic
+
+Relevant functions:
+
+- `is_screen_running_without_decrypt`
+- `get_screen_pid_without_decrypt`
+- `server_status_without_decrypt`
+- `verify_server_stopped_without_decrypt`
+
+The status model should check:
+
+- screen/session existence
+- process/PID information when available
+- game port listening
+- optional query metadata
+
+The old `SERVER_STOPPED` file should not be the source of truth.
+
+## Logging
+
+Relevant function:
+
+- `get_log`
+
+Windows/Cygwin logs come from screen logs and/or local copies. Log retrieval should remain compatible with the Panel's AJAX log view.
+
+## Scheduler
+
+Relevant functions:
+
+- `scheduler_dispatcher`
+- `scheduler_server_action`
+- `scheduler_log_events`
+- `scheduler_add_task`
+- `scheduler_del_task`
+- `scheduler_edit_task`
+- `scheduler_read_tasks`
+- `scheduler_stop`
+- `scheduler_list_tasks`
+
+The Windows scheduler implementation should remain aligned with the Linux scheduler implementation so the Panel can treat both the same way.
+
+## Windows-Specific Notes
+
+- Path conversion between Cygwin and native Windows paths matters during startup.
+- Batch wrappers are often needed for Windows executables.
+- Process cleanup must avoid killing unrelated processes that happen to share an executable name.
+- The agent should continue to use `screen` where it already does so, to stay aligned with Linux behavior.
+
--- a/docs/architecture/PANEL_AGENT_FLOW.md
+++ b/docs/architecture/PANEL_AGENT_FLOW.md
@ -0,0 +1,103 @@
+# Panel Agent Flow
+
+## Overview
+
+The Panel does not directly run servers. It prepares the request, sends it to the agent, and interprets the response.
+
+```text
+User action
+  -> Panel module page
+  -> OGPRemoteLibrary in lib_remote.php
+  -> XML-RPC request to agent /RPC2
+  -> ogp_agent.pl method
+  -> local screen/process/port work
+  -> return status or payload
+  -> Panel renders result
+```
+
+## Request Path
+
+Important Panel files:
+
+- `Panel/includes/lib_remote.php`
+- `Panel/modules/gamemanager/start_server.php`
+- `Panel/modules/gamemanager/stop_server.php`
+- `Panel/modules/gamemanager/restart_server.php`
+- `Panel/modules/gamemanager/server_monitor.php`
+- `Panel/modules/gamemanager/view_server_log.php`
+- `Panel/modules/gamemanager/get_server_log.php`
+- `Panel/modules/gamemanager/home_handling_functions.php`
+
+### Start
+
+1. Panel loads the selected server home and game XML.
+2. Panel composes startup parameters from stored values and XML templates.
+3. Panel calls `universal_start` on the agent.
+4. Agent creates the `screen` session and starts the server command.
+5. Panel polls `remote_server_status`.
+6. When the agent reports that the process/session exists and the game port listens, the server is treated as ONLINE.
+
+### Stop
+
+1. Panel calls `remote_stop_server`.
+2. Agent sends the configured graceful stop command if one exists.
+3. Agent watches the session/process and required port.
+4. If the session/process does not exit in time, the agent escalates to screen quit or process kill.
+5. Panel treats the server as stopped only when the agent confirms it is actually gone.
+
+### Restart
+
+Restart should be:
+
+```text
+stop
+  -> wait
+  -> start
+```
+
+The wait period should be explicit and visible in logs. Restart should not depend on marker files or query success.
+
+### Status
+
+1. Panel calls `remote_server_status`.
+2. Agent checks:
+   - managed screen/session
+   - PID or process tree when available
+   - required game port
+   - optional query/RCON ports
+3. Agent returns a structured status object.
+4. Panel maps the result to the UI state.
+
+### Logs
+
+1. Panel calls `get_log`.
+2. Agent returns the latest screen or console log data.
+3. The log view updates via AJAX instead of full-page refresh.
+4. The UI should preserve scroll position and only auto-scroll when the user is already at the bottom.
+
+## Data Returned by Status
+
+Recommended status fields:
+
+- `status`
+- `ready`
+- `process_running`
+- `session_running`
+- `game_port_listening`
+- `query_port_listening`
+- `rcon_port_listening`
+- `pid`
+- `session_name`
+- `ip`
+- `port`
+- `query_port`
+- `last_error`
+- optional query metadata
+
+## Practical Notes
+
+- The Panel should not mark a server failed only because query metadata was unavailable.
+- The agent should be the source of truth.
+- Marker files may exist, but they should be treated as hints only.
+- The same high-level flow should work for Linux and Windows/Cygwin.
+
--- a/docs/architecture/REPOSITORY_OVERVIEW.md
+++ b/docs/architecture/REPOSITORY_OVERVIEW.md
@ -0,0 +1,159 @@
+# Repository Overview
+
+## Purpose
+
+This repository contains the GSP game server hosting platform:
+
+- `Panel` - the web control panel and customer/admin UI.
+- `Agent_Linux` - the Linux agent that starts, stops, monitors, updates, and logs game servers.
+- `Agent-Windows` - the Windows/Cygwin agent that mirrors the Linux agent as closely as possible.
+- `Website` - the public marketing, customer, and commerce site.
+
+## Top-Level Layout
+
+```text
+/
+  Agent_Linux/
+  Agent-Windows/
+  Panel/
+  Website/
+  docs/
+```
+
+## Major Components
+
+### Panel
+
+The Panel is the orchestration layer. It:
+
+- loads module pages from `Panel/modules/*`
+- talks to agents through `Panel/includes/lib_remote.php`
+- stores panel-side state in the database
+- renders server lifecycle, file, backup, scheduler, Workshop, support, and billing pages
+
+Important Panel files:
+
+- `Panel/includes/lib_remote.php`
+- `Panel/modules/gamemanager/home_handling_functions.php`
+- `Panel/modules/gamemanager/server_monitor.php`
+- `Panel/modules/config_games/schema_server_config.xml`
+- `Panel/modules/addonsmanager/module.php`
+- `Panel/modules/cron/module.php`
+- `Panel/modules/user_games/module.php`
+
+### Agents
+
+The agents are the execution layer. They:
+
+- launch game servers inside `screen`
+- stop and restart servers
+- read logs
+- run updates and install jobs
+- execute scheduler jobs
+- report status back to the Panel
+
+Important agent files:
+
+- `Agent_Linux/ogp_agent.pl`
+- `Agent-Windows/ogp_agent.pl`
+- `Agent_Linux/startups/`
+- `Agent-Windows/ServerFiles/`
+- `Agent_Linux/php-query/`
+- `Agent-Windows/php-query/`
+
+### Website
+
+The Website is separate from the server runtime path. It is used for:
+
+- public product pages
+- documentation links
+- customer onboarding
+- billing and commerce surfaces
+
+## Panel <-> Agent Communication
+
+The Panel uses XML-RPC over HTTP to call methods exposed by `ogp_agent.pl`.
+
+The remote wrapper lives in:
+
+- `Panel/includes/lib_remote.php`
+
+The most important calls are:
+
+- `universal_start`
+- `remote_stop_server`
+- `remote_restart_server`
+- `remote_server_status`
+- `is_screen_running`
+- `get_log`
+- `remote_query`
+- scheduler methods
+
+The agents decode the request, execute the action locally, and return a status code or payload.
+
+## Database Usage
+
+The Panel database stores:
+
+- server homes and assigned ports
+- game definitions and mod mappings
+- user permissions and subusers
+- scheduler definitions and related data
+- content and Workshop metadata
+- tickets/support records
+- billing and provisioning records
+
+Key tables discovered in current code:
+
+- `server_homes`
+- `home_ip_ports`
+- `game_mods`
+- `status_cache`
+- `config_homes`
+- `config_mods`
+- `addons`
+- `server_content_workshop`
+- `server_content_manifest`
+- `server_content_install_history`
+- `tickets`
+- `ticket_messages`
+- `ticket_attachments`
+- `ticket_settings`
+- billing-related tables in `Panel/modules/billing`
+
+The agents also keep runtime files such as screen logs, update logs, scheduler state, and helper manifests, but those should be treated as runtime state rather than the source of truth.
+
+## Startup Flow
+
+1. User clicks start in the Panel.
+2. Panel builds the startup command from the game XML and stored server parameters.
+3. Panel sends `universal_start` to the agent.
+4. Agent creates a `screen` session and launches the server command.
+5. Panel polls status and logs.
+6. If the managed session exists and the required port listens, the server is considered online.
+
+## Status Reporting Flow
+
+The desired status flow is:
+
+```text
+Panel asks agent for status
+  -> agent checks managed session/process
+  -> agent checks required listening port
+  -> agent optionally performs query metadata lookup
+  -> agent returns structured status
+  -> Panel renders ONLINE / STARTING / STOPPING / UNRESPONSIVE / OFFLINE / UNKNOWN
+```
+
+Query results are metadata only. They are not the source of truth for online/offline state.
+
+## What To Read First
+
+For future investigations, start with:
+
+1. `docs/development/CODEX_GUIDE.md`
+2. `docs/architecture/PANEL_AGENT_FLOW.md`
+3. `docs/modules/GAMEMANAGER.md`
+4. `docs/features/STATUS_SYSTEM.md`
+5. `docs/features/XML_SYSTEM.md`
+
--- a/docs/development/CODEX_GUIDE.md
+++ b/docs/development/CODEX_GUIDE.md
@ -0,0 +1,138 @@
+# Codex Guide
+
+This file is the first stop for future Codex sessions working in this repository.
+
+## Repository Layout
+
+```text
+/
+  Agent_Linux/
+  Agent-Windows/
+  Panel/
+  Website/
+  docs/
+```
+
+## What To Read First
+
+1. `docs/architecture/REPOSITORY_OVERVIEW.md`
+2. `docs/architecture/PANEL_AGENT_FLOW.md`
+3. `docs/modules/MODULE_INDEX.md`
+4. `docs/modules/GAMEMANAGER.md`
+5. `docs/features/STATUS_SYSTEM.md`
+6. `docs/features/XML_SYSTEM.md`
+7. `docs/modules/SCHEDULER.md`
+8. `docs/modules/SERVER_CONTENT_MANAGER.md`
+
+## Important Files By Topic
+
+### Startup Logic
+
+- `Panel/modules/gamemanager/home_handling_functions.php`
+- `Panel/modules/gamemanager/start_server.php`
+- `Panel/modules/gamemanager/restart_server.php`
+- `Panel/modules/config_games/schema_server_config.xml`
+- `Panel/modules/config_games/server_config_parser.php`
+- `Panel/includes/lib_remote.php`
+- `Agent_Linux/ogp_agent.pl`
+- `Agent-Windows/ogp_agent.pl`
+
+### Status Logic
+
+- `Panel/includes/lib_remote.php`
+- `Panel/modules/gamemanager/home_handling_functions.php`
+- `Panel/modules/gamemanager/server_monitor.php`
+- `Agent_Linux/ogp_agent.pl`
+- `Agent-Windows/ogp_agent.pl`
+
+### Scheduler Logic
+
+- `Panel/modules/cron/module.php`
+- `Panel/modules/cron/cron.php`
+- `Panel/modules/cron/shared_cron_functions.php`
+- `Agent_Linux/ogp_agent.pl`
+- `Agent-Windows/ogp_agent.pl`
+
+### Workshop / Server Content Logic
+
+- `Panel/modules/addonsmanager/module.php`
+- `Panel/modules/addonsmanager/addons_manager.php`
+- `Panel/modules/addonsmanager/user_addons.php`
+- `Panel/modules/addonsmanager/workshop_content.php`
+- `Panel/modules/addonsmanager/workshop_action.php`
+- `Panel/modules/steam_workshop/module.php`
+
+### XML Definitions
+
+- `Panel/modules/config_games/schema_server_config.xml`
+- `Panel/modules/config_games/xml_config_creator.php`
+- `Panel/modules/config_games/set_params.php`
+- `Panel/modules/config_games/cli-params.php`
+- `Panel/modules/config_games/config_servers.php`
+
+### Agent Communication
+
+- `Panel/includes/lib_remote.php`
+- `Agent_Linux/ogp_agent.pl`
+- `Agent-Windows/ogp_agent.pl`
+
+## Common Development Workflows
+
+### Debug a start/stop/restart issue
+
+1. Read `docs/modules/GAMEMANAGER.md`.
+2. Check `Panel/includes/lib_remote.php`.
+3. Check `Panel/modules/gamemanager/home_handling_functions.php`.
+4. Check the matching `ogp_agent.pl`.
+5. Compare session/process/port logic in both agents.
+
+### Debug a status issue
+
+1. Read `docs/features/STATUS_SYSTEM.md`.
+2. Check `remote_server_status` in `Panel/includes/lib_remote.php`.
+3. Check `server_status_without_decrypt` in both agents.
+4. Check game XML query definitions in `config_games`.
+
+### Debug scheduler behavior
+
+1. Read `docs/modules/SCHEDULER.md`.
+2. Check `Panel/modules/cron/cron.php`.
+3. Check scheduler subroutines in both agents.
+4. Verify whether the action is customer-safe or admin-only.
+
+### Debug Workshop or add-on behavior
+
+1. Read `docs/modules/SERVER_CONTENT_MANAGER.md`.
+2. Check `Panel/modules/addonsmanager/module.php`.
+3. Check the user/admin content pages.
+4. Check whether the action should be treated as install, update, or uninstall.
+
+## Things Already Investigated
+
+The repository has already been mapped in these areas:
+
+- module inventory
+- panel-agent remote library
+- Linux and Windows agent `screen` use
+- status model direction
+- game XML startup and query variables
+- current Server Content Manager structure
+- current scheduler structure
+- module-level roles and dependency patterns
+
+## Things Intentionally Not Yet Implemented
+
+This documentation-only pass does not implement:
+
+- lifecycle code changes
+- status model code changes
+- scheduler redesign
+- Workshop/content redesign
+- backup system replacement
+- file manager or FTP rewrites
+- billing/provisioning changes
+
+## Practical Rule for Future Sessions
+
+Before scanning code broadly, read the docs layer first. Only open source files when the documentation does not already answer the question.
+
--- a/docs/features/STATUS_SYSTEM.md
+++ b/docs/features/STATUS_SYSTEM.md
@ -0,0 +1,54 @@
+# Status System
+
+## Current Goal
+
+The status system should tell the truth about a server's state without depending on stale marker files or query success alone.
+
+## Current Direction
+
+The current codebase is moving toward agent-owned structured status.
+
+Important files:
+
+- `Panel/includes/lib_remote.php`
+- `Panel/modules/gamemanager/home_handling_functions.php`
+- `Panel/modules/gamemanager/server_monitor.php`
+- `Agent_Linux/ogp_agent.pl`
+- `Agent-Windows/ogp_agent.pl`
+
+## Recommended State Model
+
+| State | Meaning |
+|---|---|
+| `OFFLINE` | No managed session/process and no required port listening. |
+| `STARTING` | Managed session/process exists but the required port is not ready yet. |
+| `ONLINE` | Managed session/process exists and the required port is listening. |
+| `STOPPING` | Stop is in progress and the session/process still exists. |
+| `UNRESPONSIVE` | The server did not become ready in time or stop did not complete cleanly. |
+| `UNKNOWN` | The agent cannot be reached or cannot determine state. |
+
+## What Should Be Checked
+
+The agent should check, in this order:
+
+1. managed session or screen name
+2. process or PID tree when available
+3. required game port listening
+4. optional query/RCON port listening
+5. optional query metadata
+
+## Known Problems To Remember
+
+- LGSL/GameQ may fail for supported games, blocked ports, or slow startups.
+- Marker files can become stale after crashes or power loss.
+- A game can be online even if query metadata is temporarily unavailable.
+- Some games need long startup windows, so timeouts must be configurable per game.
+
+## Planned Improvement Shape
+
+- make the agent the source of truth
+- preserve optional query metadata
+- use state hints for start/stop transitions
+- expose clear messages for `STARTING` and `UNRESPONSIVE`
+- add precise log excerpts when startup fails
+
--- a/docs/features/WORKSHOP_SYSTEM.md
+++ b/docs/features/WORKSHOP_SYSTEM.md
@ -0,0 +1,53 @@
+# Workshop System
+
+## Current State
+
+The current Workshop/content work is split across two module lines:
+
+- `Panel/modules/steam_workshop` - deprecated compatibility layer
+- `Panel/modules/addonsmanager` - the active Server Content Manager path
+
+Important files:
+
+- `Panel/modules/addonsmanager/module.php`
+- `Panel/modules/addonsmanager/user_addons.php`
+- `Panel/modules/addonsmanager/addons_manager.php`
+- `Panel/modules/addonsmanager/workshop_content.php`
+- `Panel/modules/addonsmanager/workshop_action.php`
+- `Panel/modules/steam_workshop/module.php`
+- `Panel/modules/steam_workshop/agent_update_workshop.php`
+
+## What Exists Today
+
+The current direction already supports:
+
+- content records in the Panel database
+- Workshop item IDs
+- installation metadata
+- install history tables
+- game compatibility fields
+- launch parameter additions
+- post-install behavior fields
+
+## Main Limitations
+
+- Workshop metadata is still incomplete.
+- load order is not yet a full first-class UX concept.
+- update/uninstall/enable/disable flows need a cleaner product model.
+- DayZ/Arma-specific folder and key-copy behavior needs a stronger canonical path.
+- caching and cleanup policy need product-level design, not just ad hoc scripts.
+
+## Recommended Mental Model
+
+Use `addonsmanager` as the main future home for:
+
+- mods
+- add-ons
+- Workshop items
+- scripts
+- config packs
+- server content manifests
+- install history
+
+Treat `steam_workshop` as a legacy bridge for migration only.
+
--- a/docs/features/XML_SYSTEM.md
+++ b/docs/features/XML_SYSTEM.md
@ -0,0 +1,105 @@
+# XML Game Configuration System
+
+## Purpose
+
+The XML game configuration system describes how a game server should be started, queried, and customized.
+
+Primary files:
+
+- `Panel/modules/config_games/schema_server_config.xml`
+- `Panel/modules/config_games/server_config_parser.php`
+- `Panel/modules/config_games/xml_config_creator.php`
+- `Panel/modules/config_games/config_servers.php`
+- `Panel/modules/config_games/cli-params.php`
+- `Panel/modules/config_games/set_params.php`
+
+## What XML Controls
+
+The schema supports:
+
+- game and installer names
+- startup command templates
+- CLI parameter substitution
+- reserved ports
+- query port calculation
+- control protocol selection
+- mod definitions
+- custom fields
+- server parameter groups
+- text replacement helpers
+
+## Important Variables
+
+The schema and startup builder can work with variables such as:
+
+- `GAME_TYPE`
+- `HOSTNAME`
+- `IP`
+- `MAP`
+- `PID_FILE`
+- `PLAYERS`
+- `PORT`
+- `QUERY_PORT`
+- `BASE_PATH`
+- `HOME_PATH`
+- `SAVE_PATH`
+- `OUTPUT_PATH`
+- `USER_PATH`
+- `CONTROL_PASSWORD`
+
+## Startup Parameters
+
+The Panel builds startup parameters from the XML template and the stored server configuration.
+
+Key concepts:
+
+- `cli_template`
+- `cli_params`
+- `reserve_ports`
+- `server_params`
+- `custom_fields`
+- `clean_server_param_value`
+
+The XML file defines:
+
+- which parameters exist
+- how they are quoted or spaced
+- whether the parameter is editable by the customer
+- what defaults should be used
+
+## Query Definitions
+
+The XML schema supports query-related concepts such as:
+
+- `gameq`
+- `lgsl`
+- `teamspeak3`
+- query port offset calculations
+- control protocol selection
+
+These values are used by `gamemanager` and the agent status logic to calculate query metadata, not to decide online/offline by themselves.
+
+## Installation and File Editing
+
+XML definitions also feed:
+
+- config file shortcuts
+- install-time behavior
+- docs links
+- reserved ports
+- mod or content behavior
+
+## Recommended Mental Model
+
+Think of the XML system as the capability definition layer:
+
+```text
+game XML
+  -> startup template
+  -> parameter rules
+  -> query rules
+  -> content/mod hooks
+  -> docs links
+  -> scheduler and status hints
+```
+
--- a/docs/modules/GAMEMANAGER.md
+++ b/docs/modules/GAMEMANAGER.md
@ -0,0 +1,82 @@
+# GameManager
+
+## Role
+
+`Panel/modules/gamemanager` is the core customer server control module. It owns:
+
+- start
+- stop
+- restart
+- logs
+- server monitor
+- update flow hooks
+- RCON integration
+- status display
+
+## Important Files
+
+- `Panel/modules/gamemanager/module.php`
+- `Panel/modules/gamemanager/home_handling_functions.php`
+- `Panel/modules/gamemanager/server_monitor.php`
+- `Panel/modules/gamemanager/start_server.php`
+- `Panel/modules/gamemanager/stop_server.php`
+- `Panel/modules/gamemanager/restart_server.php`
+- `Panel/modules/gamemanager/log.php`
+- `Panel/modules/gamemanager/view_server_log.php`
+- `Panel/modules/gamemanager/get_server_log.php`
+- `Panel/modules/gamemanager/update_server.php`
+
+## Start / Stop / Restart
+
+The module calls the agent through `Panel/includes/lib_remote.php`.
+
+Current shape:
+
+- start -> `universal_start`
+- stop -> `remote_stop_server`
+- restart -> `remote_restart_server`
+
+The right behavior is:
+
+- start shows `STARTING` as soon as the managed session exists
+- online status requires the process/session plus the game port
+- restart should be stop, wait, start
+- stop should not be treated as complete until the session/process is actually gone
+
+## Status Reporting
+
+The current flow now points toward agent-truth status reporting via:
+
+- `remote_server_status`
+- `get_agent_server_status` in `home_handling_functions.php`
+- `server_status_without_decrypt` in both agents
+
+Useful state labels:
+
+- `OFFLINE`
+- `STARTING`
+- `ONLINE`
+- `STOPPING`
+- `UNRESPONSIVE`
+- `UNKNOWN`
+
+Query checks should remain optional metadata only.
+
+## Log Viewer
+
+Relevant files:
+
+- `Panel/modules/gamemanager/log.php`
+- `Panel/modules/gamemanager/view_server_log.php`
+- `Panel/modules/gamemanager/get_server_log.php`
+
+The log view should be treated as live, AJAX-updated output rather than a full page reload workflow.
+
+## What This Module Depends On
+
+- `config_games` for startup parameters and protocol definitions
+- `lib_remote.php` for agent calls
+- `user_games` for server home records
+- `rcon` for command support where available
+- `addonsmanager` for content/mod interactions
+
--- a/docs/modules/MODULE_INDEX.md
+++ b/docs/modules/MODULE_INDEX.md
@ -0,0 +1,68 @@
+# Module Index
+
+This is the current Panel module inventory. It is intentionally concise so future Codex sessions can decide which module to inspect in code.
+
+| Module | Purpose | Current State | Dependencies | Notes |
+|---|---|---|---|---|
+| `TS3Admin` | Teamspeak 3 admin interface | Required, legacy niche | TS3 admin files | Keep if TS3 hosting is sold. |
+| `addonsmanager` | Server Content Manager | Required, actively evolving | DB tables, game XML, agent install scripts | Best current home for mods, add-ons, Workshop, and content installs. |
+| `administration` | Admin utilities | Required | Core admin pages | Includes logger/watch tools. |
+| `backup-restore` | Backup/restore UI | Optional, broken/testing | Hard-coded backup host/path logic | Hide until replaced. |
+| `billing` | Billing, provisioning, commerce | Optional, large custom module | Payment gateways, invoices, shop/provisioning docs | Important for commercial hosting. |
+| `circular` | Notification/circular messages | Optional | Panel UI | Good candidate for maintenance and announcement notices. |
+| `config_games` | Game XML definitions and CLI builder | Required | XML schema/parser | Critical for startup templates, queries, custom fields, and game capabilities. |
+| `cron` | Scheduler / CRON | Required | Agent scheduler methods, Panel action selection | Needs safe action registry and task history. |
+| `dashboard` | Main landing dashboard | Required | Panel auth and server summaries | Should surface status, support, billing, and alerts. |
+| `dsi` | Dynamic Server Image | Optional | Game imagery and cached assets | Useful for server cards and branding. |
+| `editconfigfiles` | Config file shortcuts | Optional | Game config metadata | Good for surfacing common editable files. |
+| `faq` | FAQ/help | Required | Site docs/content | Should link to game docs and common workflows. |
+| `fast_download` | FastDL support | Required | Source/GoldSrc-style web distribution | Still useful for older Source engine communities. |
+| `ftp` | FTP admin | Required | File transfer service, access rights | Needs security review but remains important. |
+| `gamemanager` | Server monitor, lifecycle, logs, RCON | Required | Agent RPC, game XML, query libraries | Core customer workflow module. |
+| `lgsl_with_img_mod` | LGSL server status images | Optional legacy | Query/image cache data | Secondary to agent truth. |
+| `litefm` | In-panel file manager | Required | File system access rights | Should be the preferred in-panel file tool. |
+| `lostpwd` | Password recovery | Required | Auth/account flow | Basic account support. |
+| `modulemanager` | Module installation/configuration | Required | Module metadata | Admin maintenance tool. |
+| `mysql` | MySQL hosting/admin | Required | MySQL service setup | Good future product tie-in for databases. |
+| `news` | Legacy news/announcements | Optional legacy | Old CMS-like data | Consider hiding unless modernized. |
+| `rcon` | RCON admin tool | Required | Server protocol support | Useful for commands, warnings, and scheduler integration. |
+| `register` | Account registration | Required | Auth flow | Basic customer onboarding. |
+| `server` | Server manager | Required | Agent/node management | Admin-facing node controls. |
+| `settings` | Global settings | Required | Auth, site config | Admin configuration area. |
+| `status` | Status page | Optional alpha | Status data | Not ready for customer-facing critical use. |
+| `steam_workshop` | Legacy Workshop module | Optional deprecated | Workshop DB helpers | Hidden/deprecated in favor of `addonsmanager`. |
+| `subusers` | Subuser permissions | Required | Authorization model | Important for commercial teams and communities. |
+| `support` | Support landing page | Required | Ticketing/docs | Better as an entry point than the full ticket workflow. |
+| `teamspeak3` | Teamspeak 3 web interface | Required if sold | TS3 service | Hide if not part of the product offering. |
+| `tickets` | Support ticket system | Optional but useful | DB tables, attachments, notifications | Stronger support workflow than `support` alone. |
+| `tshock` | Terraria/TShock utilities | Optional niche | Terraria/TShock game support | Expose only for supported games. |
+| `update` | Panel updates | Required admin tool | Patch/update system | Admin-only maintenance. |
+| `user_admin` | User management | Required | Auth/admin roles | Important for staff administration. |
+| `user_games` | Server provisioning and assignment | Required | Game homes, ports, billing integration | Core provisioning path. |
+| `util` | Utility tools | Required | Misc tools | Keep useful tools, hide legacy helpers that are not maintained. |
+
+## Dependency Notes
+
+Common dependencies across many modules:
+
+- `includes/lib_remote.php`
+- auth/session and role checks
+- `config_games` XML parsing
+- DB access helpers
+- server home and IP/port records
+
+## High-Value Modules
+
+The modules most likely to matter in future investigations are:
+
+1. `gamemanager`
+2. `config_games`
+3. `user_games`
+4. `addonsmanager`
+5. `cron`
+6. `litefm`
+7. `ftp`
+8. `billing`
+9. `tickets`
+10. `subusers`
+
--- a/docs/modules/SCHEDULER.md
+++ b/docs/modules/SCHEDULER.md
@ -0,0 +1,96 @@
+# Scheduler
+
+## Current Implementation
+
+The scheduler lives in the `cron` module on the Panel and in scheduler methods inside the agents.
+
+Important files:
+
+- `Panel/modules/cron/module.php`
+- `Panel/modules/cron/cron.php`
+- `Panel/modules/cron/shared_cron_functions.php`
+- `Agent_Linux/ogp_agent.pl`
+- `Agent-Windows/ogp_agent.pl`
+
+## How It Works Today
+
+The Panel builds cron-like jobs and sends them to the agent using RPC methods such as:
+
+- `scheduler_add_task`
+- `scheduler_edit_task`
+- `scheduler_del_task`
+- `scheduler_list_tasks`
+- `scheduler_read_tasks`
+
+The agent stores and executes the tasks locally.
+
+## Current Task Model
+
+Current jobs are built as cron expressions plus a command string.
+
+The command can be:
+
+- a safe predefined server action
+- an update-related action
+- a server content action
+- a raw admin command
+
+## Scheduled Actions Observed
+
+From the current codebase and related Server Content work, the action set includes:
+
+- restart server
+- stop server
+- start server
+- Steam auto update
+- server content update checks
+- server content install/update actions
+- validate files
+- backup before update
+- notify-only update flow
+
+## Problems With the Current Design
+
+- The task model is not strongly typed.
+- Customer-safe and admin-only actions are too easy to blur together.
+- Task output and run history are not user-friendly enough.
+- The agent is the executor, but the Panel needs a better task record and result view.
+- Overlap/conflict rules are not explicit.
+- Missed-task behavior after reboot should be documented and normalized.
+
+## Recommended Next-Step Shape
+
+Use typed actions instead of raw command strings for customer-facing scheduler tasks.
+
+Suggested fields:
+
+- action key
+- display name
+- role
+- arguments
+- timeout
+- retry behavior
+- conflict rules
+- log policy
+
+## Agent Interaction Pattern
+
+```text
+Panel schedules task
+  -> Panel stores intent and UI data
+  -> Panel sends job to agent
+  -> agent writes/loads scheduler state
+  -> agent executes action at the right time
+  -> agent logs result
+  -> Panel reads back task state
+```
+
+## What To Inspect in Code
+
+If scheduler behavior needs deeper investigation, start with:
+
+- `Panel/modules/cron/cron.php`
+- `Panel/modules/cron/shared_cron_functions.php`
+- `Agent_Linux/ogp_agent.pl` scheduler subroutines
+- `Agent-Windows/ogp_agent.pl` scheduler subroutines
+
--- a/docs/modules/SERVER_CONTENT_MANAGER.md
+++ b/docs/modules/SERVER_CONTENT_MANAGER.md
@ -0,0 +1,70 @@
+# Server Content Manager
+
+## Current State
+
+`Panel/modules/addonsmanager` is the current home of GSP's Server Content / Add-ons / Workshop work.
+
+The module title has already been moved toward `Server Content Manager`, but the schema and some folder names remain backward-compatible.
+
+Important files:
+
+- `Panel/modules/addonsmanager/module.php`
+- `Panel/modules/addonsmanager/addons_manager.php`
+- `Panel/modules/addonsmanager/user_addons.php`
+- `Panel/modules/addonsmanager/workshop_content.php`
+- `Panel/modules/addonsmanager/workshop_action.php`
+- `Panel/modules/addonsmanager/server_content_helpers.php`
+- `Panel/modules/addonsmanager/server_content_categories.php`
+
+## Database Tables
+
+Known tables used by the module:
+
+- `addons`
+- `server_content_workshop`
+- `server_content_manifest`
+- `server_content_install_history`
+
+## What It Already Does
+
+The module can already represent several content types, including:
+
+- downloads/extracted packages
+- post-script driven installs
+- workshop-oriented items
+- config packs
+- future profile-type content
+
+For Workshop items, the current flow lets users enter IDs and routes the install through module pages and agent-side scripts.
+
+## Current Limitations
+
+- Workshop and content metadata is still partial.
+- Load order and enable/disable behavior need a cleaner first-class model.
+- Async install job progress should be more visible.
+- Install strategies are still being broadened and need consistent game-specific rules.
+- DayZ/Arma style key-copy and startup-param behavior needs a stronger canonical implementation.
+- Cache and cleanup policy need a clearer product design.
+
+## Where To Start Reading
+
+1. `Panel/modules/addonsmanager/module.php`
+2. `Panel/modules/addonsmanager/addons_manager.php`
+3. `Panel/modules/addonsmanager/user_addons.php`
+4. `Panel/modules/addonsmanager/workshop_content.php`
+5. `Panel/modules/addonsmanager/workshop_action.php`
+
+## Important Concept
+
+This module is the right place for:
+
+- mods
+- add-ons
+- Workshop content
+- config packs
+- script-driven installs
+- server content manifests
+- install history
+
+The old `steam_workshop` module should be treated as a deprecated compatibility layer, not the main future path.
+