Codex documentstion created

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
+

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

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