doc updates

SHADER_CONTRACT.md

@@ -55,7 +55,7 @@ float4 shadeVideo(ShaderContext context)
 }
 ```
 
-With `autoReload` enabled in `config/runtime-host.json`, edits to shader source, manifests, and declared texture assets are picked up automatically.
+With `autoReload` enabled in `config/runtime-host.json`, edits to shader source, manifests, and declared texture assets are picked up automatically. You can also use **Reload shaders** in the control UI to manually rescan the shader library.
 
 ## Guidance For Shaders
 
@@ -80,7 +80,7 @@ Important rules:
 - If adapting third-party code, include attribution and source URL in the manifest description when the license allows adaptation.
 - If the source license is unclear or incompatible, do not add the shader package.
 
-Before finishing, compile-check the shader through the runtime wrapper or launch the app and verify the shader appears without an error in the selector.
+Before finishing, compile-check the shader through the runtime wrapper or launch the app and verify the shader appears without an error in the selector. CI also runs shader validation, so every available package in `shaders/` should compile successfully. Intentionally broken examples should stay visibly marked as broken rather than pretending to be production shaders.
 
 ## Manifest Fields
 
@@ -102,7 +102,7 @@ Optional fields:
 - `fonts`: packaged font assets for live text parameters.
 - `temporal`: history-buffer requirements.
 
-Parameter objects may also include an optional `description` string. The control UI displays it as helper text underneath the parameter label, so use it for short operational guidance rather than long documentation.
+Parameter objects may also include an optional `description` string. The control UI displays it as one-line helper text with the full text available on hover, so use it for short operational guidance rather than long documentation.
 
 Shader-visible identifiers must be valid Slang-style identifiers:
 
@@ -126,7 +126,7 @@ Most shaders should omit `passes`. The runtime then creates one implicit pass:
 }
 ```
 
-Advanced shaders may declare explicit passes:
+Advanced shaders may declare explicit passes. All passes may live in one `.slang` file by using different `entryPoint` values, or they may be split across multiple source files:
 
 ```json
 {
@@ -165,6 +165,28 @@ Pass input names:
 
 If `inputs` is omitted, the first pass samples `layerInput` and later passes sample `previousPass`.
 
+Single-file multipass example:
+
+```json
+{
+  "passes": [
+    {
+      "id": "mask",
+      "source": "shader.slang",
+      "entryPoint": "makeMask",
+      "output": "maskBuffer"
+    },
+    {
+      "id": "final",
+      "source": "shader.slang",
+      "entryPoint": "finish",
+      "inputs": ["maskBuffer"],
+      "output": "layerOutput"
+    }
+  ]
+}
+```
+
 Pass output names:
 
 - `layerOutput`: the final visible output of this layer.
@@ -609,6 +631,8 @@ When a shader compiles, the runtime writes generated files under `runtime/shader
 
 These files are ignored by git and are useful for debugging compiler output. If a shader fails to compile, inspect the wrapper first; it shows the exact generated Slang code including your included shader.
 
+For multipass shaders, these files reflect the most recently compiled pass. If a package has several passes, the reported compile error and pass name are usually more useful than assuming the cache contains the first pass.
+
 ## Common Pitfalls
 
 - Do not use hyphens in parameter IDs, texture IDs, or entry point names.