# Codex Guide

Workspace reference: [`GSP-WORKSPACE.md`](../../../GSP-WORKSPACE.md)

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/architecture/API_REFERENCE.md`
4. `docs/architecture/PANEL_AGENT_COMMANDS.md`
5. `docs/architecture/MODULE_DEPENDENCIES.md`
6. `docs/architecture/LIBRARY_REFERENCE.md`
7. `docs/modules/MODULE_INDEX.md`
8. `docs/modules/GAMEMANAGER.md`
9. `docs/features/STATUS_SYSTEM.md`
10. `docs/features/XML_SYSTEM.md`
11. `docs/modules/SCHEDULER.md`
12. `docs/features/SCHEDULER_ACTIONS.md`
13. `docs/modules/SERVER_CONTENT_MANAGER.md`
14. `docs/features/USER_API.md`
15. `docs/decisions/`
16. `docs/games/`

## 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/OGP64/OGP/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/OGP64/OGP/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/OGP64/OGP/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/OGP64/OGP/ogp_agent.pl`

### Decisions And Historical Reports

- `docs/architecture/AI_GSP_ARCHITECTURE.md`
- `docs/decisions/0001-screen-vs-tmux.md`
- `docs/decisions/0002-status-detection.md`
- `docs/decisions/0003-companion-programs.md`
- `docs/decisions/0004-workshop-system.md`
- `docs/decisions/0005-control-path-layout.md`
- `docs/decisions/0006-installers.md`
- `docs/decisions/COMPANION_PROGRAMS_DESIGN.md`
- `docs/decisions/SCHEDULER_ACTIONS_DESIGN.md`
- `docs/decisions/STEAM_WORKSHOP_DESIGN.md`
- `docs/development/GSP_PLATFORM_IMPROVEMENT_REPORT.md`

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

### Debug Panel or Agent updates

1. Read `docs/modules/UPDATE.md`.
2. Check `Panel/modules/update/update.php`.
3. Check `Panel/modules/administration/panel_update.php`.
4. Check `Panel/includes/lib_remote.php` for the `component_update` wrapper.
5. Check both `Agent_Linux/ogp_agent.pl` and `Agent-Windows/OGP64/OGP/ogp_agent.pl` for the `component_update` RPC.
6. Remember that local Panel/Website updates and remote agent updates both clone a configured Git branch into staging and copy only configured component folders.
7. Never let updater logic delete server homes, game install folders, user data, agent `Cfg/`, logs, uploads, backups, or runtime PID files.

## 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
- preserved investigation reports have been moved into the docs tree

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