Import verified AzerothAI snapshot from GitHub

Source branch: feature/ai-brain-router
Source commit: c2a09e0460465201a58aaab56c71424e9a96405e

deploy/playable/README.md

@@ -0,0 +1,234 @@
+# Playable AzerothAI Realm
+
+This profile turns the current prototype into a realm you can connect a **WoW 3.3.5a client** to.
+
+It uses:
+
+- the `mod-playerbots/azerothcore-wotlk` **Playerbot** branch
+- `mod-playerbots`
+- `mod-ale`
+- AzerothAI's ALE bridge
+- MySQL
+- AzerothAI's local dashboard/runtime
+- optional Ollama + `qwen3.5:4b`
+
+The server exposes only the standard WoW ports needed by the client:
+
+- TCP 3724 — authserver
+- TCP 8085 — worldserver
+
+SOAP runs on TCP 7878 but the playable profile binds it to **127.0.0.1 only** for the AzerothAI operator/GM channel.
+
+## Recommended network
+
+For the mini PC, the cleanest private setup is:
+
+```text
+Windows WoW PC ─────┐
+                    │  LAN or Tailscale
+HP EliteDesk ───────┘
+  ├─ AzerothCore
+  ├─ Playerbots
+  ├─ ALE
+  ├─ AzerothAI
+  └─ Ollama
+```
+
+If Tailscale is installed, the bootstrap automatically prefers the machine's Tailscale IPv4 address. Otherwise it uses the first LAN IPv4 address it can detect.
+
+You can override it:
+
+```bash
+REALM_ADDRESS=192.168.1.50 bash deploy/playable/bootstrap.sh
+```
+
+## Bootstrap
+
+Run this from the AzerothAI checkout on the Linux host:
+
+```bash
+bash deploy/playable/bootstrap.sh
+```
+
+The script:
+
+1. builds AzerothAI and initializes its local D1/SQLite state
+2. generates private bridge/operator tokens
+3. starts AzerothAI on port 8787
+4. clones the Playerbots AzerothCore fork
+5. installs `mod-playerbots` and `mod-ale`
+6. mounts `ale/azerothai_bridge.lua` into the real worldserver
+7. builds AzerothCore
+8. prepares client data and databases
+9. starts authserver/worldserver
+10. updates the realm address so another machine can connect
+
+The generated secrets are stored outside the repo at:
+
+```text
+~/azerothai-playable/runtime.env
+```
+
+with owner-only permissions.
+
+## Create your player/GM account
+
+AzerothCore recommends account creation through the worldserver console rather than manually creating auth rows.
+
+```bash
+cd ~/azerothai-playable/azerothcore
+docker attach ac-worldserver
+```
+
+Then:
+
+```text
+account create YOURNAME YOURPASSWORD
+account set gmlevel YOURNAME 3 -1
+```
+
+Detach from Docker without stopping worldserver:
+
+```text
+Ctrl-P, then Ctrl-Q
+```
+
+Then save the same GM account for AzerothAI's local SOAP client:
+
+```bash
+bash deploy/playable/set-gm-credentials.sh YOURNAME YOURPASSWORD
+```
+
+Restart AzerothAI by stopping/re-running the playable profile so the new local credentials are loaded.
+
+## Connect the WoW client
+
+In the 3.3.5a client's:
+
+```text
+Data/enUS/realmlist.wtf
+```
+
+set:
+
+```text
+set realmlist <the address printed by bootstrap>
+```
+
+Then launch the client normally and log in with the account you created.
+
+The realm should appear as:
+
+```text
+AzerothAI Lab
+```
+
+## Dashboard
+
+From another machine on the same LAN/Tailscale network:
+
+```text
+http://<server-address>:8787
+```
+
+The dashboard and WoW realm are separate surfaces:
+
+- WoW client: live game world
+- AzerothAI dashboard: population, identities, memories, operator tools, events, model settings
+
+## AI brain
+
+The realm can run without Ollama; decisions remain deterministic.
+
+When Ollama is available:
+
+```bash
+ollama pull qwen3.5:4b
+```
+
+Then choose **Ollama** in AzerothAI's Server & Models page.
+
+Routine Qwen decisions use non-thinking mode so the small host spends its generation budget on a fast structured action instead of hidden reasoning.
+
+## Autonomous living world
+
+The playable profile now enables a real unattended Playerbot population by default.
+
+- native Playerbots log in and keep playing even when no human is connected
+- bots remain fully active while alone
+- periodic artificial rerandomization/teleporting is pushed out to a one-year horizon so normal movement, questing, combat and leveling remain the source of progression
+- ALE emits authoritative Playerbot snapshots with character GUID/account bindings
+- AzerothAI adopts observed Playerbots as persistent resident identities
+- the local autonomy worker periodically turns each resident's goals/personality/memories into high-level PlayerBotAI intentions
+- AzerothCore/Playerbots remains authoritative for movement, combat, spells, quest rules, loot and actual outcomes
+- Zaku is bound to a physical Undead Warlock Playerbot when a suitable body exists; his plot-armor rule stays runtime-only and is never exposed to his character context
+
+For an already-running realm, apply the living-world upgrade with:
+
+```bash
+bash deploy/playable/enable-autonomous-world.sh
+```
+
+The default target is 10 simultaneously active Playerbots. Override it before running the helper, for example:
+
+```bash
+AZEROTHAI_RANDOM_BOTS=20 bash deploy/playable/enable-autonomous-world.sh
+```
+
+The helper does not report success merely because configuration files changed. It waits for real Playerbot accounts, physically-online bot characters, authoritative ALE observations, and at least one adopted AzerothAI resident.
+
+## Useful commands
+
+Check status:
+
+```bash
+bash deploy/playable/status.sh
+```
+
+Stop the lab while preserving all data:
+
+```bash
+bash deploy/playable/stop.sh
+```
+
+Restart later by running bootstrap again.
+
+Worldserver logs:
+
+```bash
+cd ~/azerothai-playable/azerothcore
+docker compose logs -f ac-worldserver
+```
+
+AzerothAI log:
+
+```bash
+tail -f ~/azerothai-playable/azerothai.log
+```
+
+Autonomous high-level decisions:
+
+```bash
+tail -f ~/azerothai-playable/autonomy.log
+```
+
+If your existing lab was created by the PC-lab helper, the scripts automatically detect `~/azerothai-pc-lab` as well.
+
+## Storage
+
+By default:
+
+```text
+~/azerothai-playable/
+├── azerothcore/
+├── client-data/
+├── etc/
+├── logs/
+├── runtime.env
+├── azerothai.log
+└── azerothai.pid
+```
+
+The project checkout keeps AzerothAI's local D1 state in `.wrangler/state`.
+
+Do not delete these directories if you want the realm and character history to survive restarts.