docs

OGP64/OGP/documentation/agent-guide.md

@@ -2,6 +2,8 @@
 
 This Markdown file mirrors the internal WDS wiki instructions so you can ship it with release archives or import it into any other knowledge base.
 
+Workspace reference: [`GSP-WORKSPACE.md`](../../../../GSP-WORKSPACE.md)
+
 ## Purpose
 
 The Windows agent bundles Cygwin, Perl, GNU Screen, and helper scripts so the GameServer Panel can manage Windows Server 2019/2022 game hosts. It exposes the same RPC surface as the Linux agent and expects the same shared key.

README.md

@@ -0,0 +1,40 @@
+# GSP Windows Agent
+
+Cygwin-based packaging tree for the GSP Windows agent. The maintained runtime lives under `OGP64/`, which contains the Cygwin environment, the bundled OGP Perl agent, startup scripts, and supporting files.
+
+Workspace reference: [`GSP-WORKSPACE.md`](../GSP-WORKSPACE.md)
+
+## What this repository owns
+
+- Windows/Cygwin agent packaging
+- startup and stop scripts
+- bundled runtime files for the OGP Perl agent
+- Windows-specific installation and update helpers
+- Windows agent documentation
+
+## Runtime model
+
+The Windows agent mirrors the Linux agent as closely as practical while using Cygwin to provide the command and process model expected by the OGP Perl agent.
+
+## Important paths
+
+| Path | Purpose |
+| --- | --- |
+| `OGP64/` | Cygwin root and runtime bundle |
+| `OGP64/OGP/ogp_agent.pl` | Core Windows agent Perl service |
+| `OGP64/agent_start.bat` | Root launcher used to start the agent manually |
+| `OGP64/agent_stop.bat` | Root launcher used to stop the agent manually |
+| `OGP64/OGP/Cfg/` | Runtime config and template files |
+
+## Documentation entry points
+
+- [`docs/AGENT_ARCHITECTURE.md`](docs/AGENT_ARCHITECTURE.md)
+- [`docs/CYGWIN_INTEGRATION.md`](docs/CYGWIN_INTEGRATION.md)
+- [`docs/COMMAND_EXECUTION.md`](docs/COMMAND_EXECUTION.md)
+- [`docs/PROCESS_MANAGEMENT.md`](docs/PROCESS_MANAGEMENT.md)
+- [`docs/PANEL_INTEGRATION.md`](docs/PANEL_INTEGRATION.md)
+
+## Related documentation
+
+- [`OGP64/OGP/README.md`](OGP64/OGP/README.md)
+- [`OGP64/OGP/documentation/agent-guide.md`](OGP64/OGP/documentation/agent-guide.md)

docs/AGENT_ARCHITECTURE.md

@@ -0,0 +1,27 @@
+# GSP Windows Agent Architecture
+
+Workspace reference: [`GSP-WORKSPACE.md`](../../GSP-WORKSPACE.md)
+
+This repository owns the Windows execution engine for GSP.
+
+## Responsibilities
+
+- expose the same agent RPC surface as the Linux agent
+- launch and monitor customer game servers on Windows
+- manage lifecycle operations using Cygwin-compatible tooling
+- execute panel-approved commands and scripts
+- return logs, status, and command results
+
+## Primary runtime pieces
+
+| Path | Purpose |
+| --- | --- |
+| `OGP64/bin/` | Cygwin runtime binaries |
+| `OGP64/OGP/ogp_agent.pl` | Core OGP Perl agent |
+| `OGP64/agent_start.bat` | Manual startup launcher |
+| `OGP64/agent_stop.bat` | Manual shutdown launcher |
+| `OGP64/OGP/Cfg/` | Runtime configuration and templates |
+
+## Design rule
+
+Keep the Windows agent behavior as close to Linux as possible, but isolate unavoidable platform differences in the Windows layer.

docs/COMMAND_EXECUTION.md

@@ -0,0 +1,25 @@
+# GSP Windows Agent Command Execution
+
+Workspace reference: [`GSP-WORKSPACE.md`](../../GSP-WORKSPACE.md)
+
+The Panel sends remote requests to the Windows agent. The agent translates those requests into local actions inside the Cygwin runtime.
+
+## Execution model
+
+1. Receive a panel request.
+2. Validate the request.
+3. Run the requested command or lifecycle action through the agent runtime.
+4. Capture output and exit status.
+5. Return the result to the Panel.
+
+## Common actions
+
+- start / stop / restart servers
+- install or update files
+- inspect logs
+- report process state
+- run scheduled maintenance
+
+## Rule
+
+Do not allow customer input to become arbitrary shell code. The agent should only execute validated, panel-generated requests.

docs/CYGWIN_INTEGRATION.md

@@ -0,0 +1,20 @@
+# GSP Windows Agent Cygwin Integration
+
+Workspace reference: [`GSP-WORKSPACE.md`](../../GSP-WORKSPACE.md)
+
+The Windows agent depends on Cygwin to provide the Linux-like execution environment expected by the OGP Perl agent.
+
+## What Cygwin provides
+
+- `bash`
+- GNU Screen-compatible behavior where used
+- Perl runtime compatibility
+- Unix-style path and shell semantics for the agent scripts
+
+## Operational rule
+
+Startup scripts should detect the bundled Cygwin root first and fall back only when the bundled environment is missing. The launcher should point to the actual bundled `OGP64` tree, not to an unrelated system installation.
+
+## Maintenance rule
+
+Keep Cygwin-specific behavior isolated to this repository so the Panel can continue to treat the Windows and Linux agents as equivalent execution targets.

docs/PANEL_INTEGRATION.md

@@ -0,0 +1,15 @@
+# GSP Windows Agent Panel Integration
+
+Workspace reference: [`GSP-WORKSPACE.md`](../../GSP-WORKSPACE.md)
+
+The Panel is authoritative. The Windows agent executes the work the Panel requests.
+
+## Integration points
+
+- shared key and RPC configuration live in `OGP64/OGP/Cfg/Config.pm`
+- startup preferences live in `OGP64/OGP/Cfg/bash_prefs.cfg`
+- the Panel talks to the same command surface as the Linux agent wherever practical
+
+## Compatibility rule
+
+The Windows agent should mirror the Linux agent behaviorally as much as possible so the Panel can treat both platforms as one product family.

docs/PROCESS_MANAGEMENT.md

@@ -0,0 +1,23 @@
+# GSP Windows Agent Process Management
+
+Workspace reference: [`GSP-WORKSPACE.md`](../../GSP-WORKSPACE.md)
+
+The Windows agent manages customer servers through the Cygwin runtime and the OGP Perl agent.
+
+## Current model
+
+- `OGP64` is the Cygwin root for the maintained launcher
+- process state is tracked through the agent runtime and PID files
+- manual startup and shutdown are handled by the root batch scripts
+- Windows-specific user and service assumptions belong here, not in the Panel
+
+## Important files
+
+- `OGP64/agent_start.bat`
+- `OGP64/agent_stop.bat`
+- `OGP64/OGP/ogp_agent.pl`
+- `OGP64/OGP/Cfg/`
+
+## Rule
+
+Keep startup and stop behavior visible and explicit. Failures should be reported in the same console when launched manually.