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

package/dist/ai-service/prompt-builder-service/types.d.ts

@@ -1,20 +1,9 @@
-import type { NodePath, Node } from "@babel/traverse";
 import { z } from "zod";
-import { type PromptClassification, type SbElement } from "@superblocksteam/library-shared/types";
-import type { ArtifactProcessor, FileArtifact, SdkIntegration } from "../types.js";
+import { type PromptClassification } from "@superblocksteam/library-shared/types";
+import type { FileArtifact, SdkIntegration } from "../types.js";
 export declare const PromptClassificationEnum: z.ZodEnum<[string, ...string[]]>;
-export interface ComponentTarget {
-    bindName: string | undefined;
-    elementId: SbElement;
-    tagName: string;
-    filePath: string;
-    isCustomComponent: boolean;
-    nodePath: NodePath<Node>;
-}
 export interface PromptBuildOptions {
     classification: PromptClassification;
-    artifactProcessor: ArtifactProcessor;
-    componentTargets?: ComponentTarget[];
     workingDirectory?: string;
     integrationPromptContent?: SdkIntegration[];
     unresolvedIntegrations?: string[];

package/dist/ai-service/prompt-builder-service/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/ai-service/prompt-builder-service/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,SAAS,EACf,MAAM,uCAAuC,CAAC;AAE/C,OAAO,KAAK,EACV,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACf,MAAM,aAAa,CAAC;AAErB,eAAO,MAAM,wBAAwB,kCAKpC,CAAC;AACF,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,SAAS,EAAE,SAAS,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC,cAAc,EAAE,oBAAoB,CAAC;IACrC,iBAAiB,EAAE,iBAAiB,CAAC;IAIrC,gBAAgB,CAAC,EAAE,eAAe,EAAE,CAAC;IACrC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B,wBAAwB,CAAC,EAAE,cAAc,EAAE,CAAC;IAC5C,sBAAsB,CAAC,EAAE,MAAM,EAAE,CAAC;IAClC,aAAa,CAAC,EAAE,YAAY,EAAE,CAAC;IAC/B,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/ai-service/prompt-builder-service/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,uCAAuC,CAAC;AAE/C,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAEhE,eAAO,MAAM,wBAAwB,kCAKpC,CAAC;AAEF,MAAM,WAAW,kBAAkB;IACjC,cAAc,EAAE,oBAAoB,CAAC;IAErC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B,wBAAwB,CAAC,EAAE,cAAc,EAAE,CAAC;IAC5C,sBAAsB,CAAC,EAAE,MAAM,EAAE,CAAC;IAClC,aAAa,CAAC,EAAE,YAAY,EAAE,CAAC;IAC/B,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B"}

package/dist/ai-service/prompt-builder-service/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/ai-service/prompt-builder-service/types.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EACL,iCAAiC,GAGlC,MAAM,uCAAuC,CAAC;AAQ/C,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,IAAI,CAC5C,MAAM,CAAC,IAAI,CAAC,iCAAiC,CAAC,CAAC,MAAM;AACnD,wCAAwC;AACxC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,UAAU,CACH,CAC3B,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/ai-service/prompt-builder-service/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EACL,iCAAiC,GAElC,MAAM,uCAAuC,CAAC;AAI/C,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,IAAI,CAC5C,MAAM,CAAC,IAAI,CAAC,iCAAiC,CAAC,CAAC,MAAM;AACnD,wCAAwC;AACxC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,UAAU,CACH,CAC3B,CAAC"}

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

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

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

@@ -7,6 +7,9 @@ import { content as superblocks_api_references_sql_databases } from "./superbloc
 import { content as superblocks_api_skill } from "./superblocks-api/skill.generated.js";
 import { content as superblocks_frontend_references_embedding } from "./superblocks-frontend/references/embedding.generated.js";
 import { content as superblocks_frontend_skill } from "./superblocks-frontend/skill.generated.js";
+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";
 /**
  * Map of skill file paths to their content.
  * Keys are relative paths from skills/system/ (e.g., "superblocks-frontend/SKILL.md")
@@ -19,5 +22,8 @@ export const SYSTEM_SKILLS = {
     "superblocks-api/references/sql-databases.md": superblocks_api_references_sql_databases,
     "superblocks-frontend/SKILL.md": superblocks_frontend_skill,
     "superblocks-frontend/references/embedding.md": superblocks_frontend_references_embedding,
+    "superblocks-migration/SKILL.md": superblocks_migration_skill,
+    "superblocks-migration/references/focused-debug.md": superblocks_migration_references_focused_debug,
+    "superblocks-migration/references/yaml-block-mapping.md": superblocks_migration_references_yaml_block_mapping,
 };
 //# sourceMappingURL=_registry.generated.js.map

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

@@ -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;AAElG;;;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;CAC1F,CAAC"}
+{"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;AAEpG;;;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;CAC9G,CAAC"}

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

@@ -0,0 +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";
+//# sourceMappingURL=focused-debug.generated.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,58 @@
+// Auto-generated from src/ai-service/skills/system/superblocks-migration/references/focused-debug.md
+// Do not edit directly - edit the .md file instead
+export const content = `# Focused retry playbook
+
+Reference for \`superblocks-migration/SKILL.md\`. Load this **only** when the runtime prompt tells you this is a focused-retry turn.
+
+This is a _retry_ attempt. Earlier runs already tried — and failed — 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.
+
+## 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.
+
+Only address the APIs surfaced by that query — the rest of the app is already migrated.
+
+## Step 2: debugging checklist (work through this before editing)
+
+- Did the prior attempt misread the integration kind? Re-check \`node_modules/@superblocksteam/sdk-api/src/index.ts\` for the correct factory export.
+- Was the YAML using a block construct you skipped (\`conditional\`, \`parallel\`, \`tryCatch\`, \`loop\`, \`variables\`, inline \`javascript\`)? Translate it explicitly instead of bailing.
+- 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\`.
+- Was the item marked \`failed\` because a target file (\`index.ts\`, a stub path) was "missing"? Confirm on disk — create nothing you were not told to create, but do not bail if the file actually exists.
+- Was a SQL statement's parameter shape wrong (scalar vs array, pg type cast)? Use \`= ANY($N::<type>[])\` for lists.
+- Prefer the **narrowest** rewrite that compiles and preserves behavior. If a full rewrite failed, try converting block-by-block.
+- 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.
+
+## Meta-rule override: when the blocker is _information_, call \`askMultiChoice\` — DO NOT mark \`failed\`
+
+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.
+
+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
+
+1. 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.
+2. 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.
+3. The user only sees tool calls — a free-text question from you will sit there unanswered forever and this turn will be wasted.
+
+### How to structure the \`askMultiChoice\` call
+
+- **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.
+- \`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.
+- \`choices\`: 2 or 3 entries. The first 1–2 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\` — this is the user's escape hatch for APIs they don't need.
+- \`selectionType\`: \`"single"\`.
+
+### After the user responds
+
+- 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.
+- 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"\`.
+- 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".
+
+### Self-check before you respond
+
+Ask 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.
+
+## Then execute
+
+Use the per-API procedure in \`SKILL.md\` for the actual translation work, but treat the prior \`failureReason\` as primary context when choosing your approach.
+`;
+//# sourceMappingURL=focused-debug.generated.js.map

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

@@ -0,0 +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"}

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

@@ -0,0 +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";
+//# sourceMappingURL=yaml-block-mapping.generated.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,107 @@
+// Auto-generated from src/ai-service/skills/system/superblocks-migration/references/yaml-block-mapping.md
+// Do not edit directly - edit the .md file instead
+export const content = `# YAML block → TypeScript mapping
+
+Reference for \`superblocks-migration/SKILL.md\`. Covers how each legacy block type in \`api.yaml\` maps to the new \`@superblocksteam/sdk-api\` TypeScript format.
+
+## Integration-backed blocks (SQL, REST, vendor plugins)
+
+Shape in YAML:
+
+\`\`\`yaml
+step:
+  name: <BlockName>
+  integration: <uuid> # OR a plugin key like "restapi"
+  <plugin>: # e.g. postgresql, snowflake, restapi, openApiAction
+    body: | # SQL, request body, etc.
+      ...
+    parameters:
+      - name: <n>
+        value: <expr>
+\`\`\`
+
+### SQL integrations (PostgreSQL, MySQL, Snowflake, Databricks, etc.)
+
+- Rows returned (\`SELECT\`, \`SHOW\`, \`RETURNING *\`) → \`await ctx.integrations.<key>.query(sql, Schema, params)\` with a Zod schema.
+- No rows actionable (\`INSERT\` w/o \`RETURNING\`, \`UPDATE\`, \`DELETE\`, DDL) → \`await ctx.integrations.<key>.execute(sql, params)\`.
+- **Parameterize everything.** Zero \`\${…}\` inside the SQL string. Dynamic lists use \`= ANY($N::<type>[])\`, never string-concatenated \`IN (…)\`.
+
+### REST / OpenAPI / vendor plugin blocks
+
+- \`openApiAction\`, \`restapi:\`, and vendor plugin keys (e.g. \`salesforce:\`, \`stripe:\`, \`openai:\`) → the matching factory from the sdk-api barrel (\`node_modules/@superblocksteam/sdk-api/src/index.ts\`).
+- Never emit \`openapi(...)\`, \`http(...)\`, or \`openApiAction(...)\` — those are not sdk-api factories.
+- Client method names come from the integration README — never invent them. If the README only documents \`apiRequest\`, use \`apiRequest\`.
+
+## JavaScript blocks
+
+\`\`\`yaml
+step:
+  name: <BlockName>
+  integration: javascript
+  javascript:
+    body: |
+      ...JS code...
+\`\`\`
+
+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.
+
+## Control-flow blocks
+
+| YAML block                        | TS construct                                                             |
+| --------------------------------- | ------------------------------------------------------------------------ |
+| \`conditional:\` (if / else)        | \`if (...) { ... } else { ... }\` around the nested block TS               |
+| \`loop:\` with \`type: TYPE_FOREACH\` | \`for (const x of xs) { ... }\` with **sequential** \`await\` (default)      |
+| \`loop:\` with \`type: TYPE_WHILE\`   | \`while (cond) { ... }\`                                                   |
+| \`parallel:\` (explicit)            | \`await Promise.all(xs.map(async x => ...))\`                              |
+| \`variables:\`                      | \`const\`s in the enclosing scope                                          |
+| \`throw:\`                          | \`throw new Error(...)\` (or the sdk-api error class the README documents) |
+| \`return:\`                         | \`return ...;\` from \`run\`                                                 |
+| \`tryCatch:\`                       | \`try { ... } catch (err) { ... }\`                                        |
+| \`break:\`                          | \`break;\`                                                                 |
+
+Only use \`Promise.all\` when the YAML explicitly uses a \`parallel:\` block. A plain \`TYPE_FOREACH\` is sequential by contract — do not silently parallelize it.
+
+## Per-block \`.output\` references
+
+Legacy blocks expose \`<BlockName>.output\` to downstream blocks. In the TS port each block's result is a local \`const\`:
+
+\`\`\`ts
+const users = await ctx.integrations.pg.query(USERS_SQL, UsersSchema, [orgId]);
+// downstream: reference \`users\`, not \`GetUsers.output\`
+\`\`\`
+
+## Metadata mapping
+
+- \`metadata.name\` → the string passed to \`api({ name: "<metadata.name>" })\` and the file base name (kebab-case).
+- \`metadata.description\` → the \`description\` field on \`api({ ... })\` if the sdk-api contract supports it (check the README; do not invent fields).
+- \`authorization.type: AUTHORIZATION_TYPE_APP_USERS\` → 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\`.
+
+## Inputs
+
+The YAML's \`apiInputs\` (or equivalent) enumerates the externally-accepted parameters. In the TS port:
+
+- Declare them on the \`input\` shape passed to \`run(ctx, input)\`.
+- Drop any input that is now sourced from \`ctx.user\` or from \`ctx.integrations.<key>\` state.
+- Keep the **minimal** union of identifiers the YAML actually references downstream.
+
+## Integration UUIDs
+
+Every distinct \`step.integration\` UUID in a YAML becomes a named \`const\` at the top of the TS file — one \`const\` per unique integration, reused by every \`ctx.integrations.<key>\` call. Do not inline UUIDs. Do not carry UUIDs across files.
+
+\`\`\`ts
+const PG_MAIN = "550e8400-e29b-41d4-a716-446655440000";
+
+const db = ctx.integrations.pg(PG_MAIN);
+const rows = await db.query(...);
+\`\`\`
+
+(Exact binding form depends on the sdk-api contract — confirm against the README.)
+
+## What NOT to emit
+
+- \`// TODO\` or \`// FIXME\` comments that silently ship — unresolved items live only as \`failed\` checklist entries.
+- Narrative code comments ("this step fetches users"). Code should read directly.
+- Retry wrappers, caching layers, or extra logging beyond the single \`ctx.log.info("<ApiName> start", {...})\` at the top of \`run\`.
+- Envelope wrappers around the response — the external output shape must mirror the legacy API exactly.
+`;
+//# sourceMappingURL=yaml-block-mapping.generated.js.map

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

@@ -0,0 +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"}

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

@@ -0,0 +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";
+//# sourceMappingURL=skill.generated.d.ts.map

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

@@ -0,0 +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"}

package/dist/ai-service/skills/system/superblocks-migration/skill.generated.js

@@ -0,0 +1,137 @@
+// Auto-generated from src/ai-service/skills/system/superblocks-migration/SKILL.md
+// Do not edit directly - edit the .md file instead
+export const content = `---
+name: superblocks-migration
+description: |
+  Convert legacy Superblocks 2.0 YAML APIs ("block-chain" format) to the new 3.0 sdk-api TypeScript format.
+  Load when executing a v2→v3 migration turn — the runtime prompt will tell you to.
+readOnly: true
+metadata:
+  author: superblocks
+  version: "1.0"
+---
+
+# v2 → v3 API Translation
+
+You 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.
+
+## Meta-rule: ZERO judgment calls
+
+If 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.
+
+Corollary: do not add \`// TODO\` comments that silently ship. Unresolved items live only as \`failed\` checklist entries.
+
+## Inputs and outputs
+
+- **Source tree:** \`scratch/v2-backup/apis/<ApiName>/api.yaml\`. Discover the actual set by listing the directory — do not hardcode a count or list.
+- **Target tree:** \`server/apis/<ApiName>/api.ts\`. Do not create scaffolding trees that do not already exist (see "Registry registration" below).
+- **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"\` — that is your authoritative API list and count for this turn.
+
+## Required reading (read these BEFORE writing any output)
+
+Authoritative. If a rule here conflicts with your priors, these win.
+
+1. \`node_modules/@superblocksteam/sdk-api/README.md\` — whole thing (api() contract, execution model, \`ctx.*\`, exports, error classes, performance best practices, \`useApi\` frontend hook, integration method table).
+2. \`node_modules/@superblocksteam/sdk-api/src/index.ts\` (the **barrel**) — 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.
+3. The README for **every integration** referenced by the YAMLs you convert:
+   - \`node_modules/@superblocksteam/sdk-api/src/integrations/<kind>/README.md\`
+   - 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.
+4. \`skills/system/superblocks-migration/references/yaml-block-mapping.md\` — full YAML → TS mapping for each legacy block type.
+
+There is **no \`javascript\` integration** in sdk-api — inline JS/TS lives directly inside \`run(ctx, input)\`. Any block whose YAML key is \`javascript:\` becomes plain TypeScript in \`run()\`.
+
+## Preflight gate (MUST pass before any file edits)
+
+Complete this orientation sequence before writing or modifying any API file:
+
+1. Call \`build_manageChecklist\` with \`action: "get"\` and filter to \`origin: "seed_api"\` \`status: "pending"\` — this is your authoritative API list and count for this turn.
+2. Read \`node_modules/@superblocksteam/sdk-api/src/index.ts\` and treat it as the **only** source of truth for sdk-api export/factory names.
+3. Read \`node_modules/@superblocksteam/sdk-api/README.md\`.
+4. 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.
+
+Hard constraints:
+
+- Do **not** rely on prior conversation memory, "knowledge" summaries, or inferred export names.
+- Do **not** start editing API files until preflight steps 1–3 are complete.
+- If a required file cannot be read, mark that API's checklist item \`failed\` with a concrete \`failureReason\` that names the missing path.
+
+## File layout & exports
+
+- One API per file, default export: \`export default api({ ... });\`.
+- Use ESM-style relative \`.js\` specifiers in imports.
+- File path: \`server/apis/<ApiName>/api.ts\` where \`<ApiName>\` is the YAML \`metadata.name\` (for example, \`GetFloors\` → \`server/apis/GetFloors/api.ts\`).
+- The \`api({ name })\` string and the registry key must both equal the YAML \`metadata.name\` verbatim — frontends call \`useApi("<metadata.name>")\`.
+
+### Registry registration (conditional)
+
+- If \`server/apis/index.ts\` exists in the target tree: add an import + entry for each new module. Do not reorder existing entries.
+- 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.
+
+## Critical rules
+
+1. **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.
+2. **SQL: parameterize always.** Zero \`\${…}\` interpolations may remain inside any SQL string. Dynamic lists use \`= ANY($N::<type>[])\` — never string-building \`IN (…)\`.
+3. **\`query\` vs \`execute\`.** Rows returned → \`query\` with Zod schema. Nothing actionable → \`execute\`.
+4. **Output shape preservation.** Mirror the legacy API's externally-visible response exactly — shape, nullability, cardinality. Do not wrap in envelopes.
+5. **Default is sequential.** \`TYPE_FOREACH\` → \`for ... of\` with sequential \`await\`. \`Promise.all\` only when YAML explicitly used a \`parallel:\` block.
+6. **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.
+7. **Never invent client methods.** If the integration README only documents \`apiRequest\`, use \`apiRequest\`.
+
+## Security / user identity
+
+- \`authorization.type: AUTHORIZATION_TYPE_APP_USERS\` is enforced by the server; rely on \`ctx.user\` in TS.
+- If the YAML accepts \`userId\` / \`email\` / etc. as API input, remove that input and read from \`ctx.user\` instead.
+
+## Observability
+
+- One \`ctx.log.info("<ApiName> start", { <safe-ids> })\` at the top of \`run\` is allowed. Never log secrets, tokens, or PII.
+
+## Verification before you hand off
+
+Runtime verification (required):
+
+1. \`build_debug\` passing is required but not sufficient. Do not treat compile/typecheck success as proof that runtime behavior is correct.
+2. 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\`.
+3. 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.
+
+For each converted API, self-check:
+
+1. File default-exports exactly one \`api({...})\`; \`name\` matches \`metadata.name\`.
+2. Zero \`\${…}\` interpolations remain in any SQL string.
+3. No SQL \`IN (…)\` built by concatenation; dynamic lists use \`= ANY($N::<type>[])\`.
+4. Every prior block's \`.output\` read is replaced by an actual result \`const\`.
+5. Input is the minimal union of identifiers the YAML references that are not produced by earlier blocks or \`Variables\`.
+6. Output shape exactly mirrors the legacy API's external response.
+7. If \`server/apis/index.ts\` exists, it registers the new module under \`metadata.name\`.
+
+## Parallelization policy
+
+Count pending APIs from the checklist (\`build_manageChecklist\` \`action: "get"\`, filter \`origin: "seed_api"\` \`status: "pending"\`).
+
+- **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.
+- **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 — use \`spawnCodingSubagents\`.
+  - Split the APIs into batches of ~5 (aim for 4–6 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.
+  - For each batch, craft an \`instructions\` string that:
+    - Names the exact \`<ApiName>\` values that sub-agent owns, verbatim, as a bulleted list.
+    - Restates the per-API procedure below so the sub-agent is self-contained.
+    - Reminds the sub-agent to update the shared checklist (id \`api_<ApiName>\`) for every item it owns.
+  - **Call \`spawnCodingSubagents\` as the ONLY tool call in that turn.** Do not emit any other tool calls alongside it — 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 — 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.
+  - **After \`spawnCodingSubagents\` returns** — only in a subsequent turn — 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\`.
+
+## Per-API procedure
+
+For APIs you migrate yourself, or that you embed in a sub-agent's \`instructions\`:
+
+1. Call \`build_manageChecklist\` with \`action: "update"\`, \`itemId: "api_<ApiName>"\`, \`status: "in_progress"\`.
+2. Read \`scratch/v2-backup/apis/<ApiName>/api.yaml\` and any sibling files the blocks reference.
+3. Produce the TypeScript module at \`server/apis/<ApiName>/api.ts\`, overwriting the stub. Use the YAML block → TS mapping in \`skills/system/superblocks-migration/references/yaml-block-mapping.md\`.
+4. If \`server/apis/index.ts\` exists, update it to register the new module.
+5. On success → \`build_manageChecklist\` with \`status: "completed"\`.
+6. On deterministic failure → \`build_manageChecklist\` with \`status: "failed"\` and a concrete \`failureReason\` (the rule that failed + what is needed to proceed). Continue with the next API.
+
+## Run-level rules
+
+- Do NOT emit a free-text UNRESOLVED report — every unresolved item must be a \`failed\` checklist entry with a \`failureReason\`.
+- Do NOT stop the run because one API failed. Only stop once every API is either \`completed\` or \`failed\`.
+`;
+//# sourceMappingURL=skill.generated.js.map

package/dist/ai-service/skills/system/superblocks-migration/skill.generated.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill.generated.js","sourceRoot":"","sources":["../../../../../src/ai-service/skills/system/superblocks-migration/skill.generated.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,mDAAmD;AAEnD,MAAM,CAAC,MAAM,OAAO,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqItB,CAAC"}

package/dist/ai-service/state-machine/clark-fsm.d.ts

@@ -1,7 +1,7 @@
 import type { LanguageModelV3 } from "@ai-sdk/provider";
 import type { FinishReason } from "ai";
 import type { ViteDevServer } from "vite";
-import type { AiGenerateRequest, Attachment, LLMProviderConfig, PromptContextIntegration, PromptContext, PromptContextEntity, KnowledgePromotionCapabilities, RememberKnowledgeCandidate, RuntimeErrorData, AiMode, PlanContext, AiMessagePush, AiGenerationState, AiToolPermission, BrowserContext, ConsoleLogEntry, ApiRunRecord, KnowledgeSaveOutcome } from "@superblocksteam/library-shared/types";
+import type { AiGenerateRequest, Attachment, LLMProviderConfig, PromptContextIntegration, PromptContext, PromptContextEntity, KnowledgePromotionCapabilities, RememberKnowledgeCandidate, RuntimeErrorData, AiMode, PlanContext, AiChatMessage, AiGenerationState, AiToolPermission, BrowserContext, ConsoleLogEntry, ApiRunRecord, KnowledgeSaveOutcome } from "@superblocksteam/library-shared/types";
 import type { AiPromptCostUsageEntry, TracedEventEmitter } from "@superblocksteam/shared";
 import type { OperationQueue } from "../../util/operation-queue.js";
 import type { EntityPermissionStore } from "../agent/tools2/entity-permissions.js";
@@ -26,7 +26,7 @@ import type { ClarkProfiler } from "../profiler/clark-profiler.js";
 import type { PromptInterpretTask } from "../prompt-builder-service/classifiers/prompt-interpret-task.js";
 import type { RecordingManager } from "../recording/index.js";
 import type { TemplateRenderer } from "../template-renderer.js";
-import type { AiServiceConfig, AiServiceEvents, ArtifactProcessor, ChangeInfo, EditorClient, FileArtifact, UserChange } from "../types.js";
+import type { AiServiceConfig, AiServiceEvents, ChangeInfo, EditorClient, FileArtifact, UserChange } from "../types.js";
 import type { FSMOnTransitionParams, FSMTransitionHandlerFactory } from "./fsm.js";
 import { TracedFSM, type TracedFSMStateSpanOptions, type TracedFSMTagProviderFactory } from "./traced-fsm.js";
 declare const $: {
@@ -72,8 +72,14 @@ export declare const V3_AGENT_FINISHED = "v3AgentFinished";
 export type ClarkEvent = {
     type: typeof USER_SENT_PROMPT;
     request: AiGenerateRequest;
-    peer: EditorClient;
-    peerId: string;
+    /**
+     * When true, the turn runs through the FSM normally but does NOT
+     * persist the user prompt to the chat session store or surface it
+     * in the UI chat pane. Used for system-initiated turns (e.g. the
+     * post-flip v2→v3 migration turn) where the "user" is the
+     * ai-service itself.
+     */
+    internal?: boolean;
 } | {
     type: typeof USER_ACCEPTED_DRAFT;
     silently?: boolean;
@@ -257,11 +263,8 @@ export declare class Clark extends TracedFSM<ClarkState, ClarkEvent, ClarkContex
      * @param services - Active Clark session services (chat store, context manager)
      * @param label - Short category tag, e.g. "Knowledge update"
      * @param content - Human-readable description of what happened
-     * @param options - Controls how the event is attributed in LLM context
      */
-    recordSystemMessage(services: Pick<ClarkStateHandlerParams, "chatSessionStore" | "contextManagerV2" | "applicationId">, label: string, content: string, options?: {
-        role?: "assistant" | "user";
-    }): Promise<void>;
+    recordSystemMessage(services: Pick<ClarkStateHandlerParams, "chatSessionStore" | "contextManagerV2" | "applicationId">, label: string, content: string): Promise<void>;
     private pushContextUsed;
 }
 export type ClarkTransition = FSMOnTransitionParams<ClarkState, ClarkEvent>;
@@ -303,8 +306,19 @@ export interface ApiTestingState {
     denied: Set<string>;
 }
 export type ClarkContext = {
-    peer?: EditorClient;
-    peerId?: string;
+    /**
+     * The editor peer RPC client. This is a permanent `StablePeer` proxy
+     * installed at Clark construction time; its inner WebSocket client is
+     * swapped on reconnect via `StablePeer.setInner(...)`. The reference on
+     * the context itself NEVER changes — do not reassign it via
+     * `updateContext({ peer })`. Callers can cache this reference freely and
+     * trust that `peer.call.*` routes to the currently-live socket (or queues
+     * transparently during the reconnect window).
+     *
+     * The peer's identity token (`peerId`) lives on the proxy itself; read it
+     * via `stablePeer.peerId` rather than tracking a separate context field.
+     */
+    peer: EditorClient;
     hasSuggestions?: boolean;
     summaryMessages?: {
         role: "user" | "assistant";
@@ -345,7 +359,7 @@ export type ClarkContext = {
         items: {
             id: string;
             content: string;
-            status: "pending" | "in_progress" | "completed" | "cancelled";
+            status: "pending" | "in_progress" | "completed" | "cancelled" | "failed";
             createdAt: string;
             updatedAt?: string;
         }[];
@@ -376,7 +390,7 @@ export type ClarkContext = {
     };
     activeInteractiveMessage?: {
         id: string;
-        payload: AiMessagePush;
+        payload: AiChatMessage;
     };
     /** Tracks integration action prompt sent after opening setup so responses can be handled deterministically */
     pendingIntegrationActionPrompt?: {
@@ -452,7 +466,6 @@ export type ClarkContext = {
 };
 export type ClarkStateHandlerParams = AiServiceConfig & {
     templateRenderer: TemplateRenderer;
-    artifactProcessor: ArtifactProcessor;
     appShell: AppShell;
     signals: TracedEventEmitter<AiServiceEvents>;
     fileSystemInterface: FileSystemInterface;