Codex documentstion created

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.
+

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.
+