fix: harden cross-platform quality tooling

docs/local_quality_gate.md

@@ -6,38 +6,64 @@ parser errors, and LLM-generated garbage before committing.
 ## Requirements
 
 - **Python 3** with the pinned `gdtoolkit` (gdscript-toolkit). The recommended
-  setup uses `uv` and a project-local environment:
+  setup uses `uv` and a project-local environment. These commands are the same
+  in macOS shells and Windows PowerShell:
 
   ```bash
   uv venv .venv
-  uv pip install --python .venv/bin/python -r requirements-dev.txt
+  uv pip install -r requirements-dev.txt
   ```
 
-  On Windows, use `.venv/Scripts/python.exe` for the `--python` value.
 - **Godot 4.7.x** binary on `PATH`, or set the `GODOT_BIN` environment
   variable. The gate rejects other engine series before importing or testing.
 - **GUT 9.7.1** is vendored under `addons/gut` for Godot 4.7. No separate
   package-manager install is needed.
+- **Terrain3D 1.0.2** is vendored with macOS and Windows x86-64 debug and
+  release binaries. No separate native build is needed on either development
+  platform.
 
 The vendored addon comes from the official
 [`bitwes/Gut` v9.7.1 release](https://github.com/bitwes/Gut/releases/tag/v9.7.1).
 The downloaded release archive SHA-256 is
 `14969aa46adc84aa08cdd21b9f6d1a64addd92ae60b36f02d0521ed305aa4086`.
 
+Terrain3D carries one intentional local Godot 4.7 compatibility patch in
+`addons/terrain_3d/src/double_slider.gd`: its editor display-scale lookups use
+the 4.7 `interface/editor/appearance/*` setting paths. Preserve or re-evaluate
+that patch when upgrading the vendored addon; without it, the first isolated
+import fails before a class cache exists.
+
 The quality and format scripts discover `.venv` automatically; activating it
 is optional. Missing `gdformat` or `gdlint` is a gate failure rather than a
 silent skip.
 
+### Finding Godot
+
+The macOS gate checks project metadata, `godot`/`godot4` on `PATH`, and the
+standard `/Applications/Godot.app` location. The Windows gate checks project
+metadata, `PATH`, common Program Files and Local AppData locations, and a
+standard Scoop install. It prefers Godot's console executable when available.
+
+For a downloaded or custom install, set the executable explicitly:
+
+```bash
+export GODOT_BIN="/Applications/Godot.app/Contents/MacOS/Godot"
+```
+
+```powershell
+$env:GODOT_BIN = "C:\Tools\Godot\Godot_v4.7-stable_win64_console.exe"
+```
+
 ## Usage
 
 ### Full project check
 
 ```bash
-# Linux / macOS / Git Bash
 ./tools/quality.sh
+```
 
-# Windows PowerShell
-& ./tools/quality.ps1
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\quality.ps1
 ```
 
 ### Fast changed-files mode
@@ -47,7 +73,10 @@ files. The Godot dependency check and all project scenarios still run.
 
 ```bash
 ./tools/quality.sh --changed
-& ./tools/quality.ps1 -Changed
+```
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\quality.ps1 -Changed
 ```
 
 ### Auto-format (not part of the gate)
@@ -56,10 +85,27 @@ files. The Godot dependency check and all project scenarios still run.
 ./tools/fix_format.sh
 ```
 
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\fix_format.ps1
+```
+
+Both gates and both formatter entry points operate on the same game-owned
+roots: `player`, `simulation`, `tests`, `tools`, and `world`. Third-party
+addons and demos remain outside automatic formatting.
+
+### Add-on policy
+
+Add an editor or runtime add-on only for a current gameplay or diagnostic
+consumer. Pin its exact release, retain its license and source provenance, and
+avoid auto-updates. Native add-ons must vendor macOS and Windows x86-64 debug
+and release payloads; add those paths to the `platform-assets` manifest in both
+quality scripts so either development platform detects an incomplete package.
+
 ## What it checks
 
 | Check | Tool | What it detects |
 |---|---|---|
+| **platform-assets** | File manifest | Missing Terrain3D macOS or Windows native payloads |
 | **godot-import** | Godot 4.7 headless importer | Missing or stale global `class_name` cache on fresh clones |
 | **gdformat** | Game-owned GDScript roots | Formatting without rewriting addons or demos |
 | **gdlint** | Game-owned GDScript roots | Lint violations such as unused arguments and naming |
@@ -75,6 +121,7 @@ If everything passes:
 QUALITY RESULT: PASS
 Godot: 4.7.stable.official.5b4e0cb0f
 
+  platform-assets PASS
   godot-import PASS
   gdformat     PASS
   gdlint       PASS
@@ -92,6 +139,7 @@ On failure, only relevant errors and fix suggestions are shown:
 QUALITY RESULT: FAIL
 Godot: 4.7.stable.official.5b4e0cb0f
 
+  platform-assets PASS
   godot-import PASS
   gdformat     FAIL
   gdlint       FAIL
@@ -132,7 +180,7 @@ python -m pip install -r requirements-dev.txt
 The script exits non-zero on any failure, including a wrong Godot series or
 missing pinned formatter/linter, so it will fail the CI step.
 
-The shell gate isolates Godot's cross-platform user-data paths under
+Both gates isolate Godot's cross-platform user-data paths under
 `logs/quality/godot_profile`. Before running scenarios it imports project and
 GUT global classes whenever GDScript changes, so fresh, renamed, and deleted
 `class_name` scripts cannot leave the ignored cache stale. Godot/GUT script