worshop work

docs/AGENT_COMMUNICATION.md

@@ -0,0 +1,28 @@
+# GSP Agent Communication
+
+Workspace reference: [`GSP-WORKSPACE.md`](../../GSP-WORKSPACE.md)
+
+This document is the short-form overview of how the Panel talks to the Linux and Windows agents.
+
+## Transport
+
+The Panel uses its remote communication layer to send commands to an agent, which in turn forwards work to the OGP Perl agent and the host OS.
+
+## Common flow
+
+1. Panel module builds a request.
+2. `Panel/includes/lib_remote.php` sends it.
+3. The agent receives the request.
+4. The OGP Perl agent executes the requested action.
+5. The agent returns status, logs, or command results.
+
+## Key properties
+
+- requests must be explicit and validated
+- agents should report results, not decide policy
+- status reporting should remain compatible between Linux and Windows where practical
+- platform-specific differences should be isolated to the agent layer
+
+## Security rule
+
+Customer input must never become arbitrary shell command text. Panel-side validation and allowlists must happen before a request is sent to an agent.