diff --git a/app/node_replace_manager.py b/app/node_replace_manager.py
index d9aab5b22..72e8ac2b1 100644
--- a/app/node_replace_manager.py
+++ b/app/node_replace_manager.py
@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+import logging
+
 from aiohttp import web
 
 from typing import TYPE_CHECKING, TypedDict
@@ -31,8 +33,22 @@ class NodeReplaceManager:
         self._replacements: dict[str, list[NodeReplace]] = {}
 
     def register(self, node_replace: NodeReplace):
-        """Register a node replacement mapping."""
-        self._replacements.setdefault(node_replace.old_node_id, []).append(node_replace)
+        """Register a node replacement mapping.
+
+        Idempotent: if a replacement with the same (old_node_id, new_node_id)
+        is already registered, the duplicate is ignored. This prevents stale
+        entries from accumulating when custom nodes are reloaded in the same
+        process (e.g. via ComfyUI-Manager).
+        """
+        existing = self._replacements.setdefault(node_replace.old_node_id, [])
+        for entry in existing:
+            if entry.new_node_id == node_replace.new_node_id:
+                logging.debug(
+                    "Node replacement %s -> %s already registered, ignoring duplicate.",
+                    node_replace.old_node_id, node_replace.new_node_id,
+                )
+                return
+        existing.append(node_replace)
 
     def get_replacement(self, old_node_id: str) -> list[NodeReplace] | None:
         """Get replacements for an old node ID."""
diff --git a/comfy/background_removal/birefnet.json b/comfy/background_removal/birefnet.json
new file mode 100644
index 000000000..f0960af39
--- /dev/null
+++ b/comfy/background_removal/birefnet.json
@@ -0,0 +1,7 @@
+{
+    "model_type": "birefnet",
+    "image_std": [1.0, 1.0, 1.0],
+    "image_mean": [0.0, 0.0, 0.0],
+    "image_size": 1024,
+    "resize_to_original": true
+}
diff --git a/comfy/background_removal/birefnet.py b/comfy/background_removal/birefnet.py
new file mode 100644
index 000000000..df54b2b90
--- /dev/null
+++ b/comfy/background_removal/birefnet.py
@@ -0,0 +1,689 @@
+import torch
+import comfy.ops
+import numpy as np
+import torch.nn as nn
+from functools import partial
+import torch.nn.functional as F
+from torchvision.ops import deform_conv2d
+from comfy.ldm.modules.attention import optimized_attention_for_device
+
+CXT = [3072, 1536, 768, 384][1:][::-1][-3:]
+
+class Attention(nn.Module):
+    def __init__(self, dim, num_heads=8, qkv_bias=False, qk_scale=None, device=None, dtype=None, operations=None):
+        super().__init__()
+
+        self.dim = dim
+        self.num_heads = num_heads
+        head_dim = dim // num_heads
+        self.scale = qk_scale or head_dim ** -0.5
+
+        self.q = operations.Linear(dim, dim, bias=qkv_bias, device=device, dtype=dtype)
+        self.kv = operations.Linear(dim, dim * 2, bias=qkv_bias, device=device, dtype=dtype)
+        self.proj = operations.Linear(dim, dim, device=device, dtype=dtype)
+
+    def forward(self, x):
+        B, N, C = x.shape
+        optimized_attention = optimized_attention_for_device(x.device, mask=False, small_input=True)
+        q = self.q(x).reshape(B, N, self.num_heads, C // self.num_heads).permute(0, 2, 1, 3)
+        kv = self.kv(x).reshape(B, -1, 2, self.num_heads, C // self.num_heads).permute(2, 0, 3, 1, 4)
+        k, v = kv[0], kv[1]
+
+        x = optimized_attention(
+            q, k, v, heads=self.num_heads, skip_output_reshape=True, skip_reshape=True
+        ).transpose(1, 2).reshape(B, N, C)
+        x = self.proj(x)
+
+        return x
+
+class Mlp(nn.Module):
+    def __init__(self, in_features, hidden_features=None, out_features=None, device=None, dtype=None, operations=None):
+        super().__init__()
+        out_features = out_features or in_features
+        hidden_features = hidden_features or in_features
+        self.fc1 = operations.Linear(in_features, hidden_features, device=device, dtype=dtype)
+        self.act = nn.GELU()
+        self.fc2 = operations.Linear(hidden_features, out_features, device=device, dtype=dtype)
+
+    def forward(self, x):
+        x = self.fc1(x)
+        x = self.act(x)
+        x = self.fc2(x)
+        return x
+
+
+def window_partition(x, window_size):
+    B, H, W, C = x.shape
+    x = x.view(B, H // window_size, window_size, W // window_size, window_size, C)
+    windows = x.permute(0, 1, 3, 2, 4, 5).contiguous().view(-1, window_size, window_size, C)
+    return windows
+
+
+def window_reverse(windows, window_size, H, W):
+    B = int(windows.shape[0] / (H * W / window_size / window_size))
+    x = windows.view(B, H // window_size, W // window_size, window_size, window_size, -1)
+    x = x.permute(0, 1, 3, 2, 4, 5).contiguous().view(B, H, W, -1)
+    return x
+
+
+class WindowAttention(nn.Module):
+    def __init__(self, dim, window_size, num_heads, qkv_bias=True, qk_scale=None, device=None, dtype=None, operations=None):
+
+        super().__init__()
+        self.dim = dim
+        self.window_size = window_size  # Wh, Ww
+        self.num_heads = num_heads
+        head_dim = dim // num_heads
+        self.scale = qk_scale or head_dim ** -0.5
+
+        self.relative_position_bias_table = nn.Parameter(
+            torch.zeros((2 * window_size[0] - 1) * (2 * window_size[1] - 1), num_heads, device=device, dtype=dtype))
+
+        coords_h = torch.arange(self.window_size[0])
+        coords_w = torch.arange(self.window_size[1])
+        coords = torch.stack(torch.meshgrid([coords_h, coords_w], indexing='ij'))  # 2, Wh, Ww
+        coords_flatten = torch.flatten(coords, 1)  # 2, Wh*Ww
+        relative_coords = coords_flatten[:, :, None] - coords_flatten[:, None, :]  # 2, Wh*Ww, Wh*Ww
+        relative_coords = relative_coords.permute(1, 2, 0).contiguous()  # Wh*Ww, Wh*Ww, 2
+        relative_coords[:, :, 0] += self.window_size[0] - 1
+        relative_coords[:, :, 1] += self.window_size[1] - 1
+        relative_coords[:, :, 0] *= 2 * self.window_size[1] - 1
+        relative_position_index = relative_coords.sum(-1)  # Wh*Ww, Wh*Ww
+        self.register_buffer("relative_position_index", relative_position_index)
+
+        self.qkv = operations.Linear(dim, dim * 3, bias=qkv_bias, device=device, dtype=dtype)
+        self.proj = operations.Linear(dim, dim, device=device, dtype=dtype)
+        self.softmax = nn.Softmax(dim=-1)
+
+    def forward(self, x, mask=None):
+        B_, N, C = x.shape
+        qkv = self.qkv(x).reshape(B_, N, 3, self.num_heads, C // self.num_heads).permute(2, 0, 3, 1, 4)
+        q, k, v = qkv[0], qkv[1], qkv[2]
+
+        q = q * self.scale
+        attn = (q @ k.transpose(-2, -1))
+
+        relative_position_bias = self.relative_position_bias_table[self.relative_position_index.long().view(-1)].view(
+            self.window_size[0] * self.window_size[1], self.window_size[0] * self.window_size[1], -1)  # Wh*Ww,Wh*Ww,nH
+        relative_position_bias = relative_position_bias.permute(2, 0, 1).contiguous()  # nH, Wh*Ww, Wh*Ww
+        attn = attn + relative_position_bias.unsqueeze(0)
+
+        if mask is not None:
+            nW = mask.shape[0]
+            attn = attn.view(B_ // nW, nW, self.num_heads, N, N) + mask.unsqueeze(1).unsqueeze(0)
+            attn = attn.view(-1, self.num_heads, N, N)
+            attn = self.softmax(attn)
+        else:
+            attn = self.softmax(attn)
+
+        x = (attn @ v).transpose(1, 2).reshape(B_, N, C)
+        x = self.proj(x)
+        return x
+
+
+class SwinTransformerBlock(nn.Module):
+    def __init__(self, dim, num_heads, window_size=7, shift_size=0,
+                 mlp_ratio=4., qkv_bias=True, qk_scale=None,
+                 norm_layer=nn.LayerNorm, device=None, dtype=None, operations=None):
+        super().__init__()
+        self.dim = dim
+        self.num_heads = num_heads
+        self.window_size = window_size
+        self.shift_size = shift_size
+        self.mlp_ratio = mlp_ratio
+
+        self.norm1 = norm_layer(dim, device=device, dtype=dtype)
+        self.attn = WindowAttention(
+            dim, window_size=(self.window_size, self.window_size), num_heads=num_heads,
+            qkv_bias=qkv_bias, qk_scale=qk_scale, device=device, dtype=dtype, operations=operations)
+
+        self.norm2 = norm_layer(dim, device=device, dtype=dtype)
+        mlp_hidden_dim = int(dim * mlp_ratio)
+        self.mlp = Mlp(in_features=dim, hidden_features=mlp_hidden_dim, device=device, dtype=dtype, operations=operations)
+
+        self.H = None
+        self.W = None
+
+    def forward(self, x, mask_matrix):
+        B, L, C = x.shape
+        H, W = self.H, self.W
+
+        shortcut = x
+        x = self.norm1(x)
+        x = x.view(B, H, W, C)
+
+        pad_l = pad_t = 0
+        pad_r = (self.window_size - W % self.window_size) % self.window_size
+        pad_b = (self.window_size - H % self.window_size) % self.window_size
+        x = F.pad(x, (0, 0, pad_l, pad_r, pad_t, pad_b))
+        _, Hp, Wp, _ = x.shape
+
+        if self.shift_size > 0:
+            shifted_x = torch.roll(x, shifts=(-self.shift_size, -self.shift_size), dims=(1, 2))
+            attn_mask = mask_matrix
+        else:
+            shifted_x = x
+            attn_mask = None
+
+        x_windows = window_partition(shifted_x, self.window_size)
+        x_windows = x_windows.view(-1, self.window_size * self.window_size, C)
+
+        attn_windows = self.attn(x_windows, mask=attn_mask)
+
+        attn_windows = attn_windows.view(-1, self.window_size, self.window_size, C)
+        shifted_x = window_reverse(attn_windows, self.window_size, Hp, Wp)  # B H' W' C
+
+        if self.shift_size > 0:
+            x = torch.roll(shifted_x, shifts=(self.shift_size, self.shift_size), dims=(1, 2))
+        else:
+            x = shifted_x
+
+        if pad_r > 0 or pad_b > 0:
+            x = x[:, :H, :W, :].contiguous()
+
+        x = x.view(B, H * W, C)
+
+        x = shortcut + x
+        x = x + self.mlp(self.norm2(x))
+
+        return x
+
+
+class PatchMerging(nn.Module):
+    def __init__(self, dim, device=None, dtype=None, operations=None):
+        super().__init__()
+        self.dim = dim
+        self.reduction = operations.Linear(4 * dim, 2 * dim, bias=False, device=device, dtype=dtype)
+        self.norm = operations.LayerNorm(4 * dim, device=device, dtype=dtype)
+
+    def forward(self, x, H, W):
+        B, L, C = x.shape
+        x = x.view(B, H, W, C)
+
+        # padding
+        pad_input = (H % 2 == 1) or (W % 2 == 1)
+        if pad_input:
+            x = F.pad(x, (0, 0, 0, W % 2, 0, H % 2))
+
+        x0 = x[:, 0::2, 0::2, :]  # B H/2 W/2 C
+        x1 = x[:, 1::2, 0::2, :]  # B H/2 W/2 C
+        x2 = x[:, 0::2, 1::2, :]  # B H/2 W/2 C
+        x3 = x[:, 1::2, 1::2, :]  # B H/2 W/2 C
+        x = torch.cat([x0, x1, x2, x3], -1)  # B H/2 W/2 4*C
+        x = x.view(B, -1, 4 * C)  # B H/2*W/2 4*C
+
+        x = self.norm(x)
+        x = self.reduction(x)
+
+        return x
+
+
+class BasicLayer(nn.Module):
+    def __init__(self,
+                 dim,
+                 depth,
+                 num_heads,
+                 window_size=7,
+                 mlp_ratio=4.,
+                 qkv_bias=True,
+                 qk_scale=None,
+                 norm_layer=nn.LayerNorm,
+                 downsample=None,
+                 device=None, dtype=None, operations=None):
+        super().__init__()
+        self.window_size = window_size
+        self.shift_size = window_size // 2
+        self.depth = depth
+
+        # build blocks
+        self.blocks = nn.ModuleList([
+            SwinTransformerBlock(
+                dim=dim,
+                num_heads=num_heads,
+                window_size=window_size,
+                shift_size=0 if (i % 2 == 0) else window_size // 2,
+                mlp_ratio=mlp_ratio,
+                qkv_bias=qkv_bias,
+                qk_scale=qk_scale,
+                norm_layer=norm_layer,
+                device=device, dtype=dtype, operations=operations)
+            for i in range(depth)])
+
+        # patch merging layer
+        if downsample is not None:
+            self.downsample = downsample(dim=dim, device=device, dtype=dtype, operations=operations)
+        else:
+            self.downsample = None
+
+    def forward(self, x, H, W):
+        Hp = int(np.ceil(H / self.window_size)) * self.window_size
+        Wp = int(np.ceil(W / self.window_size)) * self.window_size
+        img_mask = torch.zeros((1, Hp, Wp, 1), device=x.device)  # 1 Hp Wp 1
+        h_slices = (slice(0, -self.window_size),
+                    slice(-self.window_size, -self.shift_size),
+                    slice(-self.shift_size, None))
+        w_slices = (slice(0, -self.window_size),
+                    slice(-self.window_size, -self.shift_size),
+                    slice(-self.shift_size, None))
+        cnt = 0
+        for h in h_slices:
+            for w in w_slices:
+                img_mask[:, h, w, :] = cnt
+                cnt += 1
+
+        mask_windows = window_partition(img_mask, self.window_size)
+        mask_windows = mask_windows.view(-1, self.window_size * self.window_size)
+        attn_mask = mask_windows.unsqueeze(1) - mask_windows.unsqueeze(2)
+        attn_mask = attn_mask.masked_fill(attn_mask != 0, float(-100.0)).masked_fill(attn_mask == 0, float(0.0))
+
+        for blk in self.blocks:
+            blk.H, blk.W = H, W
+            x = blk(x, attn_mask)
+        if self.downsample is not None:
+            x_down = self.downsample(x, H, W)
+            Wh, Ww = (H + 1) // 2, (W + 1) // 2
+            return x, H, W, x_down, Wh, Ww
+        else:
+            return x, H, W, x, H, W
+
+
+class PatchEmbed(nn.Module):
+    def __init__(self, patch_size=4, in_channels=3, embed_dim=96, norm_layer=None, device=None, dtype=None, operations=None):
+        super().__init__()
+        patch_size = (patch_size, patch_size)
+        self.patch_size = patch_size
+
+        self.in_channels = in_channels
+        self.embed_dim = embed_dim
+
+        self.proj = operations.Conv2d(in_channels, embed_dim, kernel_size=patch_size, stride=patch_size, device=device, dtype=dtype)
+        if norm_layer is not None:
+            self.norm = norm_layer(embed_dim, device=device, dtype=dtype)
+        else:
+            self.norm = None
+
+    def forward(self, x):
+        _, _, H, W = x.size()
+        if W % self.patch_size[1] != 0:
+            x = F.pad(x, (0, self.patch_size[1] - W % self.patch_size[1]))
+        if H % self.patch_size[0] != 0:
+            x = F.pad(x, (0, 0, 0, self.patch_size[0] - H % self.patch_size[0]))
+
+        x = self.proj(x)  # B C Wh Ww
+        if self.norm is not None:
+            Wh, Ww = x.size(2), x.size(3)
+            x = x.flatten(2).transpose(1, 2)
+            x = self.norm(x)
+            x = x.transpose(1, 2).view(-1, self.embed_dim, Wh, Ww)
+
+        return x
+
+
+class SwinTransformer(nn.Module):
+    def __init__(self,
+                 pretrain_img_size=224,
+                 patch_size=4,
+                 in_channels=3,
+                 embed_dim=96,
+                 depths=[2, 2, 6, 2],
+                 num_heads=[3, 6, 12, 24],
+                 window_size=7,
+                 mlp_ratio=4.,
+                 qkv_bias=True,
+                 qk_scale=None,
+                 patch_norm=True,
+                 out_indices=(0, 1, 2, 3),
+                 frozen_stages=-1,
+                 device=None, dtype=None, operations=None):
+        super().__init__()
+
+        norm_layer = partial(operations.LayerNorm, device=device, dtype=dtype)
+        self.pretrain_img_size = pretrain_img_size
+        self.num_layers = len(depths)
+        self.embed_dim = embed_dim
+        self.patch_norm = patch_norm
+        self.out_indices = out_indices
+        self.frozen_stages = frozen_stages
+
+        self.patch_embed = PatchEmbed(
+            patch_size=patch_size, in_channels=in_channels, embed_dim=embed_dim,
+            device=device, dtype=dtype, operations=operations,
+            norm_layer=norm_layer if self.patch_norm else None)
+
+        self.layers = nn.ModuleList()
+        for i_layer in range(self.num_layers):
+            layer = BasicLayer(
+                dim=int(embed_dim * 2 ** i_layer),
+                depth=depths[i_layer],
+                num_heads=num_heads[i_layer],
+                window_size=window_size,
+                mlp_ratio=mlp_ratio,
+                qkv_bias=qkv_bias,
+                qk_scale=qk_scale,
+                norm_layer=norm_layer,
+                downsample=PatchMerging if (i_layer < self.num_layers - 1) else None,
+                device=device, dtype=dtype, operations=operations)
+            self.layers.append(layer)
+
+        num_features = [int(embed_dim * 2 ** i) for i in range(self.num_layers)]
+        self.num_features = num_features
+
+        for i_layer in out_indices:
+            layer = norm_layer(num_features[i_layer])
+            layer_name = f'norm{i_layer}'
+            self.add_module(layer_name, layer)
+
+
+    def forward(self, x):
+        x = self.patch_embed(x)
+
+        Wh, Ww = x.size(2), x.size(3)
+
+        outs = []
+        x = x.flatten(2).transpose(1, 2)
+        for i in range(self.num_layers):
+            layer = self.layers[i]
+            x_out, H, W, x, Wh, Ww = layer(x, Wh, Ww)
+
+            if i in self.out_indices:
+                norm_layer = getattr(self, f'norm{i}')
+                x_out = norm_layer(x_out)
+
+                out = x_out.view(-1, H, W, self.num_features[i]).permute(0, 3, 1, 2).contiguous()
+                outs.append(out)
+
+        return tuple(outs)
+
+class DeformableConv2d(nn.Module):
+    def __init__(self,
+                 in_channels,
+                 out_channels,
+                 kernel_size=3,
+                 stride=1,
+                 padding=1,
+                 bias=False, device=None, dtype=None, operations=None):
+
+        super(DeformableConv2d, self).__init__()
+
+        kernel_size = kernel_size if type(kernel_size) is tuple else (kernel_size, kernel_size)
+        self.stride = stride if type(stride) is tuple else (stride, stride)
+        self.padding = padding
+
+        self.offset_conv = operations.Conv2d(in_channels,
+                                     2 * kernel_size[0] * kernel_size[1],
+                                     kernel_size=kernel_size,
+                                     stride=stride,
+                                     padding=self.padding,
+                                     bias=True, device=device, dtype=dtype)
+
+        self.modulator_conv = operations.Conv2d(in_channels,
+                                     1 * kernel_size[0] * kernel_size[1],
+                                     kernel_size=kernel_size,
+                                     stride=stride,
+                                     padding=self.padding,
+                                     bias=True, device=device, dtype=dtype)
+
+        self.regular_conv = operations.Conv2d(in_channels,
+                                      out_channels=out_channels,
+                                      kernel_size=kernel_size,
+                                      stride=stride,
+                                      padding=self.padding,
+                                      bias=bias, device=device, dtype=dtype)
+
+    def forward(self, x):
+        offset = self.offset_conv(x)
+        modulator = 2. * torch.sigmoid(self.modulator_conv(x))
+        weight, bias, offload_info = comfy.ops.cast_bias_weight(self.regular_conv, x, offloadable=True)
+
+        x = deform_conv2d(
+            input=x,
+            offset=offset,
+            weight=weight,
+            bias=None,
+            padding=self.padding,
+            mask=modulator,
+            stride=self.stride,
+        )
+        comfy.ops.uncast_bias_weight(self.regular_conv, weight, bias, offload_info)
+        return x
+
+class BasicDecBlk(nn.Module):
+    def __init__(self, in_channels=64, out_channels=64, inter_channels=64, device=None, dtype=None, operations=None):
+        super(BasicDecBlk, self).__init__()
+        inter_channels = 64
+        self.conv_in = operations.Conv2d(in_channels, inter_channels, 3, 1, padding=1, device=device, dtype=dtype)
+        self.relu_in = nn.ReLU(inplace=True)
+        self.dec_att = ASPPDeformable(in_channels=inter_channels, device=device, dtype=dtype, operations=operations)
+        self.conv_out = operations.Conv2d(inter_channels, out_channels, 3, 1, padding=1, device=device, dtype=dtype)
+        self.bn_in = operations.BatchNorm2d(inter_channels, device=device, dtype=dtype)
+        self.bn_out = operations.BatchNorm2d(out_channels, device=device, dtype=dtype)
+
+    def forward(self, x):
+        x = self.conv_in(x)
+        x = self.bn_in(x)
+        x = self.relu_in(x)
+        x = self.dec_att(x)
+        x = self.conv_out(x)
+        x = self.bn_out(x)
+        return x
+
+
+class BasicLatBlk(nn.Module):
+    def __init__(self, in_channels=64, out_channels=64, device=None, dtype=None, operations=None):
+        super(BasicLatBlk, self).__init__()
+        self.conv = operations.Conv2d(in_channels, out_channels, 1, 1, 0, device=device, dtype=dtype)
+
+    def forward(self, x):
+        x = self.conv(x)
+        return x
+
+
+class _ASPPModuleDeformable(nn.Module):
+    def __init__(self, in_channels, planes, kernel_size, padding, device, dtype, operations):
+        super(_ASPPModuleDeformable, self).__init__()
+        self.atrous_conv = DeformableConv2d(in_channels, planes, kernel_size=kernel_size,
+                                            stride=1, padding=padding, bias=False, device=device, dtype=dtype, operations=operations)
+        self.bn = operations.BatchNorm2d(planes, device=device, dtype=dtype)
+        self.relu = nn.ReLU(inplace=True)
+
+    def forward(self, x):
+        x = self.atrous_conv(x)
+        x = self.bn(x)
+
+        return self.relu(x)
+
+
+class ASPPDeformable(nn.Module):
+    def __init__(self, in_channels, out_channels=None, parallel_block_sizes=[1, 3, 7], device=None, dtype=None, operations=None):
+        super(ASPPDeformable, self).__init__()
+        self.down_scale = 1
+        if out_channels is None:
+            out_channels = in_channels
+        self.in_channelster = 256 // self.down_scale
+
+        self.aspp1 = _ASPPModuleDeformable(in_channels, self.in_channelster, 1, padding=0, device=device, dtype=dtype, operations=operations)
+        self.aspp_deforms = nn.ModuleList([
+            _ASPPModuleDeformable(in_channels, self.in_channelster, conv_size, padding=int(conv_size//2), device=device, dtype=dtype, operations=operations)
+              for conv_size in parallel_block_sizes
+        ])
+
+        self.global_avg_pool = nn.Sequential(nn.AdaptiveAvgPool2d((1, 1)),
+                                             operations.Conv2d(in_channels, self.in_channelster, 1, stride=1, bias=False, device=device, dtype=dtype),
+                                             operations.BatchNorm2d(self.in_channelster, device=device, dtype=dtype),
+                                             nn.ReLU(inplace=True))
+        self.conv1 = operations.Conv2d(self.in_channelster * (2 + len(self.aspp_deforms)), out_channels, 1, bias=False, device=device, dtype=dtype)
+        self.bn1 = operations.BatchNorm2d(out_channels, device=device, dtype=dtype)
+        self.relu = nn.ReLU(inplace=True)
+
+    def forward(self, x):
+        x1 = self.aspp1(x)
+        x_aspp_deforms = [aspp_deform(x) for aspp_deform in self.aspp_deforms]
+        x5 = self.global_avg_pool(x)
+        x5 = F.interpolate(x5, size=x1.size()[2:], mode='bilinear', align_corners=True)
+        x = torch.cat((x1, *x_aspp_deforms, x5), dim=1)
+
+        x = self.conv1(x)
+        x = self.bn1(x)
+        x = self.relu(x)
+
+        return x
+
+class BiRefNet(nn.Module):
+    def __init__(self, config=None, dtype=None, device=None, operations=None):
+        super(BiRefNet, self).__init__()
+        self.bb = SwinTransformer(embed_dim=192, depths=[2, 2, 18, 2], num_heads=[6, 12, 24, 48], window_size=12, device=device, dtype=dtype, operations=operations)
+
+        channels = [1536, 768, 384, 192]
+        channels = [c * 2 for c in channels]
+        self.cxt = channels[1:][::-1][-3:]
+        self.squeeze_module = nn.Sequential(*[
+            BasicDecBlk(channels[0]+sum(self.cxt), channels[0], device=device, dtype=dtype, operations=operations)
+            for _ in range(1)
+        ])
+
+        self.decoder = Decoder(channels, device=device, dtype=dtype, operations=operations)
+
+    def forward_enc(self, x):
+        x1, x2, x3, x4 = self.bb(x)
+        B, C, H, W = x.shape
+        x1_, x2_, x3_, x4_ = self.bb(F.interpolate(x, size=(H//2, W//2), mode='bilinear', align_corners=True))
+        x1 = torch.cat([x1, F.interpolate(x1_, size=x1.shape[2:], mode='bilinear', align_corners=True)], dim=1)
+        x2 = torch.cat([x2, F.interpolate(x2_, size=x2.shape[2:], mode='bilinear', align_corners=True)], dim=1)
+        x3 = torch.cat([x3, F.interpolate(x3_, size=x3.shape[2:], mode='bilinear', align_corners=True)], dim=1)
+        x4 = torch.cat([x4, F.interpolate(x4_, size=x4.shape[2:], mode='bilinear', align_corners=True)], dim=1)
+        x4 = torch.cat(
+            (
+                *[
+                    F.interpolate(x1, size=x4.shape[2:], mode='bilinear', align_corners=True),
+                    F.interpolate(x2, size=x4.shape[2:], mode='bilinear', align_corners=True),
+                    F.interpolate(x3, size=x4.shape[2:], mode='bilinear', align_corners=True),
+                ][-len(CXT):],
+                x4
+            ),
+            dim=1
+        )
+        return (x1, x2, x3, x4)
+
+    def forward_ori(self, x):
+        (x1, x2, x3, x4) = self.forward_enc(x)
+        x4 = self.squeeze_module(x4)
+        features = [x, x1, x2, x3, x4]
+        scaled_preds = self.decoder(features)
+        return scaled_preds
+
+    def forward(self, pixel_values, intermediate_output=None):
+        scaled_preds = self.forward_ori(pixel_values)
+        return scaled_preds
+
+
+class Decoder(nn.Module):
+    def __init__(self, channels, device, dtype, operations):
+        super(Decoder, self).__init__()
+        # factory kwargs
+        fk = {"device":device, "dtype":dtype, "operations":operations}
+        DecoderBlock = partial(BasicDecBlk, **fk)
+        LateralBlock = partial(BasicLatBlk, **fk)
+        DBlock = partial(SimpleConvs, **fk)
+
+        self.split = True
+        N_dec_ipt = 64
+        ic = 64
+        ipt_cha_opt = 1
+        self.ipt_blk5 = DBlock(2**10*3 if self.split else 3, [N_dec_ipt, channels[0]//8][ipt_cha_opt], inter_channels=ic)
+        self.ipt_blk4 = DBlock(2**8*3 if self.split else 3, [N_dec_ipt, channels[0]//8][ipt_cha_opt], inter_channels=ic)
+        self.ipt_blk3 = DBlock(2**6*3 if self.split else 3, [N_dec_ipt, channels[1]//8][ipt_cha_opt], inter_channels=ic)
+        self.ipt_blk2 = DBlock(2**4*3 if self.split else 3, [N_dec_ipt, channels[2]//8][ipt_cha_opt], inter_channels=ic)
+        self.ipt_blk1 = DBlock(2**0*3 if self.split else 3, [N_dec_ipt, channels[3]//8][ipt_cha_opt], inter_channels=ic)
+
+        self.decoder_block4 = DecoderBlock(channels[0]+([N_dec_ipt, channels[0]//8][ipt_cha_opt]), channels[1])
+        self.decoder_block3 = DecoderBlock(channels[1]+([N_dec_ipt, channels[0]//8][ipt_cha_opt]), channels[2])
+        self.decoder_block2 = DecoderBlock(channels[2]+([N_dec_ipt, channels[1]//8][ipt_cha_opt]), channels[3])
+        self.decoder_block1 = DecoderBlock(channels[3]+([N_dec_ipt, channels[2]//8][ipt_cha_opt]), channels[3]//2)
+
+        fk = {"device":device, "dtype":dtype}
+
+        self.conv_out1 = nn.Sequential(operations.Conv2d(channels[3]//2+([N_dec_ipt, channels[3]//8][ipt_cha_opt]), 1, 1, 1, 0, **fk))
+
+        self.lateral_block4 = LateralBlock(channels[1], channels[1])
+        self.lateral_block3 = LateralBlock(channels[2], channels[2])
+        self.lateral_block2 = LateralBlock(channels[3], channels[3])
+
+        self.conv_ms_spvn_4 = operations.Conv2d(channels[1], 1, 1, 1, 0, **fk)
+        self.conv_ms_spvn_3 = operations.Conv2d(channels[2], 1, 1, 1, 0, **fk)
+        self.conv_ms_spvn_2 = operations.Conv2d(channels[3], 1, 1, 1, 0, **fk)
+
+        _N = 16
+
+        self.gdt_convs_4 = nn.Sequential(operations.Conv2d(channels[0] // 2, _N, 3, 1, 1, **fk), operations.BatchNorm2d(_N, **fk), nn.ReLU(inplace=True))
+        self.gdt_convs_3 = nn.Sequential(operations.Conv2d(channels[1] // 2, _N, 3, 1, 1, **fk), operations.BatchNorm2d(_N, **fk), nn.ReLU(inplace=True))
+        self.gdt_convs_2 = nn.Sequential(operations.Conv2d(channels[2] // 2, _N, 3, 1, 1, **fk), operations.BatchNorm2d(_N, **fk), nn.ReLU(inplace=True))
+
+        [setattr(self, f"gdt_convs_pred_{i}", nn.Sequential(operations.Conv2d(_N, 1, 1, 1, 0, **fk))) for i in range(2, 5)]
+        [setattr(self, f"gdt_convs_attn_{i}", nn.Sequential(operations.Conv2d(_N, 1, 1, 1, 0, **fk))) for i in range(2, 5)]
+
+    def get_patches_batch(self, x, p):
+        _size_h, _size_w = p.shape[2:]
+        patches_batch = []
+        for idx in range(x.shape[0]):
+            columns_x = torch.split(x[idx], split_size_or_sections=_size_w, dim=-1)
+            patches_x = []
+            for column_x in columns_x:
+                patches_x += [p.unsqueeze(0) for p in torch.split(column_x, split_size_or_sections=_size_h, dim=-2)]
+            patch_sample = torch.cat(patches_x, dim=1)
+            patches_batch.append(patch_sample)
+        return torch.cat(patches_batch, dim=0)
+
+    def forward(self, features):
+        x, x1, x2, x3, x4 = features
+
+        patches_batch = self.get_patches_batch(x, x4) if self.split else x
+        x4 = torch.cat((x4, self.ipt_blk5(F.interpolate(patches_batch, size=x4.shape[2:], mode='bilinear', align_corners=True))), 1)
+        p4 = self.decoder_block4(x4)
+        p4_gdt = self.gdt_convs_4(p4)
+        gdt_attn_4 = self.gdt_convs_attn_4(p4_gdt).sigmoid()
+        p4 = p4 * gdt_attn_4
+        _p4 = F.interpolate(p4, size=x3.shape[2:], mode='bilinear', align_corners=True)
+        _p3 = _p4 + self.lateral_block4(x3)
+
+        patches_batch = self.get_patches_batch(x, _p3) if self.split else x
+        _p3 = torch.cat((_p3, self.ipt_blk4(F.interpolate(patches_batch, size=x3.shape[2:], mode='bilinear', align_corners=True))), 1)
+        p3 = self.decoder_block3(_p3)
+
+        p3_gdt = self.gdt_convs_3(p3)
+        gdt_attn_3 = self.gdt_convs_attn_3(p3_gdt).sigmoid()
+        p3 = p3 * gdt_attn_3
+        _p3 = F.interpolate(p3, size=x2.shape[2:], mode='bilinear', align_corners=True)
+        _p2 = _p3 + self.lateral_block3(x2)
+
+        patches_batch = self.get_patches_batch(x, _p2) if self.split else x
+        _p2 = torch.cat((_p2, self.ipt_blk3(F.interpolate(patches_batch, size=x2.shape[2:], mode='bilinear', align_corners=True))), 1)
+        p2 = self.decoder_block2(_p2)
+
+        p2_gdt = self.gdt_convs_2(p2)
+        gdt_attn_2 = self.gdt_convs_attn_2(p2_gdt).sigmoid()
+        p2 = p2 * gdt_attn_2
+
+        _p2 = F.interpolate(p2, size=x1.shape[2:], mode='bilinear', align_corners=True)
+        _p1 = _p2 + self.lateral_block2(x1)
+
+        patches_batch = self.get_patches_batch(x, _p1) if self.split else x
+        _p1 = torch.cat((_p1, self.ipt_blk2(F.interpolate(patches_batch, size=x1.shape[2:], mode='bilinear', align_corners=True))), 1)
+        _p1 = self.decoder_block1(_p1)
+        _p1 = F.interpolate(_p1, size=x.shape[2:], mode='bilinear', align_corners=True)
+
+        patches_batch = self.get_patches_batch(x, _p1) if self.split else x
+        _p1 = torch.cat((_p1, self.ipt_blk1(F.interpolate(patches_batch, size=x.shape[2:], mode='bilinear', align_corners=True))), 1)
+        p1_out = self.conv_out1(_p1)
+        return p1_out
+
+
+class SimpleConvs(nn.Module):
+    def __init__(
+        self, in_channels: int, out_channels: int, inter_channels=64, device=None, dtype=None, operations=None
+    ) -> None:
+        super().__init__()
+        self.conv1 = operations.Conv2d(in_channels, inter_channels, 3, 1, 1, device=device, dtype=dtype)
+        self.conv_out = operations.Conv2d(inter_channels, out_channels, 3, 1, 1, device=device, dtype=dtype)
+
+    def forward(self, x):
+        return self.conv_out(self.conv1(x))
diff --git a/comfy/bg_removal_model.py b/comfy/bg_removal_model.py
new file mode 100644
index 000000000..7877afd7f
--- /dev/null
+++ b/comfy/bg_removal_model.py
@@ -0,0 +1,78 @@
+from .utils import load_torch_file
+import os
+import json
+import torch
+import logging
+
+import comfy.ops
+import comfy.model_patcher
+import comfy.model_management
+import comfy.clip_model
+import comfy.background_removal.birefnet
+
+BG_REMOVAL_MODELS = {
+    "birefnet": comfy.background_removal.birefnet.BiRefNet
+}
+
+class BackgroundRemovalModel():
+    def __init__(self, json_config):
+        with open(json_config) as f:
+            config = json.load(f)
+
+        self.image_size = config.get("image_size", 1024)
+        self.image_mean = config.get("image_mean", [0.0, 0.0, 0.0])
+        self.image_std = config.get("image_std", [1.0, 1.0, 1.0])
+        self.model_type = config.get("model_type", "birefnet")
+        self.config = config.copy()
+        model_class = BG_REMOVAL_MODELS.get(self.model_type)
+
+        self.load_device = comfy.model_management.text_encoder_device()
+        offload_device = comfy.model_management.text_encoder_offload_device()
+        self.dtype = comfy.model_management.text_encoder_dtype(self.load_device)
+        self.model = model_class(config, self.dtype, offload_device, comfy.ops.manual_cast)
+        self.model.eval()
+
+        self.patcher = comfy.model_patcher.CoreModelPatcher(self.model, load_device=self.load_device, offload_device=offload_device)
+
+    def load_sd(self, sd):
+        return self.model.load_state_dict(sd, strict=False, assign=self.patcher.is_dynamic())
+
+    def get_sd(self):
+        return self.model.state_dict()
+
+    def encode_image(self, image):
+        comfy.model_management.load_model_gpu(self.patcher)
+        H, W = image.shape[1], image.shape[2]
+        pixel_values = comfy.clip_model.clip_preprocess(image.to(self.load_device), size=self.image_size, mean=self.image_mean, std=self.image_std, crop=False)
+        out = self.model(pixel_values=pixel_values)
+        out = torch.nn.functional.interpolate(out, size=(H, W), mode="bicubic", antialias=False)
+
+        mask = out.sigmoid().to(device=comfy.model_management.intermediate_device(), dtype=comfy.model_management.intermediate_dtype())
+        if mask.ndim == 3:
+            mask = mask.unsqueeze(0)
+        if mask.shape[1] != 1:
+            mask = mask.movedim(-1, 1)
+
+        return mask
+
+
+def load_background_removal_model(sd):
+    if "bb.layers.1.blocks.0.attn.relative_position_index" in sd:
+        json_config = os.path.join(os.path.join(os.path.dirname(os.path.realpath(__file__)), "background_removal"), "birefnet.json")
+    else:
+        return None
+
+    bg_model = BackgroundRemovalModel(json_config)
+    m, u = bg_model.load_sd(sd)
+    if len(m) > 0:
+        logging.warning("missing background removal: {}".format(m))
+    u = set(u)
+    keys = list(sd.keys())
+    for k in keys:
+        if k not in u:
+            sd.pop(k)
+    return bg_model
+
+def load(ckpt_path):
+    sd = load_torch_file(ckpt_path)
+    return load_background_removal_model(sd)
diff --git a/comfy/hooks.py b/comfy/hooks.py
index 1a76c7ba4..5458fc3d8 100644
--- a/comfy/hooks.py
+++ b/comfy/hooks.py
@@ -93,7 +93,7 @@ class Hook:
         self.hook_scope = hook_scope
         '''Scope of where this hook should apply in terms of the conds used in sampling run.'''
         self.custom_should_register = default_should_register
-        '''Can be overriden with a compatible function to decide if this hook should be registered without the need to override .should_register'''
+        '''Can be overridden with a compatible function to decide if this hook should be registered without the need to override .should_register'''
 
     @property
     def strength(self):
diff --git a/comfy/ldm/modules/diffusionmodules/util.py b/comfy/ldm/modules/diffusionmodules/util.py
index 233011dc9..aed5c149c 100644
--- a/comfy/ldm/modules/diffusionmodules/util.py
+++ b/comfy/ldm/modules/diffusionmodules/util.py
@@ -140,7 +140,7 @@ def make_ddim_sampling_parameters(alphacums, ddim_timesteps, eta, verbose=True):
     alphas = alphacums[ddim_timesteps]
     alphas_prev = np.asarray([alphacums[0]] + alphacums[ddim_timesteps[:-1]].tolist())
 
-    # according the the formula provided in https://arxiv.org/abs/2010.02502
+    # according to the formula provided in https://arxiv.org/abs/2010.02502
     sigmas = eta * np.sqrt((1 - alphas_prev) / (1 - alphas) * (1 - alphas / alphas_prev))
     if verbose:
         logging.info(f'Selected alphas for ddim sampler: a_t: {alphas}; a_(t-1): {alphas_prev}')
diff --git a/comfy/ops.py b/comfy/ops.py
index 585c185a3..77ad1d527 100644
--- a/comfy/ops.py
+++ b/comfy/ops.py
@@ -562,6 +562,25 @@ class disable_weight_init:
             else:
                 return super().forward(*args, **kwargs)
 
+    class BatchNorm2d(torch.nn.BatchNorm2d, CastWeightBiasOp):
+        def reset_parameters(self):
+            return None
+
+        def forward_comfy_cast_weights(self, input):
+            weight, bias, offload_stream = cast_bias_weight(self, input, offloadable=True)
+            running_mean = self.running_mean.to(device=input.device, dtype=weight.dtype) if self.running_mean is not None else None
+            running_var = self.running_var.to(device=input.device, dtype=weight.dtype) if self.running_var is not None else None
+            x = torch.nn.functional.batch_norm(input, running_mean, running_var, weight, bias, self.training, self.momentum, self.eps)
+            uncast_bias_weight(self, weight, bias, offload_stream)
+            return x
+
+        def forward(self, *args, **kwargs):
+            run_every_op()
+            if self.comfy_cast_weights or len(self.weight_function) > 0 or len(self.bias_function) > 0:
+                return self.forward_comfy_cast_weights(*args, **kwargs)
+            else:
+                return super().forward(*args, **kwargs)
+
     class LayerNorm(torch.nn.LayerNorm, CastWeightBiasOp):
         def reset_parameters(self):
             return None
@@ -749,6 +768,9 @@ class manual_cast(disable_weight_init):
     class Conv3d(disable_weight_init.Conv3d):
         comfy_cast_weights = True
 
+    class BatchNorm2d(disable_weight_init.BatchNorm2d):
+        comfy_cast_weights = True
+
     class GroupNorm(disable_weight_init.GroupNorm):
         comfy_cast_weights = True
 
diff --git a/comfy/utils.py b/comfy/utils.py
index 7b7faad3a..91e1ba3d3 100644
--- a/comfy/utils.py
+++ b/comfy/utils.py
@@ -1390,7 +1390,7 @@ def convert_old_quants(state_dict, model_prefix="", metadata={}):
                     k_out = "{}.weight_scale".format(layer)
 
                 if layer is not None:
-                    layer_conf = {"format": "float8_e4m3fn"}  # TODO: check if anyone did some non e4m3fn scaled checkpoints
+                    layer_conf = {"format": "float8_e4m3fn"}
                     if full_precision_matrix_mult:
                         layer_conf["full_precision_matrix_mult"] = full_precision_matrix_mult
                     layers[layer] = layer_conf
diff --git a/comfy_api/latest/_io.py b/comfy_api/latest/_io.py
index e50266bc5..5ed968960 100644
--- a/comfy_api/latest/_io.py
+++ b/comfy_api/latest/_io.py
@@ -17,6 +17,7 @@ if TYPE_CHECKING:
     from spandrel import ImageModelDescriptor
     from comfy.clip_vision import ClipVisionModel
     from comfy.clip_vision import Output as ClipVisionOutput_
+    from comfy.bg_removal_model import BackgroundRemovalModel
     from comfy.controlnet import ControlNet
     from comfy.hooks import HookGroup, HookKeyframeGroup
     from comfy.model_patcher import ModelPatcher
@@ -614,6 +615,11 @@ class Model(ComfyTypeIO):
     if TYPE_CHECKING:
         Type = ModelPatcher
 
+@comfytype(io_type="BACKGROUND_REMOVAL")
+class BackgroundRemoval(ComfyTypeIO):
+    if TYPE_CHECKING:
+        Type = BackgroundRemovalModel
+
 @comfytype(io_type="CLIP_VISION")
 class ClipVision(ComfyTypeIO):
     if TYPE_CHECKING:
@@ -2257,6 +2263,7 @@ __all__ = [
     "ModelPatch",
     "ClipVision",
     "ClipVisionOutput",
+    "BackgroundRemoval",
     "AudioEncoder",
     "AudioEncoderOutput",
     "StyleModel",
diff --git a/comfy_api_nodes/nodes_bytedance.py b/comfy_api_nodes/nodes_bytedance.py
index 2f241a775..5f74f4a14 100644
--- a/comfy_api_nodes/nodes_bytedance.py
+++ b/comfy_api_nodes/nodes_bytedance.py
@@ -1271,7 +1271,7 @@ PRICE_BADGE_VIDEO = IO.PriceBadge(
 )
 
 
-def _seedance2_text_inputs(resolutions: list[str]):
+def _seedance2_text_inputs(resolutions: list[str], default_ratio: str = "16:9"):
     return [
         IO.String.Input(
             "prompt",
@@ -1287,6 +1287,7 @@ def _seedance2_text_inputs(resolutions: list[str]):
         IO.Combo.Input(
             "ratio",
             options=["16:9", "4:3", "1:1", "3:4", "9:16", "21:9", "adaptive"],
+            default=default_ratio,
             tooltip="Aspect ratio of the output video.",
         ),
         IO.Int.Input(
@@ -1420,8 +1421,14 @@ class ByteDance2FirstLastFrameNode(IO.ComfyNode):
                 IO.DynamicCombo.Input(
                     "model",
                     options=[
-                        IO.DynamicCombo.Option("Seedance 2.0", _seedance2_text_inputs(["480p", "720p", "1080p"])),
-                        IO.DynamicCombo.Option("Seedance 2.0 Fast", _seedance2_text_inputs(["480p", "720p"])),
+                        IO.DynamicCombo.Option(
+                            "Seedance 2.0",
+                            _seedance2_text_inputs(["480p", "720p", "1080p"], default_ratio="adaptive"),
+                        ),
+                        IO.DynamicCombo.Option(
+                            "Seedance 2.0 Fast",
+                            _seedance2_text_inputs(["480p", "720p"], default_ratio="adaptive"),
+                        ),
                     ],
                     tooltip="Seedance 2.0 for maximum quality; Seedance 2.0 Fast for speed optimization.",
                 ),
@@ -1588,9 +1595,9 @@ class ByteDance2FirstLastFrameNode(IO.ComfyNode):
         return IO.NodeOutput(await download_url_to_video_output(response.content.video_url))
 
 
-def _seedance2_reference_inputs(resolutions: list[str]):
+def _seedance2_reference_inputs(resolutions: list[str], default_ratio: str = "16:9"):
     return [
-        *_seedance2_text_inputs(resolutions),
+        *_seedance2_text_inputs(resolutions, default_ratio=default_ratio),
         IO.Autogrow.Input(
             "reference_images",
             template=IO.Autogrow.TemplateNames(
@@ -1668,8 +1675,14 @@ class ByteDance2ReferenceNode(IO.ComfyNode):
                 IO.DynamicCombo.Input(
                     "model",
                     options=[
-                        IO.DynamicCombo.Option("Seedance 2.0", _seedance2_reference_inputs(["480p", "720p", "1080p"])),
-                        IO.DynamicCombo.Option("Seedance 2.0 Fast", _seedance2_reference_inputs(["480p", "720p"])),
+                        IO.DynamicCombo.Option(
+                            "Seedance 2.0",
+                            _seedance2_reference_inputs(["480p", "720p", "1080p"], default_ratio="adaptive"),
+                        ),
+                        IO.DynamicCombo.Option(
+                            "Seedance 2.0 Fast",
+                            _seedance2_reference_inputs(["480p", "720p"], default_ratio="adaptive"),
+                        ),
                     ],
                     tooltip="Seedance 2.0 for maximum quality; Seedance 2.0 Fast for speed optimization.",
                 ),
diff --git a/comfy_api_nodes/util/client.py b/comfy_api_nodes/util/client.py
index 8e1ba91ba..052301c33 100644
--- a/comfy_api_nodes/util/client.py
+++ b/comfy_api_nodes/util/client.py
@@ -488,10 +488,30 @@ async def _diagnose_connectivity() -> dict[str, bool]:
         "api_accessible": False,
     }
     timeout = aiohttp.ClientTimeout(total=5.0)
+
+    # Probe Google and Baidu in parallel: Google is blocked by the GFW in mainland China, so a Baidu probe is required
+    # to correctly detect that Chinese users with working internet do have working internet.
+    internet_probe_urls = ("https://www.google.com", "https://www.baidu.com")
+
     async with aiohttp.ClientSession(timeout=timeout) as session:
-        with contextlib.suppress(ClientError, OSError):
-            async with session.get("https://www.google.com") as resp:
-                results["internet_accessible"] = resp.status < 500
+        async def _probe(url: str) -> bool:
+            try:
+                async with session.get(url) as resp:
+                    return resp.status < 500
+            except (ClientError, OSError, asyncio.TimeoutError):
+                return False
+
+        probe_tasks = [asyncio.create_task(_probe(u)) for u in internet_probe_urls]
+        try:
+            for fut in asyncio.as_completed(probe_tasks):
+                if await fut:
+                    results["internet_accessible"] = True
+                    break
+        finally:
+            for t in probe_tasks:
+                if not t.done():
+                    t.cancel()
+            await asyncio.gather(*probe_tasks, return_exceptions=True)
         if not results["internet_accessible"]:
             return results
 
diff --git a/comfy_extras/nodes_advanced_samplers.py b/comfy_extras/nodes_advanced_samplers.py
index 7f716cd76..7e8411fa4 100644
--- a/comfy_extras/nodes_advanced_samplers.py
+++ b/comfy_extras/nodes_advanced_samplers.py
@@ -92,7 +92,7 @@ class SamplerEulerCFGpp(io.ComfyNode):
         return io.Schema(
             node_id="SamplerEulerCFGpp",
             display_name="SamplerEulerCFG++",
-            category="_for_testing",  # "sampling/custom_sampling/samplers"
+            category="experimental",  # "sampling/custom_sampling/samplers"
             inputs=[
                 io.Combo.Input("version", options=["regular", "alternative"], advanced=True),
             ],
diff --git a/comfy_extras/nodes_attention_multiply.py b/comfy_extras/nodes_attention_multiply.py
index 060a5c9be..f4ee6a689 100644
--- a/comfy_extras/nodes_attention_multiply.py
+++ b/comfy_extras/nodes_attention_multiply.py
@@ -25,7 +25,7 @@ class UNetSelfAttentionMultiply(io.ComfyNode):
     def define_schema(cls) -> io.Schema:
         return io.Schema(
             node_id="UNetSelfAttentionMultiply",
-            category="_for_testing/attention_experiments",
+            category="experimental/attention_experiments",
             inputs=[
                 io.Model.Input("model"),
                 io.Float.Input("q", default=1.0, min=0.0, max=10.0, step=0.01, advanced=True),
@@ -48,7 +48,7 @@ class UNetCrossAttentionMultiply(io.ComfyNode):
     def define_schema(cls) -> io.Schema:
         return io.Schema(
             node_id="UNetCrossAttentionMultiply",
-            category="_for_testing/attention_experiments",
+            category="experimental/attention_experiments",
             inputs=[
                 io.Model.Input("model"),
                 io.Float.Input("q", default=1.0, min=0.0, max=10.0, step=0.01, advanced=True),
@@ -72,7 +72,7 @@ class CLIPAttentionMultiply(io.ComfyNode):
         return io.Schema(
             node_id="CLIPAttentionMultiply",
             search_aliases=["clip attention scale", "text encoder attention"],
-            category="_for_testing/attention_experiments",
+            category="experimental/attention_experiments",
             inputs=[
                 io.Clip.Input("clip"),
                 io.Float.Input("q", default=1.0, min=0.0, max=10.0, step=0.01, advanced=True),
@@ -106,7 +106,7 @@ class UNetTemporalAttentionMultiply(io.ComfyNode):
     def define_schema(cls) -> io.Schema:
         return io.Schema(
             node_id="UNetTemporalAttentionMultiply",
-            category="_for_testing/attention_experiments",
+            category="experimental/attention_experiments",
             inputs=[
                 io.Model.Input("model"),
                 io.Float.Input("self_structural", default=1.0, min=0.0, max=10.0, step=0.01, advanced=True),
diff --git a/comfy_extras/nodes_audio_encoder.py b/comfy_extras/nodes_audio_encoder.py
index 13aacd41a..6a85da89b 100644
--- a/comfy_extras/nodes_audio_encoder.py
+++ b/comfy_extras/nodes_audio_encoder.py
@@ -10,6 +10,7 @@ class AudioEncoderLoader(io.ComfyNode):
     def define_schema(cls) -> io.Schema:
         return io.Schema(
             node_id="AudioEncoderLoader",
+            display_name="Load Audio Encoder",
             category="loaders",
             inputs=[
                 io.Combo.Input(
diff --git a/comfy_extras/nodes_bg_removal.py b/comfy_extras/nodes_bg_removal.py
new file mode 100644
index 000000000..8d046b8d4
--- /dev/null
+++ b/comfy_extras/nodes_bg_removal.py
@@ -0,0 +1,60 @@
+import folder_paths
+from typing_extensions import override
+from comfy_api.latest import ComfyExtension, IO
+from comfy.bg_removal_model import load
+
+
+class LoadBackgroundRemovalModel(IO.ComfyNode):
+    @classmethod
+    def define_schema(cls):
+        files = folder_paths.get_filename_list("background_removal")
+        return IO.Schema(
+            node_id="LoadBackgroundRemovalModel",
+            display_name="Load Background Removal Model",
+            category="loaders",
+            inputs=[
+                IO.Combo.Input("bg_removal_name", options=sorted(files), tooltip="The model used to remove backgrounds from images"),
+            ],
+            outputs=[
+                IO.BackgroundRemoval.Output("bg_model")
+            ]
+        )
+    @classmethod
+    def execute(cls, bg_removal_name):
+        path = folder_paths.get_full_path_or_raise("background_removal", bg_removal_name)
+        bg = load(path)
+        if bg is None:
+            raise RuntimeError("ERROR: background model file is invalid and does not contain a valid background removal model.")
+        return IO.NodeOutput(bg)
+
+class RemoveBackground(IO.ComfyNode):
+    @classmethod
+    def define_schema(cls):
+        return IO.Schema(
+            node_id="RemoveBackground",
+            display_name="Remove Background",
+            category="image/background removal",
+            inputs=[
+                IO.Image.Input("image", tooltip="Input image to remove the background from"),
+                IO.BackgroundRemoval.Input("bg_removal_model", tooltip="Background removal model used to generate the mask")
+            ],
+            outputs=[
+                IO.Mask.Output("mask", tooltip="Generated foreground mask")
+            ]
+        )
+    @classmethod
+    def execute(cls, image, bg_removal_model):
+        mask = bg_removal_model.encode_image(image)
+        return IO.NodeOutput(mask)
+
+class BackgroundRemovalExtension(ComfyExtension):
+    @override
+    async def get_node_list(self) -> list[type[IO.ComfyNode]]:
+        return [
+            LoadBackgroundRemovalModel,
+            RemoveBackground
+        ]
+
+
+async def comfy_entrypoint() -> BackgroundRemovalExtension:
+    return BackgroundRemovalExtension()
diff --git a/comfy_extras/nodes_camera_trajectory.py b/comfy_extras/nodes_camera_trajectory.py
index e7efa29ba..34b78e81b 100644
--- a/comfy_extras/nodes_camera_trajectory.py
+++ b/comfy_extras/nodes_camera_trajectory.py
@@ -153,7 +153,7 @@ class WanCameraEmbedding(io.ComfyNode):
     def define_schema(cls):
         return io.Schema(
             node_id="WanCameraEmbedding",
-            category="camera",
+            category="conditioning/video_models",
             inputs=[
                 io.Combo.Input(
                     "camera_pose",
diff --git a/comfy_extras/nodes_compositing.py b/comfy_extras/nodes_compositing.py
index 5b4423734..720efc629 100644
--- a/comfy_extras/nodes_compositing.py
+++ b/comfy_extras/nodes_compositing.py
@@ -203,7 +203,7 @@ class JoinImageWithAlpha(io.ComfyNode):
     @classmethod
     def execute(cls, image: torch.Tensor, alpha: torch.Tensor) -> io.NodeOutput:
         batch_size = max(len(image), len(alpha))
-        alpha = 1.0 - resize_mask(alpha, image.shape[1:])
+        alpha = 1.0 - resize_mask(alpha.to(image), image.shape[1:])
         alpha = comfy.utils.repeat_to_batch_size(alpha, batch_size)
         image = comfy.utils.repeat_to_batch_size(image, batch_size)
         return io.NodeOutput(torch.cat((image[..., :3], alpha.unsqueeze(-1)), dim=-1))
diff --git a/comfy_extras/nodes_cond.py b/comfy_extras/nodes_cond.py
index 86426a780..b745a43af 100644
--- a/comfy_extras/nodes_cond.py
+++ b/comfy_extras/nodes_cond.py
@@ -8,7 +8,7 @@ class CLIPTextEncodeControlnet(io.ComfyNode):
     def define_schema(cls) -> io.Schema:
         return io.Schema(
             node_id="CLIPTextEncodeControlnet",
-            category="_for_testing/conditioning",
+            category="experimental/conditioning",
             inputs=[
                 io.Clip.Input("clip"),
                 io.Conditioning.Input("conditioning"),
@@ -35,7 +35,7 @@ class T5TokenizerOptions(io.ComfyNode):
     def define_schema(cls) -> io.Schema:
         return io.Schema(
             node_id="T5TokenizerOptions",
-            category="_for_testing/conditioning",
+            category="experimental/conditioning",
             inputs=[
                 io.Clip.Input("clip"),
                 io.Int.Input("min_padding", default=0, min=0, max=10000, step=1, advanced=True),
diff --git a/comfy_extras/nodes_context_windows.py b/comfy_extras/nodes_context_windows.py
index fefc56d26..f7ca833dc 100644
--- a/comfy_extras/nodes_context_windows.py
+++ b/comfy_extras/nodes_context_windows.py
@@ -10,7 +10,7 @@ class ContextWindowsManualNode(io.ComfyNode):
         return io.Schema(
             node_id="ContextWindowsManual",
             display_name="Context Windows (Manual)",
-            category="context",
+            category="model_patches",
             description="Manually set context windows.",
             inputs=[
                 io.Model.Input("model", tooltip="The model to apply context windows to during sampling."),
diff --git a/comfy_extras/nodes_custom_sampler.py b/comfy_extras/nodes_custom_sampler.py
index 1e957c09b..c67145d2d 100644
--- a/comfy_extras/nodes_custom_sampler.py
+++ b/comfy_extras/nodes_custom_sampler.py
@@ -984,7 +984,7 @@ class AddNoise(io.ComfyNode):
     def define_schema(cls):
         return io.Schema(
             node_id="AddNoise",
-            category="_for_testing/custom_sampling/noise",
+            category="experimental/custom_sampling/noise",
             is_experimental=True,
             inputs=[
                 io.Model.Input("model"),
@@ -1034,7 +1034,7 @@ class ManualSigmas(io.ComfyNode):
         return io.Schema(
             node_id="ManualSigmas",
             search_aliases=["custom noise schedule", "define sigmas"],
-            category="_for_testing/custom_sampling",
+            category="experimental/custom_sampling",
             is_experimental=True,
             inputs=[
                 io.String.Input("sigmas", default="1, 0.5", multiline=False)
diff --git a/comfy_extras/nodes_differential_diffusion.py b/comfy_extras/nodes_differential_diffusion.py
index 34ffb9a89..4fa61ad0e 100644
--- a/comfy_extras/nodes_differential_diffusion.py
+++ b/comfy_extras/nodes_differential_diffusion.py
@@ -13,7 +13,7 @@ class DifferentialDiffusion(io.ComfyNode):
             node_id="DifferentialDiffusion",
             search_aliases=["inpaint gradient", "variable denoise strength"],
             display_name="Differential Diffusion",
-            category="_for_testing",
+            category="experimental",
             inputs=[
                 io.Model.Input("model"),
                 io.Float.Input(
diff --git a/comfy_extras/nodes_flux.py b/comfy_extras/nodes_flux.py
index 3a23c7d04..5e04a5f77 100644
--- a/comfy_extras/nodes_flux.py
+++ b/comfy_extras/nodes_flux.py
@@ -102,7 +102,7 @@ class FluxDisableGuidance(io.ComfyNode):
     append = execute  # TODO: remove
 
 
-PREFERED_KONTEXT_RESOLUTIONS = [
+PREFERRED_KONTEXT_RESOLUTIONS = [
     (672, 1568),
     (688, 1504),
     (720, 1456),
@@ -143,7 +143,7 @@ class FluxKontextImageScale(io.ComfyNode):
         width = image.shape[2]
         height = image.shape[1]
         aspect_ratio = width / height
-        _, width, height = min((abs(aspect_ratio - w / h), w, h) for w, h in PREFERED_KONTEXT_RESOLUTIONS)
+        _, width, height = min((abs(aspect_ratio - w / h), w, h) for w, h in PREFERRED_KONTEXT_RESOLUTIONS)
         image = comfy.utils.common_upscale(image.movedim(-1, 1), width, height, "lanczos", "center").movedim(1, -1)
         return io.NodeOutput(image)
 
diff --git a/comfy_extras/nodes_fresca.py b/comfy_extras/nodes_fresca.py
index eab4f303f..173f42154 100644
--- a/comfy_extras/nodes_fresca.py
+++ b/comfy_extras/nodes_fresca.py
@@ -60,7 +60,7 @@ class FreSca(io.ComfyNode):
             node_id="FreSca",
             search_aliases=["frequency guidance"],
             display_name="FreSca",
-            category="_for_testing",
+            category="experimental",
             description="Applies frequency-dependent scaling to the guidance",
             inputs=[
                 io.Model.Input("model"),
diff --git a/comfy_extras/nodes_hunyuan.py b/comfy_extras/nodes_hunyuan.py
index 4ea93a499..9e4873be5 100644
--- a/comfy_extras/nodes_hunyuan.py
+++ b/comfy_extras/nodes_hunyuan.py
@@ -131,6 +131,8 @@ class HunyuanVideo15SuperResolution(io.ComfyNode):
     def define_schema(cls):
         return io.Schema(
             node_id="HunyuanVideo15SuperResolution",
+            display_name="Hunyuan Video 1.5 Super Resolution",
+            category="conditioning/video_models",
             inputs=[
                 io.Conditioning.Input("positive"),
                 io.Conditioning.Input("negative"),
@@ -381,6 +383,8 @@ class HunyuanRefinerLatent(io.ComfyNode):
     def define_schema(cls):
         return io.Schema(
             node_id="HunyuanRefinerLatent",
+            display_name="Hunyuan Latent Refiner",
+            category="conditioning/video_models",
             inputs=[
                 io.Conditioning.Input("positive"),
                 io.Conditioning.Input("negative"),
diff --git a/comfy_extras/nodes_hunyuan3d.py b/comfy_extras/nodes_hunyuan3d.py
index fa55ead59..bf18ecb88 100644
--- a/comfy_extras/nodes_hunyuan3d.py
+++ b/comfy_extras/nodes_hunyuan3d.py
@@ -40,7 +40,7 @@ class Hunyuan3Dv2Conditioning(IO.ComfyNode):
     def define_schema(cls):
         return IO.Schema(
             node_id="Hunyuan3Dv2Conditioning",
-            category="conditioning/video_models",
+            category="conditioning/3d_models",
             inputs=[
                 IO.ClipVisionOutput.Input("clip_vision_output"),
             ],
@@ -65,7 +65,7 @@ class Hunyuan3Dv2ConditioningMultiView(IO.ComfyNode):
     def define_schema(cls):
         return IO.Schema(
             node_id="Hunyuan3Dv2ConditioningMultiView",
-            category="conditioning/video_models",
+            category="conditioning/3d_models",
             inputs=[
                 IO.ClipVisionOutput.Input("front", optional=True),
                 IO.ClipVisionOutput.Input("left", optional=True),
@@ -424,6 +424,7 @@ class VoxelToMeshBasic(IO.ComfyNode):
     def define_schema(cls):
         return IO.Schema(
             node_id="VoxelToMeshBasic",
+            display_name="Voxel to Mesh (Basic)",
             category="3d",
             inputs=[
                 IO.Voxel.Input("voxel"),
@@ -453,6 +454,7 @@ class VoxelToMesh(IO.ComfyNode):
     def define_schema(cls):
         return IO.Schema(
             node_id="VoxelToMesh",
+            display_name="Voxel to Mesh",
             category="3d",
             inputs=[
                 IO.Voxel.Input("voxel"),
diff --git a/comfy_extras/nodes_hypernetwork.py b/comfy_extras/nodes_hypernetwork.py
index 2a6a87a81..44a9c6f97 100644
--- a/comfy_extras/nodes_hypernetwork.py
+++ b/comfy_extras/nodes_hypernetwork.py
@@ -102,6 +102,7 @@ class HypernetworkLoader(IO.ComfyNode):
     def define_schema(cls):
         return IO.Schema(
             node_id="HypernetworkLoader",
+            display_name="Load Hypernetwork",
             category="loaders",
             inputs=[
                 IO.Model.Input("model"),
diff --git a/comfy_extras/nodes_lora_extract.py b/comfy_extras/nodes_lora_extract.py
index 975f90f45..bcd249c29 100644
--- a/comfy_extras/nodes_lora_extract.py
+++ b/comfy_extras/nodes_lora_extract.py
@@ -91,7 +91,7 @@ class LoraSave(io.ComfyNode):
             node_id="LoraSave",
             search_aliases=["export lora"],
             display_name="Extract and Save Lora",
-            category="_for_testing",
+            category="experimental",
             inputs=[
                 io.String.Input("filename_prefix", default="loras/ComfyUI_extracted_lora"),
                 io.Int.Input("rank", default=8, min=1, max=4096, step=1, advanced=True),
diff --git a/comfy_extras/nodes_lt.py b/comfy_extras/nodes_lt.py
index 19d8a387f..a4c85db77 100644
--- a/comfy_extras/nodes_lt.py
+++ b/comfy_extras/nodes_lt.py
@@ -106,12 +106,12 @@ class LTXVImgToVideoInplace(io.ComfyNode):
         if bypass:
             return (latent,)
 
-        samples = latent["samples"]
+        samples = latent["samples"].clone()
         _, height_scale_factor, width_scale_factor = (
             vae.downscale_index_formula
         )
 
-        batch, _, latent_frames, latent_height, latent_width = samples.shape
+        _, _, _, latent_height, latent_width = samples.shape
         width = latent_width * width_scale_factor
         height = latent_height * height_scale_factor
 
@@ -124,11 +124,7 @@ class LTXVImgToVideoInplace(io.ComfyNode):
 
         samples[:, :, :t.shape[2]] = t
 
-        conditioning_latent_frames_mask = torch.ones(
-            (batch, 1, latent_frames, 1, 1),
-            dtype=torch.float32,
-            device=samples.device,
-        )
+        conditioning_latent_frames_mask = get_noise_mask(latent)
         conditioning_latent_frames_mask[:, :, :t.shape[2]] = 1.0 - strength
 
         return io.NodeOutput({"samples": samples, "noise_mask": conditioning_latent_frames_mask})
@@ -236,7 +232,7 @@ class LTXVAddGuide(io.ComfyNode):
     def encode(cls, vae, latent_width, latent_height, images, scale_factors):
         time_scale_factor, width_scale_factor, height_scale_factor = scale_factors
         images = images[:(images.shape[0] - 1) // time_scale_factor * time_scale_factor + 1]
-        pixels = comfy.utils.common_upscale(images.movedim(-1, 1), latent_width * width_scale_factor, latent_height * height_scale_factor, "bilinear", crop="disabled").movedim(1, -1)
+        pixels = comfy.utils.common_upscale(images.movedim(-1, 1), latent_width * width_scale_factor, latent_height * height_scale_factor, "bilinear", crop="center").movedim(1, -1)
         encode_pixels = pixels[:, :, :, :3]
         t = vae.encode(encode_pixels)
         return encode_pixels, t
@@ -594,7 +590,8 @@ class LTXVPreprocess(io.ComfyNode):
     def define_schema(cls):
         return io.Schema(
             node_id="LTXVPreprocess",
-            category="image",
+            display_name="LTXV Preprocess",
+            category="video/preprocessors",
             inputs=[
                 io.Image.Input("image"),
                 io.Int.Input(
diff --git a/comfy_extras/nodes_mahiro.py b/comfy_extras/nodes_mahiro.py
index a25226e6d..7bd5f6652 100644
--- a/comfy_extras/nodes_mahiro.py
+++ b/comfy_extras/nodes_mahiro.py
@@ -11,7 +11,7 @@ class Mahiro(io.ComfyNode):
         return io.Schema(
             node_id="Mahiro",
             display_name="Positive-Biased Guidance",
-            category="_for_testing",
+            category="experimental",
             description="Modify the guidance to scale more on the 'direction' of the positive prompt rather than the difference between the negative prompt.",
             inputs=[
                 io.Model.Input("model"),
diff --git a/comfy_extras/nodes_mask.py b/comfy_extras/nodes_mask.py
index 43a933dac..c9b2a84d9 100644
--- a/comfy_extras/nodes_mask.py
+++ b/comfy_extras/nodes_mask.py
@@ -40,10 +40,21 @@ def composite(destination, source, x, y, mask = None, multiplier = 8, resize_sou
 
     inverse_mask = torch.ones_like(mask) - mask
 
-    source_portion = mask * source[..., :visible_height, :visible_width]
-    destination_portion = inverse_mask  * destination[..., top:bottom, left:right]
+    source_rgb = source[:, :3, :visible_height, :visible_width]
+    dest_slice = destination[..., top:bottom, left:right]
+
+    if destination.shape[1] == 4:
+        if torch.max(dest_slice) == 0:
+            destination[:, :3, top:bottom, left:right] = source_rgb
+            destination[:, 3:4, top:bottom, left:right] = mask
+        else:
+            destination[:, :3, top:bottom, left:right] = (mask * source_rgb) + (inverse_mask * dest_slice[:, :3])
+            destination[:, 3:4, top:bottom, left:right] = torch.max(mask, dest_slice[:, 3:4])
+    else:
+        source_portion = mask * source_rgb
+        destination_portion = inverse_mask * dest_slice
+        destination[..., top:bottom, left:right] = source_portion + destination_portion
 
-    destination[..., top:bottom, left:right] = source_portion + destination_portion
     return destination
 
 class LatentCompositeMasked(IO.ComfyNode):
@@ -84,18 +95,23 @@ class ImageCompositeMasked(IO.ComfyNode):
             display_name="Image Composite Masked",
             category="image",
             inputs=[
-                IO.Image.Input("destination"),
                 IO.Image.Input("source"),
                 IO.Int.Input("x", default=0, min=0, max=nodes.MAX_RESOLUTION, step=1),
                 IO.Int.Input("y", default=0, min=0, max=nodes.MAX_RESOLUTION, step=1),
                 IO.Boolean.Input("resize_source", default=False),
+                IO.Image.Input("destination", optional=True),
                 IO.Mask.Input("mask", optional=True),
             ],
             outputs=[IO.Image.Output()],
         )
 
     @classmethod
-    def execute(cls, destination, source, x, y, resize_source, mask = None) -> IO.NodeOutput:
+    def execute(cls, source, x, y, resize_source, destination = None, mask = None) -> IO.NodeOutput:
+        if destination is None: # transparent rgba
+            B, H, W, C = source.shape
+            destination = torch.zeros((B, H, W, 4), dtype=source.dtype, device=source.device)
+            if C == 3:
+                source = torch.nn.functional.pad(source, (0, 1), value=1.0)
         destination, source = node_helpers.image_alpha_fix(destination, source)
         destination = destination.clone().movedim(-1, 1)
         output = composite(destination, source.movedim(-1, 1), x, y, mask, 1, resize_source).movedim(1, -1)
@@ -381,7 +397,6 @@ class GrowMask(IO.ComfyNode):
 
     expand_mask = execute  # TODO: remove
 
-
 class ThresholdMask(IO.ComfyNode):
     @classmethod
     def define_schema(cls):
diff --git a/comfy_extras/nodes_math.py b/comfy_extras/nodes_math.py
index 6417bacf1..8f6e687d2 100644
--- a/comfy_extras/nodes_math.py
+++ b/comfy_extras/nodes_math.py
@@ -70,7 +70,7 @@ class MathExpressionNode(io.ComfyNode):
         return io.Schema(
             node_id="ComfyMathExpression",
             display_name="Math Expression",
-            category="math",
+            category="logic",
             search_aliases=[
                 "expression", "formula", "calculate", "calculator",
                 "eval", "math",
diff --git a/comfy_extras/nodes_number_convert.py b/comfy_extras/nodes_number_convert.py
index cac7e736d..ab3f2aa8a 100644
--- a/comfy_extras/nodes_number_convert.py
+++ b/comfy_extras/nodes_number_convert.py
@@ -21,7 +21,7 @@ class NumberConvertNode(io.ComfyNode):
         return io.Schema(
             node_id="ComfyNumberConvert",
             display_name="Number Convert",
-            category="math",
+            category="utils",
             search_aliases=[
                 "int to float", "float to int", "number convert",
                 "int2float", "float2int", "cast", "parse number",
diff --git a/comfy_extras/nodes_perpneg.py b/comfy_extras/nodes_perpneg.py
index ed1467de9..a7a72d1bc 100644
--- a/comfy_extras/nodes_perpneg.py
+++ b/comfy_extras/nodes_perpneg.py
@@ -24,8 +24,8 @@ class PerpNeg(io.ComfyNode):
     def define_schema(cls):
         return io.Schema(
             node_id="PerpNeg",
-            display_name="Perp-Neg (DEPRECATED by PerpNegGuider)",
-            category="_for_testing",
+            display_name="Perp-Neg (DEPRECATED by Perp-Neg Guider)",
+            category="experimental",
             inputs=[
                 io.Model.Input("model"),
                 io.Conditioning.Input("empty_conditioning"),
@@ -127,7 +127,8 @@ class PerpNegGuider(io.ComfyNode):
     def define_schema(cls):
         return io.Schema(
             node_id="PerpNegGuider",
-            category="_for_testing",
+            display_name="Perp-Neg Guider",
+            category="experimental",
             inputs=[
                 io.Model.Input("model"),
                 io.Conditioning.Input("positive"),
diff --git a/comfy_extras/nodes_photomaker.py b/comfy_extras/nodes_photomaker.py
index 228183c07..8a2248572 100644
--- a/comfy_extras/nodes_photomaker.py
+++ b/comfy_extras/nodes_photomaker.py
@@ -123,7 +123,7 @@ class PhotoMakerLoader(io.ComfyNode):
     def define_schema(cls):
         return io.Schema(
             node_id="PhotoMakerLoader",
-            category="_for_testing/photomaker",
+            category="experimental/photomaker",
             inputs=[
                 io.Combo.Input("photomaker_model_name", options=folder_paths.get_filename_list("photomaker")),
             ],
@@ -149,7 +149,7 @@ class PhotoMakerEncode(io.ComfyNode):
     def define_schema(cls):
         return io.Schema(
             node_id="PhotoMakerEncode",
-            category="_for_testing/photomaker",
+            category="experimental/photomaker",
             inputs=[
                 io.Photomaker.Input("photomaker"),
                 io.Image.Input("image"),
diff --git a/comfy_extras/nodes_post_processing.py b/comfy_extras/nodes_post_processing.py
index d938a2035..1fa14d2d2 100644
--- a/comfy_extras/nodes_post_processing.py
+++ b/comfy_extras/nodes_post_processing.py
@@ -116,6 +116,7 @@ class Quantize(io.ComfyNode):
     def define_schema(cls):
         return io.Schema(
             node_id="ImageQuantize",
+            display_name="Quantize Image",
             category="image/postprocessing",
             inputs=[
                 io.Image.Input("image"),
@@ -181,6 +182,7 @@ class Sharpen(io.ComfyNode):
     def define_schema(cls):
         return io.Schema(
             node_id="ImageSharpen",
+            display_name="Sharpen Image",
             category="image/postprocessing",
             inputs=[
                 io.Image.Input("image"),
@@ -436,7 +438,7 @@ class ResizeImageMaskNode(io.ComfyNode):
             node_id="ResizeImageMaskNode",
             display_name="Resize Image/Mask",
             description="Resize an image or mask using various scaling methods.",
-            category="transform",
+            category="image/transform",
             search_aliases=["resize", "resize image", "resize mask", "scale", "scale image", "scale mask", "image resize", "change size", "dimensions", "shrink", "enlarge"],
             inputs=[
                 io.MatchType.Input("input", template=template),
diff --git a/comfy_extras/nodes_rtdetr.py b/comfy_extras/nodes_rtdetr.py
index 7feaf3ab3..a321577c7 100644
--- a/comfy_extras/nodes_rtdetr.py
+++ b/comfy_extras/nodes_rtdetr.py
@@ -15,7 +15,7 @@ class RTDETR_detect(io.ComfyNode):
         return io.Schema(
             node_id="RTDETR_detect",
             display_name="RT-DETR Detect",
-            category="detection/",
+            category="detection",
             search_aliases=["bbox", "bounding box", "object detection", "coco"],
             inputs=[
                 io.Model.Input("model", display_name="model"),
@@ -71,7 +71,7 @@ class DrawBBoxes(io.ComfyNode):
         return io.Schema(
             node_id="DrawBBoxes",
             display_name="Draw BBoxes",
-            category="detection/",
+            category="detection",
             search_aliases=["bbox", "bounding box", "object detection", "rt_detr", "visualize detections", "coco"],
             inputs=[
                 io.Image.Input("image", optional=True),
diff --git a/comfy_extras/nodes_sag.py b/comfy_extras/nodes_sag.py
index d9c47851c..9dbf1b6f9 100644
--- a/comfy_extras/nodes_sag.py
+++ b/comfy_extras/nodes_sag.py
@@ -113,7 +113,7 @@ class SelfAttentionGuidance(io.ComfyNode):
         return io.Schema(
             node_id="SelfAttentionGuidance",
             display_name="Self-Attention Guidance",
-            category="_for_testing",
+            category="experimental",
             inputs=[
                 io.Model.Input("model"),
                 io.Float.Input("scale", default=0.5, min=-2.0, max=5.0, step=0.01),
diff --git a/comfy_extras/nodes_sam3.py b/comfy_extras/nodes_sam3.py
index c460506bf..4ea9221e9 100644
--- a/comfy_extras/nodes_sam3.py
+++ b/comfy_extras/nodes_sam3.py
@@ -93,7 +93,7 @@ class SAM3_Detect(io.ComfyNode):
         return io.Schema(
             node_id="SAM3_Detect",
             display_name="SAM3 Detect",
-            category="detection/",
+            category="detection",
             search_aliases=["sam3", "segment anything", "open vocabulary", "text detection", "segment"],
             inputs=[
                 io.Model.Input("model", display_name="model"),
@@ -265,7 +265,7 @@ class SAM3_VideoTrack(io.ComfyNode):
         return io.Schema(
             node_id="SAM3_VideoTrack",
             display_name="SAM3 Video Track",
-            category="detection/",
+            category="detection",
             search_aliases=["sam3", "video", "track", "propagate"],
             inputs=[
                 io.Image.Input("images", display_name="images", tooltip="Video frames as batched images"),
@@ -320,7 +320,7 @@ class SAM3_TrackPreview(io.ComfyNode):
         return io.Schema(
             node_id="SAM3_TrackPreview",
             display_name="SAM3 Track Preview",
-            category="detection/",
+            category="detection",
             inputs=[
                 SAM3TrackData.Input("track_data", display_name="track_data"),
                 io.Image.Input("images", display_name="images", optional=True),
@@ -478,7 +478,7 @@ class SAM3_TrackToMask(io.ComfyNode):
         return io.Schema(
             node_id="SAM3_TrackToMask",
             display_name="SAM3 Track to Mask",
-            category="detection/",
+            category="detection",
             inputs=[
                 SAM3TrackData.Input("track_data", display_name="track_data"),
                 io.String.Input("object_indices", display_name="object_indices", default="",
diff --git a/comfy_extras/nodes_stable_cascade.py b/comfy_extras/nodes_stable_cascade.py
index 8c1aebca9..0dc6c9fcd 100644
--- a/comfy_extras/nodes_stable_cascade.py
+++ b/comfy_extras/nodes_stable_cascade.py
@@ -119,7 +119,7 @@ class StableCascade_SuperResolutionControlnet(io.ComfyNode):
     def define_schema(cls):
         return io.Schema(
             node_id="StableCascade_SuperResolutionControlnet",
-            category="_for_testing/stable_cascade",
+            category="experimental/stable_cascade",
             is_experimental=True,
             inputs=[
                 io.Image.Input("image"),
diff --git a/comfy_extras/nodes_textgen.py b/comfy_extras/nodes_textgen.py
index 1661a1011..d52faf815 100644
--- a/comfy_extras/nodes_textgen.py
+++ b/comfy_extras/nodes_textgen.py
@@ -26,7 +26,8 @@ class TextGenerate(io.ComfyNode):
 
         return io.Schema(
             node_id="TextGenerate",
-            category="textgen",
+            display_name="Generate Text",
+            category="text",
             search_aliases=["LLM", "gemma"],
             inputs=[
                 io.Clip.Input("clip"),
@@ -157,6 +158,7 @@ class TextGenerateLTX2Prompt(TextGenerate):
         parent_schema = super().define_schema()
         return io.Schema(
             node_id="TextGenerateLTX2Prompt",
+            display_name="Generate LTX2 Prompt",
             category=parent_schema.category,
             inputs=parent_schema.inputs,
             outputs=parent_schema.outputs,
diff --git a/comfy_extras/nodes_torch_compile.py b/comfy_extras/nodes_torch_compile.py
index c9e2e0026..d4506b1a9 100644
--- a/comfy_extras/nodes_torch_compile.py
+++ b/comfy_extras/nodes_torch_compile.py
@@ -10,7 +10,7 @@ class TorchCompileModel(io.ComfyNode):
     def define_schema(cls) -> io.Schema:
         return io.Schema(
             node_id="TorchCompileModel",
-            category="_for_testing",
+            category="experimental",
             inputs=[
                 io.Model.Input("model"),
                 io.Combo.Input(
diff --git a/comfy_extras/nodes_train.py b/comfy_extras/nodes_train.py
index 0616dfc2d..e9871369b 100644
--- a/comfy_extras/nodes_train.py
+++ b/comfy_extras/nodes_train.py
@@ -1361,7 +1361,7 @@ class SaveLoRA(io.ComfyNode):
             node_id="SaveLoRA",
             search_aliases=["export lora"],
             display_name="Save LoRA Weights",
-            category="loaders",
+            category="advanced/model_merging",
             is_experimental=True,
             is_output_node=True,
             inputs=[
diff --git a/comfy_extras/nodes_video_model.py b/comfy_extras/nodes_video_model.py
index bf98e6b82..0f3881a24 100644
--- a/comfy_extras/nodes_video_model.py
+++ b/comfy_extras/nodes_video_model.py
@@ -15,7 +15,7 @@ class ImageOnlyCheckpointLoader:
     RETURN_TYPES = ("MODEL", "CLIP_VISION", "VAE")
     FUNCTION = "load_checkpoint"
 
-    CATEGORY = "loaders/video_models"
+    CATEGORY = "loaders"
 
     def load_checkpoint(self, ckpt_name, output_vae=True, output_clip=True):
         ckpt_path = folder_paths.get_full_path_or_raise("checkpoints", ckpt_name)
diff --git a/custom_nodes/websocket_image_save.py b/custom_nodes/websocket_image_save.py
index 15f87f9f5..6a8646d0e 100644
--- a/custom_nodes/websocket_image_save.py
+++ b/custom_nodes/websocket_image_save.py
@@ -22,7 +22,7 @@ class SaveImageWebsocket:
 
     OUTPUT_NODE = True
 
-    CATEGORY = "api/image"
+    CATEGORY = "image"
 
     def save_images(self, images):
         pbar = comfy.utils.ProgressBar(images.shape[0])
@@ -42,3 +42,7 @@ class SaveImageWebsocket:
 NODE_CLASS_MAPPINGS = {
     "SaveImageWebsocket": SaveImageWebsocket,
 }
+
+NODE_DISPLAY_NAME_MAPPINGS = {
+    "SaveImageWebsocket": "Save Image (Websocket)",
+}
\ No newline at end of file
diff --git a/folder_paths.py b/folder_paths.py
index 98d3b1880..92e8df3cf 100644
--- a/folder_paths.py
+++ b/folder_paths.py
@@ -52,6 +52,8 @@ folder_names_and_paths["model_patches"] = ([os.path.join(models_dir, "model_patc
 
 folder_names_and_paths["audio_encoders"] = ([os.path.join(models_dir, "audio_encoders")], supported_pt_extensions)
 
+folder_names_and_paths["background_removal"] = ([os.path.join(models_dir, "background_removal")], supported_pt_extensions)
+
 folder_names_and_paths["frame_interpolation"] = ([os.path.join(models_dir, "frame_interpolation")], supported_pt_extensions)
 
 folder_names_and_paths["optical_flow"] = ([os.path.join(models_dir, "optical_flow")], supported_pt_extensions)
diff --git a/models/background_removal/put_background_removal_models_here b/models/background_removal/put_background_removal_models_here
new file mode 100644
index 000000000..e69de29bb
diff --git a/nodes.py b/nodes.py
index ad0cbc675..5755f0bb8 100644
--- a/nodes.py
+++ b/nodes.py
@@ -330,7 +330,7 @@ class VAEDecodeTiled:
     RETURN_TYPES = ("IMAGE",)
     FUNCTION = "decode"
 
-    CATEGORY = "_for_testing"
+    CATEGORY = "experimental"
 
     def decode(self, vae, samples, tile_size, overlap=64, temporal_size=64, temporal_overlap=8):
         if tile_size < overlap * 4:
@@ -377,7 +377,7 @@ class VAEEncodeTiled:
     RETURN_TYPES = ("LATENT",)
     FUNCTION = "encode"
 
-    CATEGORY = "_for_testing"
+    CATEGORY = "experimental"
 
     def encode(self, vae, pixels, tile_size, overlap, temporal_size=64, temporal_overlap=8):
         t = vae.encode_tiled(pixels, tile_x=tile_size, tile_y=tile_size, overlap=overlap, tile_t=temporal_size, overlap_t=temporal_overlap)
@@ -493,7 +493,7 @@ class SaveLatent:
 
     OUTPUT_NODE = True
 
-    CATEGORY = "_for_testing"
+    CATEGORY = "experimental"
 
     def save(self, samples, filename_prefix="ComfyUI", prompt=None, extra_pnginfo=None):
         full_output_folder, filename, counter, subfolder, filename_prefix = folder_paths.get_save_image_path(filename_prefix, self.output_dir)
@@ -538,7 +538,7 @@ class LoadLatent:
         files = [f for f in os.listdir(input_dir) if os.path.isfile(os.path.join(input_dir, f)) and f.endswith(".latent")]
         return {"required": {"latent": [sorted(files), ]}, }
 
-    CATEGORY = "_for_testing"
+    CATEGORY = "experimental"
 
     RETURN_TYPES = ("LATENT", )
     FUNCTION = "load"
@@ -1443,7 +1443,7 @@ class LatentBlend:
     RETURN_TYPES = ("LATENT",)
     FUNCTION = "blend"
 
-    CATEGORY = "_for_testing"
+    CATEGORY = "experimental"
 
     def blend(self, samples1, samples2, blend_factor:float, blend_mode: str="normal"):
 
@@ -2092,6 +2092,8 @@ NODE_DISPLAY_NAME_MAPPINGS = {
     "StyleModelLoader": "Load Style Model",
     "CLIPVisionLoader": "Load CLIP Vision",
     "UNETLoader": "Load Diffusion Model",
+    "unCLIPCheckpointLoader": "Load unCLIP Checkpoint",
+    "GLIGENLoader": "Load GLIGEN Model",
     # Conditioning
     "CLIPVisionEncode": "CLIP Vision Encode",
     "StyleModelApply": "Apply Style Model",
@@ -2140,7 +2142,7 @@ NODE_DISPLAY_NAME_MAPPINGS = {
     "ImageSharpen": "Sharpen Image",
     "ImageScaleToTotalPixels": "Scale Image to Total Pixels",
     "GetImageSize": "Get Image Size",
-    # _for_testing
+    # experimental
     "VAEDecodeTiled": "VAE Decode (Tiled)",
     "VAEEncodeTiled": "VAE Encode (Tiled)",
 }
@@ -2427,6 +2429,7 @@ async def init_builtin_extra_nodes():
         "nodes_number_convert.py",
         "nodes_painter.py",
         "nodes_curve.py",
+        "nodes_bg_removal.py",
         "nodes_rtdetr.py",
         "nodes_frame_interpolation.py",
         "nodes_sam3.py",
diff --git a/openapi.yaml b/openapi.yaml
index 29b5f544b..d4c9e67ca 100644
--- a/openapi.yaml
+++ b/openapi.yaml
@@ -62,6 +62,21 @@ tags:
   - name: assets
     description: Asset management (feature-gated behind enable-assets)
 
+  - name: auth
+    description: Authentication and session management (cloud-only)
+  - name: billing
+    description: Billing, subscriptions, and payment management (cloud-only)
+  - name: workspace
+    description: Workspace and team management (cloud-only)
+  - name: hub
+    description: "ComfyUI Hub: profiles, shared workflows, and labels (cloud-only)"
+  - name: workflows
+    description: Cloud workflow management and versioning (cloud-only)
+  - name: task
+    description: Background task management (cloud-only)
+  - name: runtime-only
+    description: Operations served exclusively by the cloud runtime with no local equivalent
+
 paths:
   # ---------------------------------------------------------------------------
   # WebSocket
@@ -2056,6 +2071,3459 @@ paths:
                     type: integer
                     description: Number of assets marked as missing
 
+
+  # ===========================================================================
+  # Cloud-runtime FE-facing operations
+  #
+  # These operations are served by the cloud runtime. The local runtime returns
+  # 404 for all of these paths. Each operation is tagged x-runtime: [cloud].
+  # ===========================================================================
+
+  # ---------------------------------------------------------------------------
+  # Jobs / prompts (cloud)
+  # ---------------------------------------------------------------------------
+  /api/jobs/{job_id}/cancel:
+    post:
+      operationId: cancelJob
+      tags: [queue]
+      summary: Cancel a running or pending job
+      description: "[cloud-only] Requests cancellation of a job. If the job is currently executing, execution is interrupted. If it is pending in the queue, it is removed."
+      x-runtime: [cloud]
+      parameters:
+        - name: job_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+          description: The job ID to cancel.
+      responses:
+        "200":
+          description: Cancellation accepted
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudJobStatus"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/job/{job_id}/status:
+    get:
+      operationId: getCloudJobStatus
+      tags: [queue]
+      summary: Get status of a cloud job
+      description: "[cloud-only] Returns the current execution status of a cloud job."
+      x-runtime: [cloud]
+      parameters:
+        - name: job_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+          description: The job ID to check status for.
+      responses:
+        "200":
+          description: Job status
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudJobStatus"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/prompt/{prompt_id}:
+    get:
+      operationId: getCloudPrompt
+      tags: [prompt]
+      summary: Get a cloud prompt by ID
+      description: "[cloud-only] Returns the full prompt record for a cloud-executed prompt, including the submitted workflow graph and execution metadata."
+      x-runtime: [cloud]
+      parameters:
+        - name: prompt_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+          description: The prompt ID to fetch.
+      responses:
+        "200":
+          description: Cloud prompt detail
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudPrompt"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/history_v2:
+    get:
+      operationId: getHistoryV2
+      tags: [history]
+      summary: Get paginated execution history (v2)
+      description: "[cloud-only] Returns a paginated list of execution history entries in the v2 format, with richer metadata than the legacy history endpoint."
+      x-runtime: [cloud]
+      parameters:
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            default: 20
+          description: Maximum number of results
+        - name: offset
+          in: query
+          schema:
+            type: integer
+            default: 0
+          description: Pagination offset
+        - name: status
+          in: query
+          schema:
+            type: string
+          description: Filter by execution status
+      responses:
+        "200":
+          description: History list
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HistoryV2Response"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/history_v2/{prompt_id}:
+    get:
+      operationId: getHistoryV2ByPromptId
+      tags: [history]
+      summary: Get v2 history for a specific prompt
+      description: "[cloud-only] Returns the v2 history entry for a specific prompt execution."
+      x-runtime: [cloud]
+      parameters:
+        - name: prompt_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+          description: The prompt ID to fetch history for.
+      responses:
+        "200":
+          description: History entry
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HistoryV2Entry"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/logs:
+    get:
+      operationId: getCloudLogs
+      tags: [system]
+      summary: Get cloud execution logs
+      description: "[cloud-only] Returns execution logs for the authenticated user's cloud jobs."
+      x-runtime: [cloud]
+      parameters:
+        - name: job_id
+          in: query
+          schema:
+            type: string
+          description: Filter logs by job ID
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            default: 100
+          description: Maximum number of log entries
+        - name: offset
+          in: query
+          schema:
+            type: integer
+            default: 0
+          description: Pagination offset
+      responses:
+        "200":
+          description: Log entries
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudLogsResponse"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  # ---------------------------------------------------------------------------
+  # Assets extensions (cloud)
+  # ---------------------------------------------------------------------------
+  /api/assets/download:
+    post:
+      operationId: downloadAssets
+      tags: [assets]
+      summary: Download assets to cloud runtime
+      description: "[cloud-only] Initiates a download of one or more assets to the cloud runtime environment. Returns a task ID for tracking download progress via WebSocket."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - assets
+              properties:
+                assets:
+                  type: array
+                  items:
+                    $ref: "#/components/schemas/AssetDownloadRequest"
+                  description: Assets to download
+      responses:
+        "200":
+          description: Download initiated
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  task_id:
+                    type: string
+                    description: Task ID for tracking progress via WebSocket
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/assets/export:
+    post:
+      operationId: exportAssets
+      tags: [assets]
+      summary: Export assets as a downloadable archive
+      description: "[cloud-only] Initiates a bulk export of assets. Returns a task ID for tracking progress via WebSocket. When complete, the export can be downloaded via the exports endpoint."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - asset_ids
+              properties:
+                asset_ids:
+                  type: array
+                  items:
+                    type: string
+                    format: uuid
+                  description: IDs of assets to export
+                export_name:
+                  type: string
+                  description: Name for the export archive
+      responses:
+        "200":
+          description: Export initiated
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  task_id:
+                    type: string
+                  export_name:
+                    type: string
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/assets/exports/{exportName}:
+    get:
+      operationId: getAssetExport
+      tags: [assets]
+      summary: Download a completed asset export
+      description: "[cloud-only] Returns the archive file for a completed asset export."
+      x-runtime: [cloud]
+      parameters:
+        - name: exportName
+          in: path
+          required: true
+          schema:
+            type: string
+          description: Name of the export to download
+      responses:
+        "200":
+          description: Export archive file
+          content:
+            application/zip:
+              schema:
+                type: string
+                format: binary
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/assets/from-workflow:
+    post:
+      operationId: createAssetsFromWorkflow
+      tags: [assets]
+      summary: Create asset records from a workflow execution
+      description: "[cloud-only] Registers output files from a workflow execution as assets in the asset database."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - prompt_id
+              properties:
+                prompt_id:
+                  type: string
+                  format: uuid
+                  description: Prompt ID whose outputs should be registered as assets
+                tags:
+                  type: array
+                  items:
+                    type: string
+                  description: Tags to apply to the created assets
+      responses:
+        "201":
+          description: Assets created
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  assets:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/Asset"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/assets/import:
+    post:
+      operationId: importAssets
+      tags: [assets]
+      summary: Import assets from external URLs
+      description: "[cloud-only] Imports one or more assets from external URLs into the cloud asset store."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - imports
+              properties:
+                imports:
+                  type: array
+                  items:
+                    $ref: "#/components/schemas/AssetImportRequest"
+                  description: Assets to import
+      responses:
+        "200":
+          description: Import initiated
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  assets:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/Asset"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/assets/remote-metadata:
+    get:
+      operationId: getAssetRemoteMetadata
+      tags: [assets]
+      summary: Fetch metadata for a remote asset URL
+      description: "[cloud-only] Fetches and returns metadata (content type, size, filename) for a remote URL without downloading the full content."
+      x-runtime: [cloud]
+      parameters:
+        - name: url
+          in: query
+          required: true
+          schema:
+            type: string
+            format: uri
+          description: URL to inspect
+      responses:
+        "200":
+          description: Remote metadata
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RemoteAssetMetadata"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  # ---------------------------------------------------------------------------
+  # Custom nodes / hub (cloud)
+  # ---------------------------------------------------------------------------
+  /api/experiment/nodes:
+    get:
+      operationId: getNodeInfoSchema
+      tags: [runtime-only]
+      summary: Get pre-rendered node info schema
+      description: "[cloud-only] Returns the static ComfyUI object_info schema, identical for every caller, rendered once at startup with empty model/user-file context. Served by a raw HTTP handler that writes pre-rendered bytes with ETag + Cache-Control validators for RFC 7232 conditional GETs."
+      x-runtime: [cloud]
+      parameters:
+        - name: If-None-Match
+          in: header
+          required: false
+          schema:
+            type: string
+          description: Entity tag previously returned by this endpoint. When present and matching, the server returns 304 Not Modified.
+      responses:
+        "200":
+          description: Node info schema
+          headers:
+            ETag:
+              schema:
+                type: string
+              description: Entity tag for conditional request validation
+            Cache-Control:
+              schema:
+                type: string
+              description: Cache directives for the response
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties:
+                  $ref: "#/components/schemas/NodeInfo"
+        "304":
+          description: Not Modified — returned when the client sends a matching If-None-Match header
+    post:
+      operationId: installCloudNode
+      tags: [node]
+      summary: Install a custom node package
+      description: "[cloud-only] Installs a custom node package in the cloud runtime by ID or repository URL."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - id
+              properties:
+                id:
+                  type: string
+                  description: Node package ID or repository URL
+                version:
+                  type: string
+                  description: Specific version to install
+      responses:
+        "200":
+          description: Node installed
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudNode"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/experiment/nodes/{id}:
+    get:
+      operationId: getNodeByID
+      tags: [runtime-only]
+      summary: Get a single node definition by ID
+      description: "[cloud-only] Returns one node's definition from the pre-indexed object_info schema. Served by a raw HTTP handler that writes pre-rendered bytes with ETag + Cache-Control validators for RFC 7232 conditional GETs."
+      x-runtime: [cloud]
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: Node class identifier
+        - name: If-None-Match
+          in: header
+          required: false
+          schema:
+            type: string
+          description: Entity tag previously returned by this endpoint. When present and matching, the server returns 304 Not Modified.
+      responses:
+        "200":
+          description: Single node definition
+          headers:
+            ETag:
+              schema:
+                type: string
+              description: Entity tag for conditional request validation
+            Cache-Control:
+              schema:
+                type: string
+              description: Cache directives for the response
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/NodeInfo"
+        "304":
+          description: Not Modified — returned when the client sends a matching If-None-Match header
+        "404":
+          description: Node not found
+    delete:
+      operationId: uninstallCloudNode
+      tags: [node]
+      summary: Uninstall a custom node package
+      description: "[cloud-only] Removes a custom node package from the cloud runtime."
+      x-runtime: [cloud]
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: Custom node package ID
+      responses:
+        "204":
+          description: Node uninstalled
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/hub/assets/upload-url:
+    post:
+      operationId: getHubAssetUploadUrl
+      tags: [hub]
+      summary: Get a pre-signed upload URL for a hub asset
+      description: "[cloud-only] Returns a pre-signed URL that can be used to upload an asset file directly to storage."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - filename
+                - content_type
+              properties:
+                filename:
+                  type: string
+                  description: Name of the file to upload
+                content_type:
+                  type: string
+                  description: MIME type of the file
+                size:
+                  type: integer
+                  format: int64
+                  description: File size in bytes
+      responses:
+        "200":
+          description: Upload URL
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  upload_url:
+                    type: string
+                    format: uri
+                    description: Pre-signed upload URL
+                  asset_url:
+                    type: string
+                    format: uri
+                    description: Public URL after upload completes
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/hub/labels:
+    get:
+      operationId: listHubLabels
+      tags: [hub]
+      summary: List available hub labels
+      description: "[cloud-only] Returns the list of labels/categories available for tagging hub content."
+      x-runtime: [cloud]
+      responses:
+        "200":
+          description: Label list
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/HubLabel"
+
+  /api/hub/profiles:
+    get:
+      operationId: listHubProfiles
+      tags: [hub]
+      summary: List hub user profiles
+      description: "[cloud-only] Returns a paginated list of public hub user profiles."
+      x-runtime: [cloud]
+      parameters:
+        - name: limit
+          in: query
+          schema:
+            type: integer
+          description: Maximum number of results
+        - name: offset
+          in: query
+          schema:
+            type: integer
+          description: Pagination offset
+        - name: search
+          in: query
+          schema:
+            type: string
+          description: Search by username or display name
+      responses:
+        "200":
+          description: Profile list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  profiles:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/HubProfile"
+                  total:
+                    type: integer
+                  has_more:
+                    type: boolean
+    post:
+      operationId: createHubProfile
+      tags: [hub]
+      summary: Create a Hub profile
+      description: "[cloud-only] Creates a hub profile for the specified workspace. Username is immutable after creation."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateHubProfileRequest"
+      responses:
+        "201":
+          description: Hub profile created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HubProfile"
+        "400":
+          description: Bad request (e.g. invalid username)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "409":
+          description: Username already taken or profile already exists
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/hub/profiles/{username}:
+    get:
+      operationId: getHubProfile
+      tags: [hub]
+      summary: Get a hub profile by username
+      description: "[cloud-only] Returns the public hub profile for the given username."
+      x-runtime: [cloud]
+      parameters:
+        - name: username
+          in: path
+          required: true
+          schema:
+            type: string
+          description: Hub username
+      responses:
+        "200":
+          description: Profile
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HubProfile"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/hub/profiles/check:
+    get:
+      operationId: checkHubProfileUsername
+      tags: [hub]
+      summary: Check if a hub username is available
+      description: "[cloud-only] Returns whether the given username is available for registration."
+      x-runtime: [cloud]
+      parameters:
+        - name: username
+          in: query
+          required: true
+          schema:
+            type: string
+          description: Username to check
+      responses:
+        "200":
+          description: Availability result
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  available:
+                    type: boolean
+                  username:
+                    type: string
+
+  /api/hub/profiles/me:
+    get:
+      operationId: getMyHubProfile
+      tags: [hub]
+      summary: Get the authenticated user's hub profile
+      description: "[cloud-only] Returns the hub profile of the currently authenticated user."
+      x-runtime: [cloud]
+      responses:
+        "200":
+          description: Profile
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HubProfile"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    put:
+      operationId: updateMyHubProfile
+      tags: [hub]
+      summary: Update the authenticated user's hub profile
+      description: "[cloud-only] Updates the hub profile of the currently authenticated user."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                username:
+                  type: string
+                display_name:
+                  type: string
+                bio:
+                  type: string
+                avatar_url:
+                  type: string
+                  format: uri
+                links:
+                  type: array
+                  items:
+                    type: string
+                    format: uri
+      responses:
+        "200":
+          description: Updated profile
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HubProfile"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "409":
+          description: Conflict
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/hub/workflows:
+    get:
+      operationId: listHubWorkflows
+      tags: [hub]
+      summary: List published hub workflows
+      description: "[cloud-only] Returns a paginated list of publicly shared workflows on the hub."
+      x-runtime: [cloud]
+      parameters:
+        - name: limit
+          in: query
+          schema:
+            type: integer
+          description: Maximum number of results
+        - name: offset
+          in: query
+          schema:
+            type: integer
+          description: Pagination offset
+        - name: sort
+          in: query
+          schema:
+            type: string
+          description: Sort field (e.g. created_at, likes)
+        - name: order
+          in: query
+          schema:
+            type: string
+            enum: [asc, desc]
+          description: Sort direction
+        - name: search
+          in: query
+          schema:
+            type: string
+          description: Search by title or description
+        - name: labels
+          in: query
+          schema:
+            type: string
+          description: Filter by label IDs (comma-separated)
+      responses:
+        "200":
+          description: Hub workflow list
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HubWorkflowList"
+    post:
+      operationId: publishHubWorkflow
+      tags: [hub]
+      summary: Publish a workflow to the hub
+      description: "[cloud-only] Publishes a workflow to the hub with metadata, thumbnail, and sample images."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/PublishHubWorkflowRequest"
+      responses:
+        "200":
+          description: Workflow published to hub
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HubWorkflowDetail"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Workflow or profile not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/hub/workflows/{share_id}:
+    get:
+      operationId: getHubWorkflow
+      tags: [hub]
+      summary: Get a published hub workflow by share ID
+      description: "[cloud-only] Returns the full details of a published workflow on the hub."
+      x-runtime: [cloud]
+      parameters:
+        - name: share_id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: Workflow share ID
+      responses:
+        "200":
+          description: Hub workflow
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HubWorkflow"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    delete:
+      operationId: deleteHubWorkflow
+      tags: [hub]
+      summary: Unpublish a workflow from the hub
+      description: "[cloud-only] Removes a workflow from the hub listing."
+      x-runtime: [cloud]
+      parameters:
+        - name: share_id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: Workflow share ID
+      responses:
+        "204":
+          description: Successfully unpublished
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Workflow not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/hub/workflows/index:
+    get:
+      operationId: getHubWorkflowIndex
+      tags: [hub]
+      summary: Get the hub workflow index
+      description: "[cloud-only] Returns the lightweight index of all hub workflows for client-side search and navigation."
+      x-runtime: [cloud]
+      responses:
+        "200":
+          description: Workflow index
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/HubWorkflowIndexEntry"
+
+  # ---------------------------------------------------------------------------
+  # Workflows (cloud)
+  # ---------------------------------------------------------------------------
+  /api/workflows:
+    get:
+      operationId: listCloudWorkflows
+      tags: [workflows]
+      summary: List cloud workflows
+      description: "[cloud-only] Returns a paginated list of the authenticated user's cloud workflows."
+      x-runtime: [cloud]
+      parameters:
+        - name: limit
+          in: query
+          schema:
+            type: integer
+          description: Maximum number of results
+        - name: offset
+          in: query
+          schema:
+            type: integer
+          description: Pagination offset
+        - name: sort
+          in: query
+          schema:
+            type: string
+          description: Sort field
+        - name: order
+          in: query
+          schema:
+            type: string
+            enum: [asc, desc]
+          description: Sort direction
+        - name: search
+          in: query
+          schema:
+            type: string
+          description: Search by workflow name
+      responses:
+        "200":
+          description: Workflow list
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudWorkflowList"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    post:
+      operationId: createCloudWorkflow
+      tags: [workflows]
+      summary: Create a new cloud workflow
+      description: "[cloud-only] Creates a new cloud workflow with the provided name and optional initial content."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - name
+              properties:
+                name:
+                  type: string
+                  description: Workflow name
+                description:
+                  type: string
+                  description: Workflow description
+                content:
+                  type: object
+                  additionalProperties: true
+                  description: Initial workflow graph JSON
+      responses:
+        "201":
+          description: Workflow created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudWorkflow"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/workflows/{workflow_id}:
+    get:
+      operationId: getCloudWorkflow
+      tags: [workflows]
+      summary: Get a cloud workflow by ID
+      description: "[cloud-only] Returns the metadata for a cloud workflow."
+      x-runtime: [cloud]
+      parameters:
+        - name: workflow_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+          description: The workflow ID.
+      responses:
+        "200":
+          description: Workflow detail
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudWorkflow"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    patch:
+      operationId: updateCloudWorkflow
+      tags: [workflows]
+      summary: Update a cloud workflow
+      description: "[cloud-only] Updates the metadata (name, description) of an existing cloud workflow."
+      x-runtime: [cloud]
+      parameters:
+        - name: workflow_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+          description: The workflow ID.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                name:
+                  type: string
+                description:
+                  type: string
+      responses:
+        "200":
+          description: Workflow updated
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudWorkflow"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    delete:
+      operationId: deleteCloudWorkflow
+      tags: [workflows]
+      summary: Delete a cloud workflow
+      description: "[cloud-only] Deletes a cloud workflow and all its versions."
+      x-runtime: [cloud]
+      parameters:
+        - name: workflow_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+          description: The workflow ID.
+      responses:
+        "204":
+          description: Workflow deleted
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/workflows/{workflow_id}/content:
+    get:
+      operationId: getCloudWorkflowContent
+      tags: [workflows]
+      summary: Get the content of a cloud workflow
+      description: "[cloud-only] Returns the full workflow graph JSON for the latest version of a cloud workflow."
+      x-runtime: [cloud]
+      parameters:
+        - name: workflow_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+          description: The workflow ID.
+        - name: version_id
+          in: query
+          schema:
+            type: string
+          description: Specific version ID to fetch
+      responses:
+        "200":
+          description: Workflow content
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: true
+                description: The full workflow graph JSON
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    put:
+      operationId: updateCloudWorkflowContent
+      tags: [workflows]
+      summary: Update the content of a cloud workflow
+      description: "[cloud-only] Saves new workflow graph JSON as a new version of the cloud workflow."
+      x-runtime: [cloud]
+      parameters:
+        - name: workflow_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+          description: The workflow ID.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: true
+              description: The workflow graph JSON to save
+      responses:
+        "200":
+          description: Content updated
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudWorkflowVersion"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/workflows/{workflow_id}/fork:
+    post:
+      operationId: forkCloudWorkflow
+      tags: [workflows]
+      summary: Fork a cloud workflow
+      description: "[cloud-only] Creates a copy of a cloud workflow under the authenticated user's account."
+      x-runtime: [cloud]
+      parameters:
+        - name: workflow_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+          description: The workflow ID to fork.
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                name:
+                  type: string
+                  description: Name for the forked workflow (defaults to original name)
+      responses:
+        "201":
+          description: Forked workflow
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudWorkflow"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/workflows/{workflow_id}/versions:
+    get:
+      operationId: listCloudWorkflowVersions
+      tags: [workflows]
+      summary: List versions of a cloud workflow
+      description: "[cloud-only] Returns the version history of a cloud workflow."
+      x-runtime: [cloud]
+      parameters:
+        - name: workflow_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+          description: The workflow ID.
+        - name: limit
+          in: query
+          schema:
+            type: integer
+          description: Maximum number of results
+        - name: offset
+          in: query
+          schema:
+            type: integer
+          description: Pagination offset
+      responses:
+        "200":
+          description: Version list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  versions:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/CloudWorkflowVersion"
+                  total:
+                    type: integer
+                  has_more:
+                    type: boolean
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    post:
+      operationId: createCloudWorkflowVersion
+      tags: [workflows]
+      summary: Create a new cloud workflow version
+      description: "[cloud-only] Creates a new workflow version with updated workflow JSON. Uses optimistic concurrency via base_version."
+      x-runtime: [cloud]
+      parameters:
+        - name: workflow_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+          description: The workflow ID.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateWorkflowVersionRequest"
+      responses:
+        "201":
+          description: Version created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WorkflowVersionResponse"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "403":
+          description: Forbidden — not the workflow owner
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "409":
+          description: Version conflict — base_version does not match latest
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/workflows/published/{share_id}:
+    get:
+      operationId: getPublishedWorkflow
+      tags: [workflows]
+      summary: Get a published workflow by share ID
+      description: "[cloud-only] Returns a publicly published cloud workflow by its share identifier."
+      x-runtime: [cloud]
+      parameters:
+        - name: share_id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The workflow share ID.
+      responses:
+        "200":
+          description: Published workflow
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudWorkflow"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  # ---------------------------------------------------------------------------
+  # Auth / session (cloud)
+  # ---------------------------------------------------------------------------
+  /api/auth/session:
+    get:
+      operationId: getAuthSession
+      tags: [auth]
+      summary: Get the current authentication session
+      description: "[cloud-only] Returns the current session state for the authenticated user, including user identity and active workspace."
+      x-runtime: [cloud]
+      responses:
+        "200":
+          description: Session info
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AuthSession"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    post:
+      operationId: createAuthSession
+      tags: [auth]
+      summary: Create a session cookie
+      description: "[cloud-only] Creates a session cookie from the bearer token in the Authorization header. Returns a Set-Cookie header with a secure HttpOnly session cookie. Cookie authentication is not allowed for this endpoint."
+      x-runtime: [cloud]
+      responses:
+        "200":
+          description: Session created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CreateSessionResponse"
+        "400":
+          description: Bad request — invalid or expired ID token
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    delete:
+      operationId: deleteAuthSession
+      tags: [auth]
+      summary: Delete session cookie (logout)
+      description: "[cloud-only] Clears the session cookie and optionally revokes the session on the server."
+      x-runtime: [cloud]
+      responses:
+        "200":
+          description: Session deleted
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DeleteSessionResponse"
+
+  /api/auth/token:
+    post:
+      operationId: createAuthToken
+      tags: [auth]
+      summary: Exchange credentials for an access token
+      description: "[cloud-only] Exchanges authentication credentials (e.g. an authorization code) for an access token."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - grant_type
+              properties:
+                grant_type:
+                  type: string
+                  enum: [authorization_code, refresh_token]
+                  description: OAuth2 grant type
+                code:
+                  type: string
+                  description: Authorization code (for authorization_code grant)
+                refresh_token:
+                  type: string
+                  description: Refresh token (for refresh_token grant)
+                redirect_uri:
+                  type: string
+                  format: uri
+                  description: Redirect URI used in the authorization request
+      responses:
+        "200":
+          description: Token response
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AuthTokenResponse"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /.well-known/jwks.json:
+    get:
+      operationId: getJwks
+      tags: [auth]
+      summary: Get JSON Web Key Set
+      description: "[cloud-only] Returns the JSON Web Key Set (JWKS) used to verify JWTs issued by the cloud authentication service."
+      x-runtime: [cloud]
+      responses:
+        "200":
+          description: JWKS
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/JwksResponse"
+
+  # ---------------------------------------------------------------------------
+  # Billing (cloud)
+  # ---------------------------------------------------------------------------
+  /api/billing/balance:
+    get:
+      operationId: getBillingBalance
+      tags: [billing]
+      summary: Get current credit balance
+      description: "[cloud-only] Returns the authenticated user's current credit balance and usage summary."
+      x-runtime: [cloud]
+      responses:
+        "200":
+          description: Balance info
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BillingBalance"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/billing/events:
+    get:
+      operationId: listBillingEvents
+      tags: [billing]
+      summary: List billing events
+      description: "[cloud-only] Returns a paginated list of billing events (charges, credits, refunds) for the authenticated user."
+      x-runtime: [cloud]
+      parameters:
+        - name: limit
+          in: query
+          schema:
+            type: integer
+          description: Maximum number of results
+        - name: offset
+          in: query
+          schema:
+            type: integer
+          description: Pagination offset
+        - name: type
+          in: query
+          schema:
+            type: string
+          description: Filter by event type
+      responses:
+        "200":
+          description: Billing events
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BillingEventList"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/billing/ops/{id}:
+    get:
+      operationId: getBillingOp
+      tags: [billing]
+      summary: Get a billing operation by ID
+      description: "[cloud-only] Returns details of a specific billing operation."
+      x-runtime: [cloud]
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The billing operation ID.
+      responses:
+        "200":
+          description: Billing operation
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BillingOp"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/billing/payment-portal:
+    post:
+      operationId: createPaymentPortalSession
+      tags: [billing]
+      summary: Create a payment portal session
+      description: "[cloud-only] Creates a Stripe customer portal session for managing payment methods and invoices. Returns a URL to redirect the user to."
+      x-runtime: [cloud]
+      responses:
+        "200":
+          description: Portal session
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  url:
+                    type: string
+                    format: uri
+                    description: Stripe portal URL
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/billing/plans:
+    get:
+      operationId: listBillingPlans
+      tags: [billing]
+      summary: List available billing plans
+      description: "[cloud-only] Returns the list of available subscription plans and their pricing."
+      x-runtime: [cloud]
+      responses:
+        "200":
+          description: Plan list
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/BillingPlan"
+
+  /api/billing/preview-subscribe:
+    post:
+      operationId: previewSubscription
+      tags: [billing]
+      summary: Preview a subscription change
+      description: "[cloud-only] Returns a preview of what a subscription change would cost, including prorations."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - plan_id
+              properties:
+                plan_id:
+                  type: string
+                  description: ID of the plan to preview
+      responses:
+        "200":
+          description: Subscription preview
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SubscriptionPreview"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/billing/status:
+    get:
+      operationId: getBillingStatus
+      tags: [billing]
+      summary: Get billing status
+      description: "[cloud-only] Returns the authenticated user's current billing and subscription status."
+      x-runtime: [cloud]
+      responses:
+        "200":
+          description: Billing status
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BillingStatus"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/billing/subscribe:
+    post:
+      operationId: createSubscription
+      tags: [billing]
+      summary: Subscribe to a billing plan
+      description: "[cloud-only] Creates a new subscription to the specified billing plan."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - plan_id
+              properties:
+                plan_id:
+                  type: string
+                  description: ID of the plan to subscribe to
+                payment_method_id:
+                  type: string
+                  description: Stripe payment method ID
+      responses:
+        "200":
+          description: Subscription created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BillingSubscription"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/billing/subscription/cancel:
+    post:
+      operationId: cancelSubscription
+      tags: [billing]
+      summary: Cancel the active subscription
+      description: "[cloud-only] Cancels the authenticated user's active subscription. The subscription remains active until the end of the current billing period."
+      x-runtime: [cloud]
+      responses:
+        "200":
+          description: Subscription cancelled
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BillingSubscription"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/billing/subscription/resubscribe:
+    post:
+      operationId: resubscribe
+      tags: [billing]
+      summary: Resubscribe after cancellation
+      description: "[cloud-only] Reactivates a subscription that was previously cancelled but has not yet expired."
+      x-runtime: [cloud]
+      responses:
+        "200":
+          description: Subscription reactivated
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BillingSubscription"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/billing/topup:
+    post:
+      operationId: topUpCredits
+      tags: [billing]
+      summary: Purchase additional credits
+      description: "[cloud-only] Purchases a one-time credit top-up using the user's payment method on file."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - amount
+              properties:
+                amount:
+                  type: integer
+                  description: Number of credits to purchase
+      responses:
+        "200":
+          description: Top-up successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BillingBalance"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  # ---------------------------------------------------------------------------
+  # Workspace (cloud)
+  # ---------------------------------------------------------------------------
+  /api/workspace/api-keys:
+    get:
+      operationId: listWorkspaceApiKeys
+      tags: [workspace]
+      summary: List workspace API keys
+      description: "[cloud-only] Returns the list of API keys for the current workspace."
+      x-runtime: [cloud]
+      responses:
+        "200":
+          description: API key list
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/WorkspaceApiKey"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "403":
+          description: Forbidden
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    post:
+      operationId: createWorkspaceApiKey
+      tags: [workspace]
+      summary: Create a workspace API key
+      description: "[cloud-only] Creates a new API key for the current workspace."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - name
+              properties:
+                name:
+                  type: string
+                  description: Display name for the API key
+      responses:
+        "201":
+          description: API key created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WorkspaceApiKeyCreated"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "403":
+          description: Forbidden
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/workspace/api-keys/{id}:
+    delete:
+      operationId: deleteWorkspaceApiKey
+      tags: [workspace]
+      summary: Delete a workspace API key
+      description: "[cloud-only] Revokes and deletes a workspace API key."
+      x-runtime: [cloud]
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The API key ID.
+      responses:
+        "204":
+          description: API key deleted
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "403":
+          description: Forbidden
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/workspace/invites:
+    get:
+      operationId: listWorkspaceInvites
+      tags: [workspace]
+      summary: List pending workspace invites
+      description: "[cloud-only] Returns the list of pending invitations for the current workspace."
+      x-runtime: [cloud]
+      responses:
+        "200":
+          description: Invite list
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/WorkspaceInvite"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "403":
+          description: Forbidden
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    post:
+      operationId: createWorkspaceInvite
+      tags: [workspace]
+      summary: Invite a user to the workspace
+      description: "[cloud-only] Creates an invitation for a user to join the current workspace."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - email
+              properties:
+                email:
+                  type: string
+                  format: email
+                  description: Email address to invite
+                role:
+                  type: string
+                  enum: [admin, member]
+                  description: Role to assign
+      responses:
+        "201":
+          description: Invite created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WorkspaceInvite"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "403":
+          description: Forbidden
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "409":
+          description: Conflict
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/workspace/invites/{inviteId}:
+    delete:
+      operationId: deleteWorkspaceInvite
+      tags: [workspace]
+      summary: Cancel a workspace invite
+      description: "[cloud-only] Cancels a pending workspace invitation."
+      x-runtime: [cloud]
+      parameters:
+        - name: inviteId
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The invite ID.
+      responses:
+        "204":
+          description: Invite cancelled
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "403":
+          description: Forbidden
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/workspace/leave:
+    post:
+      operationId: leaveWorkspace
+      tags: [workspace]
+      summary: Leave the current workspace
+      description: "[cloud-only] Removes the authenticated user from the current workspace."
+      x-runtime: [cloud]
+      responses:
+        "204":
+          description: Left workspace
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "403":
+          description: Forbidden
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/workspace/members:
+    get:
+      operationId: listWorkspaceMembers
+      tags: [workspace]
+      summary: List workspace members
+      description: "[cloud-only] Returns the list of members in the current workspace."
+      x-runtime: [cloud]
+      responses:
+        "200":
+          description: Member list
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/WorkspaceMember"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "403":
+          description: Forbidden
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/workspace/members/{user_id}/api-keys:
+    get:
+      operationId: listMemberApiKeys
+      tags: [workspace]
+      summary: List API keys for a workspace member
+      description: "[cloud-only] Returns the API keys belonging to a specific workspace member. Requires admin role."
+      x-runtime: [cloud]
+      parameters:
+        - name: user_id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The member's user ID.
+      responses:
+        "200":
+          description: API key list
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/WorkspaceApiKey"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "403":
+          description: Forbidden
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    delete:
+      operationId: bulkRevokeMemberApiKeys
+      tags: [workspace]
+      summary: Bulk revoke a member's API keys
+      description: "[cloud-only] Revokes all active API keys for a specific workspace member. Only workspace owners can perform this action."
+      x-runtime: [cloud]
+      parameters:
+        - name: user_id
+          in: path
+          required: true
+          schema:
+            type: string
+            minLength: 1
+          description: The member's user ID.
+      responses:
+        "200":
+          description: Keys revoked
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BulkRevokeAPIKeysResponse"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "403":
+          description: Forbidden — must be workspace owner
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/workspace/members/{userId}:
+    patch:
+      operationId: updateWorkspaceMember
+      tags: [workspace]
+      summary: Update a workspace member's role
+      description: "[cloud-only] Updates the role of a workspace member. Requires admin role."
+      x-runtime: [cloud]
+      parameters:
+        - name: userId
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The member's user ID.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - role
+              properties:
+                role:
+                  type: string
+                  enum: [admin, member]
+                  description: New role to assign
+      responses:
+        "200":
+          description: Member updated
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WorkspaceMember"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "403":
+          description: Forbidden
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    delete:
+      operationId: removeWorkspaceMember
+      tags: [workspace]
+      summary: Remove a member from the workspace
+      description: "[cloud-only] Removes a member from the current workspace. Requires admin role."
+      x-runtime: [cloud]
+      parameters:
+        - name: userId
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The member's user ID.
+      responses:
+        "204":
+          description: Member removed
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "403":
+          description: Forbidden
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/workspaces:
+    get:
+      operationId: listWorkspaces
+      tags: [workspace]
+      summary: List workspaces the user belongs to
+      description: "[cloud-only] Returns the list of workspaces the authenticated user is a member of."
+      x-runtime: [cloud]
+      responses:
+        "200":
+          description: Workspace list
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Workspace"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    post:
+      operationId: createWorkspace
+      tags: [workspace]
+      summary: Create a new workspace
+      description: "[cloud-only] Creates a new workspace. The authenticated user becomes the owner."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - name
+              properties:
+                name:
+                  type: string
+                  description: Workspace name
+      responses:
+        "201":
+          description: Workspace created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Workspace"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/workspaces/{id}:
+    get:
+      operationId: getWorkspace
+      tags: [workspace]
+      summary: Get a workspace by ID
+      description: "[cloud-only] Returns details of a workspace the user is a member of."
+      x-runtime: [cloud]
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The workspace ID.
+      responses:
+        "200":
+          description: Workspace detail
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Workspace"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "403":
+          description: Forbidden
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    patch:
+      operationId: updateWorkspace
+      tags: [workspace]
+      summary: Update workspace settings
+      description: "[cloud-only] Updates the name or settings of a workspace. Requires admin role."
+      x-runtime: [cloud]
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The workspace ID.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                name:
+                  type: string
+                  description: New workspace name
+      responses:
+        "200":
+          description: Workspace updated
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Workspace"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "403":
+          description: Forbidden
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    delete:
+      operationId: deleteWorkspace
+      tags: [workspace]
+      summary: Delete a workspace
+      description: "[cloud-only] Soft-deletes a workspace. Requires owner role. Personal workspaces cannot be deleted."
+      x-runtime: [cloud]
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The workspace ID.
+      responses:
+        "204":
+          description: Workspace deleted
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "403":
+          description: Forbidden — must be workspace owner
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  # ---------------------------------------------------------------------------
+  # User / settings / misc (cloud)
+  # ---------------------------------------------------------------------------
+  /api/feedback:
+    post:
+      operationId: submitFeedback
+      tags: [user]
+      summary: Submit user feedback
+      description: "[cloud-only] Submits feedback from the user about their experience with the cloud runtime."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - message
+              properties:
+                message:
+                  type: string
+                  description: Feedback message
+                rating:
+                  type: integer
+                  minimum: 1
+                  maximum: 5
+                  description: Optional satisfaction rating
+                context:
+                  type: object
+                  additionalProperties: true
+                  description: Additional context metadata
+      responses:
+        "200":
+          description: Feedback submitted
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  id:
+                    type: string
+                  status:
+                    type: string
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/files/mask-layers:
+    get:
+      operationId: getMaskLayers
+      tags: [assets]
+      summary: Get related mask layer filenames
+      description: "[cloud-only] Given a mask file (any of the 4 layers), returns all related mask layer filenames. Used by the mask editor to load the paint, mask, and painted layers when reopening a previously edited mask."
+      x-runtime: [cloud]
+      parameters:
+        - name: filename
+          in: query
+          required: true
+          schema:
+            type: string
+          description: Hash filename of any mask layer file
+      responses:
+        "200":
+          description: Related mask layers
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  mask:
+                    type: string
+                    description: Filename of the mask layer
+                    nullable: true
+                  paint:
+                    type: string
+                    description: Filename of the paint strokes layer
+                    nullable: true
+                  painted:
+                    type: string
+                    description: Filename of the painted image layer
+                    nullable: true
+                  painted_masked:
+                    type: string
+                    description: Filename of the final composite layer
+                    nullable: true
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: File not found or not a mask file
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/internal/cloud_analytics:
+    post:
+      operationId: postCloudAnalytics
+      tags: [internal]
+      summary: Post client analytics events
+      description: "[cloud-only] Receives analytics events from the frontend for processing by the cloud analytics pipeline."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - events
+              properties:
+                events:
+                  type: array
+                  items:
+                    type: object
+                    required:
+                      - event_name
+                    properties:
+                      event_name:
+                        type: string
+                      timestamp:
+                        type: string
+                        format: date-time
+                      properties:
+                        type: object
+                        additionalProperties: true
+      responses:
+        "200":
+          description: Events accepted
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/invites/{token}/accept:
+    post:
+      operationId: acceptInvite
+      tags: [workspace]
+      summary: Accept a workspace invitation
+      description: "[cloud-only] Accepts a workspace invitation using the invite token. The authenticated user is added to the workspace."
+      x-runtime: [cloud]
+      parameters:
+        - name: token
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The invitation token.
+      responses:
+        "200":
+          description: Invite accepted
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Workspace"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/secrets:
+    get:
+      operationId: listSecrets
+      tags: [settings]
+      summary: List user secrets
+      description: "[cloud-only] Returns the list of secrets (API keys for third-party services) stored for the authenticated user. Secret values are redacted."
+      x-runtime: [cloud]
+      responses:
+        "200":
+          description: Secret list
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/SecretMeta"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    post:
+      operationId: createSecret
+      tags: [settings]
+      summary: Create or update a secret
+      description: "[cloud-only] Stores a new secret or updates an existing one. Secrets are encrypted at rest."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - name
+                - value
+              properties:
+                name:
+                  type: string
+                  description: Secret name (unique per user)
+                value:
+                  type: string
+                  description: Secret value
+      responses:
+        "201":
+          description: Secret created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SecretMeta"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/secrets/{id}:
+    get:
+      operationId: getSecret
+      tags: [settings]
+      summary: Get secret metadata
+      description: "[cloud-only] Returns metadata for a specific secret. Does not return the plaintext secret value."
+      x-runtime: [cloud]
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+          description: The secret ID.
+      responses:
+        "200":
+          description: Secret metadata
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SecretMeta"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    patch:
+      operationId: updateSecret
+      tags: [settings]
+      summary: Update a secret
+      description: "[cloud-only] Updates an existing secret's name and/or value. Both fields are optional; only provided fields are updated."
+      x-runtime: [cloud]
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+          description: The secret ID.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/UpdateSecretRequest"
+      responses:
+        "200":
+          description: Secret updated
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SecretMeta"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "409":
+          description: Conflict — a secret with this name already exists
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    delete:
+      operationId: deleteSecret
+      tags: [settings]
+      summary: Delete a secret
+      description: "[cloud-only] Permanently deletes a stored secret."
+      x-runtime: [cloud]
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The secret ID.
+      responses:
+        "204":
+          description: Secret deleted
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/user:
+    get:
+      operationId: getCloudUser
+      tags: [user]
+      summary: Get the authenticated cloud user
+      description: "[cloud-only] Returns the profile and account information for the currently authenticated user."
+      x-runtime: [cloud]
+      responses:
+        "200":
+          description: User profile
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudUser"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    put:
+      operationId: updateCloudUser
+      tags: [user]
+      summary: Update the authenticated cloud user profile
+      description: "[cloud-only] Updates the profile information for the currently authenticated user."
+      x-runtime: [cloud]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                display_name:
+                  type: string
+                avatar_url:
+                  type: string
+                  format: uri
+      responses:
+        "200":
+          description: Updated profile
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudUser"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/userdata/{file}/publish:
+    get:
+      operationId: getUserdataFilePublish
+      tags: [userdata]
+      summary: Get publish info for a userdata file
+      description: "[cloud-only] Returns the publish status and share info for a userdata workflow file."
+      x-runtime: [cloud]
+      parameters:
+        - name: file
+          in: path
+          required: true
+          schema:
+            type: string
+          description: File path relative to user data directory
+      responses:
+        "200":
+          description: Publish info (publish_time is null if never published)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WorkflowPublishInfo"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Workflow not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+    post:
+      operationId: publishUserdataFile
+      tags: [userdata]
+      summary: Publish a userdata file to the cloud
+      description: "[cloud-only] Makes a userdata file available via a public URL for sharing or embedding."
+      x-runtime: [cloud]
+      parameters:
+        - name: file
+          in: path
+          required: true
+          schema:
+            type: string
+          description: File path relative to user data directory
+      responses:
+        "200":
+          description: Published file URL
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  url:
+                    type: string
+                    format: uri
+                    description: Public URL of the published file
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/vhs/queryvideo:
+    get:
+      operationId: queryVhsVideo
+      tags: [view]
+      summary: Query VHS video metadata
+      description: "[cloud-only] Returns metadata about a video file processed by the VHS (Video Helper Suite) integration."
+      x-runtime: [cloud]
+      parameters:
+        - name: filename
+          in: query
+          required: true
+          schema:
+            type: string
+          description: Video filename
+        - name: type
+          in: query
+          schema:
+            type: string
+            enum: [input, output, temp]
+          description: Directory type
+        - name: subfolder
+          in: query
+          schema:
+            type: string
+          description: Subfolder within the directory
+      responses:
+        "200":
+          description: Video metadata
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: true
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/vhs/viewaudio:
+    get:
+      operationId: viewVhsAudio
+      tags: [view]
+      summary: View or download VHS audio
+      description: "[cloud-only] Returns audio content from a VHS-processed file."
+      x-runtime: [cloud]
+      parameters:
+        - name: filename
+          in: query
+          required: true
+          schema:
+            type: string
+          description: Audio filename
+        - name: type
+          in: query
+          schema:
+            type: string
+            enum: [input, output, temp]
+          description: Directory type
+        - name: subfolder
+          in: query
+          schema:
+            type: string
+          description: Subfolder within the directory
+      responses:
+        "200":
+          description: Audio content
+          content:
+            audio/*:
+              schema:
+                type: string
+                format: binary
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/vhs/viewvideo:
+    get:
+      operationId: viewVhsVideo
+      tags: [view]
+      summary: View or download VHS video
+      description: "[cloud-only] Returns video content from a VHS-processed file."
+      x-runtime: [cloud]
+      parameters:
+        - name: filename
+          in: query
+          required: true
+          schema:
+            type: string
+          description: Video filename
+        - name: type
+          in: query
+          schema:
+            type: string
+            enum: [input, output, temp]
+          description: Directory type
+        - name: subfolder
+          in: query
+          schema:
+            type: string
+          description: Subfolder within the directory
+      responses:
+        "200":
+          description: Video content
+          content:
+            video/*:
+              schema:
+                type: string
+                format: binary
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/viewvideo:
+    get:
+      operationId: viewVideo
+      tags: [view]
+      summary: View or download a video file
+      description: "[cloud-only] Serves a video file from the output directory. Used by the frontend video player."
+      x-runtime: [cloud]
+      parameters:
+        - name: filename
+          in: query
+          required: true
+          schema:
+            type: string
+          description: Video filename
+        - name: type
+          in: query
+          schema:
+            type: string
+            enum: [input, output, temp]
+          description: Directory type
+        - name: subfolder
+          in: query
+          schema:
+            type: string
+          description: Subfolder within the directory
+      responses:
+        "200":
+          description: Video content
+          content:
+            video/*:
+              schema:
+                type: string
+                format: binary
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/tasks:
+    get:
+      operationId: listTasks
+      tags: [task]
+      summary: List background tasks
+      description: "[cloud-only] Retrieve a paginated list of background tasks for the authenticated user. Supports filtering by task type, status, and creation time."
+      x-runtime: [cloud]
+      parameters:
+        - name: task_name
+          in: query
+          schema:
+            type: string
+          description: Filter by task type name (exact match).
+        - name: idempotency_key
+          in: query
+          schema:
+            type: string
+          description: Filter by idempotency key (exact match).
+        - name: status
+          in: query
+          schema:
+            type: string
+          description: Filter by one or more statuses (comma-separated).
+        - name: created_after
+          in: query
+          schema:
+            type: string
+            format: date-time
+          description: Filter tasks created after this timestamp.
+        - name: created_before
+          in: query
+          schema:
+            type: string
+            format: date-time
+          description: Filter tasks created before this timestamp.
+        - name: sort_order
+          in: query
+          schema:
+            type: string
+            enum: [asc, desc]
+            default: desc
+          description: Sort direction by create_time.
+        - name: offset
+          in: query
+          schema:
+            type: integer
+            minimum: 0
+            default: 0
+          description: Pagination offset (0-based).
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 20
+          description: Maximum items per page (1-100).
+      responses:
+        "200":
+          description: Tasks retrieved
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TasksListResponse"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "422":
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+  /api/tasks/{task_id}:
+    get:
+      operationId: getTask
+      tags: [task]
+      summary: Get task details
+      description: "[cloud-only] Retrieve full details for a specific background task."
+      x-runtime: [cloud]
+      parameters:
+        - name: task_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+          description: Task identifier (UUID).
+      responses:
+        "200":
+          description: Task details
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TaskResponse"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+        "404":
+          description: Task not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloudError"
+
+
 components:
   parameters:
     ComfyUserHeader:
@@ -2823,14 +6291,29 @@ components:
         name:
           type: string
           description: Name of the asset file
+        hash:
+          type: string
+          nullable: true
+          description: Blake3 content hash of the asset (preferred over asset_hash)
+          pattern: "^blake3:[a-f0-9]{64}$"
         asset_hash:
           type: string
-          description: Blake3 hash of the asset content
+          nullable: true
+          deprecated: true
+          description: "Deprecated: use `hash` instead. Blake3 hash of the asset content."
           pattern: "^blake3:[a-f0-9]{64}$"
         size:
           type: integer
           format: int64
           description: Size of the asset in bytes
+        width:
+          type: integer
+          nullable: true
+          description: "Original image width in pixels. Null for non-image assets or assets ingested before dimension extraction."
+        height:
+          type: integer
+          nullable: true
+          description: "Original image height in pixels. Null for non-image assets or assets ingested before dimension extraction."
         mime_type:
           type: string
           description: MIME type of the asset
@@ -2859,7 +6342,14 @@ components:
         prompt_id:
           type: string
           format: uuid
-          description: ID of the prompt that created this asset
+          nullable: true
+          deprecated: true
+          description: "Deprecated: use job_id instead. ID of the prompt that created this asset."
+        job_id:
+          type: string
+          format: uuid
+          nullable: true
+          description: ID of the job that created this asset
         created_at:
           type: string
           format: date-time
@@ -2897,8 +6387,16 @@ components:
           format: uuid
         name:
           type: string
+        hash:
+          type: string
+          nullable: true
+          description: Blake3 content hash of the asset (preferred over asset_hash)
+          pattern: "^blake3:[a-f0-9]{64}$"
         asset_hash:
           type: string
+          nullable: true
+          deprecated: true
+          description: "Deprecated: use `hash` instead. Blake3 hash of the asset content."
           pattern: "^blake3:[a-f0-9]{64}$"
         tags:
           type: array
@@ -2909,6 +6407,17 @@ components:
         user_metadata:
           type: object
           additionalProperties: true
+        prompt_id:
+          type: string
+          format: uuid
+          nullable: true
+          deprecated: true
+          description: "Deprecated: use job_id instead. ID of the prompt that created this asset."
+        job_id:
+          type: string
+          format: uuid
+          nullable: true
+          description: ID of the job that created this asset
         updated_at:
           type: string
           format: date-time
@@ -3365,3 +6874,1202 @@ components:
           enum: [created, running, completed, failed]
         error:
           type: string
+
+
+    # -------------------------------------------------------------------
+    # Cloud-runtime schemas
+    #
+    # These schemas are exclusively referenced by cloud-runtime operations.
+    # Tagged x-runtime: [cloud].
+    # -------------------------------------------------------------------
+    CloudError:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Standard error response from cloud endpoints."
+      required:
+        - error
+      properties:
+        error:
+          type: string
+          description: Error message
+        code:
+          type: string
+          description: Machine-readable error code
+        details:
+          type: object
+          additionalProperties: true
+          description: Additional error context
+
+    CloudJobStatus:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Status of a cloud job."
+      required:
+        - id
+        - status
+      properties:
+        id:
+          type: string
+          format: uuid
+        status:
+          type: string
+          enum: [pending, running, completed, failed, cancelled]
+        progress:
+          type: number
+          minimum: 0
+          maximum: 1
+          description: "Execution progress (0.0 to 1.0)"
+        started_at:
+          type: string
+          format: date-time
+          nullable: true
+        completed_at:
+          type: string
+          format: date-time
+          nullable: true
+
+    CloudPrompt:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] A cloud-executed prompt record."
+      required:
+        - id
+        - status
+      properties:
+        id:
+          type: string
+          format: uuid
+        status:
+          type: string
+        workflow:
+          type: object
+          additionalProperties: true
+        outputs:
+          type: object
+          additionalProperties: true
+        created_at:
+          type: string
+          format: date-time
+        completed_at:
+          type: string
+          format: date-time
+          nullable: true
+
+    HistoryV2Response:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Paginated execution history in v2 format."
+      required:
+        - items
+        - total
+        - has_more
+      properties:
+        items:
+          type: array
+          items:
+            $ref: "#/components/schemas/HistoryV2Entry"
+        total:
+          type: integer
+        has_more:
+          type: boolean
+
+    HistoryV2Entry:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] A single execution history entry in v2 format."
+      required:
+        - id
+        - status
+      properties:
+        id:
+          type: string
+          format: uuid
+        status:
+          type: string
+        workflow:
+          type: object
+          additionalProperties: true
+        outputs:
+          type: object
+          additionalProperties: true
+        created_at:
+          type: string
+          format: date-time
+        started_at:
+          type: string
+          format: date-time
+          nullable: true
+        completed_at:
+          type: string
+          format: date-time
+          nullable: true
+        preview_output:
+          type: object
+          additionalProperties: true
+
+    CloudLogsResponse:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Paginated cloud execution logs."
+      required:
+        - entries
+      properties:
+        entries:
+          type: array
+          items:
+            type: object
+            properties:
+              timestamp:
+                type: string
+                format: date-time
+              level:
+                type: string
+                enum: [debug, info, warn, error]
+              message:
+                type: string
+              job_id:
+                type: string
+                format: uuid
+        total:
+          type: integer
+        has_more:
+          type: boolean
+
+    AssetDownloadRequest:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] A single asset to download to the cloud runtime."
+      required:
+        - asset_id
+      properties:
+        asset_id:
+          type: string
+          format: uuid
+          description: ID of the asset to download
+        target_path:
+          type: string
+          description: Target path on the runtime filesystem
+
+    AssetImportRequest:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] A single asset to import from an external URL."
+      required:
+        - url
+      properties:
+        url:
+          type: string
+          format: uri
+          description: URL of the asset to import
+        name:
+          type: string
+          description: Display name for the imported asset
+        tags:
+          type: array
+          items:
+            type: string
+
+    RemoteAssetMetadata:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Metadata fetched from a remote asset URL."
+      properties:
+        content_type:
+          type: string
+          description: MIME type of the remote file
+        content_length:
+          type: integer
+          format: int64
+          description: Size in bytes
+        filename:
+          type: string
+          description: Suggested filename from Content-Disposition or URL
+
+    CloudNode:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] An installed custom node package in the cloud runtime."
+      required:
+        - id
+        - name
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        version:
+          type: string
+        description:
+          type: string
+        author:
+          type: string
+        repository:
+          type: string
+          format: uri
+        installed_at:
+          type: string
+          format: date-time
+        enabled:
+          type: boolean
+
+    HubLabel:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] A label/category used for tagging hub content."
+      required:
+        - id
+        - name
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        description:
+          type: string
+        color:
+          type: string
+          description: Hex color code for the label
+
+    HubProfile:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] A public user profile on the ComfyUI Hub."
+      required:
+        - username
+      properties:
+        username:
+          type: string
+        display_name:
+          type: string
+        bio:
+          type: string
+        avatar_url:
+          type: string
+          format: uri
+        links:
+          type: array
+          items:
+            type: string
+            format: uri
+        workflow_count:
+          type: integer
+        created_at:
+          type: string
+          format: date-time
+
+    HubWorkflow:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] A published workflow on the ComfyUI Hub."
+      required:
+        - share_id
+        - name
+      properties:
+        share_id:
+          type: string
+        name:
+          type: string
+        description:
+          type: string
+        author:
+          $ref: "#/components/schemas/HubProfile"
+        labels:
+          type: array
+          items:
+            $ref: "#/components/schemas/HubLabel"
+        thumbnail_url:
+          type: string
+          format: uri
+        content:
+          type: object
+          additionalProperties: true
+          description: Workflow graph JSON
+        likes:
+          type: integer
+        views:
+          type: integer
+        forks:
+          type: integer
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+
+    HubWorkflowList:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Paginated list of hub workflows."
+      required:
+        - workflows
+        - total
+        - has_more
+      properties:
+        workflows:
+          type: array
+          items:
+            $ref: "#/components/schemas/HubWorkflow"
+        total:
+          type: integer
+        has_more:
+          type: boolean
+
+    HubWorkflowIndexEntry:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Lightweight entry in the hub workflow index for client-side search."
+      required:
+        - share_id
+        - name
+      properties:
+        share_id:
+          type: string
+        name:
+          type: string
+        author_username:
+          type: string
+        labels:
+          type: array
+          items:
+            type: string
+        likes:
+          type: integer
+        updated_at:
+          type: string
+          format: date-time
+
+    CloudWorkflow:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] A cloud-managed workflow with version history."
+      required:
+        - id
+        - name
+      properties:
+        id:
+          type: string
+          format: uuid
+        name:
+          type: string
+        description:
+          type: string
+        share_id:
+          type: string
+          nullable: true
+          description: Public share identifier if published
+        latest_version_id:
+          type: string
+          format: uuid
+          nullable: true
+        thumbnail_url:
+          type: string
+          format: uri
+          nullable: true
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+
+    CloudWorkflowList:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Paginated list of cloud workflows."
+      required:
+        - workflows
+        - total
+        - has_more
+      properties:
+        workflows:
+          type: array
+          items:
+            $ref: "#/components/schemas/CloudWorkflow"
+        total:
+          type: integer
+        has_more:
+          type: boolean
+
+    CloudWorkflowVersion:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] A version of a cloud workflow."
+      required:
+        - id
+        - workflow_id
+      properties:
+        id:
+          type: string
+          format: uuid
+        workflow_id:
+          type: string
+          format: uuid
+        version_number:
+          type: integer
+        created_at:
+          type: string
+          format: date-time
+
+    AuthSession:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Current authentication session state."
+      required:
+        - user
+      properties:
+        user:
+          $ref: "#/components/schemas/CloudUser"
+        workspace:
+          $ref: "#/components/schemas/Workspace"
+        expires_at:
+          type: string
+          format: date-time
+
+    AuthTokenResponse:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] OAuth2 token response."
+      required:
+        - access_token
+        - token_type
+      properties:
+        access_token:
+          type: string
+        token_type:
+          type: string
+          description: Always "Bearer"
+        expires_in:
+          type: integer
+          description: Token lifetime in seconds
+        refresh_token:
+          type: string
+          nullable: true
+        scope:
+          type: string
+
+    JwksResponse:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] JSON Web Key Set for JWT verification."
+      required:
+        - keys
+      properties:
+        keys:
+          type: array
+          items:
+            type: object
+            required:
+              - kty
+              - kid
+              - use
+            properties:
+              kty:
+                type: string
+                description: Key type (e.g. RSA)
+              kid:
+                type: string
+                description: Key ID
+              use:
+                type: string
+                description: Key use (e.g. sig)
+              alg:
+                type: string
+                description: Algorithm (e.g. RS256)
+              n:
+                type: string
+                description: RSA modulus (base64url)
+              e:
+                type: string
+                description: RSA exponent (base64url)
+            additionalProperties: true
+
+    BillingBalance:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Current credit balance and usage summary."
+      required:
+        - credits_remaining
+      properties:
+        credits_remaining:
+          type: integer
+          description: Available credits
+        credits_used:
+          type: integer
+          description: Credits used in current billing period
+        credits_total:
+          type: integer
+          description: Total credits allocated in current period
+
+    BillingEvent:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] A billing event (charge, credit, refund)."
+      required:
+        - id
+        - type
+        - amount
+        - created_at
+      properties:
+        id:
+          type: string
+        type:
+          type: string
+          enum: [charge, credit, refund, topup, subscription]
+        amount:
+          type: integer
+          description: Amount in credits
+        description:
+          type: string
+        job_id:
+          type: string
+          format: uuid
+          nullable: true
+        created_at:
+          type: string
+          format: date-time
+
+    BillingEventList:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Paginated list of billing events."
+      required:
+        - events
+        - total
+        - has_more
+      properties:
+        events:
+          type: array
+          items:
+            $ref: "#/components/schemas/BillingEvent"
+        total:
+          type: integer
+        has_more:
+          type: boolean
+
+    BillingOp:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] A billing operation record."
+      required:
+        - id
+        - status
+      properties:
+        id:
+          type: string
+        status:
+          type: string
+          enum: [pending, completed, failed]
+        type:
+          type: string
+        amount:
+          type: integer
+        created_at:
+          type: string
+          format: date-time
+        completed_at:
+          type: string
+          format: date-time
+          nullable: true
+
+    BillingPlan:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] A subscription plan with pricing details."
+      required:
+        - id
+        - name
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        description:
+          type: string
+        credits_per_month:
+          type: integer
+        price_cents:
+          type: integer
+          description: Monthly price in cents (USD)
+        currency:
+          type: string
+          default: usd
+        features:
+          type: array
+          items:
+            type: string
+          description: List of plan features
+
+    BillingStatus:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Overall billing and subscription status."
+      properties:
+        subscription:
+          $ref: "#/components/schemas/BillingSubscription"
+        balance:
+          $ref: "#/components/schemas/BillingBalance"
+        has_payment_method:
+          type: boolean
+
+    BillingSubscription:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Active subscription details."
+      required:
+        - id
+        - status
+        - plan_id
+      properties:
+        id:
+          type: string
+        status:
+          type: string
+          enum: [active, cancelled, past_due, trialing]
+        plan_id:
+          type: string
+        plan_name:
+          type: string
+        current_period_start:
+          type: string
+          format: date-time
+        current_period_end:
+          type: string
+          format: date-time
+        cancel_at_period_end:
+          type: boolean
+
+    SubscriptionPreview:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Preview of a subscription change including prorations."
+      properties:
+        plan_id:
+          type: string
+        plan_name:
+          type: string
+        amount_due:
+          type: integer
+          description: Amount due in cents
+        proration_amount:
+          type: integer
+          description: Proration adjustment in cents
+        currency:
+          type: string
+        next_billing_date:
+          type: string
+          format: date-time
+
+    Workspace:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] A cloud workspace for team collaboration."
+      required:
+        - id
+        - name
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        owner_id:
+          type: string
+        member_count:
+          type: integer
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+
+    WorkspaceMember:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] A member of a cloud workspace."
+      required:
+        - user_id
+        - role
+      properties:
+        user_id:
+          type: string
+        email:
+          type: string
+          format: email
+        display_name:
+          type: string
+        avatar_url:
+          type: string
+          format: uri
+        role:
+          type: string
+          enum: [owner, admin, member]
+        joined_at:
+          type: string
+          format: date-time
+
+    WorkspaceInvite:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] A pending workspace invitation."
+      required:
+        - id
+        - email
+        - role
+      properties:
+        id:
+          type: string
+        email:
+          type: string
+          format: email
+        role:
+          type: string
+          enum: [admin, member]
+        invited_by:
+          type: string
+        created_at:
+          type: string
+          format: date-time
+        expires_at:
+          type: string
+          format: date-time
+
+    WorkspaceApiKey:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] A workspace API key (secret value redacted)."
+      required:
+        - id
+        - name
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        prefix:
+          type: string
+          description: First few characters of the key for identification
+        created_at:
+          type: string
+          format: date-time
+        last_used_at:
+          type: string
+          format: date-time
+          nullable: true
+        created_by:
+          type: string
+
+    WorkspaceApiKeyCreated:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] A newly created workspace API key, including the full secret value (shown only once)."
+      required:
+        - id
+        - name
+        - key
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        key:
+          type: string
+          description: Full API key value (only returned on creation)
+        prefix:
+          type: string
+        created_at:
+          type: string
+          format: date-time
+
+    CloudUser:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] A cloud-authenticated user profile."
+      required:
+        - id
+        - email
+      properties:
+        id:
+          type: string
+        email:
+          type: string
+          format: email
+        display_name:
+          type: string
+        avatar_url:
+          type: string
+          format: uri
+        created_at:
+          type: string
+          format: date-time
+
+    SecretMeta:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Metadata for a stored secret (value is never returned)."
+      required:
+        - id
+        - name
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        provider:
+          type: string
+          description: "[cloud-only] Provider identifier (e.g., huggingface, civitai)."
+          x-runtime: [cloud]
+        last_used_at:
+          type: string
+          format: date-time
+          description: "[cloud-only] When the secret was last used for decryption."
+          x-runtime: [cloud]
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+
+    UpdateSecretRequest:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Request body for updating an existing user secret."
+      properties:
+        name:
+          type: string
+          description: New name for the secret
+        secret_value:
+          type: string
+          description: New secret value (API key, token, etc.)
+
+    CreateSessionResponse:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Response after creating a session cookie."
+      required:
+        - success
+      properties:
+        success:
+          type: boolean
+        expiresIn:
+          type: integer
+          description: Session expiration time in seconds.
+
+    DeleteSessionResponse:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Response after deleting a session cookie."
+      required:
+        - success
+      properties:
+        success:
+          type: boolean
+
+    CreateHubProfileRequest:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Request body for creating a new Hub profile."
+      required:
+        - workspace_id
+        - username
+      properties:
+        workspace_id:
+          type: string
+        username:
+          type: string
+          description: Unique URL-safe slug. Immutable after creation.
+        display_name:
+          type: string
+        description:
+          type: string
+        avatar_token:
+          type: string
+        website_urls:
+          type: array
+          items:
+            type: string
+
+    PublishHubWorkflowRequest:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Request body for publishing or updating a workflow on the Hub."
+      required:
+        - username
+        - name
+        - workflow_filename
+        - asset_ids
+      properties:
+        username:
+          type: string
+        name:
+          type: string
+        workflow_filename:
+          type: string
+        asset_ids:
+          type: array
+          items:
+            type: string
+        description:
+          type: string
+        tags:
+          type: array
+          items:
+            type: string
+        models:
+          type: array
+          items:
+            type: string
+        custom_nodes:
+          type: array
+          items:
+            type: string
+        tutorial_url:
+          type: string
+        metadata:
+          type: object
+          additionalProperties: true
+        thumbnail_type:
+          type: string
+          enum: [image, video, image_comparison]
+        thumbnail_token_or_url:
+          type: string
+        thumbnail_comparison_token_or_url:
+          type: string
+        sample_image_tokens_or_urls:
+          type: array
+          items:
+            type: string
+
+    HubWorkflowDetail:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Full Hub workflow detail including versions, assets, and statistics."
+      required:
+        - share_id
+        - workflow_id
+        - name
+        - workflow_json
+        - assets
+        - profile
+        - status
+      properties:
+        share_id:
+          type: string
+        workflow_id:
+          type: string
+        name:
+          type: string
+        status:
+          type: string
+          enum: [pending, approved, rejected, deprecated]
+        description:
+          type: string
+        thumbnail_type:
+          type: string
+          enum: [image, video, image_comparison]
+        thumbnail_url:
+          type: string
+        thumbnail_comparison_url:
+          type: string
+        tutorial_url:
+          type: string
+        metadata:
+          type: object
+          additionalProperties: true
+        sample_image_urls:
+          type: array
+          items:
+            type: string
+        publish_time:
+          type: string
+          format: date-time
+          nullable: true
+        workflow_json:
+          type: object
+          additionalProperties: true
+        assets:
+          type: array
+          items:
+            $ref: "#/components/schemas/AssetInfo"
+        profile:
+          $ref: "#/components/schemas/HubProfile"
+
+    AssetInfo:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Lightweight asset reference used in workflow publishing payloads."
+      required:
+        - id
+        - filename
+      properties:
+        id:
+          type: string
+        filename:
+          type: string
+        mime_type:
+          type: string
+        size_bytes:
+          type: integer
+          format: int64
+
+    BulkRevokeAPIKeysResponse:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Response after bulk-revoking API keys for a workspace member."
+      required:
+        - revoked_count
+      properties:
+        revoked_count:
+          type: integer
+          minimum: 0
+
+    CreateWorkflowVersionRequest:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Request body for creating a new version of a saved workflow."
+      required:
+        - base_version
+        - workflow_json
+      properties:
+        base_version:
+          type: integer
+          description: Version number this change is based on (for optimistic concurrency).
+        workflow_json:
+          type: object
+          additionalProperties: true
+
+    WorkflowVersionResponse:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Metadata for a single workflow version."
+      required:
+        - id
+        - version
+        - latest_version
+        - created_by
+        - created_at
+      properties:
+        id:
+          type: string
+        version:
+          type: integer
+        latest_version:
+          type: integer
+        created_by:
+          type: string
+        created_at:
+          type: string
+          format: date-time
+
+    WorkflowPublishInfo:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Publishing metadata for a workflow shared to the Hub."
+      required:
+        - workflow_id
+        - share_id
+        - listed
+        - assets
+      properties:
+        workflow_id:
+          type: string
+        share_id:
+          type: string
+        publish_time:
+          type: string
+          format: date-time
+          nullable: true
+        listed:
+          type: boolean
+        assets:
+          type: array
+          items:
+            $ref: "#/components/schemas/AssetInfo"
+
+    TaskEntry:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Task data for list views."
+      required:
+        - id
+        - task_name
+        - status
+        - create_time
+      properties:
+        id:
+          type: string
+          format: uuid
+        task_name:
+          type: string
+        status:
+          type: string
+          enum: [created, running, completed, failed]
+        create_time:
+          type: string
+          format: date-time
+        started_at:
+          type: string
+          format: date-time
+        completed_at:
+          type: string
+          format: date-time
+
+    TaskResponse:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Full task details including payload and result."
+      required:
+        - id
+        - idempotency_key
+        - task_name
+        - payload
+        - status
+        - create_time
+        - update_time
+      properties:
+        id:
+          type: string
+          format: uuid
+        idempotency_key:
+          type: string
+        task_name:
+          type: string
+        payload:
+          type: object
+          additionalProperties: true
+        status:
+          type: string
+          enum: [created, running, completed, failed]
+        result:
+          type: object
+          additionalProperties: true
+        create_time:
+          type: string
+          format: date-time
+        update_time:
+          type: string
+          format: date-time
+        started_at:
+          type: string
+          format: date-time
+        completed_at:
+          type: string
+          format: date-time
+        error:
+          type: string
+
+    TasksListResponse:
+      type: object
+      x-runtime: [cloud]
+      description: "[cloud-only] Paginated list of background tasks for the authenticated user."
+      required:
+        - tasks
+        - pagination
+      properties:
+        tasks:
+          type: array
+          items:
+            $ref: "#/components/schemas/TaskEntry"
+        pagination:
+          $ref: "#/components/schemas/PaginationInfo"
\ No newline at end of file
diff --git a/tests-unit/app_test/node_replace_manager_test.py b/tests-unit/app_test/node_replace_manager_test.py
new file mode 100644
index 000000000..8a3fd18bb
--- /dev/null
+++ b/tests-unit/app_test/node_replace_manager_test.py
@@ -0,0 +1,90 @@
+"""Tests for NodeReplaceManager registration behavior."""
+import importlib
+import sys
+import types
+
+import pytest
+
+
+@pytest.fixture
+def NodeReplaceManager(monkeypatch):
+    """Provide NodeReplaceManager with `nodes` stubbed.
+
+    `app.node_replace_manager` does `import nodes` at module level, which pulls in
+    torch + the full ComfyUI graph. register() doesn't actually need it, so we
+    stub `nodes` per-test (via monkeypatch so it's torn down) and reload the
+    module so it picks up the stub instead of any cached real import.
+    """
+    fake_nodes = types.ModuleType("nodes")
+    fake_nodes.NODE_CLASS_MAPPINGS = {}
+    monkeypatch.setitem(sys.modules, "nodes", fake_nodes)
+    monkeypatch.delitem(sys.modules, "app.node_replace_manager", raising=False)
+    module = importlib.import_module("app.node_replace_manager")
+    yield module.NodeReplaceManager
+    # Drop the freshly-imported module so the next test (or a later real import
+    # of `nodes`) starts from a clean slate.
+    sys.modules.pop("app.node_replace_manager", None)
+
+
+class FakeNodeReplace:
+    """Lightweight stand-in for comfy_api.latest._io.NodeReplace."""
+    def __init__(self, new_node_id, old_node_id, old_widget_ids=None,
+                 input_mapping=None, output_mapping=None):
+        self.new_node_id = new_node_id
+        self.old_node_id = old_node_id
+        self.old_widget_ids = old_widget_ids
+        self.input_mapping = input_mapping
+        self.output_mapping = output_mapping
+
+
+def test_register_adds_replacement(NodeReplaceManager):
+    manager = NodeReplaceManager()
+    manager.register(FakeNodeReplace(new_node_id="NewNode", old_node_id="OldNode"))
+    assert manager.has_replacement("OldNode")
+    assert len(manager.get_replacement("OldNode")) == 1
+
+
+def test_register_allows_multiple_alternatives_for_same_old_node(NodeReplaceManager):
+    """Different new_node_ids for the same old_node_id should all be kept."""
+    manager = NodeReplaceManager()
+    manager.register(FakeNodeReplace(new_node_id="AltA", old_node_id="OldNode"))
+    manager.register(FakeNodeReplace(new_node_id="AltB", old_node_id="OldNode"))
+    replacements = manager.get_replacement("OldNode")
+    assert len(replacements) == 2
+    assert {r.new_node_id for r in replacements} == {"AltA", "AltB"}
+
+
+def test_register_is_idempotent_for_duplicate_pair(NodeReplaceManager):
+    """Re-registering the same (old_node_id, new_node_id) should be a no-op."""
+    manager = NodeReplaceManager()
+    manager.register(FakeNodeReplace(new_node_id="NewNode", old_node_id="OldNode"))
+    manager.register(FakeNodeReplace(new_node_id="NewNode", old_node_id="OldNode"))
+    manager.register(FakeNodeReplace(new_node_id="NewNode", old_node_id="OldNode"))
+    assert len(manager.get_replacement("OldNode")) == 1
+
+
+def test_register_idempotent_preserves_first_registration(NodeReplaceManager):
+    """First registration wins; later duplicates with different mappings are ignored."""
+    manager = NodeReplaceManager()
+    first = FakeNodeReplace(
+        new_node_id="NewNode", old_node_id="OldNode",
+        input_mapping=[{"new_id": "a", "old_id": "x"}],
+    )
+    second = FakeNodeReplace(
+        new_node_id="NewNode", old_node_id="OldNode",
+        input_mapping=[{"new_id": "b", "old_id": "y"}],
+    )
+    manager.register(first)
+    manager.register(second)
+    replacements = manager.get_replacement("OldNode")
+    assert len(replacements) == 1
+    assert replacements[0] is first
+
+
+def test_register_dedupe_does_not_affect_other_old_nodes(NodeReplaceManager):
+    manager = NodeReplaceManager()
+    manager.register(FakeNodeReplace(new_node_id="NewA", old_node_id="OldA"))
+    manager.register(FakeNodeReplace(new_node_id="NewA", old_node_id="OldA"))
+    manager.register(FakeNodeReplace(new_node_id="NewB", old_node_id="OldB"))
+    assert len(manager.get_replacement("OldA")) == 1
+    assert len(manager.get_replacement("OldB")) == 1
diff --git a/tests/execution/testing_nodes/testing-pack/api_test_nodes.py b/tests/execution/testing_nodes/testing-pack/api_test_nodes.py
index b2eaae05e..70c2a9e95 100644
--- a/tests/execution/testing_nodes/testing-pack/api_test_nodes.py
+++ b/tests/execution/testing_nodes/testing-pack/api_test_nodes.py
@@ -21,7 +21,7 @@ class TestAsyncProgressUpdate(ComfyNodeABC):
 
     RETURN_TYPES = (IO.ANY,)
     FUNCTION = "execute"
-    CATEGORY = "_for_testing/async"
+    CATEGORY = "experimental/async"
 
     async def execute(self, value, sleep_seconds):
         start = time.time()
@@ -51,7 +51,7 @@ class TestSyncProgressUpdate(ComfyNodeABC):
 
     RETURN_TYPES = (IO.ANY,)
     FUNCTION = "execute"
-    CATEGORY = "_for_testing/async"
+    CATEGORY = "experimental/async"
 
     def execute(self, value, sleep_seconds):
         start = time.time()
diff --git a/tests/execution/testing_nodes/testing-pack/async_test_nodes.py b/tests/execution/testing_nodes/testing-pack/async_test_nodes.py
index 547eea6f4..589dabf17 100644
--- a/tests/execution/testing_nodes/testing-pack/async_test_nodes.py
+++ b/tests/execution/testing_nodes/testing-pack/async_test_nodes.py
@@ -21,7 +21,7 @@ class TestAsyncValidation(ComfyNodeABC):
 
     RETURN_TYPES = ("IMAGE",)
     FUNCTION = "process"
-    CATEGORY = "_for_testing/async"
+    CATEGORY = "experimental/async"
 
     @classmethod
     async def VALIDATE_INPUTS(cls, value, threshold):
@@ -53,7 +53,7 @@ class TestAsyncError(ComfyNodeABC):
 
     RETURN_TYPES = (IO.ANY,)
     FUNCTION = "error_execution"
-    CATEGORY = "_for_testing/async"
+    CATEGORY = "experimental/async"
 
     async def error_execution(self, value, error_after):
         await asyncio.sleep(error_after)
@@ -74,7 +74,7 @@ class TestAsyncValidationError(ComfyNodeABC):
 
     RETURN_TYPES = ("IMAGE",)
     FUNCTION = "process"
-    CATEGORY = "_for_testing/async"
+    CATEGORY = "experimental/async"
 
     @classmethod
     async def VALIDATE_INPUTS(cls, value, max_value):
@@ -105,7 +105,7 @@ class TestAsyncTimeout(ComfyNodeABC):
 
     RETURN_TYPES = (IO.ANY,)
     FUNCTION = "timeout_execution"
-    CATEGORY = "_for_testing/async"
+    CATEGORY = "experimental/async"
 
     async def timeout_execution(self, value, timeout, operation_time):
         try:
@@ -129,7 +129,7 @@ class TestSyncError(ComfyNodeABC):
 
     RETURN_TYPES = (IO.ANY,)
     FUNCTION = "sync_error"
-    CATEGORY = "_for_testing/async"
+    CATEGORY = "experimental/async"
 
     def sync_error(self, value):
         raise RuntimeError("Intentional sync execution error for testing")
@@ -150,7 +150,7 @@ class TestAsyncLazyCheck(ComfyNodeABC):
 
     RETURN_TYPES = ("IMAGE",)
     FUNCTION = "process"
-    CATEGORY = "_for_testing/async"
+    CATEGORY = "experimental/async"
 
     async def check_lazy_status(self, condition, input1, input2):
         # Simulate async checking (e.g., querying remote service)
@@ -184,7 +184,7 @@ class TestDynamicAsyncGeneration(ComfyNodeABC):
 
     RETURN_TYPES = ("IMAGE",)
     FUNCTION = "generate_async_workflow"
-    CATEGORY = "_for_testing/async"
+    CATEGORY = "experimental/async"
 
     def generate_async_workflow(self, image1, image2, num_async_nodes, sleep_duration):
         g = GraphBuilder()
@@ -229,7 +229,7 @@ class TestAsyncResourceUser(ComfyNodeABC):
 
     RETURN_TYPES = (IO.ANY,)
     FUNCTION = "use_resource"
-    CATEGORY = "_for_testing/async"
+    CATEGORY = "experimental/async"
 
     async def use_resource(self, value, resource_id, duration):
         # Check if resource is already in use
@@ -265,7 +265,7 @@ class TestAsyncBatchProcessing(ComfyNodeABC):
 
     RETURN_TYPES = ("IMAGE",)
     FUNCTION = "process_batch"
-    CATEGORY = "_for_testing/async"
+    CATEGORY = "experimental/async"
 
     async def process_batch(self, images, process_time_per_item, unique_id):
         batch_size = images.shape[0]
@@ -305,7 +305,7 @@ class TestAsyncConcurrentLimit(ComfyNodeABC):
 
     RETURN_TYPES = (IO.ANY,)
     FUNCTION = "limited_execution"
-    CATEGORY = "_for_testing/async"
+    CATEGORY = "experimental/async"
 
     async def limited_execution(self, value, duration, node_id):
         async with self._semaphore:
diff --git a/tests/execution/testing_nodes/testing-pack/specific_tests.py b/tests/execution/testing_nodes/testing-pack/specific_tests.py
index 4f8f01ae4..2eb5d520e 100644
--- a/tests/execution/testing_nodes/testing-pack/specific_tests.py
+++ b/tests/execution/testing_nodes/testing-pack/specific_tests.py
@@ -409,7 +409,7 @@ class TestSleep(ComfyNodeABC):
     RETURN_TYPES = (IO.ANY,)
     FUNCTION = "sleep"
 
-    CATEGORY = "_for_testing"
+    CATEGORY = "experimental"
 
     async def sleep(self, value, seconds, unique_id):
         pbar = ProgressBar(seconds, node_id=unique_id)
@@ -440,7 +440,7 @@ class TestParallelSleep(ComfyNodeABC):
         }
     RETURN_TYPES = ("IMAGE",)
     FUNCTION = "parallel_sleep"
-    CATEGORY = "_for_testing"
+    CATEGORY = "experimental"
     OUTPUT_NODE = True
 
     def parallel_sleep(self, image1, image2, image3, sleep1, sleep2, sleep3, unique_id):
@@ -474,7 +474,7 @@ class TestOutputNodeWithSocketOutput:
         }
     RETURN_TYPES = ("IMAGE",)
     FUNCTION = "process"
-    CATEGORY = "_for_testing"
+    CATEGORY = "experimental"
     OUTPUT_NODE = True
 
     def process(self, image, value):