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
+