fix(birdhouse): manual pendant teleport + mushtree transport

.gitignore

@@ -52,3 +52,4 @@ nb-configuration.xml
 nbproject/
 public/**
 /CreatePluginDocs.ps1
+.worktrees/

AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

CLAUDE.md

@@ -127,6 +127,8 @@ If a plugin needs additional libraries beyond the Microbot client:
 
 ## Testing and Debugging Plugins
 
+**Before chasing a "script does nothing" bug, read [`docs/PLUGIN_DEBUGGING_NOTES.md`](docs/PLUGIN_DEBUGGING_NOTES.md).** It documents the recurring failure modes in Hub plugins (instanced-region coordinate mismatches, the new Queryable API not auto-walking, null-guard predicates masking broken lookups, static field leakage across plugin restarts, etc.) and the agent-server `curl` workflow for inspecting live state instead of theorizing from code.
+
 ### Running Plugins in Debug Mode
 
 1. Edit `src/test/java/net/runelite/client/Microbot.java`
@@ -207,6 +209,35 @@ Key capabilities for Hub plugin testing:
 - **Script lifecycle**: Start/stop plugins by class name via HTTP, poll runtime status, submit and retrieve structured test results.
 - **Java result API**: Hub scripts can call `ScriptResultStore.submit(className, data)` directly from within the JVM.
 
+## Dynamic Script Deployment (Hot-Reload)
+
+**Core Mechanism:** Compile Java source → load via custom URLClassLoader → inject into Guice → start as a RuneLite plugin. No client restart needed.
+
+**HTTP endpoints (127.0.0.1:8081):**
+- `POST /scripts/deploy` — compile & start
+- `POST /scripts/deploy/reload` — recompile in place
+- `POST /scripts/deploy/undeploy` — stop & unload
+- `GET /scripts/deploy` — list deployments
+
+**Core files:** `agentserver/scripting/DynamicScriptManager.java`, `DynamicScriptCompiler.java`, `handler/DynamicScriptDeployHandler.java`
+
+### Supporting Systems
+
+1. **microbot-cli** — bash wrapper for the agent server (`./microbot-cli scripts deploy|reload|undeploy|health|results`)
+2. **Agent Server API** — query state (NPCs, objects, inventory, widgets) and drive the client (walk, interact, dialogue). Full reference in `docs/AGENT_SERVER.md`.
+3. **Probe plugin pattern** — minimal `@PluginDescriptor` classes deployed to inspect engine state, iterate with hot-reload. Used by the `/debugger` skill.
+4. **StateMachineScript** — base class for multi-phase scripts; transitions observable via `GET /debug/snapshot?script=Name`.
+5. **ScriptResultStore** — scripts submit results in-process; retrieve via `/scripts/results` for test workflows.
+6. **`scripts/test_hot_reload.py`** — working end-to-end example of the deploy/reload/undeploy lifecycle.
+
+### Typical Loop
+
+```
+edit source → microbot-cli scripts reload → microbot-cli scripts health → observe logs → repeat
+```
+
+Everything binds to `127.0.0.1` only.
+
 ## Common Patterns
 
 - Plugins extending `SchedulablePlugin` implement `getStartCondition()` and `getStopCondition()` for scheduler integration

build.gradle

@@ -16,6 +16,19 @@ apply from: 'gradle/plugin-utils.gradle'
 def microbotClientVersion = project.ext.getMicrobotClientVersion()
 def microbotClientPath = project.findProperty("microbotClientPath")
 
+if (!microbotClientPath && project.hasProperty("microbotClientDir")) {
+    def clientDir = file(project.findProperty("microbotClientDir"))
+    if (clientDir.isDirectory()) {
+        def match = clientDir.listFiles()?.findAll { it.name ==~ /microbot-.*\.jar/ && !it.name.contains('sources') && !it.name.contains('shaded') }
+                ?.sort { -it.lastModified() }
+                ?.first()
+        if (match) {
+            microbotClientPath = match.absolutePath
+            logger.lifecycle("🤖 Resolved local microbot client JAR: ${microbotClientPath}")
+        }
+    }
+}
+
 // Java toolchain configuration
 java {
     toolchain {