Render: render.backend says why it renders on the CPU; mcp --gpu documented (#262)

get_project / render.backend reported "gpuAcceleration": true with
"active": "cpu" and no reason, which read as a broken GPU. The
headless MCP server only attaches the GPU compositor when started with
--gpu, which docs/agents.md didn't mention, and a failed --gpu said
only "no usable GPU adapter" (the adapter's error went to a log no
one sees). The session now keeps the host's reason there is no GPU
compositor (accel_note): the CLI's "headless: renders on the CPU
unless started with --gpu", or the desktop app's compositor setup or
retirement error. The status reports it as `why` whenever it renders
on the CPU (or that the project's renderer is Software Only). --gpu
failures include the adapter's error (Gpu::try_headless).
docs/agents.md documents `mcp --gpu`.

Test: render_backend_says_why_it_renders_on_the_cpu (engine).
Checked with effectcraft-cli mcp and mcp --gpu.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

crates/gpu/src/lib.rs

@@ -117,7 +117,13 @@ impl Gpu {
     /// On a device of its own (CLI, tests, benchmarks); `None` without a usable adapter.
     #[cfg(not(target_arch = "wasm32"))]
     pub fn headless() -> Option<Gpu> {
-        GpuContext::headless().map(Gpu::from_context)
+        Gpu::try_headless().map_err(|e| log::info!("gpu: {e}")).ok()
+    }
+
+    /// [`Gpu::headless`], with why there is none.
+    #[cfg(not(target_arch = "wasm32"))]
+    pub fn try_headless() -> Result<Gpu, String> {
+        pollster::block_on(GpuContext::request()).map(Gpu::from_context)
     }
 
     /// On an existing device (the desktop app shares egui-wgpu's).