doc changes and reference folder

docs/features/WORKSHOP_SYSTEM.md

@@ -68,9 +68,33 @@ Default install paths:
 App ID rules:
 
 - `workshop_app_id` must come from a Server Content template, Steam Workshop profile, or game XML.
+- Game XML should declare Workshop support in the canonical `workshop_support` block.
 - Do not silently use the dedicated server Steam app ID as the Workshop app ID unless a legacy profile explicitly does so.
 - Arma 3 XML declares Workshop app ID `107410`; its dedicated server Steam app ID remains `233780`.
 
+Canonical XML:
+
+```xml
+<workshop_support>
+  <enabled>1</enabled>
+  <provider>steam</provider>
+  <steam_app_id>107410</steam_app_id>
+  <workshop_app_id>107410</workshop_app_id>
+  <download_method>steamcmd</download_method>
+  <install_strategy>arma_mod_folder</install_strategy>
+  <install_path>{SERVER_ROOT}/{MOD_FOLDER}</install_path>
+  <startup_param_format>-mod={MOD_LIST}</startup_param_format>
+  <mod_separator>;</mod_separator>
+  <mod_prefix>@</mod_prefix>
+  <copy_keys enabled="1">
+    <source_pattern>{MOD_PATH}/keys/*.bikey</source_pattern>
+    <target_path>{SERVER_ROOT}/keys</target_path>
+  </copy_keys>
+</workshop_support>
+```
+
+The Panel helper parser reads `workshop_support` first. Older direct tags are tolerated only as a compatibility fallback in helper code; they are not the canonical XML format.
+
 ## Database State
 
 `server_content_workshop` tracks:
@@ -140,3 +164,31 @@ Use `addonsmanager` as the main future home for:
 - install history
 
 Treat `steam_workshop` as a legacy bridge for migration only.
+
+## Panel-Agent Contract
+
+Phase 1 does not use the legacy `steam_workshop` XML-RPC method for the primary user workflow. Instead:
+
+1. Panel parses customer input into numeric Workshop IDs.
+2. Panel writes `{SERVER_HOME}/gsp_server_content/workshop_manifest.json`.
+3. Panel stages the OS-appropriate bundled handler under `{SERVER_HOME}/gsp_server_content/scripts/workshop/`.
+4. Panel invokes the handler through the existing authenticated agent `exec` RPC.
+5. The handler writes `workshop_install.log` or `workshop_install_windows.log` under `gsp_server_content`.
+6. Panel updates `server_content_workshop.install_state` from queued/installing to installed/failed/removed.
+
+Important manifest fields:
+
+- `home_id`
+- `home_cfg_id`
+- `game_path`
+- `server_path`
+- `workshop_app_id`
+- `steam_app_id`
+- `items`
+- `item_details`
+- `install_strategy`
+- `target_path`
+- `extra.copy_keys`
+- `extra.keys_target_path`
+
+Both bundled handlers validate numeric item IDs, keep writes under the server home, use SteamCMD, copy files into the resolved target path, and copy `.bikey` files for DayZ/Arma strategies when enabled.