diff --git a/scripting/api-reference/gpu/color-attachment.mdx b/scripting/api-reference/gpu/color-attachment.mdx
index a0009ee5..9fb781b4 100644
--- a/scripting/api-reference/gpu/color-attachment.mdx
+++ b/scripting/api-reference/gpu/color-attachment.mdx
@@ -2,19 +2,20 @@
 title: ColorAttachment
 ---
 
-Color attachment descriptor for beginRenderPass.
+Color attachment descriptor for context:beginRenderPass.
 
 
 ## Fields
 
 ### `view`
 
-Explicit render target view; defaults to canvas backing texture.
+Required render target view. Use GPUCanvas:colorView() for the
+canvas's 1× presentation target, or any GPUTexture:view().
 
 
 ### `resolveTarget`
 
-1x resolve target for MSAA (formats must match).
+1× resolve target for MSAA (formats must match `view`).
 
 
 ### `loadOp`
diff --git a/scripting/api-reference/gpu/depth-stencil-attachment.mdx b/scripting/api-reference/gpu/depth-stencil-attachment.mdx
index 085fefc3..08f580d6 100644
--- a/scripting/api-reference/gpu/depth-stencil-attachment.mdx
+++ b/scripting/api-reference/gpu/depth-stencil-attachment.mdx
@@ -2,7 +2,7 @@
 title: DepthStencilAttachment
 ---
 
-Depth/stencil attachment descriptor for beginRenderPass.
+Depth/stencil attachment descriptor for context:beginRenderPass.
 
 
 ## Fields
diff --git a/scripting/api-reference/gpu/gpu-canvas.mdx b/scripting/api-reference/gpu/gpu-canvas.mdx
index e51884d4..bcc9c052 100644
--- a/scripting/api-reference/gpu/gpu-canvas.mdx
+++ b/scripting/api-reference/gpu/gpu-canvas.mdx
@@ -2,8 +2,12 @@
 title: GPUCanvas
 ---
 
-A GPU canvas. Use `.image` with `renderer:drawImage()` to composite
-the result. Issue GPU draw calls via `beginRenderPass()`.
+A GPU canvas — a 1× presentation target, same role as a WebGPU surface
+texture. Use `.image` with `renderer:drawImage()` to composite the
+result. Render to it via `context:beginRenderPass({ color = {{ view =
+canvas:colorView(), ... }} })`. MSAA requires a user-allocated
+`GPUTexture.new({ sampleCount = N, renderTarget = true })` as the
+color view, with the canvas's `colorView()` set as `resolveTarget`.
 
 
 ## Fields
@@ -45,20 +49,9 @@ resize(width: number, height: number) -> ()
 ```
 </div>
 
-Resize the canvas. Recreates the backing texture and any depth buffer.
-
-
-### `beginRenderPass`
-
-{/* function beginRenderPass(self, desc: RenderPassDesc?): GPURenderPass */}
-<div class="signature">
-```lua
-beginRenderPass(desc: RenderPassDesc?) -> GPURenderPass
-```
-</div>
-
-Begin a GPU render pass targeting this canvas.
-Omitting desc.color renders to the canvas's own backing texture.
+Resize the canvas. Recreates the 1× backing texture. Any
+user-allocated MSAA / depth textures must be recreated by the
+script to match the new dimensions.
 
 
 ### `colorView`
@@ -70,6 +63,7 @@ colorView() -> GPUTextureView
 ```
 </div>
 
-View of the canvas backing texture. Use as a sampler input in a subsequent pass.
+View of the canvas backing texture. Use as a color attachment, an
+MSAA resolve target, or a sampler input in a subsequent pass.
 
 
diff --git a/scripting/api-reference/gpu/render-pass-desc.mdx b/scripting/api-reference/gpu/render-pass-desc.mdx
index dd57b97b..d30fc21e 100644
--- a/scripting/api-reference/gpu/render-pass-desc.mdx
+++ b/scripting/api-reference/gpu/render-pass-desc.mdx
@@ -2,7 +2,10 @@
 title: RenderPassDesc
 ---
 
-Full render pass descriptor for GPUCanvas:beginRenderPass.
+Render pass descriptor for context:beginRenderPass. Must include at
+least one color attachment or a depthStencil attachment. All attachments
+(color views + depth) must share one sampleCount, derived per WebGPU
+rules — pass sampleCount is inferred from the views, not declared.
 
 
 ## Fields
diff --git a/scripting/api-reference/interfaces/context.mdx b/scripting/api-reference/interfaces/context.mdx
index 1ca48793..7297a848 100644
--- a/scripting/api-reference/interfaces/context.mdx
+++ b/scripting/api-reference/interfaces/context.mdx
@@ -256,20 +256,35 @@ Use beginFrame/endFrame inside drawCanvas to render.
 {/* function gpuCanvas(self, desc: {
         width: number,
         height: number,
-        sampleCount: number?,
     }): GPUCanvas */}
 <div class="signature">
 ```lua
-gpuCanvas(desc: {width: number, height: number, sampleCount: number?,}) -> GPUCanvas
+gpuCanvas(desc: {width: number, height: number,}) -> GPUCanvas
 ```
 </div>
 
-Create a GPU canvas for custom GPU rendering.
-Use beginRenderPass inside drawCanvas to render.
-Pass `sampleCount` (2, 4, or 8) to enable MSAA on the canvas backing
-texture. When set, beginRenderPass automatically routes rendering
-through the MSAA color texture and resolves to the 1× backing —
-no extra setup needed in the script.
+Create a GPU canvas — a 1× presentation target. Render to it via
+`context:beginRenderPass(...)` using `canvas:colorView()` as a
+color attachment. For MSAA, allocate the multisampled color and
+depth textures yourself with `GPUTexture.new({ sampleCount = N,
+renderTarget = true })` and pass them in the descriptor.
+
+
+### `beginRenderPass`
+
+{/* function beginRenderPass(self, desc: RenderPassDesc): GPURenderPass */}
+<div class="signature">
+```lua
+beginRenderPass(desc: RenderPassDesc) -> GPURenderPass
+```
+</div>
+
+Open a GPU render pass. The descriptor must include at least one
+color attachment or a depthStencil attachment; every attachment
+carries its own GPUTextureView. The pass's sampleCount is derived
+from the attachments (WebGPU rules: all must share one
+sampleCount). Must be called inside a drawCanvas phase. Issue
+draw calls on the returned pass, then call `:finish()`.
 
 
 ### `features`
diff --git a/scripting/api-reference/interfaces/node.mdx b/scripting/api-reference/interfaces/node.mdx
index 55dda234..ebbcc012 100644
--- a/scripting/api-reference/interfaces/node.mdx
+++ b/scripting/api-reference/interfaces/node.mdx
@@ -140,7 +140,7 @@ drawCanvas(self: T) -> ()
 </div>
 
 Called during the drawCanvases pass (before draw).
-All canvas beginFrame/beginRenderPass calls must happen here.
+All canvas:beginFrame / context:beginRenderPass calls must happen here.
 
 
 ### `pointerDown`