npm - @superblocksteam/vite-plugin-file-sync - Versions diffs - 2.0.119-next.1 → 2.0.120-next.0 - Mend

@superblocksteam/vite-plugin-file-sync 2.0.119-next.1 → 2.0.120-next.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (345) hide show

package/dist/ai-service/llmobs/tracer.js CHANGED Viewed

@@ -1,7 +1,9 @@
 import { AsyncLocalStorage } from "async_hooks";
+import { context as otelContextApi, trace as otelTrace, } from "@opentelemetry/api";
 import ddTrace from "dd-trace";
 import { safeJsonStringify } from "../../util/log-sanitizer.js";
 import { getErrorMeta, getLogger } from "../../util/logger.js";
+import { otelContextRegistry } from "./context-registry.js";
 /**
  * Lazily initialize dd-trace with LLMObs if not already configured.
  * This is needed when running via turbo (start:all:obs) which bypasses
@@ -251,9 +253,33 @@ export class LLMObsTracer {
             }
         };
         return this.activate(parentContext, () => {
+            // Capture OTEL context BEFORE llmobs.trace() activates the new dd-trace span.
+            // Inside the llmobs.trace callback, dd-trace has already activated the new span
+            // and propagates it into OTEL's AsyncLocalStorage — so otelContextApi.active()
+            // called there returns the newly-created span's context, not the pre-span context.
+            // Capturing here (before the callback) gives us the true ambient OTEL context
+            // at the moment the LLMObs span was requested.
+            //
+            // Only root LLMObs spans (no parentContext) need a captured entry:
+            // processBatch resolves child contexts via perFlushCtx / crossBatch, so child
+            // entries in `captured` would never be consumed and would just leak memory.
+            //
+            // We deliberately strip any active OTEL span from the captured context using
+            // otelTrace.deleteSpan(). Even though we capture before llmobs.trace(), the
+            // dd-trace WebSocket connection span is still bridged into OTEL's
+            // AsyncLocalStorage — so otelContextApi.active() returns a context carrying
+            // the WS span as the active span. If we kept it, that WS span would become
+            // clark.session's OTEL parent, making it appear as a child trace in Datadog
+            // rather than a true root. otelTrace.deleteSpan() returns a new context
+            // with no active span while preserving all other context values (e.g. baggage),
+            // so clark.session starts as a trace root in Datadog as intended.
+            const capturedOtelCtx = LLMObsTracer.isCloudPrem() && !parentContext
+                ? otelTrace.deleteSpan(otelContextApi.active())
+                : undefined;
             if (finish === "auto") {
                 return this.llmobs.trace(rest, (span) => {
                     return this.localStorage.run(new State(), () => {
+                        this.maybeCaptureRootOtelCtx(span, capturedOtelCtx);
                         setup(span, parentContext);
                         return fn(span);
                     });
@@ -261,6 +287,7 @@ export class LLMObsTracer {
             }
             else {
                 return this.llmobs.trace(rest, (span, _done) => {
+                    this.maybeCaptureRootOtelCtx(span, capturedOtelCtx);
                     setup(span, parentContext);
                     return fn(span);
                 });
@@ -282,6 +309,17 @@ export class LLMObsTracer {
         span.__isNoopSpan = true;
         return span;
     }
+    /**
+     * Store the captured OTEL context in the registry if applicable.
+     * Shared between the auto-finish and manual-finish branches of _trace().
+     * Only called for root LLMObs spans (capturedOtelCtx is undefined for children).
+     * Noop spans are excluded — they have no real dd-trace span ID to key on.
+     */
+    maybeCaptureRootOtelCtx(span, capturedOtelCtx) {
+        if (capturedOtelCtx && !isNoopSpan(span)) {
+            otelContextRegistry.captureAtSpanStart(span.context().toSpanId(), capturedOtelCtx);
+        }
+    }
     /** Activate a span as the current parent context for downstream traces. */
     activate(span, fn) {
         if (!this.llmobs.enabled) {

package/dist/ai-service/llmobs/tracer.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"tracer.js","sourceRoot":"","sources":["../../../src/ai-service/llmobs/tracer.ts"],"names":[],"mappings":"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"}
1	+ {"version":3,"file":"tracer.js","sourceRoot":"","sources":["../../../src/ai-service/llmobs/tracer.ts"],"names":[],"mappings":"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"}

package/dist/ai-service/skills/system/_registry.generated.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"_registry.generated.d.ts","sourceRoot":"","sources":["../../../../src/ai-service/skills/system/_registry.generated.ts"],"names":[],"mappings":"~~AAkBA~~;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,~~CAehD~~,CAAC"}
1	+ {"version":3,"file":"_registry.generated.d.ts","sourceRoot":"","sources":["../../../../src/ai-service/skills/system/_registry.generated.ts"],"names":[],"mappings":"AAmBA;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAgBhD,CAAC"}

package/dist/ai-service/skills/system/_registry.generated.js CHANGED Viewed

@@ -10,6 +10,7 @@ import { content as superblocks_frontend_skill } from "./superblocks-frontend/sk
 import { content as superblocks_migration_references_focused_debug } from "./superblocks-migration/references/focused-debug.generated.js";
 import { content as superblocks_migration_references_yaml_block_mapping } from "./superblocks-migration/references/yaml-block-mapping.generated.js";
 import { content as superblocks_migration_skill } from "./superblocks-migration/skill.generated.js";
+import { content as third_party_migration_claude_design } from "./third-party-migration/claude-design.generated.js";
 import { content as third_party_migration_lovable } from "./third-party-migration/lovable.generated.js";
 import { content as third_party_migration_replit } from "./third-party-migration/replit.generated.js";
 import { content as third_party_migration_skill } from "./third-party-migration/skill.generated.js";
@@ -30,6 +31,7 @@ export const SYSTEM_SKILLS = {
     "superblocks-migration/references/focused-debug.md": superblocks_migration_references_focused_debug,
     "superblocks-migration/references/yaml-block-mapping.md": superblocks_migration_references_yaml_block_mapping,
     "third-party-migration/SKILL.md": third_party_migration_skill,
+    "third-party-migration/claude-design.md": third_party_migration_claude_design,
     "third-party-migration/lovable.md": third_party_migration_lovable,
     "third-party-migration/replit.md": third_party_migration_replit,
     "third-party-migration/v0.md": third_party_migration_v0,

package/dist/ai-service/skills/system/_registry.generated.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"_registry.generated.js","sourceRoot":"","sources":["../../../../src/ai-service/skills/system/_registry.generated.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,qDAAqD;AAErD,OAAO,EAAE,OAAO,IAAI,sCAAsC,EAAE,MAAM,uDAAuD,CAAC;AAC1H,OAAO,EAAE,OAAO,IAAI,kCAAkC,EAAE,MAAM,mDAAmD,CAAC;AAClH,OAAO,EAAE,OAAO,IAAI,oCAAoC,EAAE,MAAM,qDAAqD,CAAC;AACtH,OAAO,EAAE,OAAO,IAAI,wCAAwC,EAAE,MAAM,yDAAyD,CAAC;AAC9H,OAAO,EAAE,OAAO,IAAI,qBAAqB,EAAE,MAAM,sCAAsC,CAAC;AACxF,OAAO,EAAE,OAAO,IAAI,yCAAyC,EAAE,MAAM,0DAA0D,CAAC;AAChI,OAAO,EAAE,OAAO,IAAI,0BAA0B,EAAE,MAAM,2CAA2C,CAAC;AAClG,OAAO,EAAE,OAAO,IAAI,8CAA8C,EAAE,MAAM,+DAA+D,CAAC;AAC1I,OAAO,EAAE,OAAO,IAAI,mDAAmD,EAAE,MAAM,oEAAoE,CAAC;AACpJ,OAAO,EAAE,OAAO,IAAI,2BAA2B,EAAE,MAAM,4CAA4C,CAAC;AACpG,OAAO,EAAE,OAAO,IAAI,6BAA6B,EAAE,MAAM,8CAA8C,CAAC;AACxG,OAAO,EAAE,OAAO,IAAI,4BAA4B,EAAE,MAAM,6CAA6C,CAAC;AACtG,OAAO,EAAE,OAAO,IAAI,2BAA2B,EAAE,MAAM,4CAA4C,CAAC;AACpG,OAAO,EAAE,OAAO,IAAI,wBAAwB,EAAE,MAAM,yCAAyC,CAAC;AAE9F;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAA2B;IACnD,0BAA0B,EAAE,qBAAqB;IACjD,2CAA2C,EAAE,sCAAsC;IACnF,uCAAuC,EAAE,kCAAkC;IAC3E,yCAAyC,EAAE,oCAAoC;IAC/E,6CAA6C,EAAE,wCAAwC;IACvF,+BAA+B,EAAE,0BAA0B;IAC3D,8CAA8C,EAAE,yCAAyC;IACzF,gCAAgC,EAAE,2BAA2B;IAC7D,mDAAmD,EAAE,8CAA8C;IACnG,wDAAwD,EAAE,mDAAmD;IAC7G,gCAAgC,EAAE,2BAA2B;IAC7D,kCAAkC,EAAE,6BAA6B;IACjE,iCAAiC,EAAE,4BAA4B;IAC/D,6BAA6B,EAAE,wBAAwB;CACxD,CAAC"}
1	+ {"version":3,"file":"_registry.generated.js","sourceRoot":"","sources":["../../../../src/ai-service/skills/system/_registry.generated.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,qDAAqD;AAErD,OAAO,EAAE,OAAO,IAAI,sCAAsC,EAAE,MAAM,uDAAuD,CAAC;AAC1H,OAAO,EAAE,OAAO,IAAI,kCAAkC,EAAE,MAAM,mDAAmD,CAAC;AAClH,OAAO,EAAE,OAAO,IAAI,oCAAoC,EAAE,MAAM,qDAAqD,CAAC;AACtH,OAAO,EAAE,OAAO,IAAI,wCAAwC,EAAE,MAAM,yDAAyD,CAAC;AAC9H,OAAO,EAAE,OAAO,IAAI,qBAAqB,EAAE,MAAM,sCAAsC,CAAC;AACxF,OAAO,EAAE,OAAO,IAAI,yCAAyC,EAAE,MAAM,0DAA0D,CAAC;AAChI,OAAO,EAAE,OAAO,IAAI,0BAA0B,EAAE,MAAM,2CAA2C,CAAC;AAClG,OAAO,EAAE,OAAO,IAAI,8CAA8C,EAAE,MAAM,+DAA+D,CAAC;AAC1I,OAAO,EAAE,OAAO,IAAI,mDAAmD,EAAE,MAAM,oEAAoE,CAAC;AACpJ,OAAO,EAAE,OAAO,IAAI,2BAA2B,EAAE,MAAM,4CAA4C,CAAC;AACpG,OAAO,EAAE,OAAO,IAAI,mCAAmC,EAAE,MAAM,oDAAoD,CAAC;AACpH,OAAO,EAAE,OAAO,IAAI,6BAA6B,EAAE,MAAM,8CAA8C,CAAC;AACxG,OAAO,EAAE,OAAO,IAAI,4BAA4B,EAAE,MAAM,6CAA6C,CAAC;AACtG,OAAO,EAAE,OAAO,IAAI,2BAA2B,EAAE,MAAM,4CAA4C,CAAC;AACpG,OAAO,EAAE,OAAO,IAAI,wBAAwB,EAAE,MAAM,yCAAyC,CAAC;AAE9F;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAA2B;IACnD,0BAA0B,EAAE,qBAAqB;IACjD,2CAA2C,EAAE,sCAAsC;IACnF,uCAAuC,EAAE,kCAAkC;IAC3E,yCAAyC,EAAE,oCAAoC;IAC/E,6CAA6C,EAAE,wCAAwC;IACvF,+BAA+B,EAAE,0BAA0B;IAC3D,8CAA8C,EAAE,yCAAyC;IACzF,gCAAgC,EAAE,2BAA2B;IAC7D,mDAAmD,EAAE,8CAA8C;IACnG,wDAAwD,EAAE,mDAAmD;IAC7G,gCAAgC,EAAE,2BAA2B;IAC7D,wCAAwC,EAAE,mCAAmC;IAC7E,kCAAkC,EAAE,6BAA6B;IACjE,iCAAiC,EAAE,4BAA4B;IAC/D,6BAA6B,EAAE,wBAAwB;CACxD,CAAC"}

package/dist/ai-service/skills/system/superblocks-frontend/skill.generated.d.ts CHANGED Viewed

@@ -1,2 +1,2 @@
-export declare const content = "---\nname: superblocks-frontend\ndescription: |\n  Build frontend UI using React, Tailwind CSS, and Superblocks components. Essential for connecting Superblocks UIs with APIs.\n  Use when creating pages, components, handling user interactions, or working with the design system.\nreadOnly: true\nmetadata:\n  author: superblocks\n  version: \"1.0\"\n---\n\n# Superblocks Frontend Development\n\nThis skill covers building frontend UI for Superblocks applications using React, Tailwind CSS v4, and the Superblocks component library.\n\n## Platform Overview\n\nThis is a React-based web application platform. Use standard React patterns:\n\n- `useState`, `useEffect`, `useCallback`, `useMemo`\n- Event handlers and controlled components\n- JSX with Tailwind CSS classes\n\n## Using APIs from Frontend\n\nThree primitives are available from `@superblocksteam/library`:\n\n- **`useApiData`** \u2014 declarative reads with SWR caching (preferred for data loading)\n- **`useApi`** \u2014 imperative mutations (for event-driven actions)\n- **`executeApi`** \u2014 plain Promise outside React (utility functions, event handlers without hooks)\n\n**Data loading** \u2014 auto-fetches on mount and when inputs change (preferred for reads):\n\n```typescript\nimport { useApiData } from \"@superblocksteam/library\";\n\n// Auto-fetches when email or name changes. No useEffect or HMR guards needed.\n// IMPORTANT: Always use `fetching` to show a loading indicator during refetches.\nconst { data, loading, fetching, isError, error } = useApiData(\"GetUsers\", {\n  email,\n  name,\n});\n```\n\n**Mutations** \u2014 call `run()` manually (for event-driven actions like form submissions):\n\n```typescript\nimport { useApi } from \"@superblocksteam/library\";\nimport { toast } from \"sonner\";\n\nconst { run: createOrder, loading } = useApi(\"CreateOrder\");\n\nconst handleSubmit = useCallback(async () => {\n  try {\n    await createOrder({ item, qty });\n  } catch (error) {\n    const message =\n      error && typeof error === \"object\" && \"message\" in error\n        ? String((error as { message: unknown }).message)\n        : String(error);\n    toast.error(\"Error creating order: \" + message);\n  }\n}, [item, qty, createOrder]);\n```\n\n**Outside React** \u2014 call APIs as a plain Promise (utility functions, event handlers):\n\n```typescript\nimport { executeApi } from \"@superblocksteam/library\";\n\nconst result = await executeApi(\"GetUsers\", { email });\n```\n\n`useApiData` returns `{ data, loading, fetching, isError, isSuccess, isStale, error, status, fetchStatus, refetch, cancel }`. `data` persists across background refetches (stale-while-revalidate). `loading` is true on first fetch with no cached data. `fetching` is true during any fetch including background refetch. `status` is `\"pending\"` | `\"success\"` | `\"error\"`. `fetchStatus` is `\"idle\"` | `\"fetching\"`. `cancel()` is synchronous (returns `void`).\n\n`useApi` returns `{ run, cancel, reset, loading, data, error, status, variables }`. `data` persists across re-runs (shows previous result while loading). `error` holds the most recent failure, or `undefined` on success. `status` is `\"idle\"` | `\"pending\"` | `\"success\"` | `\"error\"`. `variables` holds the inputs from the most recent `run()`. `reset()` clears all state back to idle. HMR double-fetch prevention is built in \u2014 no `useRef` guard needed.\n\n### useApiData Options\n\n```typescript\nconst { data } = useApiData(\"GetUsers\", { email }, {\n  enabled: true,           // Skip fetching when false (conditional fetching)\n  staleTime: 0,            // Ms before cached data is considered stale (0 = always refetch)\n  retry: 3,                // Retry attempts on failure (false to disable)\n  retryDelay: (n) => ...,  // Custom delay strategy (default: exponential backoff, max 30s)\n  refetchOnWindowFocus: false, // Refetch when tab regains focus\n  refetchOnReconnect: true,    // Refetch when network reconnects\n  refetchInterval: false,      // Polling interval in ms (false = disabled)\n  structuralSharing: false,    // Deep-compare to preserve object identity\n  placeholderData: undefined,  // Shown while the first fetch is in progress\n});\n```\n\n### Cache invalidation and optimistic updates\n\n**Same scope as the read**: After a mutation, prefer `refetch()` from the `useApiData` that loads the data (same component or wherever you can pass `refetch`).\n\n```typescript\nimport { useApi, useApiData } from \"@superblocksteam/library\";\nimport { toast } from \"sonner\";\n\nconst { data: orders, refetch } = useApiData(\"GetOrders\", { status });\nconst { run: createOrder } = useApi(\"CreateOrder\");\n\nconst handleSubmit = useCallback(async () => {\n  try {\n    await createOrder({ item, qty });\n    await refetch();\n  } catch (error) {\n    const message =\n      error && typeof error === \"object\" && \"message\" in error\n        ? String((error as { message: unknown }).message)\n        : String(error);\n    toast.error(\"Error creating order: \" + message);\n  }\n}, [item, qty, createOrder, refetch]);\n```\n\n**Cross-scope or broad invalidation**: Use `queryClient.invalidateQueries` when you cannot call that `refetch` (mutation in a different place than the `useApiData`, or you need every cached variant of an API to refetch). For **`queryClient.invalidateQueries`, `buildCacheKey`, `setQueryData`, and any other `queryClient` usage, always import `queryClient` from `@superblocksteam/library`**.\n\n```typescript\nimport { queryClient, useApi } from \"@superblocksteam/library\";\nimport { toast } from \"sonner\";\n\nconst { run: createOrder } = useApi(\"CreateOrder\");\n\nconst handleSubmit = useCallback(async () => {\n  try {\n    await createOrder({ item, qty });\n    await queryClient.invalidateQueries(\"GetOrders\");\n  } catch (error) {\n    const message =\n      error && typeof error === \"object\" && \"message\" in error\n        ? String((error as { message: unknown }).message)\n        : String(error);\n    toast.error(\"Error creating order: \" + message);\n  }\n}, [item, qty, createOrder]);\n```\n\n```typescript\n// Optimistic update: set cached data without refetching\nimport { queryClient } from \"@superblocksteam/library\";\n\nconst cacheKey = queryClient.buildCacheKey(\"GetOrders\", { status: \"active\" });\nqueryClient.setQueryData(cacheKey, (old) => ({\n  ...old,\n  orders: [...old.orders, newOrder],\n}));\n```\n\n### Critical API Rules\n\n1. **MUST call API by exact name**: Format is `<ApiName>` matching folder `apis/<ApiName>/api.yaml`\n2. **Use `useApiData` for data loading, `useApi` for mutations**: For data fetching, use `useApiData(\"GetUsers\", { email })`. Only use `useApi` for event-driven actions (button clicks, form submissions). Use `executeApi` for API calls outside React components.\n3. **Use the hook's state fields**: Do NOT create separate `useState` for loading or response data \u2014 the hooks manage this for you\n4. **ALWAYS check API interfaces**: NEVER guess the response structure\n5. **Include all parameters**: Even optional ones should be passed as `null`\n6. **ALWAYS use try/catch**: In imperative mode, APIs throw errors when they fail - wrap ALL `run()` calls in try/catch blocks. In declarative mode, check the `error` field for failure details.\n\n### File Handling\n\n**CRITICAL: Files must be wrapped in `{ files: [...] }` format:**\n\n```tsx\n// \u2705 CORRECT - Frontend: wrap files in { files: [...] }\nconst response = await runUploadApi({ userFile: { files: selectedFiles } });\n\n// \u274C WRONG - backend cannot process unwrapped files\nconst response = await runUploadApi({ userFile: selectedFiles });\n```\n\n## Platform Hooks and Functions\n\nAvailable hooks and functions from `@superblocksteam/library`:\n\n### User and Group Context\n\n```typescript\nimport {\n  useSuperblocksUser,\n  useSuperblocksGroups,\n} from \"@superblocksteam/library\";\n\n// Get current user info\nconst user = useSuperblocksUser();\n// user.name, user.email, user.id, user.groups, user.username, user.metadata\n\n// Get organization groups\nconst groups = useSuperblocksGroups();\n```\n\n### Environments and Data Tags\n\nConcepts & terminology:\n\n- `Data tags` are labels for different data segments, such as `Staging`, `Production`, or `us-east`.\n- `Profiles` is the legacy term for the same concept. If a user asks about profiles, treat that as data tags.\n- `Environments` are `Edit`, `Preview`, and `Production`, and each data tag is allowed in one or more of those environments.\n- Clark operates in `Edit` mode, so the data tags visible in app context represent the tags available in `Edit`; do not assume this is the same set that will be available in `Preview` or `Production`.\n- When implementing app code, prefer `useSuperblocksDataTags()`, `dataTags`, and `setDataTag()`.\n\nThe `DataTag` type has these fields (it is an alias for `Profile` from `@superblocksteam/shared`):\n\n```typescript\ntype DataTag = {\n  id: string;\n  key: string;\n  displayName: string; // human-readable label \u2014 use this for display, NOT \"name\"\n  description: string;\n  type: \"RESERVED\" | \"CUSTOM\";\n};\n```\n\nRelevant hooks and functions:\n\n```typescript\nimport { useSuperblocksDataTags, getAppMode } from \"@superblocksteam/library\";\nimport type { DataTag, DataTags } from \"@superblocksteam/library\";\n\n// Manage data tags\nconst { dataTags, setDataTag } = useSuperblocksDataTags();\n// dataTags.available: DataTag[]   \u2014 all tags in the current environment\n// dataTags.selected:  DataTag | undefined \u2014 currently active tag (may be undefined)\n// dataTags.default:   DataTag     \u2014 the default tag\n// setDataTag(dataTag.key)         \u2014 switch the active tag by key\n\n// Read the current app mode when reasoning about environment-specific behavior\nconst appMode = getAppMode();\n```\n\nExample \u2014 data tag switcher using a Select:\n\n```tsx\nconst { dataTags, setDataTag } = useSuperblocksDataTags();\n\n<Select value={dataTags?.selected?.key} onValueChange={setDataTag}>\n  {dataTags?.available.map((tag) => (\n    <SelectItem key={tag.key} value={tag.key}>\n      {tag.displayName}\n    </SelectItem>\n  ))}\n</Select>;\n```\n\n### Embedded Applications\n\n**For embedded applications**, see the `references/embedding.md` file for `useEmbedProperties`, `useEmbedEvent`, and `useEmitEmbedEvent` hooks.\n\n## Logging Out of Integrations\n\nWhen building a \"Log out\" or \"Sign out\" button for apps that use OAuth-like integrations, use `logoutIntegrations` from the library to clear OAuth tokens:\n\n```typescript\nimport { logoutIntegrations } from \"@superblocksteam/library\";\n\nconst handleLogout = async () => {\n  await logoutIntegrations();\n  // Optionally redirect or show confirmation\n};\n```\n\n## Application Architecture\n\n### App.tsx Layout Structure\n\n**For single-page applications:**\n\n- Put all content in `pages/<pageName>/index.tsx`\n- Use components to compose and build the page\n- Keep `App.tsx` minimal with just `<AppProvider>` and `<Outlet />`\n\n**For multi-page applications:**\n\n- Put shared navigation/layout in `App.tsx` (sidebars, headers, footers)\n- Always include `<Outlet />` for page content\n- Always include `<AppProvider />` wrapper\n- Individual pages focus on content, not layout\n\n```tsx\n// \u2705 CORRECT - Multi-page App.tsx layout\n<AppProvider>\n  <div className=\"flex flex-row size-screen\">\n    {/* Sidebar - persistent across all pages */}\n    <div className=\"flex bg-sidebar border-r w-[250px]\">\n      <Navigation />\n    </div>\n\n    {/* Main content area */}\n    <div className=\"flex flex-1 h-full flex-col\">\n      {/* Header - persistent across all pages */}\n      <div className=\"flex bg-header border-b h-[60px]\">\n        <Header />\n      </div>\n\n      {/* Page content area */}\n      <div className=\"flex p-4 flex-1 overflow-auto\">\n        <Outlet />\n      </div>\n    </div>\n  </div>\n</AppProvider>\n```\n\n**PROTECTED: NEVER remove `<AppProvider>` or `<Outlet />` from App.tsx!**\n\n### Page Structure\n\n```tsx\n// \u2705 CORRECT - Page focuses on content only\n<div className=\"flex flex-col gap-4 size-screen overflow-auto\">\n  <h1 className=\"text-3xl font-bold\">Dashboard Content</h1>\n  <Card>{/* Page-specific content */}</Card>\n</div>\n```\n\n**IMPORTANT**: The first div on the page must have `overflow-auto` so the user's page can scroll.\n\n## Routing\n\nUse `react-router@7` in data mode. Standard patterns apply:\n\n- `useNavigate()` for programmatic navigation\n- `useParams()` for route parameters\n- `useSearchParams()` for query strings\n\n**If you add new pages or rename files, you MUST update the router.**\n\n## Design System (Tailwind CSS v4)\n\n**All design tokens are defined in `index.css`**. Apps come with a professional black-and-white theme by default.\n\n### Semantic Tokens Rule\n\n**ALWAYS use semantic tokens** \u2014 NEVER raw Tailwind utilities:\n\n```tsx\n// \u2705 CORRECT\n<Card className=\"bg-background text-foreground border border-border\" />\n\n// \u274C WRONG\n<Card className=\"bg-white text-black border-gray-200\" />\n```\n\n### When to Modify index.css\n\nOnly modify when:\n\n- User explicitly requests branding/theme changes\n- Replicating a specific brand look (e.g., Yelp, Instacart)\n- Migrating an attached third-party app \u2014 see `skills/system/third-party-migration/SKILL.md` (its theme-port rules override the Modification Rules below \u2014 copy source tokens as-is, do not convert to OKLCH or trim the palette)\n- Feature requests (lists, filters, CRUD) do NOT require changes\n\n**Modification Rules:**\n\n- All colors must be in OKLCH format\n- Use semantic names (`--color-warning`, `--shadow-elevated`)\n- Do not remove or rename existing tokens\n- Limit color palette to 5 colors max\n- Avoid gradients unless explicitly requested\n- Minimal font sizes (3 max: body, section heading, main heading)\n\n### Component Variants\n\nUse or create variants instead of one-off styles:\n\n```tsx\n// \u274C WRONG - Hacky inline overrides\n<Button className=\"text-white border-white hover:bg-white\" />\n\n// \u2705 CORRECT - Use a variant\n<Button variant=\"secondary\" />\n```\n\n## Icons\n\nUse icons from Lucide React library:\n\n```tsx\nimport { Icon } from \"@/components/ui/icon\";\n<Icon icon=\"heart\" />;\n\nimport { Button } from \"@/components/ui/button\";\n<Button>\n  <Icon icon=\"plus\" /> Add Item\n</Button>;\n```\n\n**Always use icons rather than emojis unless explicitly requested.**\n\n## Custom Components\n\n**CRITICAL: Component composition is MANDATORY. DO NOT create monolithic pages.**\n\n### The Composition Rule\n\nWhen building ANY feature:\n\n1. **First**, identify reusable parts (list items, cards, forms, filters, headers)\n2. **Then**, create separate component files\n3. **Finally**, compose them together in the page\n\n### When to Create Components\n\n- **Rendering any list** - Extract to a component\n- **Building cards/complex UI** - Each card type is a component\n- **Creating forms** - Form sections are components\n- **Adding filters/headers** - These are components\n- **Page has >50 lines JSX** - Break it down\n\n### Component Boundary Rules\n\n**Inside a custom component:**\n\n- \u2705 Use React hooks (useState, useReducer, useEffect, etc.)\n- \u2705 Use local React state\n- \u2705 Use internal helper components\n- \u2705 Use other registered components\n- \u274C CANNOT call APIs - must pass data into the component\n\n### Example: Proper Component Structure\n\n```tsx\n// components/ProductCard/index.tsx - Extract to component\nimport { Card } from \"@/components/ui/card\";\nimport { Button } from \"@/components/ui/button\";\n\ntype ProductCardProps = {\n  product: {\n    id: string;\n    name: string;\n    image: string;\n  };\n};\n\nexport default function ProductCard(props: ProductCardProps) {\n  return (\n    <Card>\n      <img src={props.product.image} />\n      <h3 className=\"text-lg font-semibold\">{props.product.name}</h3>\n      <Button>Add</Button>\n    </Card>\n  );\n}\n\n// pages/Products/index.tsx - Clean composition\nimport ProductCard from \"@/components/ProductCard\";\n\nconst ProductsPage = () => {\n  const [products, setProducts] = useState([]);\n\n  return (\n    <div className=\"grid grid-cols-3 gap-4\">\n      {products.map((p) => (\n        <ProductCard key={p.id} product={p} />\n      ))}\n    </div>\n  );\n};\n```\n\n## Visual Excellence\n\n**Prioritize visual excellence from the start:**\n\n1. **Design System Enhancement**: Start by enhancing `index.css` with app-specific colors that match the target aesthetic\n2. **Professional Layout Architecture**: Use sophisticated layouts with proper spacing, responsive design\n3. **Rich Interactive Components**: Leverage advanced components with proper variants and states\n4. **Visual Polish**: Add shadows, smooth transitions, skeleton loaders, hover effects, typography hierarchy\n5. **Real-World UI Patterns**: Create layouts that feel like professional applications\n\n**Make applications that look and feel like real, polished products - not basic wireframes.**\n\n### Loading States\n\nLoading behavior must differ based on whether data has already been fetched:\n\n**Initial load (no data yet):** Show skeleton shimmers that mirror the shape of the final content. Never show a blank screen or a generic spinner.\n\n**Refetch / background refresh (data already exists):** Keep showing the existing data. Use `fetching` from `useApiData` to apply a subtle visual indicator: light opacity (e.g. `opacity-70`) to signal a refresh is in progress, plus a non-blocking label such as a small inline spinner, a thin progress bar, or an \"Updating\u2026\" label. **Do not** use `pointer-events-none` or otherwise disable the content \u2014 it must remain fully interactive during refetch.\n\nUse `loading` and `fetching` from `useApiData` to distinguish these states:\n\n```tsx\nconst { data, loading, fetching, isError, error } = useApiData(\"GetOrders\", {\n  status: statusFilter,\n  search,\n});\n\n// Initial load \u2014 no data yet \u2192 show skeleton placeholder\nif (loading) {\n  return <OrderTableSkeleton />;\n}\n\nif (isError) return <ErrorBanner error={error} />;\n\n// Refetch \u2014 data exists \u2192 subtle opacity + indicator, table stays interactive\nreturn (\n  <div>\n    {fetching && <div className=\"text-xs text-muted-foreground\">Updating\u2026</div>}\n    <div className={fetching ? \"opacity-70\" : \"\"}>\n      <OrderTable orders={data.orders} />\n    </div>\n  </div>\n);\n```\n\n```tsx\n// \u274C WRONG \u2014 pointer-events-none disables the table, making it feel broken\nreturn (\n  <div className={fetching ? \"pointer-events-none\" : \"\"}>\n    <OrderTable orders={data.orders} />\n  </div>\n);\n\n// \u274C WRONG \u2014 no loading feedback when filters change\nif (loading) return <Skeleton />;\nreturn <OrderTable orders={data.orders} />;\n```\n\n#### Table Loading Rules\n\n- **Do not** use `pointer-events-none` on a table during loading \u2014 this disables interaction and makes the UI feel broken. During refetch, apply a subtle opacity (e.g. `opacity-70`) plus a non-blocking indicator (e.g., an \"Updating\u2026\" label or a thin progress bar). The table must remain clickable, sortable, and scrollable.\n- **Do not** replace a populated table with a full skeleton on refetch \u2014 this causes disorienting content flashes.\n- **Skeleton tables are only for initial load** (`loading` is true) when there is no data to display yet. Build them to match the real table's column structure (header + a few placeholder rows).\n\n### Efficient Loading Patterns\n\n1. **Always show loading indicators on refetch**: When inputs change (e.g. filters, search), show a non-blocking visual indicator while new data loads. Use `fetching` from `useApiData`.\n2. **Loading State Hierarchy**:\n   - No data yet (`loading`) \u2192 Full skeleton placeholder\n   - Has data, refetching (`fetching` && !`loading`) \u2192 Keep showing current data with a subtle visual indicator: light opacity (e.g. `opacity-70`) plus a non-blocking label (e.g. \"Updating\u2026\" text, thin progress bar, inline spinner). Do not use `pointer-events-none` \u2014 the content must remain fully interactive.\n   - Error state (`isError`) \u2192 Show error with retry option, optionally keep stale data visible\n3. **Debounce Rapid Requests**: Prevent multiple API calls in short succession\n4. **Use useApiData for automatic refetching**: `useApiData` auto-refetches when inputs change and supports `staleTime`, `refetchOnWindowFocus`, `refetchOnReconnect`, `refetchInterval`, and `retry` options.\n\n## Performance Rules\n\n### 1. ALWAYS Paginate Tables and Lists\n\n**NEVER render more than 50 rows without pagination.** Always add client-side pagination:\n\n```tsx\nfunction PaginatedTable({ data }: { data: any[] }) {\n  const PAGE_SIZE = 20;\n  const [page, setPage] = useState(0);\n  const totalPages = Math.ceil(data.length / PAGE_SIZE);\n  const pageData = useMemo(\n    () => data.slice(page * PAGE_SIZE, (page + 1) * PAGE_SIZE),\n    [data, page],\n  );\n\n  useEffect(() => {\n    setPage(0);\n  }, [data.length]);\n\n  return (\n    <>\n      <Table>{/* render pageData rows */}</Table>\n      <span>\n        Page {page + 1} of {totalPages} ({data.length} total rows)\n      </span>\n      <Button\n        onClick={() => setPage((p) => Math.max(0, p - 1))}\n        disabled={page === 0}\n      >\n        Previous\n      </Button>\n      <Button\n        onClick={() => setPage((p) => Math.min(totalPages - 1, p + 1))}\n        disabled={page >= totalPages - 1}\n      >\n        Next\n      </Button>\n    </>\n  );\n}\n```\n\nFor 200+ rows, prefer **server-side pagination**; use cursor/keyset pagination for high offsets instead of `LIMIT`/`OFFSET`.\n\nFor 500+ item lists where pagination doesn't fit the UX (chat messages, infinite scroll feeds, large dropdowns), use **virtualization** (`react-virtuoso` or `@tanstack/react-virtual`) to render only the items visible in the viewport.\n\n### 2. ALWAYS Debounce Input-Driven API Calls\n\n**NEVER call an API directly from onChange.** Debounce search/filter inputs with a 300ms timer:\n\n```tsx\nfunction DebouncedSearch({ onSearch }: { onSearch: (query: string) => void }) {\n  const [localValue, setLocalValue] = useState(\"\");\n  const timerRef = useRef<ReturnType<typeof setTimeout>>();\n  const handleChange = useCallback(\n    (e: React.ChangeEvent<HTMLInputElement>) => {\n      setLocalValue(e.target.value);\n      clearTimeout(timerRef.current);\n      timerRef.current = setTimeout(() => onSearch(e.target.value), 300);\n    },\n    [onSearch],\n  );\n  useEffect(() => () => clearTimeout(timerRef.current), []);\n\n  return (\n    <Input value={localValue} onChange={handleChange} placeholder=\"Search...\" />\n  );\n}\n```\n\n### 3. Memoize Expensive Renders\n\nUse memoization (`memo()`, `useMemo`, `useCallback`) when it prevents measurable re-renders or expensive recomputation:\n\n```tsx\nconst OrderRow = memo(function OrderRow({\n  order,\n  onSelect,\n}: {\n  order: Order;\n  onSelect: (id: string) => void;\n}) {\n  return (\n    <TableRow onClick={() => onSelect(order.id)}>\n      <TableCell>{order.id}</TableCell>...\n    </TableRow>\n  );\n});\n\nconst handleSelect = useCallback((id: string) => {\n  setSelectedId(id);\n}, []);\n\nconst filtered = useMemo(\n  () =>\n    orders.filter((o) => o.status === status).sort((a, b) => b.total - a.total),\n  [orders, status],\n);\n```\n\n### 4. ALWAYS Clean Up Side Effects\n\nClean up timers, event listeners, and subscriptions in `useEffect` return functions:\n\n```tsx\nuseEffect(() => {\n  const handler = (e: KeyboardEvent) => {\n    /* ... */\n  };\n  window.addEventListener(\"keydown\", handler);\n  return () => window.removeEventListener(\"keydown\", handler);\n}, []);\n```\n\n### 5. Cancel In-Flight API Requests on Unmount\n\nFor search/filter patterns, prefer `useApiData` \u2014 it handles cancellation and cleanup automatically:\n\n```tsx\n// useApiData: auto-fetches and cancels on unmount/input change\nconst { data, fetching } = useApiData(\"SearchProducts\", { query });\n```\n\nFor imperative usage with manual cleanup, use the `cancel()` function:\n\n```tsx\nconst { run, cancel } = useApi(\"SearchProducts\");\n\nuseEffect(() => {\n  if (!query) return;\n  run({ query }).catch(console.error);\n  return () => {\n    cancel().catch(() => {});\n  };\n}, [query, run, cancel]);\n```\n";
+export declare const content = "---\nname: superblocks-frontend\ndescription: |\n  Build frontend UI using React, Tailwind CSS, and Superblocks components. Essential for connecting Superblocks UIs with APIs.\n  Use when creating pages, components, handling user interactions, or working with the design system.\nreadOnly: true\nmetadata:\n  author: superblocks\n  version: \"1.0\"\n---\n\n# Superblocks Frontend Development\n\nThis skill covers building frontend UI for Superblocks applications using React, Tailwind CSS v4, and the Superblocks component library.\n\n## Platform Overview\n\nThis is a React-based web application platform. Use standard React patterns:\n\n- `useState`, `useEffect`, `useCallback`, `useMemo`\n- Event handlers and controlled components\n- JSX with Tailwind CSS classes\n\n## Using APIs from Frontend\n\nThree primitives are available from `@superblocksteam/library`:\n\n- **`useApiData`** \u2014 declarative reads with SWR caching (preferred for data loading)\n- **`useApi`** \u2014 imperative mutations (for event-driven actions)\n- **`executeApi`** \u2014 plain Promise outside React (utility functions, event handlers without hooks)\n\n**Data loading** \u2014 auto-fetches on mount and when inputs change (preferred for reads):\n\n```typescript\nimport { useApiData } from \"@superblocksteam/library\";\n\n// Auto-fetches when email or name changes. No useEffect or HMR guards needed.\n// IMPORTANT: Always use `fetching` to show a loading indicator during refetches.\nconst { data, loading, fetching, isError, error } = useApiData(\"GetUsers\", {\n  email,\n  name,\n});\n```\n\n**Mutations** \u2014 call `run()` manually (for event-driven actions like form submissions):\n\n```typescript\nimport { useApi } from \"@superblocksteam/library\";\nimport { toast } from \"sonner\";\n\nconst { run: createOrder, loading } = useApi(\"CreateOrder\");\n\nconst handleSubmit = useCallback(async () => {\n  try {\n    await createOrder({ item, qty });\n  } catch (error) {\n    const message =\n      error && typeof error === \"object\" && \"message\" in error\n        ? String((error as { message: unknown }).message)\n        : String(error);\n    toast.error(\"Error creating order: \" + message);\n  }\n}, [item, qty, createOrder]);\n```\n\n**Outside React** \u2014 call APIs as a plain Promise (utility functions, event handlers):\n\n```typescript\nimport { executeApi } from \"@superblocksteam/library\";\n\nconst result = await executeApi(\"GetUsers\", { email });\n```\n\n`useApiData` returns `{ data, loading, fetching, isError, isSuccess, isStale, error, status, fetchStatus, refetch, cancel }`. `data` persists across background refetches (stale-while-revalidate). `loading` is true on first fetch with no cached data. `fetching` is true during any fetch including background refetch. `status` is `\"pending\"` | `\"success\"` | `\"error\"`. `fetchStatus` is `\"idle\"` | `\"fetching\"`. `cancel()` is synchronous (returns `void`).\n\n`useApi` returns `{ run, cancel, reset, loading, data, error, status, variables }`. `data` persists across re-runs (shows previous result while loading). `error` holds the most recent failure, or `undefined` on success. `status` is `\"idle\"` | `\"pending\"` | `\"success\"` | `\"error\"`. `variables` holds the inputs from the most recent `run()`. `reset()` clears all state back to idle. HMR double-fetch prevention is built in \u2014 no `useRef` guard needed.\n\n### useApiData Options\n\n```typescript\nconst { data } = useApiData(\"GetUsers\", { email }, {\n  enabled: true,           // Skip fetching when false (conditional fetching)\n  staleTime: 0,            // Ms before cached data is considered stale (0 = always refetch)\n  retry: 3,                // Retry attempts on failure (false to disable)\n  retryDelay: (n) => ...,  // Custom delay strategy (default: exponential backoff, max 30s)\n  refetchOnWindowFocus: false, // Refetch when tab regains focus\n  refetchOnReconnect: true,    // Refetch when network reconnects\n  refetchInterval: false,      // Polling interval in ms (false = disabled)\n  structuralSharing: false,    // Deep-compare to preserve object identity\n  placeholderData: undefined,  // Shown while the first fetch is in progress\n});\n```\n\n### Cache invalidation and optimistic updates\n\n**Same scope as the read**: After a mutation, prefer `refetch()` from the `useApiData` that loads the data (same component or wherever you can pass `refetch`).\n\n```typescript\nimport { useApi, useApiData } from \"@superblocksteam/library\";\nimport { toast } from \"sonner\";\n\nconst { data: orders, refetch } = useApiData(\"GetOrders\", { status });\nconst { run: createOrder } = useApi(\"CreateOrder\");\n\nconst handleSubmit = useCallback(async () => {\n  try {\n    await createOrder({ item, qty });\n    await refetch();\n  } catch (error) {\n    const message =\n      error && typeof error === \"object\" && \"message\" in error\n        ? String((error as { message: unknown }).message)\n        : String(error);\n    toast.error(\"Error creating order: \" + message);\n  }\n}, [item, qty, createOrder, refetch]);\n```\n\n**Cross-scope or broad invalidation**: Use `queryClient.invalidateQueries` when you cannot call that `refetch` (mutation in a different place than the `useApiData`, or you need every cached variant of an API to refetch). For **`queryClient.invalidateQueries`, `buildCacheKey`, `setQueryData`, and any other `queryClient` usage, always import `queryClient` from `@superblocksteam/library`**.\n\n```typescript\nimport { queryClient, useApi } from \"@superblocksteam/library\";\nimport { toast } from \"sonner\";\n\nconst { run: createOrder } = useApi(\"CreateOrder\");\n\nconst handleSubmit = useCallback(async () => {\n  try {\n    await createOrder({ item, qty });\n    await queryClient.invalidateQueries(\"GetOrders\");\n  } catch (error) {\n    const message =\n      error && typeof error === \"object\" && \"message\" in error\n        ? String((error as { message: unknown }).message)\n        : String(error);\n    toast.error(\"Error creating order: \" + message);\n  }\n}, [item, qty, createOrder]);\n```\n\n```typescript\n// Optimistic update: set cached data without refetching\nimport { queryClient } from \"@superblocksteam/library\";\n\nconst cacheKey = queryClient.buildCacheKey(\"GetOrders\", { status: \"active\" });\nqueryClient.setQueryData(cacheKey, (old) => ({\n  ...old,\n  orders: [...old.orders, newOrder],\n}));\n```\n\n### Critical API Rules\n\n1. **MUST call API by exact name**: Format is `<ApiName>` matching folder `apis/<ApiName>/api.yaml`\n2. **Use `useApiData` for data loading, `useApi` for mutations**: For data fetching, use `useApiData(\"GetUsers\", { email })`. Only use `useApi` for event-driven actions (button clicks, form submissions). Use `executeApi` for API calls outside React components.\n3. **Use the hook's state fields**: Do NOT create separate `useState` for loading or response data \u2014 the hooks manage this for you\n4. **ALWAYS check API interfaces**: NEVER guess the response structure\n5. **Include all parameters**: Even optional ones should be passed as `null`\n6. **ALWAYS use try/catch**: In imperative mode, APIs throw errors when they fail - wrap ALL `run()` calls in try/catch blocks. In declarative mode, check the `error` field for failure details.\n\n### File Handling\n\n**CRITICAL: Files must be wrapped in `{ files: [...] }` format:**\n\n```tsx\n// \u2705 CORRECT - Frontend: wrap files in { files: [...] }\nconst response = await runUploadApi({ userFile: { files: selectedFiles } });\n\n// \u274C WRONG - backend cannot process unwrapped files\nconst response = await runUploadApi({ userFile: selectedFiles });\n```\n\n## Platform Hooks and Functions\n\nAvailable hooks and functions from `@superblocksteam/library`:\n\n### User and Group Context\n\n```typescript\nimport {\n  useSuperblocksUser,\n  useSuperblocksGroups,\n} from \"@superblocksteam/library\";\n\n// Get current user info\nconst user = useSuperblocksUser();\n// user.name, user.email, user.id, user.groups, user.username, user.metadata\n\n// Get organization groups\nconst groups = useSuperblocksGroups();\n```\n\n### Environments and Data Tags\n\nConcepts & terminology:\n\n- `Data tags` are labels for different data segments, such as `Staging`, `Production`, or `us-east`.\n- `Profiles` is the legacy term for the same concept. If a user asks about profiles, treat that as data tags.\n- `Environments` are `Edit`, `Preview`, and `Production`, and each data tag is allowed in one or more of those environments.\n- Clark operates in `Edit` mode, so the data tags visible in app context represent the tags available in `Edit`; do not assume this is the same set that will be available in `Preview` or `Production`.\n- When implementing app code, prefer `useSuperblocksDataTags()`, `dataTags`, and `setDataTag()`.\n\nThe `DataTag` type has these fields (it is an alias for `Profile` from `@superblocksteam/shared`):\n\n```typescript\ntype DataTag = {\n  id: string;\n  key: string;\n  displayName: string; // human-readable label \u2014 use this for display, NOT \"name\"\n  description: string;\n  type: \"RESERVED\" | \"CUSTOM\";\n};\n```\n\nRelevant hooks and functions:\n\n```typescript\nimport { useSuperblocksDataTags, getAppMode } from \"@superblocksteam/library\";\nimport type { DataTag, DataTags } from \"@superblocksteam/library\";\n\n// Manage data tags\nconst { dataTags, setDataTag } = useSuperblocksDataTags();\n// dataTags.available: DataTag[]   \u2014 all tags in the current environment\n// dataTags.selected:  DataTag | undefined \u2014 currently active tag (may be undefined)\n// dataTags.default:   DataTag     \u2014 the default tag\n// setDataTag(dataTag.key)         \u2014 switch the active tag by key\n\n// Read the current app mode when reasoning about environment-specific behavior\nconst appMode = getAppMode();\n```\n\nExample \u2014 data tag switcher using a Select:\n\n```tsx\nconst { dataTags, setDataTag } = useSuperblocksDataTags();\n\n<Select value={dataTags?.selected?.key} onValueChange={setDataTag}>\n  {dataTags?.available.map((tag) => (\n    <SelectItem key={tag.key} value={tag.key}>\n      {tag.displayName}\n    </SelectItem>\n  ))}\n</Select>;\n```\n\n### Embedded Applications\n\n**For embedded applications**, see the `references/embedding.md` file for `useEmbedProperties`, `useEmbedEvent`, and `useEmitEmbedEvent` hooks.\n\n## Logging Out of Integrations\n\nWhen building a \"Log out\" or \"Sign out\" button for apps that use OAuth-like integrations, use `logoutIntegrations` from the library to clear OAuth tokens:\n\n```typescript\nimport { logoutIntegrations } from \"@superblocksteam/library\";\n\nconst handleLogout = async () => {\n  await logoutIntegrations();\n  // Optionally redirect or show confirmation\n};\n```\n\n## Application Architecture\n\n### App.tsx Layout Structure\n\n**For single-page applications:**\n\n- Put all content in `pages/<pageName>/index.tsx`\n- Use components to compose and build the page\n- Keep `App.tsx` minimal with just `<AppProvider>` and `<Outlet />`\n\n**For multi-page applications:**\n\n- Put shared navigation/layout in `App.tsx` (sidebars, headers, footers)\n- Always include `<Outlet />` for page content\n- Always include `<AppProvider />` wrapper\n- Individual pages focus on content, not layout\n\n```tsx\n// \u2705 CORRECT - Multi-page App.tsx layout\n<AppProvider>\n  <div className=\"flex flex-row size-screen\">\n    {/* Sidebar - persistent across all pages */}\n    <div className=\"flex bg-sidebar border-r w-[250px]\">\n      <Navigation />\n    </div>\n\n    {/* Main content area */}\n    <div className=\"flex flex-1 h-full flex-col\">\n      {/* Header - persistent across all pages */}\n      <div className=\"flex bg-header border-b h-[60px]\">\n        <Header />\n      </div>\n\n      {/* Page content area */}\n      <div className=\"flex p-4 flex-1 overflow-auto\">\n        <Outlet />\n      </div>\n    </div>\n  </div>\n</AppProvider>\n```\n\n**PROTECTED: NEVER remove `<AppProvider>` or `<Outlet />` from App.tsx!**\n\n### Page Structure\n\n```tsx\n// \u2705 CORRECT - Page focuses on content only\n<div className=\"flex flex-col gap-4 size-screen overflow-auto\">\n  <h1 className=\"text-3xl font-bold\">Dashboard Content</h1>\n  <Card>{/* Page-specific content */}</Card>\n</div>\n```\n\n**IMPORTANT**: The first div on the page must have `overflow-auto` so the user's page can scroll.\n\n## Routing\n\nUse `react-router@7` in data mode. Standard patterns apply:\n\n- `useNavigate()` for programmatic navigation\n- `useParams()` for route parameters\n- `useSearchParams()` for query strings\n\n**If you add new pages or rename files, you MUST update the router.**\n\n## Design System (Tailwind CSS v4)\n\n**All design tokens are defined in `index.css`**. Apps come with a professional black-and-white theme by default.\n\n### Semantic Tokens Rule\n\n**ALWAYS use semantic tokens** \u2014 NEVER raw Tailwind utilities:\n\n```tsx\n// \u2705 CORRECT\n<Card className=\"bg-background text-foreground border border-border\" />\n\n// \u274C WRONG\n<Card className=\"bg-white text-black border-gray-200\" />\n```\n\n### When to Modify index.css\n\nOnly modify when:\n\n- User explicitly requests branding/theme changes\n- Replicating a specific brand look (e.g., Yelp, Instacart)\n- Migrating an attached third-party app \u2014 see `skills/system/third-party-migration/SKILL.md` (its theme-port rules override the Modification Rules below \u2014 copy source tokens as-is, do not convert to OKLCH or trim the palette)\n- Feature requests (lists, filters, CRUD) do NOT require changes\n\n**Modification Rules:**\n\n- All colors must be in OKLCH format\n- Use semantic names (`--color-warning`, `--shadow-elevated`)\n- Do not remove or rename existing tokens\n- Limit color palette to 5 colors max\n- Avoid gradients unless explicitly requested\n- Minimal font sizes (3 max: body, section heading, main heading)\n\n### Component Variants\n\nUse or create variants instead of one-off styles:\n\n```tsx\n// \u274C WRONG - Hacky inline overrides\n<Button className=\"text-white border-white hover:bg-white\" />\n\n// \u2705 CORRECT - Use a variant\n<Button variant=\"secondary\" />\n```\n\n## Icons\n\nUse icons from Lucide React library:\n\n```tsx\nimport { Icon } from \"@/components/ui/icon\";\n<Icon icon=\"heart\" />;\n\nimport { Button } from \"@/components/ui/button\";\n<Button>\n  <Icon icon=\"plus\" /> Add Item\n</Button>;\n```\n\n**Always use icons rather than emojis unless explicitly requested.**\n\nUse current Lucide icon names, not stale aliases: use `house` instead of `home`, `life-buoy` instead of `help-circle` or `circle-help`, and `chart-column-big` instead of `bar-chart-3`.\n\n## Custom Components\n\n**CRITICAL: Component composition is MANDATORY. DO NOT create monolithic pages.**\n\n### The Composition Rule\n\nWhen building ANY feature:\n\n1. **First**, identify reusable parts (list items, cards, forms, filters, headers)\n2. **Then**, create separate component files\n3. **Finally**, compose them together in the page\n\n### When to Create Components\n\n- **Rendering any list** - Extract to a component\n- **Building cards/complex UI** - Each card type is a component\n- **Creating forms** - Form sections are components\n- **Adding filters/headers** - These are components\n- **Page has >50 lines JSX** - Break it down\n\n### Component Boundary Rules\n\n**Inside a custom component:**\n\n- \u2705 Use React hooks (useState, useReducer, useEffect, etc.)\n- \u2705 Use local React state\n- \u2705 Use internal helper components\n- \u2705 Use other registered components\n- \u274C CANNOT call APIs - must pass data into the component\n\n### Example: Proper Component Structure\n\n```tsx\n// components/ProductCard/index.tsx - Extract to component\nimport { Card } from \"@/components/ui/card\";\nimport { Button } from \"@/components/ui/button\";\n\ntype ProductCardProps = {\n  product: {\n    id: string;\n    name: string;\n    image: string;\n  };\n};\n\nexport default function ProductCard(props: ProductCardProps) {\n  return (\n    <Card>\n      <img src={props.product.image} />\n      <h3 className=\"text-lg font-semibold\">{props.product.name}</h3>\n      <Button>Add</Button>\n    </Card>\n  );\n}\n\n// pages/Products/index.tsx - Clean composition\nimport ProductCard from \"@/components/ProductCard\";\n\nconst ProductsPage = () => {\n  const [products, setProducts] = useState([]);\n\n  return (\n    <div className=\"grid grid-cols-3 gap-4\">\n      {products.map((p) => (\n        <ProductCard key={p.id} product={p} />\n      ))}\n    </div>\n  );\n};\n```\n\n## Visual Excellence\n\n**Prioritize visual excellence from the start:**\n\n1. **Design System Enhancement**: Start by enhancing `index.css` with app-specific colors that match the target aesthetic\n2. **Professional Layout Architecture**: Use sophisticated layouts with proper spacing, responsive design\n3. **Rich Interactive Components**: Leverage advanced components with proper variants and states\n4. **Visual Polish**: Add shadows, smooth transitions, skeleton loaders, hover effects, typography hierarchy\n5. **Real-World UI Patterns**: Create layouts that feel like professional applications\n\n**Make applications that look and feel like real, polished products - not basic wireframes.**\n\n### Loading States\n\nLoading behavior must differ based on whether data has already been fetched:\n\n**Initial load (no data yet):** Show skeleton shimmers that mirror the shape of the final content. Never show a blank screen or a generic spinner.\n\n**Refetch / background refresh (data already exists):** Keep showing the existing data. Use `fetching` from `useApiData` to apply a subtle visual indicator: light opacity (e.g. `opacity-70`) to signal a refresh is in progress, plus a non-blocking label such as a small inline spinner, a thin progress bar, or an \"Updating\u2026\" label. **Do not** use `pointer-events-none` or otherwise disable the content \u2014 it must remain fully interactive during refetch.\n\nUse `loading` and `fetching` from `useApiData` to distinguish these states:\n\n```tsx\nconst { data, loading, fetching, isError, error } = useApiData(\"GetOrders\", {\n  status: statusFilter,\n  search,\n});\n\n// Initial load \u2014 no data yet \u2192 show skeleton placeholder\nif (loading) {\n  return <OrderTableSkeleton />;\n}\n\nif (isError) return <ErrorBanner error={error} />;\n\n// Refetch \u2014 data exists \u2192 subtle opacity + indicator, table stays interactive\nreturn (\n  <div>\n    {fetching && <div className=\"text-xs text-muted-foreground\">Updating\u2026</div>}\n    <div className={fetching ? \"opacity-70\" : \"\"}>\n      <OrderTable orders={data.orders} />\n    </div>\n  </div>\n);\n```\n\n```tsx\n// \u274C WRONG \u2014 pointer-events-none disables the table, making it feel broken\nreturn (\n  <div className={fetching ? \"pointer-events-none\" : \"\"}>\n    <OrderTable orders={data.orders} />\n  </div>\n);\n\n// \u274C WRONG \u2014 no loading feedback when filters change\nif (loading) return <Skeleton />;\nreturn <OrderTable orders={data.orders} />;\n```\n\n#### Table Loading Rules\n\n- **Do not** use `pointer-events-none` on a table during loading \u2014 this disables interaction and makes the UI feel broken. During refetch, apply a subtle opacity (e.g. `opacity-70`) plus a non-blocking indicator (e.g., an \"Updating\u2026\" label or a thin progress bar). The table must remain clickable, sortable, and scrollable.\n- **Do not** replace a populated table with a full skeleton on refetch \u2014 this causes disorienting content flashes.\n- **Skeleton tables are only for initial load** (`loading` is true) when there is no data to display yet. Build them to match the real table's column structure (header + a few placeholder rows).\n\n### Efficient Loading Patterns\n\n1. **Always show loading indicators on refetch**: When inputs change (e.g. filters, search), show a non-blocking visual indicator while new data loads. Use `fetching` from `useApiData`.\n2. **Loading State Hierarchy**:\n   - No data yet (`loading`) \u2192 Full skeleton placeholder\n   - Has data, refetching (`fetching` && !`loading`) \u2192 Keep showing current data with a subtle visual indicator: light opacity (e.g. `opacity-70`) plus a non-blocking label (e.g. \"Updating\u2026\" text, thin progress bar, inline spinner). Do not use `pointer-events-none` \u2014 the content must remain fully interactive.\n   - Error state (`isError`) \u2192 Show error with retry option, optionally keep stale data visible\n3. **Debounce Rapid Requests**: Prevent multiple API calls in short succession\n4. **Use useApiData for automatic refetching**: `useApiData` auto-refetches when inputs change and supports `staleTime`, `refetchOnWindowFocus`, `refetchOnReconnect`, `refetchInterval`, and `retry` options.\n\n## Performance Rules\n\n### 1. ALWAYS Paginate Tables and Lists\n\n**NEVER render more than 50 rows without pagination.** Always add client-side pagination:\n\n```tsx\nfunction PaginatedTable({ data }: { data: any[] }) {\n  const PAGE_SIZE = 20;\n  const [page, setPage] = useState(0);\n  const totalPages = Math.ceil(data.length / PAGE_SIZE);\n  const pageData = useMemo(\n    () => data.slice(page * PAGE_SIZE, (page + 1) * PAGE_SIZE),\n    [data, page],\n  );\n\n  useEffect(() => {\n    setPage(0);\n  }, [data.length]);\n\n  return (\n    <>\n      <Table>{/* render pageData rows */}</Table>\n      <span>\n        Page {page + 1} of {totalPages} ({data.length} total rows)\n      </span>\n      <Button\n        onClick={() => setPage((p) => Math.max(0, p - 1))}\n        disabled={page === 0}\n      >\n        Previous\n      </Button>\n      <Button\n        onClick={() => setPage((p) => Math.min(totalPages - 1, p + 1))}\n        disabled={page >= totalPages - 1}\n      >\n        Next\n      </Button>\n    </>\n  );\n}\n```\n\nFor 200+ rows, prefer **server-side pagination**; use cursor/keyset pagination for high offsets instead of `LIMIT`/`OFFSET`.\n\nFor 500+ item lists where pagination doesn't fit the UX (chat messages, infinite scroll feeds, large dropdowns), use **virtualization** (`react-virtuoso` or `@tanstack/react-virtual`) to render only the items visible in the viewport.\n\n### 2. ALWAYS Debounce Input-Driven API Calls\n\n**NEVER call an API directly from onChange.** Debounce search/filter inputs with a 300ms timer:\n\n```tsx\nfunction DebouncedSearch({ onSearch }: { onSearch: (query: string) => void }) {\n  const [localValue, setLocalValue] = useState(\"\");\n  const timerRef = useRef<ReturnType<typeof setTimeout>>();\n  const handleChange = useCallback(\n    (e: React.ChangeEvent<HTMLInputElement>) => {\n      setLocalValue(e.target.value);\n      clearTimeout(timerRef.current);\n      timerRef.current = setTimeout(() => onSearch(e.target.value), 300);\n    },\n    [onSearch],\n  );\n  useEffect(() => () => clearTimeout(timerRef.current), []);\n\n  return (\n    <Input value={localValue} onChange={handleChange} placeholder=\"Search...\" />\n  );\n}\n```\n\n### 3. Memoize Expensive Renders\n\nUse memoization (`memo()`, `useMemo`, `useCallback`) when it prevents measurable re-renders or expensive recomputation:\n\n```tsx\nconst OrderRow = memo(function OrderRow({\n  order,\n  onSelect,\n}: {\n  order: Order;\n  onSelect: (id: string) => void;\n}) {\n  return (\n    <TableRow onClick={() => onSelect(order.id)}>\n      <TableCell>{order.id}</TableCell>...\n    </TableRow>\n  );\n});\n\nconst handleSelect = useCallback((id: string) => {\n  setSelectedId(id);\n}, []);\n\nconst filtered = useMemo(\n  () =>\n    orders.filter((o) => o.status === status).sort((a, b) => b.total - a.total),\n  [orders, status],\n);\n```\n\n### 4. ALWAYS Clean Up Side Effects\n\nClean up timers, event listeners, and subscriptions in `useEffect` return functions:\n\n```tsx\nuseEffect(() => {\n  const handler = (e: KeyboardEvent) => {\n    /* ... */\n  };\n  window.addEventListener(\"keydown\", handler);\n  return () => window.removeEventListener(\"keydown\", handler);\n}, []);\n```\n\n### 5. Cancel In-Flight API Requests on Unmount\n\nFor search/filter patterns, prefer `useApiData` \u2014 it handles cancellation and cleanup automatically:\n\n```tsx\n// useApiData: auto-fetches and cancels on unmount/input change\nconst { data, fetching } = useApiData(\"SearchProducts\", { query });\n```\n\nFor imperative usage with manual cleanup, use the `cancel()` function:\n\n```tsx\nconst { run, cancel } = useApi(\"SearchProducts\");\n\nuseEffect(() => {\n  if (!query) return;\n  run({ query }).catch(console.error);\n  return () => {\n    cancel().catch(() => {});\n  };\n}, [query, run, cancel]);\n```\n";
 //# sourceMappingURL=skill.generated.d.ts.map

package/dist/ai-service/skills/system/superblocks-frontend/skill.generated.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"skill.generated.d.ts","sourceRoot":"","sources":["../../../../../src/ai-service/skills/system/superblocks-frontend/skill.generated.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,OAAO,~~g/vBAiqBnB~~,CAAC"}
1	+ {"version":3,"file":"skill.generated.d.ts","sourceRoot":"","sources":["../../../../../src/ai-service/skills/system/superblocks-frontend/skill.generated.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,OAAO,4qwBAmqBnB,CAAC"}

package/dist/ai-service/skills/system/superblocks-frontend/skill.generated.js CHANGED Viewed

@@ -390,6 +390,8 @@ import { Button } from "@/components/ui/button";
 **Always use icons rather than emojis unless explicitly requested.**
+Use current Lucide icon names, not stale aliases: use \`house\` instead of \`home\`, \`life-buoy\` instead of \`help-circle\` or \`circle-help\`, and \`chart-column-big\` instead of \`bar-chart-3\`.
 ## Custom Components
 **CRITICAL: Component composition is MANDATORY. DO NOT create monolithic pages.**

package/dist/ai-service/skills/system/superblocks-frontend/skill.generated.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"skill.generated.js","sourceRoot":"","sources":["../../../../../src/ai-service/skills/system/superblocks-frontend/skill.generated.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,mDAAmD;AAEnD,MAAM,CAAC,MAAM,OAAO,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiqBtB,CAAC"}
1	+ {"version":3,"file":"skill.generated.js","sourceRoot":"","sources":["../../../../../src/ai-service/skills/system/superblocks-frontend/skill.generated.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,mDAAmD;AAEnD,MAAM,CAAC,MAAM,OAAO,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmqBtB,CAAC"}

package/dist/ai-service/skills/system/superblocks-migration/references/focused-debug.generated.d.ts CHANGED Viewed

@@ -1,2 +1,2 @@
-export declare const content = "# Focused retry playbook\n\nReference for `superblocks-migration/SKILL.md`. Load this **only** when the runtime prompt tells you this is a focused-retry turn.\n\nThis is a _retry_ attempt. Earlier runs already tried \u2014 and failed \u2014 on the APIs currently `pending` in the migration checklist. Your job is to finish them. Before writing any code, stop and think about **why** the prior attempt failed for each one and pick a _different_ strategy. Do not repeat the same approach; if the same plan failed twice, it will fail a third time.\n\n## Step 1: pull the prior-failure context\n\nThe checklist stores each item's most recent `lastFailureReason`. Call `build_manageChecklist` with `action: \"get\"` and read the `lastFailureReason` for every `seed_api` item still `pending`. Treat each reason as primary context when choosing your approach for that API.\n\nOnly address the APIs surfaced by that query \u2014 the rest of the app is already migrated.\n\n## Step 2: debugging checklist (work through this before editing)\n\n- Did the prior attempt misread the integration kind? Re-check `node_modules/@superblocksteam/sdk-api/src/index.ts` for the correct factory export.\n- Was the YAML using a block construct you skipped (`conditional`, `parallel`, `tryCatch`, `loop`, `variables`, inline `javascript`)? Translate it explicitly instead of bailing.\n- Did parameterization fail because a value flows in from a prior block's `.output` rather than `params`? Bind the right `ctx.*` or a local `const`.\n- Was the item marked `failed` because a target file (`index.ts`, a stub path) was \"missing\"? Confirm on disk \u2014 create nothing you were not told to create, but do not bail if the file actually exists.\n- Was a SQL statement's parameter shape wrong (scalar vs array, pg type cast)? Use `= ANY($N::<type>[])` for lists.\n- Prefer the **narrowest** rewrite that compiles and preserves behavior. If a full rewrite failed, try converting block-by-block.\n- If a documented method compiles but repeatedly fails at runtime, do not keep retrying the same pattern. Run one reload/retest cycle (`build_reloadFile`, then `testApi`) and then move to the next API. If no other APIs remain, leave a concrete `failureReason` describing the runtime limitation.\n\n## Meta-rule override: when the blocker is _information_, call `askMultiChoice` \u2014 DO NOT mark `failed`\n\nThe prior run already hit the `ZERO judgment calls` rule and marked these items `failed`. Repeating that reasoning on every retry is a loop that burns the user's budget and never converges. The user is _right here, right now, watching this turn_. Ask them.\n\nWhen the missing piece is something a human can supply (the original SQL, which integration to use, the intended output shape, whether a stubbed block can be dropped, etc.), you **MUST** call the `askMultiChoice` tool. This is a **tool call** \u2014 not a message, not a paragraph, not a list you type into the assistant response. You are not asking in English. You are invoking the tool named `askMultiChoice` with a JSON payload of `{ question, choices }`.\n\n### Exact rule\n\n1. Before you ever call `build_manageChecklist` with `status: \"failed\"` on an item in this retry, you **MUST** have already called `askMultiChoice` about it at least once in this turn. No exceptions.\n2. If you find yourself typing a sentence like _\"What would you like me to do?\"_ or _\"Please provide the SQL\"_ or _\"I need more information\"_ directly into your response, **stop**. Delete that text. Call `askMultiChoice` instead. The tool is the channel. The assistant text is not.\n3. The user only sees tool calls \u2014 a free-text question from you will sit there unanswered forever and this turn will be wasted.\n\n### How to structure the `askMultiChoice` call\n\n- **One call per distinct blocker.** If two APIs share the same missing information (e.g. both need the original SQL that was stubbed out), put them in a single question.\n- `question`: a short markdown string. Name the APIs in the question so the user knows what they're deciding about. Reference the relevant `failureReason` so the user has context.\n- `choices`: 2 or 3 entries. The first 1\u20132 should be concrete, actionable suggestions based on the YAML/integration/prior failure (e.g. _\"Provide the SQL query for these APIs\"_, _\"Use integration <name> with a SELECT _ query\"\\*). The **last choice** must be the literal string `Mark these APIs as complete and continue` \u2014 this is the user's escape hatch for APIs they don't need.\n- `selectionType`: `\"single\"`.\n\n### After the user responds\n\n- If they pick `Mark these APIs as complete and continue`: for every API covered by that question, call `build_manageChecklist` with `action: \"update\"`, `itemId: \"api_<ApiName>\"`, `status: \"completed\"`. Do not mark them `failed`. Move to the next blocker or finish.\n- If they provide information (via a concrete choice or a free-text reply that gives you what you needed): use it to finish the translation, emit the TypeScript module, register it if there's an `index.ts`, then `build_manageChecklist` `status: \"completed\"`.\n- Only call `build_manageChecklist` `status: \"failed\"` if the user's response explicitly says they cannot help or chose an option equivalent to \"skip this one\".\n\n### Self-check before you respond\n\nAsk yourself: _did I actually call the `askMultiChoice` tool in this turn for any item I'm about to leave unresolved?_ If the answer is no, you have not followed the rule. Call the tool.\n\n## Then execute\n\nUse the per-API procedure in `SKILL.md` for the actual translation work, but treat the prior `failureReason` as primary context when choosing your approach.\n";
+export declare const content = "# Focused retry playbook\n\nReference for `superblocks-migration/SKILL.md`. Load this **only** when the runtime prompt tells you this is a focused-retry turn.\n\nThis is a _retry_ attempt. Earlier runs already tried \u2014 and failed \u2014 on the APIs currently `pending` in the migration checklist. Your job is to finish them. Before writing any code, stop and think about **why** the prior attempt failed for each one and pick a _different_ strategy. Do not repeat the same approach; if the same plan failed twice, it will fail a third time.\n\n## Step 1: pull the prior-failure context\n\nThe checklist stores each item's most recent `lastFailureReason`. Call `build_manageChecklist` with `action: \"get\"` and read the `lastFailureReason` for every `2.0-upgrade` item still `pending` (or legacy `seed_api` items in older runs). Treat each reason as primary context when choosing your approach for that API.\n\nOnly address the APIs surfaced by that query \u2014 the rest of the app is already migrated.\n\n## Step 2: debugging checklist (work through this before editing)\n\n- Did the prior attempt misread the integration kind? Re-check `node_modules/@superblocksteam/sdk-api/src/index.ts` for the correct factory export.\n- Was the YAML using a block construct you skipped (`conditional`, `parallel`, `tryCatch`, `loop`, `variables`, inline `javascript`)? Translate it explicitly instead of bailing.\n- Did parameterization fail because a value flows in from a prior block's `.output` rather than `params`? Bind the right `ctx.*` or a local `const`.\n- Was the item marked `failed` because a target file (`index.ts`, a stub path) was \"missing\"? Confirm on disk \u2014 create nothing you were not told to create, but do not bail if the file actually exists.\n- Was a SQL statement's parameter shape wrong (scalar vs array, pg type cast)? Use `= ANY($N::<type>[])` for lists.\n- Prefer the **narrowest** rewrite that compiles and preserves behavior. If a full rewrite failed, try converting block-by-block.\n- If a documented method compiles but repeatedly fails at runtime, do not keep retrying the same pattern. Run one reload/retest cycle (`build_reloadFile`, then `testApi`) and then move to the next API. If no other APIs remain, leave a concrete `failureReason` describing the runtime limitation.\n\n## Meta-rule override: when the blocker is _information_, call `askMultiChoice` \u2014 DO NOT mark `failed`\n\nThe prior run already hit the `ZERO judgment calls` rule and marked these items `failed`. Repeating that reasoning on every retry is a loop that burns the user's budget and never converges. The user is _right here, right now, watching this turn_. Ask them.\n\nThe runtime also enforces a grouped unresolved guidance prompt when a migration pass ends with unresolved `seed_api` items. Treat that as a safety net, not a replacement for your own targeted `askMultiChoice` calls when you know exactly what information is missing.\n\nWhen the missing piece is something a human can supply (the original SQL, which integration to use, the intended output shape, whether a stubbed block can be dropped, etc.), you **MUST** call the `askMultiChoice` tool. This is a **tool call** \u2014 not a message, not a paragraph, not a list you type into the assistant response. You are not asking in English. You are invoking the tool named `askMultiChoice` with a JSON payload of `{ question, choices }`.\n\n### Exact rule\n\n1. Before you ever call `build_manageChecklist` with `status: \"failed\"` on an item in this retry, you **MUST** have already called `askMultiChoice` about it at least once in this turn. No exceptions.\n2. If you find yourself typing a sentence like _\"What would you like me to do?\"_ or _\"Please provide the SQL\"_ or _\"I need more information\"_ directly into your response, **stop**. Delete that text. Call `askMultiChoice` instead. The tool is the channel. The assistant text is not.\n3. The user only sees tool calls \u2014 a free-text question from you will sit there unanswered forever and this turn will be wasted.\n\n### How to structure the `askMultiChoice` call\n\n- **One call per distinct blocker.** If two APIs share the same missing information (e.g. both need the original SQL that was stubbed out), put them in a single question.\n- `question`: a short markdown string. Name the APIs in the question so the user knows what they're deciding about. Reference the relevant `failureReason` so the user has context.\n- `choices`: 2 or 3 entries. The first 1\u20132 should be concrete, actionable suggestions based on the YAML/integration/prior failure (e.g. _\"Provide the SQL query for these APIs\"_, _\"Use integration <name> with a SELECT _ query\"\\*). The **last choice** must be the literal string `Mark these APIs as complete and continue` \u2014 this is the user's escape hatch for APIs they don't need.\n- `selectionType`: `\"single\"`.\n\n### After the user responds\n\n- If they pick `Mark these APIs as complete and continue`: for every API covered by that question, call `build_manageChecklist` with `action: \"update\"`, `itemId: \"api_<ApiName>\"`, `status: \"completed\"`. Do not mark them `failed`. Move to the next blocker or finish.\n- If they provide information (via a concrete choice or a free-text reply that gives you what you needed): use it to finish the translation, emit the TypeScript module, register it if there's an `index.ts`, then `build_manageChecklist` `status: \"completed\"`.\n- Only call `build_manageChecklist` `status: \"failed\"` if the user's response explicitly says they cannot help or chose an option equivalent to \"skip this one\".\n\n### Self-check before you respond\n\nAsk yourself: _did I actually call the `askMultiChoice` tool in this turn for any item I'm about to leave unresolved?_ If the answer is no, you have not followed the rule. Call the tool.\n\n## Then execute\n\nUse the per-API procedure in `SKILL.md` for the actual translation work, but treat the prior `failureReason` as primary context when choosing your approach.\n";
 //# sourceMappingURL=focused-debug.generated.d.ts.map

package/dist/ai-service/skills/system/superblocks-migration/references/focused-debug.generated.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"focused-debug.generated.d.ts","sourceRoot":"","sources":["../../../../../../src/ai-service/skills/system/superblocks-migration/references/focused-debug.generated.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,OAAO,~~6lLAsDnB~~,CAAC"}
1	+ {"version":3,"file":"focused-debug.generated.d.ts","sourceRoot":"","sources":["../../../../../../src/ai-service/skills/system/superblocks-migration/references/focused-debug.generated.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,OAAO,w5LAwDnB,CAAC"}

package/dist/ai-service/skills/system/superblocks-migration/references/focused-debug.generated.js CHANGED Viewed

@@ -8,7 +8,7 @@ This is a _retry_ attempt. Earlier runs already tried — and failed — on the
 ## Step 1: pull the prior-failure context
-The checklist stores each item's most recent \`lastFailureReason\`. Call \`build_manageChecklist\` with \`action: "get"\` and read the \`lastFailureReason\` for every \`seed_api\` item still \`pending\`. Treat each reason as primary context when choosing your approach for that API.
+The checklist stores each item's most recent \`lastFailureReason\`. Call \`build_manageChecklist\` with \`action: "get"\` and read the \`lastFailureReason\` for every \`2.0-upgrade\` item still \`pending\` (or legacy \`seed_api\` items in older runs). Treat each reason as primary context when choosing your approach for that API.
 Only address the APIs surfaced by that query — the rest of the app is already migrated.
@@ -26,6 +26,8 @@ Only address the APIs surfaced by that query — the rest of the app is already
 The prior run already hit the \`ZERO judgment calls\` rule and marked these items \`failed\`. Repeating that reasoning on every retry is a loop that burns the user's budget and never converges. The user is _right here, right now, watching this turn_. Ask them.
+The runtime also enforces a grouped unresolved guidance prompt when a migration pass ends with unresolved \`seed_api\` items. Treat that as a safety net, not a replacement for your own targeted \`askMultiChoice\` calls when you know exactly what information is missing.
 When the missing piece is something a human can supply (the original SQL, which integration to use, the intended output shape, whether a stubbed block can be dropped, etc.), you **MUST** call the \`askMultiChoice\` tool. This is a **tool call** — not a message, not a paragraph, not a list you type into the assistant response. You are not asking in English. You are invoking the tool named \`askMultiChoice\` with a JSON payload of \`{ question, choices }\`.
 ### Exact rule

package/dist/ai-service/skills/system/superblocks-migration/references/focused-debug.generated.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"focused-debug.generated.js","sourceRoot":"","sources":["../../../../../../src/ai-service/skills/system/superblocks-migration/references/focused-debug.generated.ts"],"names":[],"mappings":"AAAA,qGAAqG;AACrG,mDAAmD;AAEnD,MAAM,CAAC,MAAM,OAAO,GAAG~~;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsDtB~~,CAAC"}
1	+ {"version":3,"file":"focused-debug.generated.js","sourceRoot":"","sources":["../../../../../../src/ai-service/skills/system/superblocks-migration/references/focused-debug.generated.ts"],"names":[],"mappings":"AAAA,qGAAqG;AACrG,mDAAmD;AAEnD,MAAM,CAAC,MAAM,OAAO,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwDtB,CAAC"}

package/dist/ai-service/skills/system/superblocks-migration/references/yaml-block-mapping.generated.d.ts CHANGED Viewed

@@ -1,2 +1,2 @@
-export declare const content = "# YAML block \u2192 TypeScript mapping\n\nReference for `superblocks-migration/SKILL.md`. Covers how each legacy block type in `api.yaml` maps to the new `@superblocksteam/sdk-api` TypeScript format.\n\n## Integration-backed blocks (SQL, REST, vendor plugins)\n\nShape in YAML:\n\n```yaml\nstep:\n  name: <BlockName>\n  integration: <uuid> # OR a plugin key like \"restapi\"\n  <plugin>: # e.g. postgresql, snowflake, restapi, openApiAction\n    body: | # SQL, request body, etc.\n      ...\n    parameters:\n      - name: <n>\n        value: <expr>\n```\n\n### SQL integrations (PostgreSQL, MySQL, Snowflake, Databricks, etc.)\n\n- Rows returned (`SELECT`, `SHOW`, `RETURNING *`) \u2192 `await ctx.integrations.<key>.query(sql, Schema, params)` with a Zod schema.\n- No rows actionable (`INSERT` w/o `RETURNING`, `UPDATE`, `DELETE`, DDL) \u2192 `await ctx.integrations.<key>.execute(sql, params)`.\n- **Parameterize everything.** Zero `${\u2026}` inside the SQL string. Dynamic lists use `= ANY($N::<type>[])`, never string-concatenated `IN (\u2026)`.\n\n### REST / OpenAPI / vendor plugin blocks\n\n- `openApiAction`, `restapi:`, and vendor plugin keys (e.g. `salesforce:`, `stripe:`, `openai:`) \u2192 the matching factory from the sdk-api barrel (`node_modules/@superblocksteam/sdk-api/src/index.ts`).\n- Never emit `openapi(...)`, `http(...)`, or `openApiAction(...)` \u2014 those are not sdk-api factories.\n- Client method names come from the integration README \u2014 never invent them. If the README only documents `apiRequest`, use `apiRequest`.\n\n## JavaScript blocks\n\n```yaml\nstep:\n  name: <BlockName>\n  integration: javascript\n  javascript:\n    body: |\n      ...JS code...\n```\n\nThere is **no `javascript` integration** in sdk-api. Inline the body as plain TypeScript inside `run(ctx, input)`. Any references to prior blocks' `<PriorBlock>.output` are replaced by the local `const` bound to that block's result.\n\n## Control-flow blocks\n\n| YAML block                        | TS construct                                                             |\n| --------------------------------- | ------------------------------------------------------------------------ |\n| `conditional:` (if / else)        | `if (...) { ... } else { ... }` around the nested block TS               |\n| `loop:` with `type: TYPE_FOREACH` | `for (const x of xs) { ... }` with **sequential** `await` (default)      |\n| `loop:` with `type: TYPE_WHILE`   | `while (cond) { ... }`                                                   |\n| `parallel:` (explicit)            | `await Promise.all(xs.map(async x => ...))`                              |\n| `variables:`                      | `const`s in the enclosing scope                                          |\n| `throw:`                          | `throw new Error(...)` (or the sdk-api error class the README documents) |\n| `return:`                         | `return ...;` from `run`                                                 |\n| `tryCatch:`                       | `try { ... } catch (err) { ... }`                                        |\n| `break:`                          | `break;`                                                                 |\n\nOnly use `Promise.all` when the YAML explicitly uses a `parallel:` block. A plain `TYPE_FOREACH` is sequential by contract \u2014 do not silently parallelize it.\n\n## Per-block `.output` references\n\nLegacy blocks expose `<BlockName>.output` to downstream blocks. In the TS port each block's result is a local `const`:\n\n```ts\nconst users = await ctx.integrations.pg.query(USERS_SQL, UsersSchema, [orgId]);\n// downstream: reference `users`, not `GetUsers.output`\n```\n\n## Metadata mapping\n\n- `metadata.name` \u2192 the string passed to `api({ name: \"<metadata.name>\" })` and the file base name (kebab-case).\n- `metadata.description` \u2192 the `description` field on `api({ ... })` if the sdk-api contract supports it (check the README; do not invent fields).\n- `authorization.type: AUTHORIZATION_TYPE_APP_USERS` \u2192 server-enforced; use `ctx.user` in TS. Remove any `userId`/`email` inputs the YAML declared as API input if they are now derivable from `ctx.user`.\n\n## Inputs\n\nThe YAML's `apiInputs` (or equivalent) enumerates the externally-accepted parameters. In the TS port:\n\n- Declare them on the `input` shape passed to `run(ctx, input)`.\n- Drop any input that is now sourced from `ctx.user` or from `ctx.integrations.<key>` state.\n- Keep the **minimal** union of identifiers the YAML actually references downstream.\n\n## Integration UUIDs\n\nEvery distinct `step.integration` UUID in a YAML becomes a named `const` at the top of the TS file \u2014 one `const` per unique integration, reused by every `ctx.integrations.<key>` call. Do not inline UUIDs. Do not carry UUIDs across files.\n\n```ts\nconst PG_MAIN = \"550e8400-e29b-41d4-a716-446655440000\";\n\nconst db = ctx.integrations.pg(PG_MAIN);\nconst rows = await db.query(...);\n```\n\n(Exact binding form depends on the sdk-api contract \u2014 confirm against the README.)\n\n## What NOT to emit\n\n- `// TODO` or `// FIXME` comments that silently ship \u2014 unresolved items live only as `failed` checklist entries.\n- Narrative code comments (\"this step fetches users\"). Code should read directly.\n- Retry wrappers, caching layers, or extra logging beyond the single `ctx.log.info(\"<ApiName> start\", {...})` at the top of `run`.\n- Envelope wrappers around the response \u2014 the external output shape must mirror the legacy API exactly.\n";
+export declare const content = "# YAML block \u2192 TypeScript mapping\n\nReference for `superblocks-migration/SKILL.md`. Covers how each legacy block type in `api.yaml` maps to the new `@superblocksteam/sdk-api` TypeScript format.\n\n## Integration-backed blocks (SQL, REST, vendor plugins)\n\nShape in YAML:\n\n```yaml\nstep:\n  name: <BlockName>\n  integration: <uuid> # OR a plugin key like \"restapi\"\n  <plugin>: # e.g. postgresql, snowflake, restapi, openApiAction\n    body: | # SQL, request body, etc.\n      ...\n    parameters:\n      - name: <n>\n        value: <expr>\n```\n\n### SQL integrations (PostgreSQL, MySQL, Snowflake, Databricks, etc.)\n\n- Rows returned (`SELECT`, `SHOW`, `RETURNING *`) \u2192 `await ctx.integrations.<key>.query(sql, Schema, params)` with a Zod schema.\n- No rows actionable (`INSERT` w/o `RETURNING`, `UPDATE`, `DELETE`, DDL) \u2192 `await ctx.integrations.<key>.execute(sql, params)`.\n- **Parameterize everything.** Zero `${\u2026}` inside the SQL string. Dynamic lists use `= ANY($N::<type>[])`, never string-concatenated `IN (\u2026)`.\n\n### REST / OpenAPI / vendor plugin blocks\n\n- `openApiAction`, `restapi:`, and vendor plugin keys (e.g. `salesforce:`, `stripe:`, `openai:`) \u2192 the matching factory from the sdk-api barrel (`node_modules/@superblocksteam/sdk-api/src/index.ts`).\n- Never emit `openapi(...)`, `http(...)`, or `openApiAction(...)` \u2014 those are not sdk-api factories.\n- Client method names come from the integration README \u2014 never invent them. If the README only documents `apiRequest`, use `apiRequest`.\n\n## JavaScript blocks\n\n```yaml\nstep:\n  name: <BlockName>\n  integration: javascript\n  javascript:\n    body: |\n      ...JS code...\n```\n\nThere is **no `javascript` integration** in sdk-api. Inline the body as plain TypeScript inside `run(ctx, input)`. Any references to prior blocks' `<PriorBlock>.output` are replaced by the local `const` bound to that block's result.\n\n## Python blocks\n\n```yaml\nstep:\n  name: <BlockName>\n  integration: python\n  python:\n    body: |\n      ...Python code...\n```\n\nThere is **no `python` integration** in sdk-api. Re-write the body as equivalent TypeScript inside `run(ctx, input)` \u2014 the same placement as a `javascript:` block. Translate idioms 1:1 where possible:\n\n| Python                    | TypeScript                                  |\n| ------------------------- | ------------------------------------------- |\n| `requests.get(url, ...)`  | `await fetch(url, ...)` then `.json()`      |\n| `requests.post(url, ...)` | `await fetch(url, { method: \"POST\", ... })` |\n| `[f(x) for x in xs]`      | `xs.map(x => f(x))`                         |\n| `[x for x in xs if p(x)]` | `xs.filter(p)`                              |\n| `len(xs)`                 | `xs.length`                                 |\n| `d[\"k\"]` / `d.get(\"k\")`   | `d.k` / `d[\"k\"]`                            |\n| `os.environ[\"X\"]`         | `process.env.X`                             |\n| `json.dumps(o)`           | `JSON.stringify(o)`                         |\n| `json.loads(s)`           | `JSON.parse(s)`                             |\n| `raise Exception(\"...\")`  | `throw new Error(\"...\")`                    |\n| `try / except`            | `try { ... } catch (err) { ... }`           |\n\nReferences to prior blocks' `<PriorBlock>.output` become the local `const` bound to that block's result \u2014 same rule as JavaScript blocks. If the Python relied on a third-party PyPI package with no straightforward JS equivalent (e.g. numpy, pandas, scipy, a vendor SDK), do not fabricate a port \u2014 mark that API `failed` with a `failureReason` that names the package.\n\n## Control-flow blocks\n\n| YAML block                        | TS construct                                                             |\n| --------------------------------- | ------------------------------------------------------------------------ |\n| `conditional:` (if / else)        | `if (...) { ... } else { ... }` around the nested block TS               |\n| `loop:` with `type: TYPE_FOREACH` | `for (const x of xs) { ... }` with **sequential** `await` (default)      |\n| `loop:` with `type: TYPE_WHILE`   | `while (cond) { ... }`                                                   |\n| `parallel:` (explicit)            | `await Promise.all(xs.map(async x => ...))`                              |\n| `variables:`                      | `const`s in the enclosing scope                                          |\n| `throw:`                          | `throw new Error(...)` (or the sdk-api error class the README documents) |\n| `return:`                         | `return ...;` from `run`                                                 |\n| `tryCatch:`                       | `try { ... } catch (err) { ... }`                                        |\n| `break:`                          | `break;`                                                                 |\n\nOnly use `Promise.all` when the YAML explicitly uses a `parallel:` block. A plain `TYPE_FOREACH` is sequential by contract \u2014 do not silently parallelize it.\n\n## Per-block `.output` references\n\nLegacy blocks expose `<BlockName>.output` to downstream blocks. In the TS port each block's result is a local `const`:\n\n```ts\nconst users = await ctx.integrations.pg.query(USERS_SQL, UsersSchema, [orgId]);\n// downstream: reference `users`, not `GetUsers.output`\n```\n\n## Metadata mapping\n\n- `metadata.name` \u2192 the string passed to `api({ name: \"<metadata.name>\" })` and the file base name (kebab-case).\n- `metadata.description` \u2192 the `description` field on `api({ ... })` if the sdk-api contract supports it (check the README; do not invent fields).\n- `authorization.type: AUTHORIZATION_TYPE_APP_USERS` \u2192 server-enforced; use `ctx.user` in TS. Remove any `userId`/`email` inputs the YAML declared as API input if they are now derivable from `ctx.user`.\n\n## Inputs\n\nThe YAML's `apiInputs` (or equivalent) enumerates the externally-accepted parameters. In the TS port:\n\n- Declare them on the `input` shape passed to `run(ctx, input)`.\n- Drop any input that is now sourced from `ctx.user` or from `ctx.integrations.<key>` state.\n- Keep the **minimal** union of identifiers the YAML actually references downstream.\n\n## Integration UUIDs\n\nEvery distinct `step.integration` UUID in a YAML becomes a named `const` at the top of the TS file \u2014 one `const` per unique integration, reused by every `ctx.integrations.<key>` call. Do not inline UUIDs. Do not carry UUIDs across files.\n\n```ts\nconst PG_MAIN = \"550e8400-e29b-41d4-a716-446655440000\";\n\nconst db = ctx.integrations.pg(PG_MAIN);\nconst rows = await db.query(...);\n```\n\n(Exact binding form depends on the sdk-api contract \u2014 confirm against the README.)\n\n## What NOT to emit\n\n- `// TODO` or `// FIXME` comments that silently ship \u2014 unresolved items live only as `failed` checklist entries.\n- Narrative code comments (\"this step fetches users\"). Code should read directly.\n- Retry wrappers, caching layers, or extra logging beyond the single `ctx.log.info(\"<ApiName> start\", {...})` at the top of `run`.\n- Envelope wrappers around the response \u2014 the external output shape must mirror the legacy API exactly.\n";
 //# sourceMappingURL=yaml-block-mapping.generated.d.ts.map

package/dist/ai-service/skills/system/superblocks-migration/references/yaml-block-mapping.generated.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"yaml-block-mapping.generated.d.ts","sourceRoot":"","sources":["../../../../../../src/ai-service/skills/system/superblocks-migration/references/yaml-block-mapping.generated.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,OAAO,~~y7KAuGnB~~,CAAC"}
1	+ {"version":3,"file":"yaml-block-mapping.generated.d.ts","sourceRoot":"","sources":["../../../../../../src/ai-service/skills/system/superblocks-migration/references/yaml-block-mapping.generated.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,OAAO,soOAoInB,CAAC"}

package/dist/ai-service/skills/system/superblocks-migration/references/yaml-block-mapping.generated.js CHANGED Viewed

@@ -45,6 +45,35 @@ step:
 There is **no \`javascript\` integration** in sdk-api. Inline the body as plain TypeScript inside \`run(ctx, input)\`. Any references to prior blocks' \`<PriorBlock>.output\` are replaced by the local \`const\` bound to that block's result.
+## Python blocks
+\`\`\`yaml
+step:
+  name: <BlockName>
+  integration: python
+  python:
+    body: |
+      ...Python code...
+\`\`\`
+There is **no \`python\` integration** in sdk-api. Re-write the body as equivalent TypeScript inside \`run(ctx, input)\` — the same placement as a \`javascript:\` block. Translate idioms 1:1 where possible:
+| Python                    | TypeScript                                  |
+| ------------------------- | ------------------------------------------- |
+| \`requests.get(url, ...)\`  | \`await fetch(url, ...)\` then \`.json()\`      |
+| \`requests.post(url, ...)\` | \`await fetch(url, { method: "POST", ... })\` |
+| \`[f(x) for x in xs]\`      | \`xs.map(x => f(x))\`                         |
+| \`[x for x in xs if p(x)]\` | \`xs.filter(p)\`                              |
+| \`len(xs)\`                 | \`xs.length\`                                 |
+| \`d["k"]\` / \`d.get("k")\`   | \`d.k\` / \`d["k"]\`                            |
+| \`os.environ["X"]\`         | \`process.env.X\`                             |
+| \`json.dumps(o)\`           | \`JSON.stringify(o)\`                         |
+| \`json.loads(s)\`           | \`JSON.parse(s)\`                             |
+| \`raise Exception("...")\`  | \`throw new Error("...")\`                    |
+| \`try / except\`            | \`try { ... } catch (err) { ... }\`           |
+References to prior blocks' \`<PriorBlock>.output\` become the local \`const\` bound to that block's result — same rule as JavaScript blocks. If the Python relied on a third-party PyPI package with no straightforward JS equivalent (e.g. numpy, pandas, scipy, a vendor SDK), do not fabricate a port — mark that API \`failed\` with a \`failureReason\` that names the package.
 ## Control-flow blocks
 | YAML block                        | TS construct                                                             |

package/dist/ai-service/skills/system/superblocks-migration/references/yaml-block-mapping.generated.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"yaml-block-mapping.generated.js","sourceRoot":"","sources":["../../../../../../src/ai-service/skills/system/superblocks-migration/references/yaml-block-mapping.generated.ts"],"names":[],"mappings":"AAAA,0GAA0G;AAC1G,mDAAmD;AAEnD,MAAM,CAAC,MAAM,OAAO,GAAG~~;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuGtB~~,CAAC"}
1	+ {"version":3,"file":"yaml-block-mapping.generated.js","sourceRoot":"","sources":["../../../../../../src/ai-service/skills/system/superblocks-migration/references/yaml-block-mapping.generated.ts"],"names":[],"mappings":"AAAA,0GAA0G;AAC1G,mDAAmD;AAEnD,MAAM,CAAC,MAAM,OAAO,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoItB,CAAC"}

package/dist/ai-service/skills/system/superblocks-migration/skill.generated.d.ts CHANGED Viewed

@@ -1,2 +1,2 @@
-export declare const content = "---\nname: superblocks-migration\ndescription: |\n  Convert legacy Superblocks 2.0 YAML APIs (\"block-chain\" format) to the new 3.0 sdk-api TypeScript format.\n  Load when executing a v2\u2192v3 migration turn \u2014 the runtime prompt will tell you to.\nreadOnly: true\nmetadata:\n  author: superblocks\n  version: \"1.0\"\n---\n\n# v2 \u2192 v3 API Translation\n\nYou are converting **legacy Superblocks \"block-chain\" YAML APIs** into the **new code-mode `@superblocksteam/sdk-api` TypeScript format**. Each YAML file under `scratch/v2-backup/apis/<ApiName>/api.yaml` must be emitted as a single TypeScript file at `server/apis/<ApiName>/api.ts` that compiles, typechecks, and preserves behavior exactly.\n\n## Meta-rule: ZERO judgment calls\n\nIf any situation below is not resolved deterministically by this document, **STOP** for that API. Do **not** pick a default. Do **not** guess a factory, a shape, or an import. Skip it, continue with other APIs, and mark the checklist item as `failed` via `build_manageChecklist` with a short `failureReason` describing the exact ambiguity (failing rule, block name if any, what would be needed to proceed). This rule overrides everything else.\n\nCorollary: do not add `// TODO` comments that silently ship. Unresolved items live only as `failed` checklist entries.\n\n## Inputs and outputs\n\n- **Source tree:** `scratch/v2-backup/apis/<ApiName>/api.yaml`. Discover the actual set by listing the directory \u2014 do not hardcode a count or list.\n- **Target tree:** `server/apis/<ApiName>/api.ts`. Do not create scaffolding trees that do not already exist (see \"Registry registration\" below).\n- **Checklist:** the migration checklist has already been seeded with one item per API (id `api_<ApiName>`, origin `seed_api`, status `pending`). Pull the live set by calling `build_manageChecklist` with `action: \"get\"` and filtering to `origin: \"seed_api\"` and `status: \"pending\"` \u2014 that is your authoritative API list and count for this turn.\n\n## Required reading (read these BEFORE writing any output)\n\nAuthoritative. If a rule here conflicts with your priors, these win.\n\n1. `node_modules/@superblocksteam/sdk-api/README.md` \u2014 whole thing (api() contract, execution model, `ctx.*`, exports, error classes, performance best practices, `useApi` frontend hook, integration method table).\n2. `node_modules/@superblocksteam/sdk-api/src/index.ts` (the **barrel**) \u2014 the authoritative list of exported factory names. Integration factory names are whatever this file exports, not whatever the directory name is. Never invent or case-fold a factory name without confirming it here.\n3. The README for **every integration** referenced by the YAMLs you convert:\n   - `node_modules/@superblocksteam/sdk-api/src/integrations/<kind>/README.md`\n   - If a vendor-specific factory exists for the target service (e.g., a dedicated one for a given LLM provider), prefer it over a generic HTTP one.\n4. `skills/system/superblocks-migration/references/yaml-block-mapping.md` \u2014 full YAML \u2192 TS mapping for each legacy block type.\n\nThere is **no `javascript` integration** in sdk-api \u2014 inline JS/TS lives directly inside `run(ctx, input)`. Any block whose YAML key is `javascript:` becomes plain TypeScript in `run()`.\n\n## Preflight gate (MUST pass before any file edits)\n\nComplete this orientation sequence before writing or modifying any API file:\n\n1. Call `build_manageChecklist` with `action: \"get\"` and filter to `origin: \"seed_api\"` `status: \"pending\"` \u2014 this is your authoritative API list and count for this turn.\n2. Read `node_modules/@superblocksteam/sdk-api/src/index.ts` and treat it as the **only** source of truth for sdk-api export/factory names.\n3. Read `node_modules/@superblocksteam/sdk-api/README.md`.\n4. For each API, read only the integration README(s) needed for that API right before migrating it (just-in-time). Do **not** preload every integration README for the entire app.\n\nHard constraints:\n\n- Do **not** rely on prior conversation memory, \"knowledge\" summaries, or inferred export names.\n- Do **not** start editing API files until preflight steps 1\u20133 are complete.\n- If a required file cannot be read, mark that API's checklist item `failed` with a concrete `failureReason` that names the missing path.\n\n## File layout & exports\n\n- One API per file, default export: `export default api({ ... });`.\n- Use ESM-style relative `.js` specifiers in imports.\n- File path: `server/apis/<ApiName>/api.ts` where `<ApiName>` is the YAML `metadata.name` (for example, `GetFloors` \u2192 `server/apis/GetFloors/api.ts`).\n- The `api({ name })` string and the registry key must both equal the YAML `metadata.name` verbatim \u2014 frontends call `useApi(\"<metadata.name>\")`.\n\n### Registry registration (conditional)\n\n- If `server/apis/index.ts` exists in the target tree: add an import + entry for each new module. Do not reorder existing entries.\n- If it does **not** exist: do **not** create it, do not create scaffolding. Mark the checklist item `failed` with a `failureReason` noting the missing registry.\n\n## Critical rules\n\n1. **Integration IDs are opaque per-YAML.** Extract each distinct `step.integration` UUID to a named `const` at the top of the file. Never carry UUIDs across files.\n2. **SQL: parameterize always.** Zero `${\u2026}` interpolations may remain inside any SQL string. Dynamic lists use `= ANY($N::<type>[])` \u2014 never string-building `IN (\u2026)`.\n3. **`query` vs `execute`.** Rows returned \u2192 `query` with Zod schema. Nothing actionable \u2192 `execute`.\n4. **Output shape preservation.** Mirror the legacy API's externally-visible response exactly \u2014 shape, nullability, cardinality. Do not wrap in envelopes.\n5. **Default is sequential.** `TYPE_FOREACH` \u2192 `for ... of` with sequential `await`. `Promise.all` only when YAML explicitly used a `parallel:` block.\n6. **Determinism, no slop.** No retries, no caching, no extra logging beyond a single `ctx.log.info(\"<ApiName> start\", {...})` at the top of `run`. No narrative code comments.\n7. **Never invent client methods.** If the integration README only documents `apiRequest`, use `apiRequest`.\n\n## Security / user identity\n\n- `authorization.type: AUTHORIZATION_TYPE_APP_USERS` is enforced by the server; rely on `ctx.user` in TS.\n- If the YAML accepts `userId` / `email` / etc. as API input, remove that input and read from `ctx.user` instead.\n\n## Observability\n\n- One `ctx.log.info(\"<ApiName> start\", { <safe-ids> })` at the top of `run` is allowed. Never log secrets, tokens, or PII.\n\n## Verification before you hand off\n\nRuntime verification (required):\n\n1. `build_debug` passing is required but not sufficient. Do not treat compile/typecheck success as proof that runtime behavior is correct.\n2. Use risk-based runtime checks: run `testApi` for APIs with integrations (REST/vendor/SQL), multi-step control flow, transformed outputs, or any uncertainty. For obviously simple APIs, you may skip `testApi`.\n3. If `testApi` output appears stale or mismatched, run `build_reloadFile` once and re-test. If runtime still fails after documented-method verification + one reload/retest cycle, record a concrete `failureReason` and continue.\n\nFor each converted API, self-check:\n\n1. File default-exports exactly one `api({...})`; `name` matches `metadata.name`.\n2. Zero `${\u2026}` interpolations remain in any SQL string.\n3. No SQL `IN (\u2026)` built by concatenation; dynamic lists use `= ANY($N::<type>[])`.\n4. Every prior block's `.output` read is replaced by an actual result `const`.\n5. Input is the minimal union of identifiers the YAML references that are not produced by earlier blocks or `Variables`.\n6. Output shape exactly mirrors the legacy API's external response.\n7. If `server/apis/index.ts` exists, it registers the new module under `metadata.name`.\n\n## Parallelization policy\n\nCount pending APIs from the checklist (`build_manageChecklist` `action: \"get\"`, filter `origin: \"seed_api\"` `status: \"pending\"`).\n\n- **If the pending count is `< 8`:** migrate the APIs yourself, sequentially. Do NOT call `spawnCodingSubagents`. Work through each API using the per-API procedure below.\n- **If the pending count is `>= 8`:** you **MUST spawn sub-agents** to migrate these APIs in parallel. There are too many APIs to migrate sequentially yourself. Do NOT attempt to migrate APIs yourself in this run \u2014 use `spawnCodingSubagents`.\n  - Split the APIs into batches of ~5 (aim for 4\u20136 per batch), with a hard cap of **5 sub-agents total**. If more than 25 APIs remain, give later batches larger shares rather than spawning more than 5 workers.\n  - For each batch, craft an `instructions` string that:\n    - Names the exact `<ApiName>` values that sub-agent owns, verbatim, as a bulleted list.\n    - Restates the per-API procedure below so the sub-agent is self-contained.\n    - Reminds the sub-agent to update the shared checklist (id `api_<ApiName>`) for every item it owns.\n  - **Call `spawnCodingSubagents` as the ONLY tool call in that turn.** Do not emit any other tool calls alongside it \u2014 no reads, no writes, no checklist updates. The tool blocks until every sub-agent finishes; you cannot do migration work \"while waiting\" because there is no waiting from your perspective \u2014 your next turn only begins after the tool returns. If you emit other tool calls in the same turn, you and the sub-agents will race on the shared checklist and corrupt state.\n  - **After `spawnCodingSubagents` returns** \u2014 only in a subsequent turn \u2014 read the checklist via `build_manageChecklist` with `action: \"get\"`. For any `failed` items, review the `failureReason`. Retry small numbers of recoverable failures yourself (sequentially, using the per-API procedure below). Leave deterministic failures as `failed`.\n\n## Per-API procedure\n\nFor APIs you migrate yourself, or that you embed in a sub-agent's `instructions`:\n\n1. Call `build_manageChecklist` with `action: \"update\"`, `itemId: \"api_<ApiName>\"`, `status: \"in_progress\"`.\n2. Read `scratch/v2-backup/apis/<ApiName>/api.yaml` and any sibling files the blocks reference.\n3. Produce the TypeScript module at `server/apis/<ApiName>/api.ts`, overwriting the stub. Use the YAML block \u2192 TS mapping in `skills/system/superblocks-migration/references/yaml-block-mapping.md`.\n4. If `server/apis/index.ts` exists, update it to register the new module.\n5. On success \u2192 `build_manageChecklist` with `status: \"completed\"`.\n6. On deterministic failure \u2192 `build_manageChecklist` with `status: \"failed\"` and a concrete `failureReason` (the rule that failed + what is needed to proceed). Continue with the next API.\n\n## Run-level rules\n\n- Do NOT emit a free-text UNRESOLVED report \u2014 every unresolved item must be a `failed` checklist entry with a `failureReason`.\n- Do NOT stop the run because one API failed. Only stop once every API is either `completed` or `failed`.\n";
+export declare const content = "---\nname: superblocks-migration\ndescription: |\n  Convert legacy Superblocks 2.0 YAML APIs (\"block-chain\" format) to the new 3.0 sdk-api TypeScript format.\n  Load when executing a v2\u2192v3 migration turn \u2014 the runtime prompt will tell you to.\nreadOnly: true\nmetadata:\n  author: superblocks\n  version: \"1.0\"\n---\n\n# v2 \u2192 v3 API Translation\n\nYou are converting **legacy Superblocks \"block-chain\" YAML APIs** into the **new code-mode `@superblocksteam/sdk-api` TypeScript format**. Each YAML file under `scratch/v2-backup/apis/<ApiName>/api.yaml` must be emitted as a single TypeScript file at `server/apis/<ApiName>/api.ts` that compiles, typechecks, and preserves behavior exactly.\n\n## Meta-rule: ZERO judgment calls\n\nIf any situation below is not resolved deterministically by this document, **STOP** for that API. Do **not** pick a default. Do **not** guess a factory, a shape, or an import. Skip it, continue with other APIs, and mark the checklist item as `failed` via `build_manageChecklist` with a short `failureReason` describing the exact ambiguity (failing rule, block name if any, what would be needed to proceed). This rule overrides everything else.\n\nCorollary: do not add `// TODO` comments that silently ship. Unresolved items live only as `failed` checklist entries.\n\nCorollary for `migration_page_route_verification_*`: see the _Page route verification_ section below \u2014 screenshot timeout/error \u2192 `failed`, never `completed`, never \"verified via router/source inspection.\" The full rule (including the hard-rule restatements) lives there to avoid drift.\n\n## Inputs and outputs\n\n- **Source tree:** `scratch/v2-backup/apis/<ApiName>/api.yaml`. Discover the actual set by listing the directory \u2014 do not hardcode a count or list.\n- **Target tree:** `server/apis/<ApiName>/api.ts`. Do not create scaffolding trees that do not already exist (see \"Registry registration\" below).\n- **Checklist:** the migration checklist has already been seeded with one item per API (id `api_<ApiName>`, origin `2.0-upgrade`, status `pending`, `clearOnFinalize: false`). Legacy in-flight runs may still have `origin: \"seed_api\"` for these API items. Pull the live set by calling `build_manageChecklist` with `action: \"get\"` and filtering to `status: \"pending\"` plus API-migration origins (`origin: \"2.0-upgrade\"` or legacy `origin: \"seed_api\"`) \u2014 that is your authoritative API list and count for this turn.\n\n## Required reading (read these BEFORE writing any output)\n\nAuthoritative. If a rule here conflicts with your priors, these win.\n\n1. `node_modules/@superblocksteam/sdk-api/README.md` \u2014 whole thing (api() contract, execution model, `ctx.*`, exports, error classes, performance best practices, `useApi` frontend hook, integration method table).\n2. `node_modules/@superblocksteam/sdk-api/src/index.ts` (the **barrel**) \u2014 the authoritative list of exported factory names. Integration factory names are whatever this file exports, not whatever the directory name is. Never invent or case-fold a factory name without confirming it here.\n3. The README for **every integration** referenced by the YAMLs you convert:\n   - `node_modules/@superblocksteam/sdk-api/src/integrations/<kind>/README.md`\n   - If a vendor-specific factory exists for the target service (e.g., a dedicated one for a given LLM provider), prefer it over a generic HTTP one.\n4. `skills/system/superblocks-migration/references/yaml-block-mapping.md` \u2014 full YAML \u2192 TS mapping for each legacy block type.\n\nThere is **no `javascript` integration** in sdk-api \u2014 inline JS/TS lives directly inside `run(ctx, input)`. Any block whose YAML key is `javascript:` becomes plain TypeScript in `run()`. The same applies to **`python:` blocks**: there is no `python` integration in sdk-api, so port the body to inline TypeScript inside `run(ctx, input)` (see \"Substituting unsupported integrations\" below and the Python section in `yaml-block-mapping.md`).\n\n## Substituting unsupported integrations\n\nThe pre-migration UI warns the user when an app references integrations whose v2 plugin is not present in sdk-api. The migration is **not** aborted on those APIs \u2014 they are still in your `seed_api` checklist and you are expected to make a best-effort port rather than immediately marking them `failed`.\n\nSubstitution rules (apply in order; first match wins):\n\n1. **`python:` step \u2192 inline TypeScript.** Re-write the Python body as equivalent TypeScript inside `run(ctx, input)`, exactly the way `javascript:` blocks are inlined. Translate Python idioms to JS/TS (e.g. `requests.get(...)` \u2192 `fetch(...)`, list comprehensions \u2192 `array.map`/`filter`, `len(x)` \u2192 `x.length`, dict access \u2192 object property access, `os.environ[...]` \u2192 `process.env[...]`, raise/except \u2192 `throw`/`try\u2026catch`). If the Python relied on a third-party PyPI package with no obvious JS equivalent, mark that one API `failed` with a `failureReason` naming the package \u2014 do not ship a guess.\n2. **HTTP-shaped vendor plugin \u2192 REST.** If an unsupported integration was effectively making REST calls (e.g. a thin wrapper around an HTTP API) and you can read the request shape from the YAML, port it to the `restApi` factory from sdk-api (or the dedicated vendor factory if one exists in the barrel \u2014 check `node_modules/@superblocksteam/sdk-api/src/index.ts`).\n3. **Otherwise, mark `failed`.** Per the meta-rule, do not invent a factory or fabricate behavior. Use `build_manageChecklist` with `status: \"failed\"` and a concrete `failureReason` (e.g. `\"unsupported integration <pluginId> with no JS-equivalent path\"`).\n\nDo **not** silently skip a step or replace it with a `// TODO` \u2014 every API still needs a deterministic outcome (`completed` or `failed`) on the checklist.\n\n## Preflight gate (MUST pass before any file edits)\n\nComplete this orientation sequence before writing or modifying any API file:\n\n0. **Install recommended user dependencies (before API work).** The platform restructure already computed exactly which v2 user-added packages the migrated client/server code imports, and persisted them at `scratch/migration-state.json` \u2192 `recommendedUserDeps` (each entry has `name`, `version`, and `dev`). Your job is to install that list \u2014 not to recompute it.\n   - Mark `migration_dependency_verification` as `in_progress` via `build_manageChecklist`.\n   - Read `scratch/migration-state.json` and extract `recommendedUserDeps`.\n   - If `recommendedUserDeps` is missing or empty, mark `migration_dependency_verification` as `completed` and continue to step 1.\n   - Otherwise, call `build_installPackages` **once** with every entry from `recommendedUserDeps` (passing `name`, `version`, and `dev` through unchanged). Do **not** skip because `node_modules` exists on disk; the platform never wrote these packages into `package.json`.\n   - **Failure semantics (covers every non-success outcome \u2014 no judgment calls):**\n     - On full success \u2192 mark `migration_dependency_verification` as `completed`.\n     - On **any** failure \u2014 full, partial (some packages installed, others did not), structured registry error (`not_in_registry`, `registry_auth_failed`, `registry_unreachable`), or unstructured error \u2014 mark `migration_dependency_verification` as `failed` with a `failureReason` that lists the affected package names and the tool's verbatim error code or message. Treat partial success the same as full failure for checklist purposes; do not split into multiple checklist items. Then continue to step 1 so API translation can still proceed. The user/operator will repair the registry/packages and re-trigger the migration turn.\n   - If `scratch/migration-state.json` also contains `recommendedUserDepsPinnedToLatest` (a string array of package names), include those names in the `failureReason` of `migration_dependency_verification` even on full success \u2014 phrased as \"pinned to latest, may need user confirmation: <names>\" \u2014 so the user can downgrade them before runtime if the latest major is incompatible. Use status `completed` in this case (the install succeeded), but the surfaced reason gives the user a checkpoint to act on.\n   - Do **not** scan imports yourself, edit `package.json`, or add packages outside `recommendedUserDeps`. If you believe a package is missing from the list, that is a platform bug: mark `migration_dependency_verification` as `failed` with `failureReason: \"platform bug: <pkg> imported by <file> but absent from recommendedUserDeps\"` and continue with API work using the packages that did install. (`build_manageChecklist` has no `note` action \u2014 `failed` with a structured `failureReason` is the only way to record this.)\n1. Call `build_manageChecklist` with `action: \"get\"` and filter to `status: \"pending\"` and API-migration origins (`origin: \"2.0-upgrade\"` or legacy `origin: \"seed_api\"`) \u2014 this is your authoritative API list and count for this turn.\n2. Read `node_modules/@superblocksteam/sdk-api/src/index.ts` and treat it as the **only** source of truth for sdk-api export/factory names.\n3. Read `node_modules/@superblocksteam/sdk-api/README.md`.\n4. For each API, read only the integration README(s) needed for that API right before migrating it (just-in-time). Do **not** preload every integration README for the entire app.\n\nHard constraints:\n\n- Do **not** rely on prior conversation memory, \"knowledge\" summaries, or inferred export names.\n- Do **not** start editing API files until preflight steps 0\u20133 are complete.\n- If a required file cannot be read, mark that API's checklist item `failed` with a concrete `failureReason` that names the missing path.\n\n## File layout & exports\n\n- One API per file, default export: `export default api({ ... });`.\n- Use ESM-style relative `.js` specifiers in imports.\n- File path: `server/apis/<ApiName>/api.ts` where `<ApiName>` is the YAML `metadata.name` (for example, `GetFloors` \u2192 `server/apis/GetFloors/api.ts`).\n- The `api({ name })` string and the registry key must both equal the YAML `metadata.name` verbatim \u2014 frontends call `useApi(\"<metadata.name>\")`.\n\n### Registry registration (conditional)\n\n- If `server/apis/index.ts` exists in the target tree: add an import + entry for each new module. Do not reorder existing entries.\n- If it does **not** exist: do **not** create it, do not create scaffolding. Mark the checklist item `failed` with a `failureReason` noting the missing registry.\n\n## Critical rules\n\n1. **Integration IDs are opaque per-YAML.** Extract each distinct `step.integration` UUID to a named `const` at the top of the file. Never carry UUIDs across files.\n2. **SQL: parameterize always.** Zero `${\u2026}` interpolations may remain inside any SQL string. Dynamic lists use `= ANY($N::<type>[])` \u2014 never string-building `IN (\u2026)`.\n3. **`query` vs `execute`.** Rows returned \u2192 `query` with Zod schema. Nothing actionable \u2192 `execute`.\n4. **Output shape preservation.** Mirror the legacy API's externally-visible response exactly \u2014 shape, nullability, cardinality. Do not wrap in envelopes.\n5. **Default is sequential.** `TYPE_FOREACH` \u2192 `for ... of` with sequential `await`. `Promise.all` only when YAML explicitly used a `parallel:` block.\n6. **Determinism, no slop.** No retries, no caching, no extra logging beyond a single `ctx.log.info(\"<ApiName> start\", {...})` at the top of `run`. No narrative code comments.\n7. **Never invent client methods.** If the integration README only documents `apiRequest`, use `apiRequest`.\n\n## Security / user identity\n\n- `authorization.type: AUTHORIZATION_TYPE_APP_USERS` is enforced by the server; rely on `ctx.user` in TS.\n- If the YAML accepts `userId` / `email` / etc. as API input, remove that input and read from `ctx.user` instead.\n\n## Observability\n\n- One `ctx.log.info(\"<ApiName> start\", { <safe-ids> })` at the top of `run` is allowed. Never log secrets, tokens, or PII.\n\n## Verification before you hand off\n\nRuntime verification (required):\n\n1. `build_debug` passing is required but not sufficient. Do not treat compile/typecheck success as proof that runtime behavior is correct.\n2. Use risk-based runtime checks: run `testApi` for APIs with integrations (REST/vendor/SQL), multi-step control flow, transformed outputs, or any uncertainty. For obviously simple APIs, you may skip `testApi`.\n3. If `testApi` output appears stale or mismatched, run `build_reloadFile` once and re-test. If runtime still fails after documented-method verification + one reload/retest cycle, record a concrete `failureReason` and continue.\n\nPage route verification (required once per migration run):\n\n**Hard rule:** A route is verified only with **runtime visual evidence on that exact path**. Reading `client/router.tsx`, page source, or backup artifacts is orientation only \u2014 it **never** satisfies verification.\n\n**Hard rule:** `build_debug` passing and `get_runtime_errors` returning `count: 0` are **not sufficient** for route verification. Do not mark routes `completed` because \"only APIs changed\" or \"the frontend files are unchanged.\"\n\n**Hard rule:** If `build_captureScreenshot` errors or times out for a route, mark that `migration_page_route_verification_*` item `failed` with `failureReason` naming the path and outcome (prefix `page_route_screenshot_timeout:` or `page_route_screenshot_error:`). Do **not** mark `completed`. Do **not** substitute router/source inspection.\n\n### Evidence required per route\n\nMark `completed` only when **all** are true:\n\n1. The app preview is on **that route's path** (not merely the default route).\n2. `build_captureScreenshot` **succeeds** and returns an image you inspect.\n3. You **describe** what you see and confirm it is not a loading-only view (follow the screenshot tool's skeleton/spinner retry procedure first).\n4. Any route-specific runtime errors are resolved (re-check after fixes).\n\n### Procedure (one route at a time)\n\n1. Enumerate checklist items whose IDs start with `migration_page_route_verification_`.\n2. Enumerate paths from `scratch/v2-backup/router.tsx` (fallback: `scratch/v2-backup/pages/**/index.tsx` confirmed against `client/router.tsx`).\n3. For each route: set the matching item `in_progress` \u2192 navigate the preview to that path (`browser_playwright_action` when available; otherwise use the editor route picker / navigation mechanism \u2014 **do not** screenshot whatever route happens to be visible) \u2192 `build_captureScreenshot` \u2192 on success, `completed`.\n4. If the preview looks stale, `build_reloadFile` **once**, then retry screenshot. If capture still fails, `failed` with `failureReason` as above.\n5. Fix import/lazy-load/runtime failures, then repeat from step 3 for that route.\n\n### Forbidden shortcuts\n\n- Marking `completed` because `client/router.tsx` lists the path\n- Marking `completed` because the page module exists under `client/pages/`\n- Marking `completed` after screenshot timeout/error\n- Batch-marking all route items without per-route screenshot evidence\n\nFor each converted API, self-check:\n\n1. File default-exports exactly one `api({...})`; `name` matches `metadata.name`.\n2. Zero `${\u2026}` interpolations remain in any SQL string.\n3. No SQL `IN (\u2026)` built by concatenation; dynamic lists use `= ANY($N::<type>[])`.\n4. Every prior block's `.output` read is replaced by an actual result `const`.\n5. Input is the minimal union of identifiers the YAML references that are not produced by earlier blocks or `Variables`.\n6. Output shape exactly mirrors the legacy API's external response.\n7. If `server/apis/index.ts` exists, it registers the new module under `metadata.name`.\n\n## Parallelization policy\n\nCount pending APIs from the checklist (`build_manageChecklist` `action: \"get\"`, filter `status: \"pending\"` and API-migration origins: `origin: \"2.0-upgrade\"` or legacy `origin: \"seed_api\"`).\n\n- **If the pending count is `< 8`:** migrate the APIs yourself, sequentially. Do NOT call `spawnCodingSubagents`. Work through each API using the per-API procedure below.\n- **If the pending count is `>= 8`:** you **MUST spawn sub-agents** to migrate these APIs in parallel. There are too many APIs to migrate sequentially yourself. Do NOT attempt to migrate APIs yourself in this run \u2014 use `spawnCodingSubagents`.\n  - Split the APIs into batches of ~5 (aim for 4\u20136 per batch), with a hard cap of **5 sub-agents total**. If more than 25 APIs remain, give later batches larger shares rather than spawning more than 5 workers.\n  - For each batch, craft an `instructions` string that:\n    - Names the exact `<ApiName>` values that sub-agent owns, verbatim, as a bulleted list.\n    - Restates the per-API procedure below so the sub-agent is self-contained.\n    - Reminds the sub-agent to update the shared checklist (id `api_<ApiName>`) for every item it owns.\n  - **Also pass `apiNames: [\"<ApiName1>\", \"<ApiName2>\", \u2026]` for every sub-agent**, listing the same names that appear in its `instructions`. The spawn tool stamps each `api_<ApiName>` checklist item with that sub-agent's `id` as `workerId` BEFORE fan-out, which lets the migration UI render one batch row per sub-agent in the chat sidebar. Forgetting `apiNames` is non-fatal (the sub-agents still run) but the sidebar checklist will fall back to one row per API instead of one per batch.\n  - **Call `spawnCodingSubagents` as the ONLY tool call in that turn.** Do not emit any other tool calls alongside it \u2014 no reads, no writes, no checklist updates. The tool blocks until every sub-agent finishes; you cannot do migration work \"while waiting\" because there is no waiting from your perspective \u2014 your next turn only begins after the tool returns. If you emit other tool calls in the same turn, you and the sub-agents will race on the shared checklist and corrupt state.\n  - **After `spawnCodingSubagents` returns** \u2014 only in a subsequent turn \u2014 read the checklist via `build_manageChecklist` with `action: \"get\"`. For any `failed` items, review the `failureReason`. Retry small numbers of recoverable failures yourself (sequentially, using the per-API procedure below). Leave deterministic failures as `failed`.\n\n## Per-API procedure\n\nFor APIs you migrate yourself, or that you embed in a sub-agent's `instructions`:\n\n1. Call `build_manageChecklist` with `action: \"update\"`, `itemId: \"api_<ApiName>\"`, `status: \"in_progress\"`.\n2. Read `scratch/v2-backup/apis/<ApiName>/api.yaml` and any sibling files the blocks reference.\n3. Produce the TypeScript module at `server/apis/<ApiName>/api.ts`, overwriting the stub. Use the YAML block \u2192 TS mapping in `skills/system/superblocks-migration/references/yaml-block-mapping.md`.\n4. If `server/apis/index.ts` exists, update it to register the new module.\n5. Call `build_debug`. If it fails, fix and repeat until it passes. Do not proceed to step 6 until `build_debug` succeeds.\n6. **Call `runMigrationVerification({ apiName: \"<ApiName>\", inputs: <inputs> })` and resolve every divergence in this same chat.** The tool's response includes `attempt` and `maxAttempts` so you don't need to track an attempt counter yourself \u2014 the server reads it from on-disk history per API.\n\n   Your job is to make v3 produce the same response as v2 \u2014 not to \"try a few times and punt to the user\". The user already lived with this API working on v2 with their real data; if v3 doesn't match, that's a regression you introduced, and you fix it here. NEVER leave a `diverged` API for the user to \"Accept divergence\" or \"Try one more attempt\" via the API calls panel \u2014 those buttons exist as escape hatches for situations the policy gate requires (mutations, denied integrations), not as a way for you to skip work.\n\n   Synthesize `inputs` the same way you would for `testApi`: inspect the v2 YAML from step 2 and the v3 TS from step 3, enumerate every binding the API references that isn't produced by an earlier block (component values like `Input1.value`/`Select1.selectedItem.id`, table selections like `Table1.selectedRow`, state variables, workflow `body`/`params`), and pick a realistic mock value for each matching the binding's expected type. Both v2 and v3 receive the same `inputs`, so this is what makes the diff meaningful \u2014 `{}` for an API with bindings produces a vacuous `both_failed` that tells you nothing.\n\n   Outcomes and how to resolve them:\n   - **`passed`**: call `build_manageChecklist` with `status: \"completed\"`. Done.\n\n   - **`skipped_mutation`**: this is a policy gate, not a deterministic pass. Do **NOT** mark the checklist item `completed` yet. Leave it unresolved (keep `in_progress`), continue processing other APIs, and resolve all skipped items in one grouped decision at the end of the run (see \"Mutation policy follow-up\" below).\n\n   - **`v2_unrunnable`**: the v2 backup itself couldn't execute, so there is no baseline to match. Call `build_manageChecklist` with `status: \"completed\"` and continue.\n\n   - **`both_failed`**:\n     - If you passed `inputs: {}` and the API references bindings: synthesize real `inputs` (per the bullet above) and retry. Do NOT mark completed here \u2014 empty inputs caused this, not a real failure.\n     - If you passed real inputs and v2 still failed: read v2's error. If it is environmental (auth/credentials/integration-unavailable: \"no integration configured\", \"401\", \"ECONNREFUSED\", \"missing API key\"), v2 cannot run in this verification context regardless of what you do \u2014 call `build_manageChecklist` with `status: \"completed\"` and continue; the user will verify manually. If it's a v2 runtime error that v3 also reproduces, treat as `diverged` (your inputs are wrong, or the API expects state that isn't reproducible here \u2014 revise inputs and retry).\n\n   - **`error`**: a system error in the verification flow itself (cannot read v3 source, etc.). Fix what you can; if it persists across one retry, mark the item `failed` with `failureReason: \"<error detail>\"` and continue.\n\n- **`diverged`**: the API ran on both sides and the outputs differ. **Iterate until v3 matches v2 byte-for-byte (modulo the normalizations api-comparator already applies: identical ISO timestamps, near-now ISO timestamps within \u00B160s of each other and \u00B15min of \"now\", UUIDs, monotonic integer IDs differing by \u22641 on fields whose leaf ends with \"id\", floats within 1e-9 relative tolerance, and per-request opaque identifiers at leaves named `requestId`/`traceId`/`spanId`/`correlationId`/`sessionId`/`nonce`/`csrfToken`/`_id` \u2014 note: a bare leaf named `token` is intentionally NOT normalized, since auth/access-token divergence is a security-relevant signal we want to surface).**\n\n  There is one bounded judgment exception: if both v2 and v3 executions succeeded, the output shape/types are equivalent, and the remaining diffs are value-level fields you reasonably infer are inherently non-deterministic outputs for this API, treat the migration as semantically complete for this run. In that case, mark the checklist item `completed` and continue.\n\n  Use this exception only when all of the following are true:\n  - The divergence is not structural (no missing/extra fields, no type mismatch, no changed nesting/cardinality, no changed error/status behavior).\n  - The differing fields are expected to vary per invocation and do not change control flow decisions.\n  - The API's functional contract remains intact for downstream consumers.\n\n  If any of those conditions are not met, the divergence is semantic and must be fixed \u2014 do NOT add code purely to mask values the comparator already tolerates.\n\n  For each `summaryForAgent` entry \u2014 every entry names the JSON path that diverged and the v2/v3 values \u2014 find the block in `server/apis/<ApiName>/api.ts` that produces that path and fix the discrepancy. Common causes, in rough order of frequency:\n  - wrong column projection or missing field in a SELECT\n  - missing transform / output shape mismatch (array vs object wrapper, single vs list)\n  - off-by-one or wrong placeholder in a SQL parameter\n  - mistyped binding key (case, plural, dotted path)\n  - type coercion (string vs number, null vs undefined, boolean vs \"true\")\n  - missing default value when the binding is undefined\n  - wrong join order or implicit ordering of rows\n  - filter/where condition different from v2\n  - missing `LIMIT`, `OFFSET`, or pagination handling\n\n  If a divergence stems from the `inputs` you passed (e.g. v2 echoes the input one way and v3 a different way because they normalize it differently), revise the inputs alongside the source.\n\n  Then call `build_debug` (fix any failures), then `runMigrationVerification` again with the revised source/inputs.\n\n  **There is no fixed retry budget \u2014 iterate until `passed` or until you have firm structural evidence that no v3 source change can reconcile v2 and v3.** Acceptable evidence for stopping: v2 references a YAML construct with no v3 SDK equivalent and the divergence is in that construct; v2 derives a value from runtime state v3 cannot observe (e.g. an env var that differs by environment). When you stop on structural grounds, mark the item `failed` with `failureReason: \"verification_diverged_irreconcilable: <one-paragraph reason naming the specific summaryForAgent entry and the structural reason> | summary: <JSON.stringify(summaryForAgent)>\"`.\n\n  Guardrail against infinite loops (NOT a retry budget): if you have iterated 8 times on the same API and the set of divergences has not materially changed across the last 3 attempts (i.e. you are flailing, not converging), stop and mark `failed` with the same `failureReason` shape. If you ARE converging \u2014 fewer divergences each attempt, or the remaining ones look smaller \u2014 keep going past 8.\n\n## Run-level rules\n\n- Do NOT emit a free-text UNRESOLVED report \u2014 every unresolved item must be a `failed` checklist entry with a `failureReason`.\n- Do NOT stop the run because one API failed. Only stop once every API is either `completed` or `failed`.\n\n## Mutation policy follow-up (required once per run if any API returned `skipped_mutation`)\n\nAfter you've done everything deterministic (all non-skipped APIs settled), if one or more APIs ended with `skipped_mutation`, call **one** grouped `askMultiChoice` with exactly these options:\n\n- `Mark all untested APIs as complete`\n- `Test them, and you'll be prompted for permission`\n\nThen:\n\n1. If user picks **`Mark all untested APIs as complete`**:\n   - For each skipped API checklist item, call `build_manageChecklist` update \u2192 `status: \"completed\"`.\n2. If user picks **`Test them, and you'll be prompted for permission`**:\n   - Clear persisted write-policy first so `deny`/`ask` modal state does not keep forcing `skipped_mutation`:\n     - read `scratch/migration-state.json`\n     - remove the `integrationWritePolicy` field\n     - write the file back\n   - Then run `testApi` for each skipped API so the runtime can prompt the user for write approval in-context.\n   - After user approvals and tests settle, update checklist status accordingly (`completed` on success, `failed` with concrete `failureReason` on deterministic blockers).\n\n## Post-batch re-verification\n\nAfter `spawnCodingSubagents` returns (or after all sequential APIs are settled), before updating the checklist overall status:\n\n1. Call `build_manageChecklist` with `action: \"get\"` and read all items.\n2. For any item where `verificationOutcome === \"auto_passed\"` and `lastVerificationAt` is older than any sibling item's `updatedAt` minus 60 seconds: this item may have drifted due to registry edits made by later sub-agents. Re-run `runMigrationVerification({ apiName, inputs: <inputs> })` for each such item \u2014 synthesize `inputs` the same way as in step 6 of the per-API procedure.\n3. If any re-verification produces `diverged`, apply the normal per-API diverge\u2192retry loop (no fixed retry budget; iterate until `passed` or firm structural-irreconcilability evidence, with the anti-flail guardrail at 8 iterations without convergence).\n4. Proceed to mark overall checklist completed/failed only after all re-verifications settle.\n";
 //# sourceMappingURL=skill.generated.d.ts.map

package/dist/ai-service/skills/system/superblocks-migration/skill.generated.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"skill.generated.d.ts","sourceRoot":"","sources":["../../../../../src/ai-service/skills/system/superblocks-migration/skill.generated.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,OAAO,~~i0VAqInB~~,CAAC"}
1	+ {"version":3,"file":"skill.generated.d.ts","sourceRoot":"","sources":["../../../../../src/ai-service/skills/system/superblocks-migration/skill.generated.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,OAAO,s23BAyQnB,CAAC"}