fix: 3D raycast annotations follow reachable collider shapes

.agents/skills/uloop-clear-console/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: uloop-clear-console
-description: "Clear all Unity Console log entries. Use when you need to: (1) Clear console before running tests or compilation, (2) Start a fresh debugging session, (3) Remove noisy logs to isolate specific output."
+description: "Clear Unity Console entries. Use before compile, tests, or debugging when stale logs would hide the current result."
 ---
 
 # uloop clear-console

.agents/skills/uloop-compile/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: uloop-compile
-description: "Compile Unity project and report errors/warnings. Use when you need to: (1) Verify code compiles after C# file edits, (2) Check for compile errors before testing, (3) Force full recompilation with Domain Reload. Returns error and warning counts."
+description: "Compile the Unity project and report errors/warnings. Use after C# edits or when a full Domain Reload compile is needed."
 ---
 
 # uloop compile
@@ -10,15 +10,15 @@ Execute Unity project compilation.
 ## Usage
 
 ```bash
-uloop compile [--force-recompile] [--wait-for-domain-reload]
+uloop compile [--force-recompile <true|false>] [--wait-for-domain-reload <true|false>]
 ```
 
 ## Parameters
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `--force-recompile` | boolean | `false` | Force full recompilation (triggers Domain Reload) |
-| `--wait-for-domain-reload` | boolean | `false` | Wait until Domain Reload completes before returning |
+| `--force-recompile` | boolean value | `false` | Force full recompilation (triggers Domain Reload). Pass `true` or `false`; bare flags are not accepted. |
+| `--wait-for-domain-reload` | boolean value | `false` | Wait until Domain Reload completes before returning. Pass `true` or `false`; bare flags are not accepted. |
 
 ## Global Options
 
@@ -33,7 +33,7 @@ uloop compile [--force-recompile] [--wait-for-domain-reload]
 uloop compile
 
 # Force full recompilation
-uloop compile --force-recompile
+uloop compile --force-recompile true
 
 # Force recompilation and wait for Domain Reload completion
 uloop compile --force-recompile true --wait-for-domain-reload true

.agents/skills/uloop-control-play-mode/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: uloop-control-play-mode
-description: "Control Unity Editor play mode (play/stop/pause). Use when you need to: (1) Start play mode to test game behavior, (2) Stop play mode to return to edit mode, (3) Pause play mode for frame-by-frame inspection."
+description: "Control Unity Editor Play Mode. Use to start, stop, or pause Play Mode for runtime behavior checks and frame inspection."
 ---
 
 # uloop control-play-mode

.agents/skills/uloop-execute-dynamic-code/references/asset-operations.md

@@ -184,6 +184,8 @@ return $"Asset has {dependencies.Length} dependencies";
 
 ## Refresh AssetDatabase
 
+Use this after terminal-based asset file changes when Unity needs to import them and generate `.meta` files.
+
 ```csharp
 using UnityEditor;
 

.agents/skills/uloop-execute-dynamic-code/references/playmode-automation-powershell.md

@@ -177,7 +177,7 @@ Use `find-game-objects` to discover buttons with their hierarchy paths, then cli
 **Step 1**: Find all GameObjects with Button component
 
 ```powershell
-uloop find-game-objects --required-components UnityEngine.UI.Button --include-inactive false
+uloop find-game-objects --required-components UnityEngine.UI.Button
 ```
 
 **Step 2**: Click the target button using the path from Step 1
@@ -203,7 +203,7 @@ Use `get-hierarchy` to explore the UI tree structure, then target the right elem
 **Step 1**: Get Canvas hierarchy to understand UI structure
 
 ```powershell
-uloop get-hierarchy --root-path 'Canvas' --max-depth 3 --include-components true
+uloop get-hierarchy --root-path 'Canvas' --max-depth 3 --include-inactive true
 ```
 
 **Step 2**: Based on the hierarchy JSON, click the desired button

.agents/skills/uloop-execute-dynamic-code/references/playmode-automation-zsh.md

@@ -146,7 +146,7 @@ Use `find-game-objects` to discover buttons with their hierarchy paths, then cli
 **Step 1**: Find all GameObjects with Button component
 
 ```zsh
-uloop find-game-objects --required-components UnityEngine.UI.Button --include-inactive false
+uloop find-game-objects --required-components UnityEngine.UI.Button
 ```
 
 **Step 2**: Click the target button using the path from Step 1
@@ -172,7 +172,7 @@ Use `get-hierarchy` to explore the UI tree structure, then target the right elem
 **Step 1**: Get Canvas hierarchy to understand UI structure
 
 ```zsh
-uloop get-hierarchy --root-path "Canvas" --max-depth 3 --include-components true
+uloop get-hierarchy --root-path "Canvas" --max-depth 3
 ```
 
 **Step 2**: Based on the hierarchy JSON, click the desired button

.agents/skills/uloop-find-game-objects/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: uloop-find-game-objects
-description: "Use first when the user asks about the currently selected GameObject in the Unity Hierarchy. Inspect selected object details with `--search-mode Selected` before using `execute-dynamic-code`. Use when you need to: (1) Get details and component properties for selected GameObject(s), (2) Search for objects by name, regex, or path, (3) Find objects with specific components, tags, or layers. Use get-hierarchy when the child tree under the selection is needed. Returns hierarchy paths, active state, tags, layers, and components (or writes to a file when multiple GameObjects are selected)."
+description: "Find or inspect Unity GameObjects, especially objects the user currently selected in the Hierarchy. Use for details, components, tags, layers, or name/path searches."
 ---
 
 # uloop find-game-objects

.agents/skills/uloop-focus-window/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: uloop-focus-window
-description: "Bring Unity Editor window to front via uloop CLI. Use when you need to: (1) Focus Unity Editor before capturing screenshots, (2) Ensure Unity window is visible for visual checks, (3) Bring Unity to foreground for user interaction."
+description: "Bring the Unity Editor window to front. Use when Unity must be visible for visual checks or user-facing interaction."
 ---
 
 # uloop focus-window

.agents/skills/uloop-get-hierarchy/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: uloop-get-hierarchy
-description: "Get Unity scene hierarchy as a structured tree from all roots, a root path, or the current Hierarchy selection. Use this when you need the child tree, parent-child structure, or descendants under selected GameObject(s) with `--use-selection`. Use find-game-objects for selected object details and component properties. Hierarchy data is written to a JSON file on disk and the response returns the file path (not the tree inline) — open the file to read the structure."
+description: "Get the Unity scene hierarchy as a structured tree. Use for parent-child structure, descendants, roots, or subtrees under objects the user currently selected."
 ---
 
 # uloop get-hierarchy

.agents/skills/uloop-get-logs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: uloop-get-logs
-description: "Retrieve current Unity Console entries via uloop CLI. Use when you need to: (1) inspect errors, warnings, or logs after compile, tests, PlayMode, or dynamic code execution, (2) search current Console messages or stack traces, (3) confirm whether a recent Unity operation emitted logs. Prefer this over reading Editor.log or Unity log files for normal Console contents; use log files only for startup, crash, freeze, or uloop connection failures."
+description: "Read current Unity Console entries from a running Editor. Use during bug investigation after compile, tests, PlayMode, or dynamic code to inspect logs, warnings, errors, and stack traces."
 ---
 
 # uloop get-logs

.agents/skills/uloop-launch/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: uloop-launch
-description: "Launch Unity project with matching Editor version via uloop CLI. Use when you need to: (1) Open a Unity project with the correct Editor version, (2) Restart Unity to apply changes, (3) Switch build target when launching."
+description: "Use when Unity Editor is not running or needs a clean restart."
 ---
 
 # uloop launch

.agents/skills/uloop-raycast/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: uloop-raycast
+description: "Raycast from Camera.main through a Game View coordinate. Use when you need to check what a screenshot coordinate would hit in 3D physics before clicking or long-pressing with simulate-mouse-input."
+---
+
+# uloop raycast
+
+Check what a top-left Game View coordinate hits in 3D physics.
+
+## Usage
+
+```bash
+uloop raycast --x <x> --y <y> [--layer-mask <mask>] [--max-distance <distance>]
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `--x` | number | `0` | Target X position in Game View pixels (origin: top-left). Use `AnnotatedElements[].SimX`, `RaycastGridPoints[].InputX`, or raw image pixels converted with `ScreenshotToInputFormula`. |
+| `--y` | number | `0` | Target Y position in Game View pixels (origin: top-left). Use `AnnotatedElements[].SimY`, `RaycastGridPoints[].InputY`, or raw image pixels converted with `ScreenshotToInputFormula`. |
+| `--layer-mask` | number | Unity default raycast layers | Physics layer mask used by the raycast. |
+| `--max-distance` | number | `1000` | Maximum raycast distance in world units. |
+
+## Coordinate System
+
+- `--x` / `--y` use the same top-left Game View input coordinates as `simulate-mouse-input`.
+- Raw image pixels from `uloop screenshot --capture-mode rendering` must be converted with `ScreenshotToInputFormula`.
+- `AnnotatedElements[].SimX/SimY` and `RaycastGridPoints[].InputX/InputY` can be passed directly to this tool.
+- Do not flip Y in the caller. The tool converts internally:
+
+```text
+unity_x = input_x
+unity_y = gameViewHeight - input_y
+```
+
+## Examples
+
+```bash
+# Check what is under a screenshot coordinate
+uloop raycast --x 960 --y 540
+
+# Check only specific layers
+uloop raycast --x 960 --y 540 --layer-mask 1
+```
+
+## Output
+
+Returns JSON with:
+- `Success`: Whether the command completed
+- `Message`: Status message
+- `Hit`: Whether physics hit anything
+- `HitGameObjectName` / `HitGameObjectPath`: Hit object identity when `Hit` is true
+- `HitLayer` / `HitLayerName`: Hit object layer when `Hit` is true
+- `Distance`, `HitPointX/Y/Z`, `HitNormalX/Y/Z`: Hit details when `Hit` is true
+- `InputCoordinateSystem`, `UnityCoordinateSystem`, `GameViewWidth/Height`, `InputPositionX/Y`, `InjectedUnityPositionX/Y`, `CoordinateConversionFormula`: Coordinate conversion details
+
+## Notes
+
+- Requires an active `Camera.main`.
+- Uses Unity Physics raycasts, not UI EventSystem raycasts.

.agents/skills/uloop-record-input/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: uloop-record-input
-description: "Record keyboard and mouse input during PlayMode into a JSON file. Use when you need to: (1) Capture human gameplay input for later replay, (2) Record input sequences for E2E testing, (3) Save input for bug reproduction. Captures Input System device-state diffs frame-by-frame in PlayMode and serializes them to JSON when stopped. Requires PlayMode and the New Input System."
+description: "Record PlayMode keyboard and mouse input to JSON. Use to capture gameplay, bug repro, or E2E input sequences for replay."
 ---
 
 # uloop record-input
@@ -39,7 +39,7 @@ Replay injects input frame-by-frame, so the game must also be deterministic to p
 
 - Unity must be in **PlayMode**
 - **Input System package** must be installed (`com.unity.inputsystem`)
-- Active Input Handling must be set to `Input System Package (New)` or `Both` in Player Settings
+- Use this only when the project already uses the New Input System.
 
 ## Output
 

.agents/skills/uloop-replay-input/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: uloop-replay-input
-description: "Replay recorded input during PlayMode with frame-precise injection. Use when you need to: (1) Reproduce recorded gameplay exactly, (2) Run E2E tests from recorded input, (3) Generate demo videos with consistent input. Deserializes the JSON recording and pushes captured device states back into Mouse.current / Keyboard.current frame-by-frame in PlayMode. Requires PlayMode and the New Input System."
+description: "Replay recorded PlayMode keyboard and mouse input. Use for exact gameplay reproduction, E2E runs, or consistent demos from JSON recordings."
 ---
 
 # uloop replay-input
@@ -39,6 +39,12 @@ uloop replay-input --action Stop
 
 Replay injects the exact same input frame-by-frame, but the game must also be deterministic to produce identical results. If replay output must be compared across runs, read [references/deterministic-replay.md](references/deterministic-replay.md) before interpreting failures.
 
+## Prerequisites
+
+- Unity must be in **PlayMode**
+- **Input System package** must be installed (`com.unity.inputsystem`)
+- Use this only when the project already uses the New Input System.
+
 ## Output
 
 Returns JSON with:

.agents/skills/uloop-run-tests/SKILL.md

@@ -1,11 +1,13 @@
 ---
 name: uloop-run-tests
-description: "Execute Unity Test Runner and get detailed results. Use when you need to: (1) Run EditMode or PlayMode unit tests, (2) Verify code changes pass all tests, (3) Diagnose test failures with error messages and stack traces. Single-flight only — never run multiple `uloop run-tests` in parallel."
+description: "Run Unity Test Runner and report detailed results. Use for EditMode/PlayMode tests, change verification, or failure diagnosis."
 ---
 
 # uloop run-tests
 
-Execute Unity Test Runner. When tests fail, NUnit XML results with error messages and stack traces are automatically saved. Read the XML file at `XmlPath` for detailed failure diagnosis.
+Execute Unity Test Runner. This command requires the Unity Test Framework package (`com.unity.test-framework`). If that package is not installed, the command returns `Success: false` with an unsupported message and does not affect the other Unity CLI Loop tools.
+
+When tests fail, NUnit XML results with error messages and stack traces are automatically saved. Read the XML file at `XmlPath` for detailed failure diagnosis.
 
 Before executing tests, `uloop run-tests` checks for unsaved loaded Scene changes and unsaved current Prefab Stage changes. If any are found, it returns `Success: false`, keeps `TestCount` at `0`, lists the unsaved items in `Message`, and does not start the Unity Test Runner. Save or discard those editor changes, then rerun the command. Use `--save-before-run true` only when the user explicitly asks to save editor changes before continuing.
 
@@ -59,7 +61,7 @@ Returns JSON with:
 - `PassedCount` (number): Passed tests
 - `FailedCount` (number): Failed tests
 - `SkippedCount` (number): Skipped tests
-- `XmlPath` (string): Path to NUnit XML result file. Empty string when no XML was saved (typically on `Success: true`); populated only when tests failed and the XML file exists on disk.
+- `XmlPath` (string | null): Path to NUnit XML result file. `null` when no XML was saved; populated only when tests failed and the XML file exists on disk.
 
 ### XML Result File