Merge remote-tracking branch 'origin/staging' into feat/permission-groups-coverage

Author: waleedlatif1

.agents/skills/add-block-preview/SKILL.md

@@ -41,7 +41,7 @@ A revealed block that is not globally GA (`enabled !== true`, or env-revealed) r
    - GA via config (code cleanup pending): `{ "enabled": true }` — suffix disappears everywhere within ~30s (AppConfig TTL) + client refetch.
 
    Same runbook as `feature-flags`: edit the hosted document, `aws appconfig start-deployment` with the `sim-<env>-fast` strategy (see the infra README).
-5. **GA cleanup:** delete `preview: true` from the block (now visible to self-hosters on their next upgrade), add its `BlockMeta` + regen docs, and drop the AppConfig entry. For a v2 upgrade, this is also when v1 gets `hideFromToolbar: true` (the superseded-version paradigm).
+5. **GA cleanup:** delete `preview: true` from the block (now visible to self-hosters on their next upgrade), add its `BlockMeta` + regen docs, and drop the AppConfig entry. For a v2 upgrade, this is also when v1 gets `hideFromToolbar: true` **and** `sunset: { status: 'legacy', replacedBy: '<v2-type>' }` (the superseded-version paradigm). Both edits must land in the **same commit** as the `preview: true` removal — `check-block-registry` fails a sunset block whose `replacedBy` is still `preview`, so splitting them breaks the build in between. Also move the block's `BLOCK_DISPLAY_WORKFLOWS` entry (`apps/docs/components/workflow-preview/block-display-workflows.ts`) to the new type, or `BlockPreview` silently renders nothing on the docs page.
 
 ## Kill switch (shipped blocks)
 

.agents/skills/add-block/SKILL.md

@@ -695,6 +695,10 @@ export const ServiceBlock: BlockConfig = {
   type: 'service',
   name: 'Service (Legacy)',
   hideFromToolbar: true,  // Hide from toolbar
+  // Required: drives the amber legacy badge and its click-to-upgrade action.
+  // `check-block-registry` fails a legacy block with no `replacedBy`, one whose
+  // target does not exist, or one whose target is itself sunset or still `preview`.
+  sunset: { status: 'legacy', replacedBy: 'service_v2' },
   // ... rest of config
 }
 

.agents/skills/add-integration/SKILL.md

@@ -598,7 +598,15 @@ If creating V2 versions (API-aligned outputs):
 
 1. **V2 Tools** - Add `_v2` suffix, version `2.0.0`, flat outputs
 2. **V2 Block** - Add `_v2` type, use `createVersionedToolSelector`
-3. **V1 Block** - Add `(Legacy)` to name, set `hideFromToolbar: true`
+3. **V1 Block** - Add `(Legacy)` to name, set `hideFromToolbar: true`, and add
+   `sunset: { status: 'legacy', replacedBy: '{service}_v2' }` — `check-block-registry`
+   fails a legacy block with no `replacedBy`, and the amber legacy badge plus its
+   click-to-upgrade action read from that field.
+
+   **Only add `replacedBy` once the target is GA.** The same check also fails when
+   the target is unregistered, itself sunset, or still `preview: true`. If v2 is
+   preview-gated, leave v1 alone until GA and drop `preview` in the *same commit*
+   that adds the sunset — splitting them breaks the build in between.
 4. **Registry** - Register both versions
 
 ```typescript

apps/docs/components/ui/icon-mapping.ts

@@ -546,6 +546,7 @@ export const blockTypeToIconMap: Record<string, IconComponent> = {
   stt_v2: STTIcon,
   supabase: SupabaseIcon,
   table: Table,
+  table_v2: Table,
   tailscale: TailscaleIcon,
   tavily: TavilyIcon,
   telegram: TelegramIcon,

apps/docs/components/workflow-preview/block-display-workflows.ts

@@ -349,14 +349,14 @@ export const BLOCK_DISPLAY_WORKFLOWS: Record<string, PreviewWorkflow> = {
     ],
     edges: [],
   },
-  table: {
-    id: 'table',
+  table_v2: {
+    id: 'table_v2',
     name: 'Table',
     blocks: [
       {
-        id: 'table',
+        id: 'table_v2',
         name: 'Table',
-        type: 'table',
+        type: 'table_v2',
         bgColor: '#10B981',
         position: { x: 0, y: 0 },
         hideTargetHandle: true,

apps/docs/components/workflow-preview/examples.ts

@@ -139,7 +139,7 @@ export const TABLE_ENRICH_WORKFLOW: PreviewWorkflow = {
     {
       id: 'table1',
       name: 'Table 1',
-      type: 'table',
+      type: 'table_v2',
       bgColor: '#10B981',
       position: { x: 0, y: 0 },
       hideTargetHandle: true,
@@ -162,7 +162,7 @@ export const TABLE_ENRICH_WORKFLOW: PreviewWorkflow = {
     {
       id: 'table2',
       name: 'Table 2',
-      type: 'table',
+      type: 'table_v2',
       bgColor: '#10B981',
       position: { x: 660, y: 0 },
       rows: [
@@ -1644,7 +1644,7 @@ export const TABLE_ROUNDTRIP_WORKFLOW: PreviewWorkflow = {
     {
       id: 'query',
       name: 'Table',
-      type: 'table',
+      type: 'table_v2',
       bgColor: '#10B981',
       position: { x: 0, y: 0 },
       hideTargetHandle: true,
@@ -1664,7 +1664,7 @@ export const TABLE_ROUNDTRIP_WORKFLOW: PreviewWorkflow = {
     {
       id: 'update',
       name: 'Table',
-      type: 'table',
+      type: 'table_v2',
       bgColor: '#10B981',
       position: { x: 680, y: 0 },
       rows: [