fixes

Agent-Windows/OGP64/OGP/documentation/agent-guide.md

@@ -31,12 +31,28 @@ The Windows agent bundles Cygwin, Perl, GNU Screen, and helper scripts so the Ga
 
 ## Updating the agent
 
+Manual update:
+
 1. Stop the scheduled task or kill any running `ogp_agent.pl` processes.
 2. Pull the latest files (`git pull` inside `C:\\gsp-agent` or download the release ZIP again).
 3. Copy updated files into `C:\\OGP`.
 4. Re-run `rebase_post_ins.bat` if new Cygwin DLLs were added.
 5. Start the agent task again.
 
+Restart-time auto-update:
+
+1. Edit `/OGP/Cfg/bash_prefs.cfg`.
+2. Set `agent_auto_update=1`.
+3. Keep the default Forgejo values unless you are testing another branch:
+   ```bash
+   agent_update_repo_url=http://forge.runlevelsystems.com/dev/GSP.git
+   agent_update_branch=Panel-unstable
+   agent_update_raw_url=http://forge.runlevelsystems.com/dev/GSP/raw/branch/Panel-unstable/Agent-Windows/OGP64/OGP/ogp_agent.pl
+   ```
+4. Restart the agent with `C:\\OGP64\\agent_start.bat` or `C:\\OGP\\Install\\agent_start.bat`.
+
+The updater downloads to a temporary file, rejects empty files, HTML error pages, `Not found` responses, and files without the expected Perl agent markers, then runs `perl -c` before replacing `/OGP/ogp_agent.pl`. Failed auto-update attempts are non-fatal and continue with the last known good agent.
+
 ## Logging & troubleshooting
 
 - Main log: `C:\\OGP\\ogp_agent.log`
@@ -44,6 +60,9 @@ The Windows agent bundles Cygwin, Perl, GNU Screen, and helper scripts so the Ga
 - Customer servers run inside GNU Screen sessions—attach via `C:\\OGP\\bin\\screen -r ogp_agent`
 - Firewall: open TCP 12679 (or your configured port) and any game-specific ports before provisioning.
 - Authentication errors almost always mean the `key` in `Cfg/Config.pm` does not match the value stored in the panel → Administration → Servers.
+- `/OGP/Cfg/bash_prefs.cfg` must use LF line endings and no leading whitespace before assignments. The launcher normalizes this automatically before sourcing the file.
+- `./ogp_agent.pl: line 1: Not: command not found` means the agent file was replaced with text/HTTP error content. Restore a backup or enable auto-update after confirming the Forgejo raw URL above is reachable.
+- `The user name could not be found. NET HELPMSG 2221.` came from the legacy root launcher that queried `cyg_server`. Use the maintained launchers above; they do not require that user for manual foreground startup.
 
 ## Usage tips