Run request analysis on demand on the VPS

docs/kb/systems/floating-window-shell.md

@@ -0,0 +1,44 @@
+# Floating Window Shell
+
+## What It Does
+
+Worldshaper relies on separate floating windows and internal popout shells for several tools. This subsystem defines how the main studio window opens, how internal tool windows are placed, and how overlay-layer tools are managed inside the editor.
+
+## Key Files
+
+- `src/worldshaperStudio/windowing.ts`
+- `src/worldshaperStudio/floatingWindowUtils.ts`
+- `src/worldshaperStudio/toolWindowController.ts`
+- `src/worldshaperStudio/changelogSplashWindowController.ts`
+- `src/worldshaperStudio/engineOverrideWindowController.ts`
+
+## Endpoints It Uses
+
+- none directly
+
+## Important Data And Rules
+
+- the launcher opens the studio in a new browser window
+- many studio tools use internal popout shells layered above the editor
+- floating window state may be persisted per tool
+- focus, z-index, clamp-to-viewport, and drag behavior all live here
+
+## Invariants And Constraints
+
+- popup blocking can break launch
+- tool windows should stay usable on small screens
+- tool windows should not render behind the main viewport layer
+- window persistence should not trap a tool off-screen forever
+
+## Common Request Themes
+
+- docking and undocking
+- better positioning behavior
+- tool window focus bugs
+- opening or closing auxiliary windows
+
+## Triage Questions
+
+- Is the request about the external studio window, or internal tool popouts?
+- Does it depend on persisted window coordinates?
+- Does it affect one tool window or the shared shell behavior?