Checkpoint 5: complete asset freshness, schema migrations and editor diagnostics

docs/manual/editor/assets.md

@@ -26,6 +26,18 @@ With MCP, call `faset_import`, then query `faset_job` using the returned job ID.
 `faset_job_cancel` requests cancellation. Cancelling an import does not Undo an
 authoring edit. See [MCP and CLI](mcp.md) for transport setup and errors.
 
+The Assets panel marks an imported asset **Stale** when its source, external glTF
+buffer/image, Blender bundle, saved import settings, importer, or target profile
+differs from the active generation. Select the imported row, then **Import / Reimport**;
+the Console reports the changed input. **Refresh** checks immediately, and the panel
+also refreshes periodically. `faset_assets` exposes the same `freshness.state` and
+structured `freshness.reasons` to MCP clients. Checks compare contents, including
+files whose size and timestamp stayed unchanged. The last good cooked asset remains
+visible until reimport succeeds; checking freshness never publishes a generation.
+Cook and export refuse referenced stale or unavailable sources and explain which
+input needs reimport. A standalone exported game uses only its packaged cooked
+generation and never needs the original source files.
+
 ## Import an image
 
 PNG and JPEG become image assets. Drag an imported image into a scene to create a

docs/manual/editor/diagnostics.md

@@ -0,0 +1,19 @@
+# Developer diagnostics
+
+The optional Dear ImGui overlay shows renderer counters inside the Editor. The Editor's normal interface remains the retained Faset UI. Enable the diagnostic build explicitly:
+
+```sh
+cmake --preset linux-debug -DFASET_DEBUG_IMGUI=ON
+cmake --build --preset linux-debug --parallel 4
+build/linux-debug/faset_editor --project examples/projects/collect-3d --gui
+```
+
+On Windows, use `windows-debug` for both presets and `build/windows-debug/faset_editor.exe`. Press **F12** to show or hide the panel. Drag its title bar to move it; **Freeze counters** holds a completed-frame sample for inspection. Closing the panel does not stop rendering. Pointer gestures inside the overlay are kept out of the authoring UI.
+
+The panel reports the previous completed frame: renderer wall time, GPU timestamp time where available, synchronous readback time, draw calls, packed vertices, culled meshes, textures, explicit Vulkan allocation sizes, actual validation availability/errors, and GPU pass-label count. Renderer wall time includes waiting for GPU work; it is not thread CPU usage. Memory excludes driver-internal allocations. The overlay itself adds drawing work, so hide it for a baseline performance measurement.
+
+The Vulkan backend emits `VK_EXT_debug_utils` labels for `ShadowMap`, `ForwardAndUI`, `Readback`, and, when presenting, `Presentation`. A graphics capture tool that supports this extension can identify those command-buffer regions. Labels remain available without the Khronos validation layer when the extension is exposed; unsupported systems continue rendering and report labels unavailable. A submitted-label count confirms calls were emitted, not that an external capture tool was tested.
+
+This module is disabled by default and is linked only to the graphical Editor and its dedicated test when enabled. Player and exported games do not link ImGui. No overlay control changes authoring documents, gameplay state or export settings.
+
+Run `ctest --test-dir build/linux-debug -R '^editor_debug_overlay$' --output-on-failure` in an enabled build to check actual ImGui geometry/font rendering, F12 toggling, pointer isolation and restoration of the underlying frame. The regular renderer pixel test also verifies GPU labels and clipped UI triangles.

docs/manual/editor/workspace.md

@@ -103,9 +103,17 @@ check **Jobs** and **Console**. A successful build and schema export refresh the
 Inspector. A failed build retains the previous metadata and reports the failure.
 
 A missing schema or unsupported component version appears as read-only raw fields
-with **Copy raw fields**. The Editor preserves that data. Restore the matching module
-or provide a migration and rebuild before expecting normal field editing or Play.
-See [Build, Play, and export](export.md) for the C++ iteration loop.
+with **Copy raw fields**. Restore a missing module to make its schema available.
+For an older component, declare [data migration rules](../scripting/api.md#editor-data-migrations),
+choose **Build C++**, then **Migrate to v…** in the Inspector. This is one undoable
+authoring edit; save explicitly afterward. Inherited components show **Open source
+to migrate** instead. Top-level local additions migrate in their owning instance.
+Missing rules or conversion errors preserve the data and appear in Console.
+
+Opening or recovering a scene never migrates it automatically. Future versions
+stay opaque and cannot be downgraded. Review instance overrides separately when
+changing the source field's units or meaning. See [Build, Play, and export](export.md)
+for the C++ iteration loop.
 
 ## Project settings