complete codex docs

README.md

@@ -0,0 +1,112 @@
+# GSP
+
+GSP is a game server hosting platform built around a web Panel, Linux and Windows/Cygwin agents, and a customer Website.
+
+The goal of this repository is to let customers manage hosted game servers with the same practical control they would expect on their own machine:
+
+- start, stop, restart, and monitor servers
+- edit config files and startup parameters
+- use FTP and file management tools
+- install mods, add-ons, and Workshop content
+- schedule safe automation tasks
+- read logs and troubleshooting docs
+- get accurate server status reporting
+- keep billing, support, and provisioning tied to the server lifecycle
+
+## Repository Layout
+
+```text
+/
+  Agent_Linux/
+  Agent-Windows/
+  Panel/
+  Website/
+  docs/
+```
+
+## Component Overview
+
+### Panel
+
+The Panel is the control layer. It loads modules from `Panel/modules/`, stores panel-side state in the database, and talks to the agents through `Panel/includes/lib_remote.php`.
+
+### Linux Agent
+
+`Agent_Linux/ogp_agent.pl` launches and monitors game servers on Linux, using `screen` as the shared runtime backend.
+
+### Windows Agent
+
+`Agent-Windows/ogp_agent.pl` mirrors the Linux agent as closely as possible for Windows/Cygwin environments.
+
+### Website
+
+`Website/` is the public-facing site for product information, onboarding, docs, and commerce.
+
+## Documentation Overview
+
+Start with:
+
+- [docs/development/CODEX_GUIDE.md](docs/development/CODEX_GUIDE.md)
+- [docs/architecture/REPOSITORY_OVERVIEW.md](docs/architecture/REPOSITORY_OVERVIEW.md)
+- [docs/architecture/PANEL_AGENT_FLOW.md](docs/architecture/PANEL_AGENT_FLOW.md)
+- [docs/architecture/API_REFERENCE.md](docs/architecture/API_REFERENCE.md)
+- [docs/modules/MODULE_INDEX.md](docs/modules/MODULE_INDEX.md)
+- [docs/features/STATUS_SYSTEM.md](docs/features/STATUS_SYSTEM.md)
+- [docs/features/XML_SYSTEM.md](docs/features/XML_SYSTEM.md)
+- [docs/features/WORKSHOP_SYSTEM.md](docs/features/WORKSHOP_SYSTEM.md)
+- [docs/features/SCHEDULER_SYSTEM.md](docs/features/SCHEDULER_SYSTEM.md)
+
+Additional architecture and decision records:
+
+- [docs/architecture/AI_GSP_ARCHITECTURE.md](docs/architecture/AI_GSP_ARCHITECTURE.md)
+- [docs/decisions/](docs/decisions/)
+- [docs/development/GSP_PLATFORM_IMPROVEMENT_REPORT.md](docs/development/GSP_PLATFORM_IMPROVEMENT_REPORT.md)
+
+## Development Workflow
+
+1. Read the docs first.
+2. Find the relevant module, agent, or feature page.
+3. Inspect code only where the docs point you.
+4. Keep changes scoped to the module you are working on.
+5. Prefer safe, structured interfaces over ad hoc shell commands.
+6. Verify behavior in both Panel and agent paths when lifecycle or content flow is affected.
+
+## Branch Strategy
+
+Use a simple stable vs unstable model:
+
+- `stable` or release branches should only contain verified customer-facing behavior.
+- `unstable` or feature branches should hold active work, investigations, and partially complete features.
+
+If the repo uses different branch names in practice, keep the same concept:
+
+- stable = customer-ready
+- unstable = in progress
+
+## Stable vs Unstable
+
+Stable code should have:
+
+- accurate lifecycle and status reporting
+- working logs
+- safe file and FTP access
+- working scheduler actions
+- working backups and restore paths
+- documented Workshop/content flows
+
+Unstable code may exist for:
+
+- experimental features
+- partial module migrations
+- new XML capabilities
+- future improvements that are not yet customer-safe
+
+## Documentation Map
+
+- Architecture: `docs/architecture/`
+- Agents: `docs/agents/`
+- Games: `docs/games/`
+- Modules: `docs/modules/`
+- Features: `docs/features/`
+- Decisions: `docs/decisions/`
+- Development notes: `docs/development/`