Merge branch 'main' of ssh.tinqs.com:tinqs/builds

# Conflicts:
#	.gitignore
#	manifest.json

.agents/handoffs/forge-windows-4.7.md

@@ -0,0 +1,62 @@
+# Handoff → Forge (Ozan's Windows box): build Windows 4.7 + ship GodotSharp
+
+**Date:** 2026-06-19 · **From:** macOS 4.7 native-module migration · **For:** Windows build owner
+
+## Why
+
+The engine moved to **Godot 4.7** and **Terrain3D + agent_skinned are now native engine modules**
+(compiled into the binary — no GDExtension `.framework`). macOS is done and shipped in this repo
+(`engine/macos-arm64/`). **Windows is still 4.6.5 with the GDExtension** and must be brought up to
+4.7 the same way, or Windows teammates can't run the new `ariki-game` (the game-side cutover removed
+the terrain GDExtension).
+
+## The critical bit (don't skip)
+
+After the 4.7 build you **must regenerate GodotSharp and ship it next to the binary.** A native
+module changes the engine's class list; the C# bindings (`GodotSharp`) must be regenerated to
+include `Terrain3D` / `MultiSkinnedMeshInstance3D`, or the game throws
+`Wrapper class not found for type: Terrain3D` (terrain = water, animals frozen). The engine does
+**not** regenerate GodotSharp at runtime.
+
+## Steps (Windows)
+
+1. **Sync engine source** to the current `tinqs/engine` `main` (single 4.7 snapshot, `4ba7b5b`).
+   ```
+   cd engine
+   tinqs pull            # or: git fetch origin && git checkout main && git reset --hard origin/main
+   ```
+2. **Build the editor**:
+   ```
+   scons platform=windows target=editor arch=x86_64 module_mono_enabled=yes
+   scons platform=windows target=editor arch=x86_64 module_mono_enabled=yes windows_subsystem=console   # console binary
+   ```
+3. **Regenerate the mono glue + GodotSharp assemblies** (this is the step that fixes the wrapper errors):
+   ```
+   bin\tinqs.windows.editor.x86_64.mono.exe --headless --generate-mono-glue modules\mono\glue
+   python modules\mono\build_scripts\build_assemblies.py --godot-output-dir=bin --godot-platform=windows
+   ```
+   Confirm `bin\GodotSharp\Api\Debug\GodotSharp.dll` exists and that
+   `modules\mono\glue\...\Generated\Constructors.cs` contains `Terrain3D` (grep it).
+4. **If you hit the same build errors I did** (already fixed in `main`, but for reference): a core
+   module can't expose an editor-API type — `Terrain3D::set_plugin` must take `Object*` not
+   `EditorPlugin*`; `Terrain3DAssetResource` must be `GDREGISTER_ABSTRACT_CLASS`; drop the redundant
+   `Terrain3DRegion::duplicate` bind. These are already in `main` — a clean pull should have them.
+5. **Drop into this builds repo** (`engine/windows-x64/`):
+   - `tinqs.windows.editor.x86_64.mono.exe` (+ `.console.exe`)
+   - the whole `GodotSharp/` folder  ← **new requirement; was previously .gitignored**
+6. **Update `manifest.json`** windows-x64 block: version `4.7…`, `engine_commit` `4ba7b5b`, new
+   sha256s, add `"godotsharp": "engine/windows-x64/GodotSharp"`, clear the "pending" note.
+7. `tinqs push`.
+
+## Verify
+
+On a Windows machine with `ariki-game`: run the update-engine skill (`.agents/skills/update-engine`,
+Windows path), launch `game.sh run`. Healthy = terrain renders, animals animate, **0**
+`Wrapper class not found`, no `.NET assemblies not found`.
+
+## Notes
+
+- `.gitattributes` already LFS-tracks `engine/**`, so the binary + GodotSharp go to LFS automatically.
+- The macOS side in this repo is the reference for exactly what the layout should look like.
+- Game-side cutover (GDExtension removal, `project.godot`→4.7) is committed on `ariki-game` `main`
+  (held pending team sync) — Windows teammates need this engine before that lands for them.

.agents/skills/update-engine/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: update-engine
+description: Install/update the local Tinqs engine (binary + GodotSharp C# bindings) from this builds repo so ariki-game runs on the current engine. Use when an engine update is announced, when setting up a new machine, or when the game shows ".NET assemblies not found" or "Wrapper class not found for type: Terrain3D" (terrain is water / animals don't animate). Covers macOS (arm64) and Windows (x64).
+---
+
+# Update the Tinqs engine from `builds`
+
+**Only Ozan edits the engine source.** Everyone else installs the prebuilt engine from this
+repo into `../engine/bin/`, which is where `ariki-game` looks for it.
+
+## ⚠️ Read this first — binary + GodotSharp are a MATCHED PAIR
+
+The engine binary and its `GodotSharp/` folder (Godot's C# bindings) are **both generated from the
+same engine source** and must be installed **together**. The binary does **not** regenerate
+`GodotSharp` — it must sit next to the binary on disk. Mismatch symptoms:
+
+| Symptom | Cause |
+|---|---|
+| `.NET assemblies not found` dialog (looks for `engine/bin/GodotSharp/Api/Debug`) | no `GodotSharp` present |
+| `Wrapper class not found for type: Terrain3D` / `MultiSkinnedMeshInstance3D` — terrain renders as water, animals don't animate | **stale** `GodotSharp` from an older engine that predates the built-in Terrain3D / agent_skinned modules |
+
+So: always **replace `GodotSharp` wholesale** when you take a new binary, and clear the game's C#
+cache so it rebuilds against the new bindings.
+
+## Assumed layout
+
+```
+tinqs-ltd/
+  ariki-game/    ← the game  (looks for ../engine/bin/…)
+  engine/bin/    ← install target: binary + GodotSharp live here
+  builds/        ← this repo (prebuilt engine)
+```
+Adjust paths below if your checkout differs.
+
+## 1. Pull the latest build
+
+```bash
+cd <…>/builds
+tinqs pull          # never `git pull` — tinqs handles LFS (the binary + GodotSharp are LFS)
+```
+Check `builds/manifest.json` for the current version/commit per platform.
+
+## 2a. Install — macOS (arm64)
+
+```bash
+BUILDS="<…>/builds"; ENGINE="<…>/engine/bin"; GAME="<…>/ariki-game"
+mkdir -p "$ENGINE"
+# 1) binary
+cp "$BUILDS/engine/macos-arm64/tinqs.macos.editor.arm64.mono" "$ENGINE/"
+chmod +x "$ENGINE/tinqs.macos.editor.arm64.mono"
+# 2) GodotSharp — REPLACE wholesale (matched pair)
+rm -rf "$ENGINE/GodotSharp"
+cp -R "$BUILDS/engine/macos-arm64/GodotSharp" "$ENGINE/GodotSharp"
+# 3) clear the game's stale C# cache
+rm -rf "$GAME/.godot/mono"
+```
+
+## 2b. Install — Windows (x64), PowerShell
+
+```powershell
+$builds="<…>\builds"; $engine="<…>\engine\bin"; $game="<…>\ariki-game"
+New-Item -ItemType Directory -Force -Path $engine | Out-Null
+# 1) binaries
+Copy-Item "$builds\engine\windows-x64\tinqs.windows.editor.x86_64.mono.exe" $engine -Force
+Copy-Item "$builds\engine\windows-x64\tinqs.windows.editor.x86_64.mono.console.exe" $engine -Force
+# 2) GodotSharp — REPLACE wholesale (matched pair)
+Remove-Item -Recurse -Force "$engine\GodotSharp" -ErrorAction SilentlyContinue
+Copy-Item -Recurse "$builds\engine\windows-x64\GodotSharp" "$engine\GodotSharp"
+# 3) clear the game's stale C# cache
+Remove-Item -Recurse -Force "$game\.godot\mono" -ErrorAction SilentlyContinue
+```
+
+## 3. Verify
+
+```bash
+"$ENGINE/tinqs.macos.editor.arm64.mono" --version          # matches manifest.json
+ls "$ENGINE/GodotSharp/Api/Debug/GodotSharp.dll"            # MUST exist
+```
+Then run the game (`cd ariki-game && bash tools/game.sh run`). Healthy = terrain renders, animals
+animate, log shows **0** `Wrapper class not found` and no `.NET assemblies not found` dialog.
+
+## Notes
+
+- **GodotSharp must be present in this repo for the copy to work.** If `builds/engine/<platform>/GodotSharp`
+  is missing, the build owner needs to add it (it ships *with* the binary — see `manifest.json`).
+- Don't mix a new binary with an old `GodotSharp`. Always replace both, together.
+- Terrain3D and the skinned-animation classes are **built into the engine binary** now (no separate
+  `addons/terrain_3d` GDExtension `.framework`). If you still have `addons/terrain_3d/terrain.gdextension`
+  or the macOS `.framework`, remove them — they conflict with the built-in module.

.gitignore

@@ -1,2 +1,3 @@
-# GodotSharp C# assemblies are now TRACKED (LFS) so consumers can build/run the
-# C# game without building the engine themselves. See manifest.json godotsharp_install.
+# GodotSharp (the engine's C# bindings) IS now tracked and shipped alongside each binary.
+# It is a matched pair with the binary — see README.md / .agents/skills/update-engine.
+# (Previously windows-x64/GodotSharp was ignored; that was wrong — teammates need it.)

README.md

@@ -1,11 +1,40 @@
 # tinqs/builds
 
-Build artifacts for the Tinqs stack — engine editor binaries and game exports.
-**Binaries are stored via Git LFS** (see `.gitattributes`). Source lives in `tinqs/engine`,
-`tinqs/ariki-game`, `tinqs/ariki-sim`. See `manifest.json` for what's here.
+Build artifacts for the Tinqs stack — engine editor binaries (+ their GodotSharp C# bindings).
+**Binaries and GodotSharp are stored via Git LFS** (see `.gitattributes`). Source lives in
+`tinqs/engine`, `tinqs/ariki-game`, `tinqs/ariki-sim`. See `manifest.json` for exact versions.
 
-Long-term plan: CI (Gitea Actions) builds on push and publishes here / to S3 — see
-`docs/ai/plans/build-pipeline-architecture-2026-06-07.md`.
+> **Use `tinqs pull` / `tinqs push`, never raw git** — these are LFS-heavy.
+
+## Installing / updating the engine
+
+**Don't copy files by hand — run the skill:** [`.agents/skills/update-engine`](.agents/skills/update-engine/SKILL.md).
+Hand it to your agent; it installs the binary + GodotSharp into `../engine/bin/`, wipes stale
+caches, and verifies. Covers macOS + Windows.
+
+## ⚠️ The one rule: binary + GodotSharp are a MATCHED PAIR
+
+Each engine binary ships with a `GodotSharp/` folder (Godot's C# bindings) **generated from that
+exact engine build**. You must install them **together** and replace any old `GodotSharp`.
+
+- The engine does **NOT** regenerate GodotSharp at runtime. If it's missing you get a
+  **`.NET assemblies not found`** dialog pointing at `engine/bin/GodotSharp/Api/Debug`.
+- A **stale** GodotSharp (from an older engine) against a newer binary throws
+  **`Wrapper class not found for type: Terrain3D`** → terrain renders as water, animals don't animate.
+
+This matters now because **Terrain3D and `agent_skinned` are native engine modules** (no separate
+`addons/terrain_3d` GDExtension `.framework`). Built-in module classes need their wrappers baked
+into GodotSharp, so GodotSharp had to be regenerated — and must ship here alongside the binary.
 
 ## Current contents
-- `engine/macos-arm64/tinqs.macos.editor.arm64.mono` — Godot 4.6.3 fork editor (mono), built on Kraken with Xcode 26.3.
+
+| Platform | Engine | Terrain3D | GodotSharp shipped? |
+|---|---|---|---|
+| `engine/macos-arm64/` | **4.7** (`4ba7b5b`) — native modules | built-in module | ✅ yes (`GodotSharp/`) |
+| `engine/windows-x64/`  | **4.6.5** (`420e74bf8`) — still GDExtension | GDExtension | ❌ pending — see handoff |
+
+**Windows is not yet on 4.7.** The 4.7 Windows build + its GodotSharp must come from Forge —
+see [`.agents/handoffs/forge-windows-4.7.md`](.agents/handoffs/forge-windows-4.7.md).
+
+Long-term: CI (Gitea Actions) builds on push and publishes here / to S3 —
+`docs/ai/plans/build-pipeline-architecture-2026-06-07.md`.

manifest.json

@@ -1,17 +1,20 @@
 {
+  "_install": "Use the update-engine skill (.agents/skills/update-engine) — it installs the binary AND GodotSharp together into ../engine/bin and clears stale caches. GodotSharp ships WITH the binary (matched pair); the engine does NOT regenerate it.",
   "engine": {
     "macos-arm64": {
       "binary": "engine/macos-arm64/tinqs.macos.editor.arm64.mono",
-      "version": "4.6.5.stable.mono.custom_build.420e74bf8",
+      "godotsharp": "engine/macos-arm64/GodotSharp",
+      "version": "4.7.stable.mono.custom_build.4ba7b5b5b",
       "engine_repo": "tinqs/engine",
-      "engine_commit": "420e74b",
-      "sha256": "69af9e1211793c0c3ca5a2770fc4fb8a448beea1c8842df412d00cced4b167fe",
+      "engine_commit": "5727de0",
+      "sha256": "19cd60deb5bbeec463319e74706d348ccc325efe096a5f319554aa031e58cfe8",
       "target": "editor",
-      "built_on": "2026-06-16",
-      "built_by": "Kraken (local build — engine 4.6.5, agent_skinned crowd platform: mat4x3 palette + GPU distance-LOD + RGBA16F + set_bone_matrices; doctests green)",
+      "built_on": "2026-06-19",
+      "built_by": "Claude (4.7 native-module fix — Godot 4.7-stable + Tinqs branding + 10 agent modules + Terrain3D & agent_skinned as NATIVE engine modules)",
       "toolchain": "Xcode 26.3 (Apple clang 17)",
       "scons_flags": "platform=macos target=editor arch=arm64 module_mono_enabled=yes vulkan_sdk_path=~/VulkanSDK/1.4.350.0/macOS",
-      "note": "Editor binary, engine 420e74b (4.6.5). agent_skinned: mat4x3 (3-texel) palette, per-instance GPU distance-LOD (near=4-bone/2-frame, far=dominant-bone/nearest), RGBA16F, set_bone_matrices bulk-load. 24 module doctests green. Windows build pending from Forge."
+      "note": "Terrain3D is now a NATIVE ENGINE MODULE (no separate GDExtension .framework). 4.7 C#-bindability fixes: Terrain3D::set_plugin EditorPlugin*->Object*, Terrain3DAssetResource registered abstract, dropped redundant Terrain3DRegion::duplicate bind — so GodotSharp glue generates wrappers for all module classes. GodotSharp shipped here alongside the binary (matched pair: a stale GodotSharp -> 'Wrapper class not found for Terrain3D'). REBUILT 2026-06-19 to restore Tinqs branding (the 4.7 upstream rebase had reset the logos to the Godot robot) — splash/app_icon/editor logos now the Viewport-Focus mark; see engine/brand/apply-branding.sh. Verified: terrain renders, animals GPU-driven, 0 wrapper errors. GodotSharp folder is UNCHANGED from the prior push (logo-only rebuild doesn't touch C# bindings).",
+      "version_hash_note": "engine main = 5727de0 (branding) on top of the 4.7 snapshot; binary --version prints 4.7.stable.mono.custom_build.4ba7b5b5b"
     },
     "windows-x64": {
       "binary": "engine/windows-x64/tinqs.windows.editor.x86_64.mono.exe",
@@ -27,24 +30,7 @@
       "built_by": "Forge (Ozan's Windows box — local build, Godot 4.7 migration)",
       "toolchain": "MSVC VS BuildTools 2022 (vcvarsall amd64), SCons 4.10.1, d3d12+angle+accesskit deps, mono glue + GodotSharp assemblies",
       "scons_flags": "platform=windows target=editor module_mono_enabled=yes d3d12=yes angle=yes accesskit=yes",
-      "godotsharp_install": "cp -R engine/windows-x64/GodotSharp <engine-bin-dir>/GodotSharp  (REQUIRED for the C# game: dotnet build links against these Api/Tools assemblies; version-matched to this binary)",
-      "note": "Branded 4.7 editor binary + console + GodotSharp C# assemblies. Built from engine 4f2e02e5b7 (4.7 single-version snapshot + Windows build fixes: terrain_3d template-safety, .rc icon refs, d3d12/angle/accesskit dep flags). Verified: editor + both export templates build clean; ariki-game runs at 59fps with sim connected. NOTE: macos-arm64 above is still 4.6.5 — Kraken must rebuild + republish for 4.7."
-    }
-  },
-  "terrain_3d": {
-    "macos-arm64": {
-      "debug_framework": "engine/macos-arm64/terrain_3d/bin/libterrain.macos.debug.framework",
-      "release_framework": "engine/macos-arm64/terrain_3d/bin/libterrain.macos.release.framework",
-      "sha256_debug": "653a16ffdc3e6bb05cf514b9700c943c8694133e28ec65800d074c58c13ea216",
-      "sha256_release": "ca16b2a6afa80c382ffd578ebb6b31ce456a251ef8642e7d1addba79ef51d564",
-      "engine_repo": "tinqs/engine",
-      "engine_commit": "bb8fe2f",
-      "built_against_engine_binary": "de00a306c",
-      "built_on": "2026-06-09",
-      "built_by": "Kraken",
-      "fix": "get_height no longer returns NaN at region borders.",
-      "install": "cp -R engine/macos-arm64/terrain_3d/bin/libterrain.macos.*.framework <ariki-game>/addons/terrain_3d/bin/",
-      "note": "GDExtension only — no engine rebuild needed."
+      "note": "4.7 editor + console + GodotSharp (matched pair). Built from engine 4f2e02e5b7 (4.7 snapshot + Windows build fixes: terrain_3d template-safety / +<array>,<vector>, .rc icon refs godot_console.ico->tinqs_console.ico, d3d12/angle/accesskit dep flags). Terrain3D is a NATIVE engine module — its C# bindings are in this GodotSharp (a stale GodotSharp -> 'Wrapper class not found for Terrain3D'). Verified: editor + both export templates build clean; ariki-game runs 59fps with sim connected. Resolves .agents/handoffs/forge-windows-4.7.md."
     }
   }
 }