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

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

@@ -21,11 +21,13 @@ If any situation below is not resolved deterministically by this document, **STO
 
 Corollary: do not add \`// TODO\` comments that silently ship. Unresolved items live only as \`failed\` checklist entries.
 
+Corollary for \`migration_page_route_verification_*\`: see the _Page route verification_ section below — screenshot timeout/error → \`failed\`, never \`completed\`, never "verified via router/source inspection." The full rule (including the hard-rule restatements) lives there to avoid drift.
+
 ## 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.
+- **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"\`) — that is your authoritative API list and count for this turn.
 
 ## Required reading (read these BEFORE writing any output)
 
@@ -38,13 +40,35 @@ Authoritative. If a rule here conflicts with your priors, these win.
    - 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()\`.
+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()\`. 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\`).
+
+## Substituting unsupported integrations
+
+The 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 — they are still in your \`seed_api\` checklist and you are expected to make a best-effort port rather than immediately marking them \`failed\`.
+
+Substitution rules (apply in order; first match wins):
+
+1. **\`python:\` step → 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(...)\` → \`fetch(...)\`, list comprehensions → \`array.map\`/\`filter\`, \`len(x)\` → \`x.length\`, dict access → object property access, \`os.environ[...]\` → \`process.env[...]\`, raise/except → \`throw\`/\`try…catch\`). 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 — do not ship a guess.
+2. **HTTP-shaped vendor plugin → 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 — check \`node_modules/@superblocksteam/sdk-api/src/index.ts\`).
+3. **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"\`).
+
+Do **not** silently skip a step or replace it with a \`// TODO\` — every API still needs a deterministic outcome (\`completed\` or \`failed\`) on the checklist.
 
 ## 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.
+0. **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\` → \`recommendedUserDeps\` (each entry has \`name\`, \`version\`, and \`dev\`). Your job is to install that list — not to recompute it.
+   - Mark \`migration_dependency_verification\` as \`in_progress\` via \`build_manageChecklist\`.
+   - Read \`scratch/migration-state.json\` and extract \`recommendedUserDeps\`.
+   - If \`recommendedUserDeps\` is missing or empty, mark \`migration_dependency_verification\` as \`completed\` and continue to step 1.
+   - 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\`.
+   - **Failure semantics (covers every non-success outcome — no judgment calls):**
+     - On full success → mark \`migration_dependency_verification\` as \`completed\`.
+     - On **any** failure — full, partial (some packages installed, others did not), structured registry error (\`not_in_registry\`, \`registry_auth_failed\`, \`registry_unreachable\`), or unstructured error — 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.
+   - 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 — phrased as "pinned to latest, may need user confirmation: <names>" — 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.
+   - 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 — \`failed\` with a structured \`failureReason\` is the only way to record this.)
+1. Call \`build_manageChecklist\` with \`action: "get"\` and filter to \`status: "pending"\` and API-migration origins (\`origin: "2.0-upgrade"\` or legacy \`origin: "seed_api"\`) — 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.
@@ -52,7 +76,7 @@ Complete this orientation sequence before writing or modifying any API file:
 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.
+- Do **not** start editing API files until preflight steps 0–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
@@ -94,6 +118,38 @@ Runtime verification (required):
 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.
 
+Page route verification (required once per migration run):
+
+**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 — it **never** satisfies verification.
+
+**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."
+
+**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.
+
+### Evidence required per route
+
+Mark \`completed\` only when **all** are true:
+
+1. The app preview is on **that route's path** (not merely the default route).
+2. \`build_captureScreenshot\` **succeeds** and returns an image you inspect.
+3. You **describe** what you see and confirm it is not a loading-only view (follow the screenshot tool's skeleton/spinner retry procedure first).
+4. Any route-specific runtime errors are resolved (re-check after fixes).
+
+### Procedure (one route at a time)
+
+1. Enumerate checklist items whose IDs start with \`migration_page_route_verification_\`.
+2. Enumerate paths from \`scratch/v2-backup/router.tsx\` (fallback: \`scratch/v2-backup/pages/**/index.tsx\` confirmed against \`client/router.tsx\`).
+3. For each route: set the matching item \`in_progress\` → navigate the preview to that path (\`browser_playwright_action\` when available; otherwise use the editor route picker / navigation mechanism — **do not** screenshot whatever route happens to be visible) → \`build_captureScreenshot\` → on success, \`completed\`.
+4. If the preview looks stale, \`build_reloadFile\` **once**, then retry screenshot. If capture still fails, \`failed\` with \`failureReason\` as above.
+5. Fix import/lazy-load/runtime failures, then repeat from step 3 for that route.
+
+### Forbidden shortcuts
+
+- Marking \`completed\` because \`client/router.tsx\` lists the path
+- Marking \`completed\` because the page module exists under \`client/pages/\`
+- Marking \`completed\` after screenshot timeout/error
+- Batch-marking all route items without per-route screenshot evidence
+
 For each converted API, self-check:
 
 1. File default-exports exactly one \`api({...})\`; \`name\` matches \`metadata.name\`.
@@ -106,7 +162,7 @@ For each converted API, self-check:
 
 ## Parallelization policy
 
-Count pending APIs from the checklist (\`build_manageChecklist\` \`action: "get"\`, filter \`origin: "seed_api"\` \`status: "pending"\`).
+Count 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"\`).
 
 - **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\`.
@@ -115,6 +171,7 @@ Count pending APIs from the checklist (\`build_manageChecklist\` \`action: "get"
     - 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.
+  - **Also pass \`apiNames: ["<ApiName1>", "<ApiName2>", …]\` 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.
   - **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\`.
 
@@ -126,12 +183,87 @@ For APIs you migrate yourself, or that you embed in a sub-agent's \`instructions
 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.
+5. Call \`build_debug\`. If it fails, fix and repeat until it passes. Do not proceed to step 6 until \`build_debug\` succeeds.
+6. **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 — the server reads it from on-disk history per API.
+
+   Your job is to make v3 produce the same response as v2 — 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 — those buttons exist as escape hatches for situations the policy gate requires (mutations, denied integrations), not as a way for you to skip work.
+
+   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 — \`{}\` for an API with bindings produces a vacuous \`both_failed\` that tells you nothing.
+
+   Outcomes and how to resolve them:
+   - **\`passed\`**: call \`build_manageChecklist\` with \`status: "completed"\`. Done.
+
+   - **\`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).
+
+   - **\`v2_unrunnable\`**: the v2 backup itself couldn't execute, so there is no baseline to match. Call \`build_manageChecklist\` with \`status: "completed"\` and continue.
+
+   - **\`both_failed\`**:
+     - If you passed \`inputs: {}\` and the API references bindings: synthesize real \`inputs\` (per the bullet above) and retry. Do NOT mark completed here — empty inputs caused this, not a real failure.
+     - 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 — 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 — revise inputs and retry).
+
+   - **\`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.
+
+- **\`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 ±60s of each other and ±5min of "now", UUIDs, monotonic integer IDs differing by ≤1 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\` — note: a bare leaf named \`token\` is intentionally NOT normalized, since auth/access-token divergence is a security-relevant signal we want to surface).**
+
+  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.
+
+  Use this exception only when all of the following are true:
+  - The divergence is not structural (no missing/extra fields, no type mismatch, no changed nesting/cardinality, no changed error/status behavior).
+  - The differing fields are expected to vary per invocation and do not change control flow decisions.
+  - The API's functional contract remains intact for downstream consumers.
+
+  If any of those conditions are not met, the divergence is semantic and must be fixed — do NOT add code purely to mask values the comparator already tolerates.
+
+  For each \`summaryForAgent\` entry — every entry names the JSON path that diverged and the v2/v3 values — find the block in \`server/apis/<ApiName>/api.ts\` that produces that path and fix the discrepancy. Common causes, in rough order of frequency:
+  - wrong column projection or missing field in a SELECT
+  - missing transform / output shape mismatch (array vs object wrapper, single vs list)
+  - off-by-one or wrong placeholder in a SQL parameter
+  - mistyped binding key (case, plural, dotted path)
+  - type coercion (string vs number, null vs undefined, boolean vs "true")
+  - missing default value when the binding is undefined
+  - wrong join order or implicit ordering of rows
+  - filter/where condition different from v2
+  - missing \`LIMIT\`, \`OFFSET\`, or pagination handling
+
+  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.
+
+  Then call \`build_debug\` (fix any failures), then \`runMigrationVerification\` again with the revised source/inputs.
+
+  **There is no fixed retry budget — 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)>"\`.
+
+  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 — fewer divergences each attempt, or the remaining ones look smaller — keep going past 8.
 
 ## 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\`.
+
+## Mutation policy follow-up (required once per run if any API returned \`skipped_mutation\`)
+
+After 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:
+
+- \`Mark all untested APIs as complete\`
+- \`Test them, and you'll be prompted for permission\`
+
+Then:
+
+1. If user picks **\`Mark all untested APIs as complete\`**:
+   - For each skipped API checklist item, call \`build_manageChecklist\` update → \`status: "completed"\`.
+2. If user picks **\`Test them, and you'll be prompted for permission\`**:
+   - Clear persisted write-policy first so \`deny\`/\`ask\` modal state does not keep forcing \`skipped_mutation\`:
+     - read \`scratch/migration-state.json\`
+     - remove the \`integrationWritePolicy\` field
+     - write the file back
+   - Then run \`testApi\` for each skipped API so the runtime can prompt the user for write approval in-context.
+   - After user approvals and tests settle, update checklist status accordingly (\`completed\` on success, \`failed\` with concrete \`failureReason\` on deterministic blockers).
+
+## Post-batch re-verification
+
+After \`spawnCodingSubagents\` returns (or after all sequential APIs are settled), before updating the checklist overall status:
+
+1. Call \`build_manageChecklist\` with \`action: "get"\` and read all items.
+2. 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 — synthesize \`inputs\` the same way as in step 6 of the per-API procedure.
+3. If any re-verification produces \`diverged\`, apply the normal per-API diverge→retry loop (no fixed retry budget; iterate until \`passed\` or firm structural-irreconcilability evidence, with the anti-flail guardrail at 8 iterations without convergence).
+4. Proceed to mark overall checklist completed/failed only after all re-verifications settle.
 `;
 //# sourceMappingURL=skill.generated.js.map

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

@@ -1 +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"}
+{"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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyQtB,CAAC"}

package/dist/ai-service/skills/system/third-party-migration/claude-design.generated.d.ts

@@ -0,0 +1,2 @@
+export declare const content = "# Claude Design-specific mapping\n\nThis is a per-platform reference loaded from `SKILL.md`. The framework \u2014 target layout, universal mapping, non-negotiables, workflow, code-emission rules \u2014 lives there. This file documents only what is specific to a Claude Design source.\n\n> Claude Design is a prototype-design tool from Anthropic. Its \"Download project as .zip\" output is a tiny, self-contained, **frontend-only** prototype: a single `<Name>.html` shell that loads React, ReactDOM, and Babel from a CDN and `<script type=\"text/babel\" src=\"...\">` files that compile in the browser at run time. There is **no backend, no `package.json`, no build step, and no module system** \u2014 every helper is hung off `window.*` or pulled from globals. Treat the export as design-quality intent (layout, typography, color, interactions, copy) that needs to be re-expressed inside the Superblocks fullstack template (Vite + React + react-router v7 + Tailwind v4 + shadcn/ui). The framework's \"Don't fabricate a backend\" rule applies \u2014 if the source is purely UI driven by inline mock data, the migrated app stays frontend-only unless the user explicitly asks for one.\n\n## Where the source lives\n\nDefinitive marker: a flat archive (no nested project folder) containing exactly one top-level `<Name>.html` file plus sibling JSX/JS files, with the HTML loading React, ReactDOM, and `@babel/standalone` from `unpkg.com` and using `<script type=\"text/babel\" src=\"...\">` for the JSX files. No `package.json`, no `node_modules`, no `vite.config.*`, no `tsconfig.json`.\n\nStrong supporting signals:\n\n- The HTML root tag is `<html lang=\"...\" data-theme=\"light\">` (or `\"dark\"`); theme switching happens by mutating `data-theme` on `<html>` and CSS variables defined under `:root[data-theme=\"light\"]` / `:root[data-theme=\"dark\"]`.\n- A `tweaks-panel.jsx` sibling that defines a draggable in-canvas controls panel and exposes `useTweaks`, `TweaksPanel`, `TweakSection`, `TweakSlider`, `TweakRadio`, `TweakColor`, `TweakToggle` as window globals. The host protocol is `__activate_edit_mode` / `__deactivate_edit_mode` postMessage handshakes plus `__edit_mode_available` / `__edit_mode_set_keys` / `__edit_mode_dismissed` responses.\n- An `app.jsx` whose top has `const TWEAK_DEFAULTS = /*EDITMODE-BEGIN*/{ ... }/*EDITMODE-END*/;` \u2014 the `EDITMODE-BEGIN` / `EDITMODE-END` markers are how the Claude Design canvas locates and rewrites the defaults block.\n- A `data.js` (or similarly named sibling) that hangs sample data off `window.*`: e.g. `window.ORDERS = [...]; window.KPIS = [...];`. Components consume the globals directly (`/* global React, ReactDOM, ORDERS, KPIS, useTweaks, ... */` at the top of `app.jsx`).\n- Mounting happens at the bottom of `app.jsx` via `ReactDOM.createRoot(document.getElementById(\"root\")).render(<App />);` against a single `<div id=\"root\"></div>` in the HTML body.\n- Inline `<style>` block in `<head>` defines the entire visual system: a light + dark token palette under `:root[data-theme=\"...\"]`, body typography (commonly DM Sans + JetBrains Mono via Google Fonts), all component styles by hand-rolled BEM-ish class names (`.topbar`, `.brand`, `.kpi`, `.orders-table`, etc.). No Tailwind, no shadcn primitives in the source.\n\nIf the user gave a path, use it. Otherwise look for the markers above in the working tree. If you see a flat archive with `EDITMODE-BEGIN` markers and a CDN-loaded React shell, it is a Claude Design export. If anything is ambiguous (e.g. someone hand-built a similar HTML+JSX shell), ask before assuming Claude Design conventions.\n\n## Typical shape (hints, not rules)\n\nUse these as starting points; re-verify against the actual source tree on every migration.\n\n- **Frontend**: One HTML shell + one or more `.jsx` files compiled in-browser by `@babel/standalone`. Components are plain functions (`function App()`, `function KpiCard({ k, theme })`) that consume `React.useState` / `useMemo` / `useEffect` from a `const { useState, useMemo, useEffect } = React;` destructure. No imports, no JSX modules, no TypeScript.\n- **Styling**: Inline `<style>` in `<head>` with hand-written CSS, custom properties, and media queries. CSS variables drive the theme: `--bg`, `--surface`, `--ink`, `--accent`, `--line`, `--muted`, `--shadow-{sm,md,lg}`, etc. Dark mode flips the variable values under `:root[data-theme=\"dark\"]`.\n- **Fonts**: Google Fonts loaded via `<link>` in `<head>`; commonly DM Sans (UI) + JetBrains Mono (mono).\n- **Tweaks**: `tweaks-panel.jsx` is a self-contained controls overlay used during prototyping. The `useTweaks(TWEAK_DEFAULTS)` hook returns `[t, setTweak]`; `<TweaksPanel>` renders the floating controls inside the canvas. Every tweak control posts `__edit_mode_set_keys` to the parent frame so the Claude Design host can persist values.\n- **Data**: `data.js` defines synthetic sample data on `window.*`. Treat as fixtures, not production data.\n- **Backend**: None. There are no API calls, no `fetch`, no auth, no DB access in a typical export.\n- **Routing**: None. Single-page prototype; no `react-router` or hashes.\n- **Assets**: Inlined SVGs in JSX or referenced from inline `<style>` background-images. No `public/`, no separate image files in the typical export.\n\n## Discovery checklist\n\nIn addition to the framework's discovery requirements, for a Claude Design source enumerate:\n\n- The HTML shell file (`<Name>.html`) and the `<title>` it sets \u2014 that is the prototype's name and should anchor your `<PageName>`.\n- Every sibling `.jsx` / `.js` file and its purpose: which one is the entry (`app.jsx`), which is the tweaks shell (`tweaks-panel.jsx`), which holds data fixtures (`data.js` or similar).\n- The full `TWEAK_DEFAULTS` object between `/*EDITMODE-BEGIN*/` and `/*EDITMODE-END*/` \u2014 every key here corresponds to a runtime control; preserve every one in the migrated app or call out which you are dropping and why.\n- The full set of CSS variables defined under `:root[data-theme=\"light\"]` and `:root[data-theme=\"dark\"]` \u2014 these are the theme tokens to port.\n- Every Google Fonts family loaded in `<head>` and which CSS rules consume them.\n- Every `window.*` global the JSX files read (look for the `/* global ... */` comment at the top of `app.jsx`) \u2014 these are the data fixtures to recreate.\n- Every top-level component function in `app.jsx` and its responsibility (KPI tile, table, modal, toast, etc.). The migrated app keeps the same component breakdown.\n- Every inline SVG and its role (icons, sparklines, chart paths) \u2014 these go straight into the migrated JSX unchanged.\n- Whether the tweaks panel is purely visual (color, density, font size) or carries semantic state (filters, modes). Visual tweaks usually drop after migration; semantic tweaks become real React state on the page.\n\nIf the discovery summary doesn't tell you which CSS variables drive the theme, what every tweak controls, and what each component renders, you haven't discovered enough.\n\n## Core mapping\n\n- **The HTML shell + `app.jsx` \u2192 one Superblocks page** at `client/pages/<Name>/index.tsx`, wired into `client/router.tsx` (commonly as the `index: true` route). The page name comes from the HTML `<title>` or the `<Name>.html` filename \u2014 pick one shape and stay consistent.\n- **Drop the CDN script tags entirely.** React, ReactDOM, and `@babel/standalone` from `unpkg` have no role in the migrated app \u2014 the Vite template ships React via `node_modules` and compiles JSX at build time. Likewise drop the `<script type=\"text/babel\" src=\"...\">` references.\n- **Drop the `<html>` / `<body>` shell.** The Superblocks template owns the document. Mounting via `ReactDOM.createRoot(...)` also drops; the platform handles render.\n- **Translate the inline `<style>` block into Tailwind v4 + `client/index.css`:**\n  - The CSS variables under `:root[data-theme=\"light\"]` / `:root[data-theme=\"dark\"]` move into `client/index.css`'s `:root` and `.dark` blocks **as-is** (CSS Color Level 4 values stay as-is \u2014 do not convert to OKLCH; see the framework's \"Theme port\" rule). Wire them into Tailwind v4 via `@theme inline` so `bg-bg`, `text-ink`, `border-line` etc. resolve to the source tokens.\n  - The Google Fonts `<link>` tags become `@import url('https://fonts.googleapis.com/...')` at the top of `client/index.css`, with `@theme { --font-sans: 'DM Sans', ...; --font-mono: 'JetBrains Mono', ...; }` so `font-sans` / `font-mono` keep working. (See v0.md's font-port checklist for the three-step pattern.)\n  - Hand-rolled component CSS (`.topbar`, `.kpi`, `.orders-table`, etc.) translates into Tailwind utility classes on the corresponding JSX. Preserve spacing, sizing, color, shadow, and breakpoint behavior **exactly**. If a rule is too gnarly to express in utilities (complex animations, pseudo-element trickery), keep it in `client/index.css` under a scoped class \u2014 do not invent a new design.\n- **Theme switching.** The source toggles theme by mutating `<html data-theme=\"...\">`. Translate to a small custom provider that toggles `class=\"dark\"` on `document.documentElement` and persists to `localStorage` (mirroring the v0 `next-themes` translation). Preserve the source's CSS variable scheme (`:root` / `.dark` blocks) \u2014 only the JS toggle changes.\n- **Tweaks panel.** The Claude Design `tweaks-panel.jsx` is **canvas-only tooling** for the Claude Design host. It does not belong in the migrated app. Drop `tweaks-panel.jsx`, the `useTweaks` import, the `<TweaksPanel>` element, the `__activate_edit_mode` / `__deactivate_edit_mode` postMessage protocol, and the `EDITMODE-BEGIN` / `EDITMODE-END` markers entirely.\n  - **But preserve what the tweaks controlled.** For each tweak in `TWEAK_DEFAULTS`:\n    - **Visual-only tweaks** (theme, accent color, density, font size) \u2192 either drop and pin to the default value, or surface as a real settings UI if the user wants it. Ask before keeping; visual tweaks are usually prototype affordances, not product features.\n    - **Semantic tweaks** (active tab, selected filter, sort order, \"show kpis\" toggles) \u2192 become real React state on the page (`useState` defaulted to the value from `TWEAK_DEFAULTS`). The user's interactions drive them; there is no edit-mode panel.\n  - Surface the full list of tweaks and your decision per tweak in the discovery summary so the user can override.\n- **`data.js` / `window.*` globals.** These are mock fixtures, not real data. Two paths:\n  - **Default: keep as inline mock data inside the migrated page** (e.g., a `const ORDERS = [...]` at module scope, or a small `client/data/<name>.ts` module). The migrated app stays frontend-only and behaves like the prototype.\n  - **If the user wants a real backend**: surface the data shape in the discovery summary and ask before fabricating APIs. Per the framework's \"Don't fabricate a backend\" rule, do not invent server-side endpoints unless the user opts in. If they do, each `window.*` collection becomes one Superblocks API returning the same shape, and the page calls `useApiData(\"<ApiName>\")` instead of reading the global.\n- **Components.** Each top-level function in `app.jsx` (`KpiCard`, `OrdersTable`, `Checkbox`, `TrackingModal`, `BulkBar`, `Toast`, ...) becomes a sibling component file under `client/pages/<Name>/components/<Name>.tsx` (or stays inline if small). Function bodies, JSX structure, prop shapes, and event handlers transfer **unchanged** \u2014 only imports change (pull `useState` / `useMemo` / `useEffect` from `react` instead of destructuring from a `React` global, and add explicit `import React from \"react\"` only if JSX runtime requires it).\n- **Inline SVGs** (sparklines, icons, chart paths) move into the migrated JSX **verbatim**. Do not swap for `lucide-react` icons or other libraries unless the user asks; the source's SVGs are part of the design.\n- **Modals, toasts, and overlays.** Source uses raw `<div>` + CSS for these. Keep as-is in the migrated page \u2014 do not silently swap for shadcn `Dialog` / `Sonner` unless the user explicitly opts in. shadcn primitives change visual behavior (focus rings, animation, scrim color) and that is a design regression.\n- **Responsive breakpoints.** The source defines `@media (max-width: 900px)` rules in the inline `<style>`. Translate to Tailwind responsive prefixes (`sm:` / `md:` / `lg:`) on the corresponding utilities, matching the source's breakpoint values exactly.\n\n## Ask-before-guessing \u2014 Claude Design specifics\n\n- \"The export has no backend. I'll keep the data as inline mocks under `client/pages/<Name>/data.ts`. Want me to fabricate APIs for it instead, or leave it frontend-only?\"\n- \"The tweaks panel exposes `<list of tweaks>`. Visual tweaks (theme, accent, density) typically drop on migration; semantic tweaks become real page state. Confirm which to keep, drop, or surface as a settings UI.\"\n- \"The source uses Google Fonts `<list>` via CDN `<link>`. I'll re-load them via `@import` in `client/index.css` and bind via `@theme`. OK, or do you want self-hosted fonts?\"\n- \"The source switches themes by toggling `<html data-theme>`. I'll translate to a provider that toggles `class='dark'` on `document.documentElement`. Acceptable, or do you want a different theme-toggle shape?\"\n- \"The export ships hand-rolled UI components (modal, toast, table). I'll keep them as-is rather than swapping in shadcn primitives, since shadcn would change the visual behavior. Confirm, or override per-component?\"\n\n## Page port \u2014 what changes vs. what doesn't\n\nFor each Claude Design page, only these change:\n\n- **Module system**: `<script type=\"text/babel\">` + `window.*` globals \u2192 ESM imports between `client/pages/...` files; `data.js` becomes a `.ts` module (or inline `const`).\n- **React acquisition**: `const { useState, ... } = React;` \u2192 `import { useState, ... } from \"react\";`\n- **Mounting**: `ReactDOM.createRoot(...).render(<App />)` \u2192 page is mounted by `client/router.tsx` via the standard route binding.\n- **Styling pipeline**: inline `<style>` + hand-rolled CSS classes \u2192 CSS variables in `client/index.css` under `@theme inline` + Tailwind utilities on JSX.\n- **Theme toggle**: `<html data-theme>` mutation \u2192 `document.documentElement` class toggle.\n- **Tweaks**: `useTweaks` / `<TweaksPanel>` \u2192 real React state for semantic tweaks; visual tweaks drop or move to a settings UI.\n- **Edit-mode protocol**: `__activate_edit_mode` / `__deactivate_edit_mode` postMessage handshakes \u2192 drop entirely.\n\nEverything else \u2014 JSX structure, component breakdown, prop shapes, event handlers, copy, layout, spacing, color, shadow, animation, breakpoints \u2014 transfers **unchanged** from the source. If the diff between source and target page goes beyond the bullets above, you are over-editing \u2014 back out the cosmetic changes.\n\n## Done \u2014 Claude Design specifics\n\nIn the final report, additionally surface:\n\n- The full list of tweaks from `TWEAK_DEFAULTS` and what happened to each (kept as state, dropped, surfaced as settings).\n- Whether the data stayed as inline mocks or was promoted to APIs (and which integration backs each, if so).\n- Any hand-rolled UI primitives (modal, toast, popover) you preserved verbatim, so the user can choose whether to standardize on shadcn later.\n- The list of Google Fonts re-loaded and the `@theme` font tokens bound.\n";
+//# sourceMappingURL=claude-design.generated.d.ts.map

package/dist/ai-service/skills/system/third-party-migration/claude-design.generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-design.generated.d.ts","sourceRoot":"","sources":["../../../../../src/ai-service/skills/system/third-party-migration/claude-design.generated.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,OAAO,kqeAuGnB,CAAC"}

package/dist/ai-service/skills/system/third-party-migration/claude-design.generated.js

@@ -0,0 +1,107 @@
+// Auto-generated from src/ai-service/skills/system/third-party-migration/claude-design.md
+// Do not edit directly - edit the .md file instead
+export const content = `# Claude Design-specific mapping
+
+This is a per-platform reference loaded from \`SKILL.md\`. The framework — target layout, universal mapping, non-negotiables, workflow, code-emission rules — lives there. This file documents only what is specific to a Claude Design source.
+
+> Claude Design is a prototype-design tool from Anthropic. Its "Download project as .zip" output is a tiny, self-contained, **frontend-only** prototype: a single \`<Name>.html\` shell that loads React, ReactDOM, and Babel from a CDN and \`<script type="text/babel" src="...">\` files that compile in the browser at run time. There is **no backend, no \`package.json\`, no build step, and no module system** — every helper is hung off \`window.*\` or pulled from globals. Treat the export as design-quality intent (layout, typography, color, interactions, copy) that needs to be re-expressed inside the Superblocks fullstack template (Vite + React + react-router v7 + Tailwind v4 + shadcn/ui). The framework's "Don't fabricate a backend" rule applies — if the source is purely UI driven by inline mock data, the migrated app stays frontend-only unless the user explicitly asks for one.
+
+## Where the source lives
+
+Definitive marker: a flat archive (no nested project folder) containing exactly one top-level \`<Name>.html\` file plus sibling JSX/JS files, with the HTML loading React, ReactDOM, and \`@babel/standalone\` from \`unpkg.com\` and using \`<script type="text/babel" src="...">\` for the JSX files. No \`package.json\`, no \`node_modules\`, no \`vite.config.*\`, no \`tsconfig.json\`.
+
+Strong supporting signals:
+
+- The HTML root tag is \`<html lang="..." data-theme="light">\` (or \`"dark"\`); theme switching happens by mutating \`data-theme\` on \`<html>\` and CSS variables defined under \`:root[data-theme="light"]\` / \`:root[data-theme="dark"]\`.
+- A \`tweaks-panel.jsx\` sibling that defines a draggable in-canvas controls panel and exposes \`useTweaks\`, \`TweaksPanel\`, \`TweakSection\`, \`TweakSlider\`, \`TweakRadio\`, \`TweakColor\`, \`TweakToggle\` as window globals. The host protocol is \`__activate_edit_mode\` / \`__deactivate_edit_mode\` postMessage handshakes plus \`__edit_mode_available\` / \`__edit_mode_set_keys\` / \`__edit_mode_dismissed\` responses.
+- An \`app.jsx\` whose top has \`const TWEAK_DEFAULTS = /*EDITMODE-BEGIN*/{ ... }/*EDITMODE-END*/;\` — the \`EDITMODE-BEGIN\` / \`EDITMODE-END\` markers are how the Claude Design canvas locates and rewrites the defaults block.
+- A \`data.js\` (or similarly named sibling) that hangs sample data off \`window.*\`: e.g. \`window.ORDERS = [...]; window.KPIS = [...];\`. Components consume the globals directly (\`/* global React, ReactDOM, ORDERS, KPIS, useTweaks, ... */\` at the top of \`app.jsx\`).
+- Mounting happens at the bottom of \`app.jsx\` via \`ReactDOM.createRoot(document.getElementById("root")).render(<App />);\` against a single \`<div id="root"></div>\` in the HTML body.
+- Inline \`<style>\` block in \`<head>\` defines the entire visual system: a light + dark token palette under \`:root[data-theme="..."]\`, body typography (commonly DM Sans + JetBrains Mono via Google Fonts), all component styles by hand-rolled BEM-ish class names (\`.topbar\`, \`.brand\`, \`.kpi\`, \`.orders-table\`, etc.). No Tailwind, no shadcn primitives in the source.
+
+If the user gave a path, use it. Otherwise look for the markers above in the working tree. If you see a flat archive with \`EDITMODE-BEGIN\` markers and a CDN-loaded React shell, it is a Claude Design export. If anything is ambiguous (e.g. someone hand-built a similar HTML+JSX shell), ask before assuming Claude Design conventions.
+
+## Typical shape (hints, not rules)
+
+Use these as starting points; re-verify against the actual source tree on every migration.
+
+- **Frontend**: One HTML shell + one or more \`.jsx\` files compiled in-browser by \`@babel/standalone\`. Components are plain functions (\`function App()\`, \`function KpiCard({ k, theme })\`) that consume \`React.useState\` / \`useMemo\` / \`useEffect\` from a \`const { useState, useMemo, useEffect } = React;\` destructure. No imports, no JSX modules, no TypeScript.
+- **Styling**: Inline \`<style>\` in \`<head>\` with hand-written CSS, custom properties, and media queries. CSS variables drive the theme: \`--bg\`, \`--surface\`, \`--ink\`, \`--accent\`, \`--line\`, \`--muted\`, \`--shadow-{sm,md,lg}\`, etc. Dark mode flips the variable values under \`:root[data-theme="dark"]\`.
+- **Fonts**: Google Fonts loaded via \`<link>\` in \`<head>\`; commonly DM Sans (UI) + JetBrains Mono (mono).
+- **Tweaks**: \`tweaks-panel.jsx\` is a self-contained controls overlay used during prototyping. The \`useTweaks(TWEAK_DEFAULTS)\` hook returns \`[t, setTweak]\`; \`<TweaksPanel>\` renders the floating controls inside the canvas. Every tweak control posts \`__edit_mode_set_keys\` to the parent frame so the Claude Design host can persist values.
+- **Data**: \`data.js\` defines synthetic sample data on \`window.*\`. Treat as fixtures, not production data.
+- **Backend**: None. There are no API calls, no \`fetch\`, no auth, no DB access in a typical export.
+- **Routing**: None. Single-page prototype; no \`react-router\` or hashes.
+- **Assets**: Inlined SVGs in JSX or referenced from inline \`<style>\` background-images. No \`public/\`, no separate image files in the typical export.
+
+## Discovery checklist
+
+In addition to the framework's discovery requirements, for a Claude Design source enumerate:
+
+- The HTML shell file (\`<Name>.html\`) and the \`<title>\` it sets — that is the prototype's name and should anchor your \`<PageName>\`.
+- Every sibling \`.jsx\` / \`.js\` file and its purpose: which one is the entry (\`app.jsx\`), which is the tweaks shell (\`tweaks-panel.jsx\`), which holds data fixtures (\`data.js\` or similar).
+- The full \`TWEAK_DEFAULTS\` object between \`/*EDITMODE-BEGIN*/\` and \`/*EDITMODE-END*/\` — every key here corresponds to a runtime control; preserve every one in the migrated app or call out which you are dropping and why.
+- The full set of CSS variables defined under \`:root[data-theme="light"]\` and \`:root[data-theme="dark"]\` — these are the theme tokens to port.
+- Every Google Fonts family loaded in \`<head>\` and which CSS rules consume them.
+- Every \`window.*\` global the JSX files read (look for the \`/* global ... */\` comment at the top of \`app.jsx\`) — these are the data fixtures to recreate.
+- Every top-level component function in \`app.jsx\` and its responsibility (KPI tile, table, modal, toast, etc.). The migrated app keeps the same component breakdown.
+- Every inline SVG and its role (icons, sparklines, chart paths) — these go straight into the migrated JSX unchanged.
+- Whether the tweaks panel is purely visual (color, density, font size) or carries semantic state (filters, modes). Visual tweaks usually drop after migration; semantic tweaks become real React state on the page.
+
+If the discovery summary doesn't tell you which CSS variables drive the theme, what every tweak controls, and what each component renders, you haven't discovered enough.
+
+## Core mapping
+
+- **The HTML shell + \`app.jsx\` → one Superblocks page** at \`client/pages/<Name>/index.tsx\`, wired into \`client/router.tsx\` (commonly as the \`index: true\` route). The page name comes from the HTML \`<title>\` or the \`<Name>.html\` filename — pick one shape and stay consistent.
+- **Drop the CDN script tags entirely.** React, ReactDOM, and \`@babel/standalone\` from \`unpkg\` have no role in the migrated app — the Vite template ships React via \`node_modules\` and compiles JSX at build time. Likewise drop the \`<script type="text/babel" src="...">\` references.
+- **Drop the \`<html>\` / \`<body>\` shell.** The Superblocks template owns the document. Mounting via \`ReactDOM.createRoot(...)\` also drops; the platform handles render.
+- **Translate the inline \`<style>\` block into Tailwind v4 + \`client/index.css\`:**
+  - The CSS variables under \`:root[data-theme="light"]\` / \`:root[data-theme="dark"]\` move into \`client/index.css\`'s \`:root\` and \`.dark\` blocks **as-is** (CSS Color Level 4 values stay as-is — do not convert to OKLCH; see the framework's "Theme port" rule). Wire them into Tailwind v4 via \`@theme inline\` so \`bg-bg\`, \`text-ink\`, \`border-line\` etc. resolve to the source tokens.
+  - The Google Fonts \`<link>\` tags become \`@import url('https://fonts.googleapis.com/...')\` at the top of \`client/index.css\`, with \`@theme { --font-sans: 'DM Sans', ...; --font-mono: 'JetBrains Mono', ...; }\` so \`font-sans\` / \`font-mono\` keep working. (See v0.md's font-port checklist for the three-step pattern.)
+  - Hand-rolled component CSS (\`.topbar\`, \`.kpi\`, \`.orders-table\`, etc.) translates into Tailwind utility classes on the corresponding JSX. Preserve spacing, sizing, color, shadow, and breakpoint behavior **exactly**. If a rule is too gnarly to express in utilities (complex animations, pseudo-element trickery), keep it in \`client/index.css\` under a scoped class — do not invent a new design.
+- **Theme switching.** The source toggles theme by mutating \`<html data-theme="...">\`. Translate to a small custom provider that toggles \`class="dark"\` on \`document.documentElement\` and persists to \`localStorage\` (mirroring the v0 \`next-themes\` translation). Preserve the source's CSS variable scheme (\`:root\` / \`.dark\` blocks) — only the JS toggle changes.
+- **Tweaks panel.** The Claude Design \`tweaks-panel.jsx\` is **canvas-only tooling** for the Claude Design host. It does not belong in the migrated app. Drop \`tweaks-panel.jsx\`, the \`useTweaks\` import, the \`<TweaksPanel>\` element, the \`__activate_edit_mode\` / \`__deactivate_edit_mode\` postMessage protocol, and the \`EDITMODE-BEGIN\` / \`EDITMODE-END\` markers entirely.
+  - **But preserve what the tweaks controlled.** For each tweak in \`TWEAK_DEFAULTS\`:
+    - **Visual-only tweaks** (theme, accent color, density, font size) → either drop and pin to the default value, or surface as a real settings UI if the user wants it. Ask before keeping; visual tweaks are usually prototype affordances, not product features.
+    - **Semantic tweaks** (active tab, selected filter, sort order, "show kpis" toggles) → become real React state on the page (\`useState\` defaulted to the value from \`TWEAK_DEFAULTS\`). The user's interactions drive them; there is no edit-mode panel.
+  - Surface the full list of tweaks and your decision per tweak in the discovery summary so the user can override.
+- **\`data.js\` / \`window.*\` globals.** These are mock fixtures, not real data. Two paths:
+  - **Default: keep as inline mock data inside the migrated page** (e.g., a \`const ORDERS = [...]\` at module scope, or a small \`client/data/<name>.ts\` module). The migrated app stays frontend-only and behaves like the prototype.
+  - **If the user wants a real backend**: surface the data shape in the discovery summary and ask before fabricating APIs. Per the framework's "Don't fabricate a backend" rule, do not invent server-side endpoints unless the user opts in. If they do, each \`window.*\` collection becomes one Superblocks API returning the same shape, and the page calls \`useApiData("<ApiName>")\` instead of reading the global.
+- **Components.** Each top-level function in \`app.jsx\` (\`KpiCard\`, \`OrdersTable\`, \`Checkbox\`, \`TrackingModal\`, \`BulkBar\`, \`Toast\`, ...) becomes a sibling component file under \`client/pages/<Name>/components/<Name>.tsx\` (or stays inline if small). Function bodies, JSX structure, prop shapes, and event handlers transfer **unchanged** — only imports change (pull \`useState\` / \`useMemo\` / \`useEffect\` from \`react\` instead of destructuring from a \`React\` global, and add explicit \`import React from "react"\` only if JSX runtime requires it).
+- **Inline SVGs** (sparklines, icons, chart paths) move into the migrated JSX **verbatim**. Do not swap for \`lucide-react\` icons or other libraries unless the user asks; the source's SVGs are part of the design.
+- **Modals, toasts, and overlays.** Source uses raw \`<div>\` + CSS for these. Keep as-is in the migrated page — do not silently swap for shadcn \`Dialog\` / \`Sonner\` unless the user explicitly opts in. shadcn primitives change visual behavior (focus rings, animation, scrim color) and that is a design regression.
+- **Responsive breakpoints.** The source defines \`@media (max-width: 900px)\` rules in the inline \`<style>\`. Translate to Tailwind responsive prefixes (\`sm:\` / \`md:\` / \`lg:\`) on the corresponding utilities, matching the source's breakpoint values exactly.
+
+## Ask-before-guessing — Claude Design specifics
+
+- "The export has no backend. I'll keep the data as inline mocks under \`client/pages/<Name>/data.ts\`. Want me to fabricate APIs for it instead, or leave it frontend-only?"
+- "The tweaks panel exposes \`<list of tweaks>\`. Visual tweaks (theme, accent, density) typically drop on migration; semantic tweaks become real page state. Confirm which to keep, drop, or surface as a settings UI."
+- "The source uses Google Fonts \`<list>\` via CDN \`<link>\`. I'll re-load them via \`@import\` in \`client/index.css\` and bind via \`@theme\`. OK, or do you want self-hosted fonts?"
+- "The source switches themes by toggling \`<html data-theme>\`. I'll translate to a provider that toggles \`class='dark'\` on \`document.documentElement\`. Acceptable, or do you want a different theme-toggle shape?"
+- "The export ships hand-rolled UI components (modal, toast, table). I'll keep them as-is rather than swapping in shadcn primitives, since shadcn would change the visual behavior. Confirm, or override per-component?"
+
+## Page port — what changes vs. what doesn't
+
+For each Claude Design page, only these change:
+
+- **Module system**: \`<script type="text/babel">\` + \`window.*\` globals → ESM imports between \`client/pages/...\` files; \`data.js\` becomes a \`.ts\` module (or inline \`const\`).
+- **React acquisition**: \`const { useState, ... } = React;\` → \`import { useState, ... } from "react";\`
+- **Mounting**: \`ReactDOM.createRoot(...).render(<App />)\` → page is mounted by \`client/router.tsx\` via the standard route binding.
+- **Styling pipeline**: inline \`<style>\` + hand-rolled CSS classes → CSS variables in \`client/index.css\` under \`@theme inline\` + Tailwind utilities on JSX.
+- **Theme toggle**: \`<html data-theme>\` mutation → \`document.documentElement\` class toggle.
+- **Tweaks**: \`useTweaks\` / \`<TweaksPanel>\` → real React state for semantic tweaks; visual tweaks drop or move to a settings UI.
+- **Edit-mode protocol**: \`__activate_edit_mode\` / \`__deactivate_edit_mode\` postMessage handshakes → drop entirely.
+
+Everything else — JSX structure, component breakdown, prop shapes, event handlers, copy, layout, spacing, color, shadow, animation, breakpoints — transfers **unchanged** from the source. If the diff between source and target page goes beyond the bullets above, you are over-editing — back out the cosmetic changes.
+
+## Done — Claude Design specifics
+
+In the final report, additionally surface:
+
+- The full list of tweaks from \`TWEAK_DEFAULTS\` and what happened to each (kept as state, dropped, surfaced as settings).
+- Whether the data stayed as inline mocks or was promoted to APIs (and which integration backs each, if so).
+- Any hand-rolled UI primitives (modal, toast, popover) you preserved verbatim, so the user can choose whether to standardize on shadcn later.
+- The list of Google Fonts re-loaded and the \`@theme\` font tokens bound.
+`;
+//# sourceMappingURL=claude-design.generated.js.map

package/dist/ai-service/skills/system/third-party-migration/claude-design.generated.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-design.generated.js","sourceRoot":"","sources":["../../../../../src/ai-service/skills/system/third-party-migration/claude-design.generated.ts"],"names":[],"mappings":"AAAA,0FAA0F;AAC1F,mDAAmD;AAEnD,MAAM,CAAC,MAAM,OAAO,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuGtB,CAAC"}

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

@@ -1,2 +1,2 @@
-export declare const content = "---\nname: third-party-migration\ndescription: |\n  Migrate a third-party app (Replit, Lovable, v0, or similar) into a Superblocks 3.0 full-stack app.\n  Load when the user asks to migrate, import, or port an external app \u2014 or when the source tree contains hallmarks of a supported platform (`replit.md` / `.replit`, `src/integrations/supabase/`, `supabase/functions/`, `lovable-tagger`, an `app/` directory with `next.config.*` and `\"use client\"` / `\"use server\"` directives, etc.) and the user wants it turned into a Superblocks app.\nreadOnly: true\nmetadata:\n  author: superblocks\n  version: \"1.0\"\n---\n\n# Third-Party App \u2192 Superblocks 3.0 Migration\n\nPort a user-provided external app into the Superblocks fullstack app you are running inside (template: `app-fullstack`). The source tree is **read-only material**. All edits land in the target app under `server/` and `client/`.\n\nThis file is the migration framework. **Per-platform mapping rules live in sibling files** \u2014 load the right one before you start mapping.\n\n## Identify the source platform\n\nMatch the source tree against these signals, then read the matching reference file in this folder. Read it once, up-front \u2014 it tells you what shapes to look for and how each maps to Superblocks.\n\n- **Replit** \u2014 `replit.md`, `.replit`, `artifacts/`, an Express server with an Orval-generated client. \u2192 load `replit.md`.\n- **Lovable** \u2014 `src/integrations/supabase/client.ts`, `supabase/config.toml`, `supabase/functions/`, `supabase/migrations/`, `lovable-tagger` in `vite.config.ts`. \u2192 load `lovable.md`.\n- **v0** \u2014 `app/<segment>/page.tsx` (Next.js App Router) plus `next.config.{js,mjs,ts}` and `next` in `package.json`, files with `\"use client\"` / `\"use server\"` directives, `next/link` / `next/navigation` imports, `components/ui/` with shadcn primitives. \u2192 load `v0.md`.\n- **Ambiguous or neither** \u2014 stop and ask the user which platform the source came from. Do not guess. It is possible that it is No Platform. In this case, follow the general guidelines in this document and ask user questions for any ambiguity.\n\nThe framework below applies to every platform; the platform file fills in the source-specific mapping.\n\n## Target layout\n\nThe app you are running inside looks like this. Do not invent new top-level directories.\n\n```\nclient/\n  App.tsx           \u2014 root with <AppProvider> + <Outlet />\n  router.tsx        \u2014 react-router v7 data mode (`createBrowserRouter`); see Router shape below\n  index.css         \u2014 Tailwind v4 + theme tokens\n  hooks/\n    useApi.ts       \u2014 typed wrapper around useTypedApi<ApiRegistry>\n    useApiData.ts   \u2014 typed wrapper around useTypedApiData<ApiRegistry>\n  lib/executeApi.ts \u2014 non-React typed executeApi\n  pages/<Name>/index.tsx\n  components/ui/    \u2014 shadcn primitives (do not modify)\nserver/\n  apis/\n    index.ts        \u2014 registry: `const apis = { ApiName: ... } as const;`\n    <ApiName>/api.ts\n```\n\n## Universal mapping (applies to every source)\n\nThese hold regardless of source platform. Per-platform specifics layer on top.\n\n- APIs are addressed by `name` via the registry \u2014 there is no URL path. Within `api()`:\n  - All inputs (whatever shape the source had \u2014 body, query, params, function args) \u2192 one unified `input` Zod schema; destructure inside `run(ctx, { ... })`.\n  - The handler's response \u2192 `return { ... }` from `run`. The `output` schema validates it automatically; do not `safeParse` by hand.\n  - Auth \u2192 `ctx.user` (`userId`, `email`, `name`, `groups`, `customClaims`). Auth is platform-managed; drop the source's auth flows entirely.\n  - Errors \u2192 throw the `SdkError` subtypes the sdk-api README documents (`InputValidationError`, `OutputValidationError`, `IntegrationError`, `ExecutionError`). Never invent error classes or return HTTP status codes.\n  - DB clients (`pg`, `knex`, `prisma`, Drizzle, `supabase.from(...)`) \u2192 declare in `integrations: { db: postgres(DB_INTEGRATION_ID) }` and call `ctx.integrations.db.query(sql, ZodSchema, params, { label: \"...\" })` / `.execute(...)`. Parameterized SQL only. Hold integration UUIDs in module-level `const`s, not literals scattered through `run`.\n  - External HTTP (`axios`, `fetch`, third-party SDKs) \u2192 declared integration + `ctx.integrations.<name>.apiRequest({ method, path, body }, { response: ZodSchema })`.\n  - `process.env.*` / `import.meta.env.*` / `Deno.env.get(...)` \u2192 `ctx.env`. Logging \u2192 `ctx.log.info/warn/error/debug(msg, data?)`.\n  - Server bootstrapping (`app.listen`, CORS, route grouping, middleware setup, `Deno.serve`) \u2192 drop entirely. The platform handles it.\n- **Each frontend page \u2192 one Superblocks page** at `client/pages/<Name>/index.tsx`, wired into `client/router.tsx`.\n- **Each backend data source (DB, REST client, S3, ...) \u2192 one Superblocks integration** referenced by UUID. Credentials live on the integration, never in code.\n\n### Router shape (`client/router.tsx`)\n\nThe editor parses this file statically to build the page list and route table. **Use one of the supported page-component bindings \u2014 anything else silently drops every route and the editor shows a \"404 / route has been deleted\" overlay.**\n\nSupported page bindings (mix freely):\n\n```tsx\n// 1. Inline lazy on the route object (preferred \u2014 matches the template):\n{ path: \"about\", lazy: () => import(\"./pages/About/index.tsx\").then(m => ({ Component: m.default })) }\n\n// 2. Static default import + Component / element:\nimport About from \"./pages/About/index.tsx\";\n{ path: \"about\", Component: About }\n{ path: \"about\", element: <About /> }\n\n// 3. Top-level `const` bound to React.lazy + Component / element:\nconst About = lazy(() => import(\"./pages/About/index.tsx\"));\n{ path: \"about\", Component: About }\n```\n\nDo **not**: assign `Component` / `element` to identifiers bound by anything other than a static import or `lazy(() => import(\"...\"))` (no IIFEs, no helper wrappers, no conditional `lazy(...)`, no objects whose keys are computed from a loop). The parser only resolves the shapes above.\n\n## Authoritative references (read just-in-time, not up front)\n\n- `node_modules/@superblocksteam/sdk-api/README.md` and `src/index.ts` \u2014 the server `api()` contract and the full list of factory names. **Never invent factory names.** If a required file is missing, mark the affected checklist item `failed` with the missing path as the reason.\n- Per-integration READMEs under `node_modules/@superblocksteam/sdk-api/src/integrations/<kind>/` \u2014 read once, when you first emit an API that uses that integration.\n- `skills/system/superblocks-frontend/SKILL.md` \u2014 the client contract (`useApi` / `useApiData` / `executeApi` from `@superblocksteam/library`).\n\n> \u26A0\uFE0F **Never** load `skills/system/superblocks-api/SKILL.md`. It describes a different, block-based API pattern that is incompatible with the fullstack template's `sdk-api`. Mixing them produces code that does not compile.\n\n## Non-negotiables\n\n1. **Track everything in the checklist.** The **first tool call after exiting plan mode** or **during build mode, before building** is `build_manageChecklist` to seed. Before every per-item edit, `update <itemId> in_progress`; after, `update <itemId> completed` (or `failed` with a concrete `failureReason`). If you are about to write code and the checklist is empty, stale, or missing the item you are working on, **stop and fix the checklist first** \u2014 the orchestration depends on it. Free-text status reports are not a substitute.\n2. **Discover before you edit.** Inventory routes, pages, data sources, env vars, _and visual surface_ (theme tokens, `index.css`, custom CSS, font setup, layout shells) across the entire source tree before writing any code. The platform file tells you what shapes to look for.\n3. **Ask before guessing.** Multiple integrations of the same kind, missing integrations, unsupported data sources, or any platform-specific ambiguity \u2192 stop and `askMultiChoice`. Never pick for the user. The platform file lists ambiguities specific to that source.\n4. **Preserve visual identity.** The migrated app must look and feel like the source. Carry over Tailwind config, shadcn theme tokens, `index.css` / `globals.css`, custom CSS modules, fonts, spacing, color palette, and layout shells (header/sidebar/grid). shadcn/ui components stay as-is. Do **not** redesign, restyle, or \"clean up\" while porting \u2014 visual regressions are bugs, not improvements. If the user wants a redesign, that is a separate task after migration.\n5. **Never copy secrets.** DSN strings, API keys, anon/service-role keys, JWT secrets, env-var lookups for credentials \u2014 none move into the target tree. Integration UUIDs replace them. Surface every leaked secret you find (especially client-side `VITE_*` / `NEXT_PUBLIC_*` keys) in the discovery summary so the user can rotate them.\n6. **No `// TODO`s.** Anything you can't finish deterministically becomes a `failed` checklist item with a concrete `failureReason`.\n7. **Don't scaffold.** If `server/apis/index.ts` or `client/router.tsx` doesn't already exist, you're in the wrong app \u2014 stop and surface this.\n8. **Don't fabricate a backend.** If the source is genuinely frontend-only, the migrated app should also be frontend-only. Don't invent APIs to \"complete\" the architecture.\n\n## Workflow\n\n1. **Locate the source.** If the user gave a path, use it. Otherwise look in the working tree for the platform signals listed above. If ambiguous, ask.\n2. **Load the platform guide.** Read `replit.md`, `lovable.md`, or `v0.md` based on what you found. Do not start mapping before you've read it \u2014 it documents the source's shape and how each piece translates.\n3. **Inventory.** Following the platform guide's discovery checklist, enumerate every route/handler, page, data source, env var, secret, and visual asset in the source tree. Surface a one-paragraph summary plus an itemized list of integrations and unsupported features before writing anything. If the source has bespoke styling, seed a `setup_theme` checklist item to port it.\n4. **Resolve integrations.** For each data source kind: call `searchIntegrations` (filter by `type`). One match \u2192 bind it. Multiple \u2192 ask the user which. Zero \u2192 ask whether to create one; if yes, use `listAvailableIntegrationTypes` (if needed) and `openIntegrationSetup`, then ask the user explicitly whether they saved or cancelled before re-searching. Resolution is **blocking** \u2014 the checklist cannot be seeded until every kind maps to a UUID, is explicitly deferred, or has been confirmed unsupported.\n5. **Seed the checklist** via `build_manageChecklist`. One `api_<ApiName>` per backend interaction, one `frontend_<PageName>` per page, plus `setup_router`, `setup_registry`, `setup_cleanup`, and any `setup_theme` / `setup_storage` / `unsupported_<feature>` items the platform guide tells you to add. Print the count as a sanity check; if it looks wrong, re-check discovery.\n6. **Execute.** Every item follows the same ritual \u2014 no exceptions:\n   - **Before touching files:** `build_manageChecklist update <itemId> in_progress`.\n   - **Emit / edit the files** for that item.\n   - **After the edit lands:** `build_manageChecklist update <itemId> completed` (or `failed` with a concrete `failureReason`).\n   - You are not done with an item until its checklist entry has moved to a terminal state. Do not batch updates at the end; update as you go.\n   - **For parallelizable work:** call `spawnCodingSubagents` with batches of tasks. Each batch's `instructions` names exact `itemId`s, includes the integration-UUID map and source path, any platform-specific context the sub-agent needs (e.g. RLS-replacement clauses for Lovable), and tells the sub-agent to follow the same `in_progress` \u2192 `completed`/`failed` ritual for every item it owns.\n   - `spawnCodingSubagents` **must be the only tool call in that turn.** It blocks until every sub-agent finishes; there is no \"while waiting\" from your perspective. Other tool calls in the same turn race on the shared checklist and corrupt state. After it returns, read the checklist and handle `failed` items sequentially. If the tool itself errors, surface it and fall back to sequential \u2014 or fail the affected items with `sub-agent orchestration failed: <error>`.\n\n## When emitting code\n\n- **Server.** Default-export one `api({ name, integrations, input, output, run })` from `@superblocksteam/sdk-api`. The `name` and the registry key in `server/apis/index.ts` must equal `<ApiName>` verbatim \u2014 the client calls `useApi(\"<ApiName>\")` by that exact string. Preserve the external response shape exactly so the migrated frontend keeps working. Use parameterized SQL only (`$N`); zero string interpolations. Throw the error classes the sdk-api README documents instead of returning HTTP status codes.\n- **Client.** Replace the source's data hooks with `useApiData` (reads) or `useApi` (mutations) keyed by `<ApiName>`. **Import the typed wrappers from the template, not the library directly:** `import { useApi } from \"@/hooks/useApi.js\"`, `import { useApiData } from \"@/hooks/useApiData.js\"`, `import { executeApi } from \"@/lib/executeApi.js\"`. They give compile-time inference from `ApiRegistry`. Drop the source's generated client packages, `QueryClientProvider`, base-URL or auth-token getters, and any auth-context plumbing \u2014 Superblocks handles all of that. shadcn/form + react-hook-form + zod stays. Follow the loading-state guidance in `superblocks-frontend/SKILL.md`.\n- **ESM imports.** Every relative import in emitted code uses an explicit `.js` extension (`./api.js`, `../hooks/useApi.js`) \u2014 even though the source is `.ts`. The template is ESM; bare specifiers fail at runtime.\n- **Theme port.** When carrying over the source's theme, copy the existing color values **as-is** into `client/index.css`'s `:root` block. HSL values written `hsl(222 47% 11%)` (CSS Color Level 4 space-separated form) work directly with the `@theme inline` mapping in Tailwind v4. **Do not convert to OKLCH** unless the source already uses OKLCH \u2014 converting introduces drift and is a common visual-regression source.\n- **Visual fidelity.** JSX structure, Tailwind classes, shadcn variants, custom CSS, theme tokens, fonts, and layout containers must transfer over **unchanged** from the source page. The only things that change in a page port are the data hooks, the auth touchpoints, and the router primitives. Do not \"improve\" markup, swap class names, or substitute components. If the diff between source and target page goes beyond data + auth + routing, you are over-editing \u2014 back out the cosmetic changes.\n- **Sub-agents must not** call `searchIntegrations`, `openIntegrationSetup`, or any integration-resolution tool. If they hit a kind missing from the map, fail the item with `unresolved integration kind: <kind>` and let the main agent handle it on return.\n\n## Done\n\nStop only when every checklist item is `completed` or `failed`. Report the counts plus any platform-specific findings the per-platform guide asks you to surface (e.g. leaked secrets, replaced RLS policies, unsupported realtime features). Do not claim success \u2014 defer verification to the user running the app.\n";
+export declare const content = "---\nname: third-party-migration\ndescription: |\n  Migrate a third-party app (Replit, Lovable, v0, or similar) into a Superblocks 3.0 full-stack app.\n  Load when the user asks to migrate, import, or port an external app \u2014 or when the source tree contains hallmarks of a supported platform (`replit.md` / `.replit`, `src/integrations/supabase/`, `supabase/functions/`, `lovable-tagger`, an `app/` directory with `next.config.*` and `\"use client\"` / `\"use server\"` directives, etc.) and the user wants it turned into a Superblocks app.\nreadOnly: true\nmetadata:\n  author: superblocks\n  version: \"1.0\"\n---\n\n# Third-Party App \u2192 Superblocks 3.0 Migration\n\nPort a user-provided external app into the Superblocks fullstack app you are running inside (template: `app-fullstack`). The source tree is **read-only material**. All edits land in the target app under `server/` and `client/`.\n\nThis file is the migration framework. **Per-platform mapping rules live in sibling files** \u2014 load the right one before you start mapping.\n\n## Checklist is mandatory\n\nChecklist discipline is required for every migration run:\n\n- Before any file edits, ensure migration checklist items are seeded via `build_manageChecklist`.\n- Before editing an item, mark it `in_progress`.\n- After the edit lands, mark it `completed`, or `failed` with a concrete `failureReason` if deterministic completion is impossible.\n- When you need an item to survive `build_finalize`, set `clearOnFinalize: false` on add/update. Use this only for migration-tracking items that must persist until explicit migration completion.\n- Do not continue implementation if checklist state is missing, stale, or inconsistent with the work you are doing. Fix checklist state first.\n- Free-text progress updates are never a substitute for checklist updates.\n\n## Identify the source platform\n\nMatch the source tree against these signals, then read the matching reference file in this folder. Read it once, up-front \u2014 it tells you what shapes to look for and how each maps to Superblocks.\n\n- **Replit** \u2014 `replit.md`, `.replit`, `artifacts/`, an Express server with an Orval-generated client. \u2192 load `replit.md`.\n- **Lovable** \u2014 `src/integrations/supabase/client.ts`, `supabase/config.toml`, `supabase/functions/`, `supabase/migrations/`, `lovable-tagger` in `vite.config.ts`. \u2192 load `lovable.md`.\n- **v0** \u2014 `app/<segment>/page.tsx` (Next.js App Router) plus `next.config.{js,mjs,ts}` and `next` in `package.json`, files with `\"use client\"` / `\"use server\"` directives, `next/link` / `next/navigation` imports, `components/ui/` with shadcn primitives. \u2192 load `v0.md`.\n- **Claude Design** \u2014 a small flat archive (no `package.json`, no `node_modules`, no build config) with one top-level `<Name>.html` plus sibling `app.jsx`, `data.js`, and `tweaks-panel.jsx`. The HTML loads React + ReactDOM + Babel from a CDN, uses `<html data-theme=\"...\">`, and references `var(--accent)` / `var(--ink)` CSS variables. The `.jsx` files contain `/*EDITMODE-BEGIN*/ ... /*EDITMODE-END*/` markers around defaults and use `useTweaks` / `TweaksPanel` / `TweakSection` / `TweakToggle` globals. \u2192 load `claude-design.md`.\n- **Ambiguous or neither** \u2014 stop and ask the user which platform the source came from. Do not guess. It is possible that it is No Platform. In this case, follow the general guidelines in this document and ask user questions for any ambiguity.\n\nThe framework below applies to every platform; the platform file fills in the source-specific mapping.\n\n## Target layout\n\nThe app you are running inside looks like this. Do not invent new top-level directories.\n\n```\nclient/\n  App.tsx           \u2014 root with <AppProvider> + <Outlet />\n  router.tsx        \u2014 react-router v7 data mode (`createBrowserRouter`); see Router shape below\n  index.css         \u2014 Tailwind v4 + theme tokens\n  hooks/\n    useApi.ts       \u2014 typed wrapper around useTypedApi<ApiRegistry>\n    useApiData.ts   \u2014 typed wrapper around useTypedApiData<ApiRegistry>\n  lib/executeApi.ts \u2014 non-React typed executeApi\n  pages/<Name>/index.tsx\n  components/ui/    \u2014 shadcn primitives (do not modify)\nserver/\n  apis/\n    index.ts        \u2014 registry: `const apis = { ApiName: ... } as const;`\n    <ApiName>/api.ts\n```\n\n## Universal mapping (applies to every source)\n\nThese hold regardless of source platform. Per-platform specifics layer on top.\n\n- APIs are addressed by `name` via the registry \u2014 there is no URL path. Within `api()`:\n  - All inputs (whatever shape the source had \u2014 body, query, params, function args) \u2192 one unified `input` Zod schema; destructure inside `run(ctx, { ... })`.\n  - The handler's response \u2192 `return { ... }` from `run`. The `output` schema validates it automatically; do not `safeParse` by hand.\n  - Auth \u2192 `ctx.user` (`userId`, `email`, `name`, `groups`, `customClaims`). Auth is platform-managed; drop the source's auth flows entirely.\n  - Errors \u2192 throw the `SdkError` subtypes the sdk-api README documents (`InputValidationError`, `OutputValidationError`, `IntegrationError`, `ExecutionError`). Never invent error classes or return HTTP status codes.\n  - DB clients (`pg`, `knex`, `prisma`, Drizzle, `supabase.from(...)`) \u2192 declare in `integrations: { db: postgres(DB_INTEGRATION_ID) }` and call `ctx.integrations.db.query(sql, ZodSchema, params, { label: \"...\" })` / `.execute(...)`. Parameterized SQL only. Hold integration UUIDs in module-level `const`s, not literals scattered through `run`.\n  - External HTTP (`axios`, `fetch`, third-party SDKs) \u2192 declared integration + `ctx.integrations.<name>.apiRequest({ method, path, body }, { response: ZodSchema })`.\n  - `process.env.*` / `import.meta.env.*` / `Deno.env.get(...)` \u2192 `ctx.env`. Logging \u2192 `ctx.log.info/warn/error/debug(msg, data?)`.\n  - Server bootstrapping (`app.listen`, CORS, route grouping, middleware setup, `Deno.serve`) \u2192 drop entirely. The platform handles it.\n- **Each frontend page \u2192 one Superblocks page** at `client/pages/<Name>/index.tsx`, wired into `client/router.tsx`.\n- **Each backend data source (DB, REST client, S3, ...) \u2192 one Superblocks integration** referenced by UUID. Credentials live on the integration, never in code.\n\n### Router shape (`client/router.tsx`)\n\nThe editor parses this file statically to build the page list and route table. **Use one of the supported page-component bindings \u2014 anything else silently drops every route and the editor shows a \"404 / route has been deleted\" overlay.**\n\nSupported page bindings (mix freely):\n\n```tsx\n// 1. Inline lazy on the route object (preferred \u2014 matches the template):\n{ path: \"about\", lazy: () => import(\"./pages/About/index.tsx\").then(m => ({ Component: m.default })) }\n\n// 2. Static default import + Component / element:\nimport About from \"./pages/About/index.tsx\";\n{ path: \"about\", Component: About }\n{ path: \"about\", element: <About /> }\n\n// 3. Top-level `const` bound to React.lazy + Component / element:\nconst About = lazy(() => import(\"./pages/About/index.tsx\"));\n{ path: \"about\", Component: About }\n```\n\nDo **not**: assign `Component` / `element` to identifiers bound by anything other than a static import or `lazy(() => import(\"...\"))` (no IIFEs, no helper wrappers, no conditional `lazy(...)`, no objects whose keys are computed from a loop). The parser only resolves the shapes above.\n\n## Authoritative references (read just-in-time, not up front)\n\n- `node_modules/@superblocksteam/sdk-api/README.md` and `src/index.ts` \u2014 the server `api()` contract and the full list of factory names. **Never invent factory names.** If a required file is missing, mark the affected checklist item `failed` with the missing path as the reason.\n- Per-integration READMEs under `node_modules/@superblocksteam/sdk-api/src/integrations/<kind>/` \u2014 read once, when you first emit an API that uses that integration.\n- `skills/system/superblocks-frontend/SKILL.md` \u2014 the client contract (`useApi` / `useApiData` / `executeApi` from `@superblocksteam/library`).\n\n> \u26A0\uFE0F **Never** load `skills/system/superblocks-api/SKILL.md`. It describes a different, block-based API pattern that is incompatible with the fullstack template's `sdk-api`. Mixing them produces code that does not compile.\n\n## Non-negotiables\n\n1. **Track everything in the checklist.** The **first tool call after exiting plan mode** or **during build mode, before building** is `build_manageChecklist` to seed. Before every per-item edit, `update <itemId> in_progress`; after, `update <itemId> completed` (or `failed` with a concrete `failureReason`). If you are about to write code and the checklist is empty, stale, or missing the item you are working on, **stop and fix the checklist first** \u2014 the orchestration depends on it. Free-text status reports are not a substitute.\n2. **Discover before you edit.** Inventory routes, pages, data sources, env vars, _and visual surface_ (theme tokens, `index.css`, custom CSS, font setup, layout shells) across the entire source tree before writing any code. The platform file tells you what shapes to look for.\n3. **Ask before guessing.** Multiple integrations of the same kind, missing integrations, unsupported data sources, or any platform-specific ambiguity \u2192 stop and `askMultiChoice`. Never pick for the user. The platform file lists ambiguities specific to that source.\n4. **Preserve visual identity.** The migrated app must be pixel-faithful to the source. Transfer these source details verbatim: copy strings (every label, heading, placeholder, helper text, button, empty state, error, alt text, tooltip, and aria-label), Tailwind class lists, CSS custom properties with original units and color space (no HSL\u2194OKLCH conversion), border-radius, spacing / padding / margin / gap, width / height literals including arbitrary values such as `w-[280px]` and `rounded-[14px]`, shadow tokens and values, typography (family, weight, size, line-height, and letter-spacing), icon identity (same lucide name or same inline SVG), inline SVG and image assets, breakpoints and responsive prefixes, animations and transitions, component breakdown, and JSX nesting. shadcn/ui components stay as-is. Do **not** redesign, restyle, or \"clean up\" while porting. A diff that goes beyond data hooks + auth + routing + framework directives is a regression \u2014 back it out.\n5. **Never copy secrets.** DSN strings, API keys, anon/service-role keys, JWT secrets, env-var lookups for credentials \u2014 none move into the target tree. Integration UUIDs replace them. Surface every leaked secret you find (especially client-side `VITE_*` / `NEXT_PUBLIC_*` keys) in the discovery summary so the user can rotate them.\n6. **No `// TODO`s.** Anything you can't finish deterministically becomes a `failed` checklist item with a concrete `failureReason`.\n7. **Don't scaffold.** If `server/apis/index.ts` or `client/router.tsx` doesn't already exist, you're in the wrong app \u2014 stop and surface this.\n8. **Don't fabricate a backend.** If the source is genuinely frontend-only, the migrated app should also be frontend-only. Don't invent APIs to \"complete\" the architecture.\n\n## Workflow\n\n1. **Locate the source.** If the user gave a path, use it. Otherwise look in the working tree for the platform signals listed above. If ambiguous, ask.\n2. **Load the platform guide.** Read `replit.md`, `lovable.md`, or `v0.md` based on what you found. Do not start mapping before you've read it \u2014 it documents the source's shape and how each piece translates.\n3. **Inventory.** Following the platform guide's discovery checklist, enumerate every route/handler, page, data source, env var, secret, and visual asset in the source tree. Surface a one-paragraph summary plus an itemized list of integrations and unsupported features before writing anything. If the source has bespoke styling, seed a `setup_theme` checklist item to port it.\n4. **Resolve integrations.** For each data source kind: call `searchIntegrations` (filter by `type`). One match \u2192 bind it. Multiple \u2192 ask the user which. Zero \u2192 ask whether to create one; if yes, use `listAvailableIntegrationTypes` (if needed) and `openIntegrationSetup`, then ask the user explicitly whether they saved or cancelled before re-searching. Resolution is **blocking** \u2014 the checklist cannot be seeded until every kind maps to a UUID, is explicitly deferred, or has been confirmed unsupported.\n5. **Seed the checklist** via `build_manageChecklist`. One `api_<ApiName>` per backend interaction, one `frontend_<PageName>` per page, plus `setup_router`, `setup_registry`, `setup_cleanup`, and any `setup_theme` / `setup_storage` / `unsupported_<feature>` items the platform guide tells you to add. Print the count as a sanity check; if it looks wrong, re-check discovery.\n6. **Execute.** Every item follows the same ritual \u2014 no exceptions:\n   - **Before touching files:** `build_manageChecklist update <itemId> in_progress`.\n   - **Classify the work** per _Before emitting code_ below \u2014 pick the right tool (copy / copy+edit / write) before you start typing.\n   - **Emit / edit the files** for that item using the tool the classification selected.\n   - **After the edit lands:** `build_manageChecklist update <itemId> completed` (or `failed` with a concrete `failureReason`).\n   - You are not done with an item until its checklist entry has moved to a terminal state. Do not batch updates at the end; update as you go.\n   - **For parallelizable work:** call `spawnCodingSubagents` with batches of tasks. Each batch's `instructions` must direct the sub-agent to `build_readFile` `skills/system/third-party-migration/SKILL.md` and the matching platform file (for example, `v0.md`) before touching any files. Do not inline the fidelity contract; keep a single source of truth. The instructions also name exact `itemId`s, include the integration-UUID map and source path, include any platform-specific context the sub-agent needs (e.g. RLS-replacement clauses for Lovable), and tell the sub-agent to follow the same `in_progress` \u2192 `completed`/`failed` ritual for every item it owns.\n   - `spawnCodingSubagents` **must be the only tool call in that turn.** It blocks until every sub-agent finishes; there is no \"while waiting\" from your perspective. Other tool calls in the same turn race on the shared checklist and corrupt state. After it returns, read the checklist and handle `failed` items sequentially. If the tool itself errors, surface it and fall back to sequential \u2014 or fail the affected items with `sub-agent orchestration failed: <error>`.\n\n## Before emitting code\n\nPick the right tool **before** you start typing. The source tree is the source of truth; preserve it byte-for-byte wherever you can. `build_writeFile` is an escalation, not the primary tool \u2014 a rewritten file is only as faithful as the model's attention, while a copied file is faithful by construction.\n\nFor each checklist item, classify the target file(s) into the **lowest bucket that fits** and use the tool for that bucket:\n\n| Source vs. target needs                                                                                        | Tool                                            | Examples                                                                                                                                       |\n| -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Directory** of non-source files                                                                              | `build_copyDirectory` \u2014 never per-file          | `public/`, `static/`, `assets/`, `src/assets/`, fonts, image bundles                                                                           |\n| **Identical** \u2014 byte-for-byte                                                                                  | `build_copyFile`                                | data modules, type files, JSON, fixtures, vendored utils, content/copy modules, shadcn primitives the source has already customized            |\n| **Trivial edits only** \u2014 \u2264 3 distinct edit sites                                                               | `build_copyFile` then `build_editFile` per site | import-path swaps (`react-router-dom` \u2192 `react-router`), single hook rename, one-line constant fix, removing a single `\"use client\"` directive |\n| **Structural changes** \u2014 different component APIs, framework wrappers, routing overhaul, data-hook replacement | `build_writeFile`                               | page components whose data layer is being rewritten, server handlers being reshaped to `api(...)`, router file being regenerated               |\n\n**Heuristic:** if you cannot name the specific lines that need to change before reading the file, you have not earned `build_writeFile` yet \u2014 `build_readFile` first, then re-classify.\n\n**Asset directories never get a per-file ruling.** If `public/` (or the platform's equivalent \u2014 see the per-platform guide) exists in the source, it ships as a single `build_copyDirectory` regardless of contents. Do not enumerate, do not skip, do not selectively copy \"the ones you think you'll need.\"\n\n## When emitting code\n\n- **Server.** Default-export one `api({ name, integrations, input, output, run })` from `@superblocksteam/sdk-api`. The `name` and the registry key in `server/apis/index.ts` must equal `<ApiName>` verbatim \u2014 the client calls `useApi(\"<ApiName>\")` by that exact string. Preserve the external response shape exactly so the migrated frontend keeps working. Use parameterized SQL only (`$N`); zero string interpolations. Throw the error classes the sdk-api README documents instead of returning HTTP status codes.\n- **Client.** Replace the source's data hooks with `useApiData` (reads) or `useApi` (mutations) keyed by `<ApiName>`. **Import the typed wrappers from the template, not the library directly:** `import { useApi } from \"@/hooks/useApi.js\"`, `import { useApiData } from \"@/hooks/useApiData.js\"`, `import { executeApi } from \"@/lib/executeApi.js\"`. They give compile-time inference from `ApiRegistry`. Drop the source's generated client packages, `QueryClientProvider`, base-URL or auth-token getters, and any auth-context plumbing \u2014 Superblocks handles all of that. shadcn/form + react-hook-form + zod stays. Follow the loading-state guidance in `superblocks-frontend/SKILL.md`.\n- **ESM imports.** Every relative import in emitted code uses an explicit `.js` extension (`./api.js`, `../hooks/useApi.js`) \u2014 even though the source is `.ts`. The template is ESM; bare specifiers fail at runtime.\n- **Theme port.** When carrying over the source's theme, copy the existing color values **as-is** into `client/index.css`'s `:root` block. HSL values written `hsl(222 47% 11%)` (CSS Color Level 4 space-separated form) work directly with the `@theme inline` mapping in Tailwind v4. **Do not convert to OKLCH** unless the source already uses OKLCH \u2014 converting introduces drift and is a common visual-regression source.\n- **Visual fidelity.** JSX structure, Tailwind classes, shadcn variants, custom CSS, theme tokens, fonts, and layout containers must transfer over **unchanged** from the source page. The only things that change in a page port are the data hooks, the auth touchpoints, and the router primitives. Do not \"improve\" markup, swap class names, or substitute components. If the diff between source and target page goes beyond data + auth + routing, you are over-editing \u2014 back out the cosmetic changes.\n- **Sub-agents must not** call `searchIntegrations`, `openIntegrationSetup`, or any integration-resolution tool. If they hit a kind missing from the map, fail the item with `unresolved integration kind: <kind>` and let the main agent handle it on return.\n\n## Done\n\nStop only when every checklist item is `completed` or `failed`. Report the counts plus any platform-specific findings the per-platform guide asks you to surface (e.g. leaked secrets, replaced RLS policies, unsupported realtime features). Do not claim success \u2014 defer verification to the user running the app.\n";
 //# sourceMappingURL=skill.generated.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"skill.generated.d.ts","sourceRoot":"","sources":["../../../../../src/ai-service/skills/system/third-party-migration/skill.generated.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,OAAO,6peAqInB,CAAC"}
+{"version":3,"file":"skill.generated.d.ts","sourceRoot":"","sources":["../../../../../src/ai-service/skills/system/third-party-migration/skill.generated.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,OAAO,otoBAmKnB,CAAC"}

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

@@ -17,6 +17,17 @@ Port a user-provided external app into the Superblocks fullstack app you are run
 
 This file is the migration framework. **Per-platform mapping rules live in sibling files** — load the right one before you start mapping.
 
+## Checklist is mandatory
+
+Checklist discipline is required for every migration run:
+
+- Before any file edits, ensure migration checklist items are seeded via \`build_manageChecklist\`.
+- Before editing an item, mark it \`in_progress\`.
+- After the edit lands, mark it \`completed\`, or \`failed\` with a concrete \`failureReason\` if deterministic completion is impossible.
+- When you need an item to survive \`build_finalize\`, set \`clearOnFinalize: false\` on add/update. Use this only for migration-tracking items that must persist until explicit migration completion.
+- Do not continue implementation if checklist state is missing, stale, or inconsistent with the work you are doing. Fix checklist state first.
+- Free-text progress updates are never a substitute for checklist updates.
+
 ## Identify the source platform
 
 Match the source tree against these signals, then read the matching reference file in this folder. Read it once, up-front — it tells you what shapes to look for and how each maps to Superblocks.
@@ -24,6 +35,7 @@ Match the source tree against these signals, then read the matching reference fi
 - **Replit** — \`replit.md\`, \`.replit\`, \`artifacts/\`, an Express server with an Orval-generated client. → load \`replit.md\`.
 - **Lovable** — \`src/integrations/supabase/client.ts\`, \`supabase/config.toml\`, \`supabase/functions/\`, \`supabase/migrations/\`, \`lovable-tagger\` in \`vite.config.ts\`. → load \`lovable.md\`.
 - **v0** — \`app/<segment>/page.tsx\` (Next.js App Router) plus \`next.config.{js,mjs,ts}\` and \`next\` in \`package.json\`, files with \`"use client"\` / \`"use server"\` directives, \`next/link\` / \`next/navigation\` imports, \`components/ui/\` with shadcn primitives. → load \`v0.md\`.
+- **Claude Design** — a small flat archive (no \`package.json\`, no \`node_modules\`, no build config) with one top-level \`<Name>.html\` plus sibling \`app.jsx\`, \`data.js\`, and \`tweaks-panel.jsx\`. The HTML loads React + ReactDOM + Babel from a CDN, uses \`<html data-theme="...">\`, and references \`var(--accent)\` / \`var(--ink)\` CSS variables. The \`.jsx\` files contain \`/*EDITMODE-BEGIN*/ ... /*EDITMODE-END*/\` markers around defaults and use \`useTweaks\` / \`TweaksPanel\` / \`TweakSection\` / \`TweakToggle\` globals. → load \`claude-design.md\`.
 - **Ambiguous or neither** — stop and ask the user which platform the source came from. Do not guess. It is possible that it is No Platform. In this case, follow the general guidelines in this document and ask user questions for any ambiguity.
 
 The framework below applies to every platform; the platform file fills in the source-specific mapping.
@@ -100,7 +112,7 @@ Do **not**: assign \`Component\` / \`element\` to identifiers bound by anything
 1. **Track everything in the checklist.** The **first tool call after exiting plan mode** or **during build mode, before building** is \`build_manageChecklist\` to seed. Before every per-item edit, \`update <itemId> in_progress\`; after, \`update <itemId> completed\` (or \`failed\` with a concrete \`failureReason\`). If you are about to write code and the checklist is empty, stale, or missing the item you are working on, **stop and fix the checklist first** — the orchestration depends on it. Free-text status reports are not a substitute.
 2. **Discover before you edit.** Inventory routes, pages, data sources, env vars, _and visual surface_ (theme tokens, \`index.css\`, custom CSS, font setup, layout shells) across the entire source tree before writing any code. The platform file tells you what shapes to look for.
 3. **Ask before guessing.** Multiple integrations of the same kind, missing integrations, unsupported data sources, or any platform-specific ambiguity → stop and \`askMultiChoice\`. Never pick for the user. The platform file lists ambiguities specific to that source.
-4. **Preserve visual identity.** The migrated app must look and feel like the source. Carry over Tailwind config, shadcn theme tokens, \`index.css\` / \`globals.css\`, custom CSS modules, fonts, spacing, color palette, and layout shells (header/sidebar/grid). shadcn/ui components stay as-is. Do **not** redesign, restyle, or "clean up" while porting — visual regressions are bugs, not improvements. If the user wants a redesign, that is a separate task after migration.
+4. **Preserve visual identity.** The migrated app must be pixel-faithful to the source. Transfer these source details verbatim: copy strings (every label, heading, placeholder, helper text, button, empty state, error, alt text, tooltip, and aria-label), Tailwind class lists, CSS custom properties with original units and color space (no HSL↔OKLCH conversion), border-radius, spacing / padding / margin / gap, width / height literals including arbitrary values such as \`w-[280px]\` and \`rounded-[14px]\`, shadow tokens and values, typography (family, weight, size, line-height, and letter-spacing), icon identity (same lucide name or same inline SVG), inline SVG and image assets, breakpoints and responsive prefixes, animations and transitions, component breakdown, and JSX nesting. shadcn/ui components stay as-is. Do **not** redesign, restyle, or "clean up" while porting. A diff that goes beyond data hooks + auth + routing + framework directives is a regression — back it out.
 5. **Never copy secrets.** DSN strings, API keys, anon/service-role keys, JWT secrets, env-var lookups for credentials — none move into the target tree. Integration UUIDs replace them. Surface every leaked secret you find (especially client-side \`VITE_*\` / \`NEXT_PUBLIC_*\` keys) in the discovery summary so the user can rotate them.
 6. **No \`// TODO\`s.** Anything you can't finish deterministically becomes a \`failed\` checklist item with a concrete \`failureReason\`.
 7. **Don't scaffold.** If \`server/apis/index.ts\` or \`client/router.tsx\` doesn't already exist, you're in the wrong app — stop and surface this.
@@ -115,12 +127,30 @@ Do **not**: assign \`Component\` / \`element\` to identifiers bound by anything
 5. **Seed the checklist** via \`build_manageChecklist\`. One \`api_<ApiName>\` per backend interaction, one \`frontend_<PageName>\` per page, plus \`setup_router\`, \`setup_registry\`, \`setup_cleanup\`, and any \`setup_theme\` / \`setup_storage\` / \`unsupported_<feature>\` items the platform guide tells you to add. Print the count as a sanity check; if it looks wrong, re-check discovery.
 6. **Execute.** Every item follows the same ritual — no exceptions:
    - **Before touching files:** \`build_manageChecklist update <itemId> in_progress\`.
-   - **Emit / edit the files** for that item.
+   - **Classify the work** per _Before emitting code_ below — pick the right tool (copy / copy+edit / write) before you start typing.
+   - **Emit / edit the files** for that item using the tool the classification selected.
    - **After the edit lands:** \`build_manageChecklist update <itemId> completed\` (or \`failed\` with a concrete \`failureReason\`).
    - You are not done with an item until its checklist entry has moved to a terminal state. Do not batch updates at the end; update as you go.
-   - **For parallelizable work:** call \`spawnCodingSubagents\` with batches of tasks. Each batch's \`instructions\` names exact \`itemId\`s, includes the integration-UUID map and source path, any platform-specific context the sub-agent needs (e.g. RLS-replacement clauses for Lovable), and tells the sub-agent to follow the same \`in_progress\` → \`completed\`/\`failed\` ritual for every item it owns.
+   - **For parallelizable work:** call \`spawnCodingSubagents\` with batches of tasks. Each batch's \`instructions\` must direct the sub-agent to \`build_readFile\` \`skills/system/third-party-migration/SKILL.md\` and the matching platform file (for example, \`v0.md\`) before touching any files. Do not inline the fidelity contract; keep a single source of truth. The instructions also name exact \`itemId\`s, include the integration-UUID map and source path, include any platform-specific context the sub-agent needs (e.g. RLS-replacement clauses for Lovable), and tell the sub-agent to follow the same \`in_progress\` → \`completed\`/\`failed\` ritual for every item it owns.
    - \`spawnCodingSubagents\` **must be the only tool call in that turn.** It blocks until every sub-agent finishes; there is no "while waiting" from your perspective. Other tool calls in the same turn race on the shared checklist and corrupt state. After it returns, read the checklist and handle \`failed\` items sequentially. If the tool itself errors, surface it and fall back to sequential — or fail the affected items with \`sub-agent orchestration failed: <error>\`.
 
+## Before emitting code
+
+Pick the right tool **before** you start typing. The source tree is the source of truth; preserve it byte-for-byte wherever you can. \`build_writeFile\` is an escalation, not the primary tool — a rewritten file is only as faithful as the model's attention, while a copied file is faithful by construction.
+
+For each checklist item, classify the target file(s) into the **lowest bucket that fits** and use the tool for that bucket:
+
+| Source vs. target needs                                                                                        | Tool                                            | Examples                                                                                                                                       |
+| -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Directory** of non-source files                                                                              | \`build_copyDirectory\` — never per-file          | \`public/\`, \`static/\`, \`assets/\`, \`src/assets/\`, fonts, image bundles                                                                           |
+| **Identical** — byte-for-byte                                                                                  | \`build_copyFile\`                                | data modules, type files, JSON, fixtures, vendored utils, content/copy modules, shadcn primitives the source has already customized            |
+| **Trivial edits only** — ≤ 3 distinct edit sites                                                               | \`build_copyFile\` then \`build_editFile\` per site | import-path swaps (\`react-router-dom\` → \`react-router\`), single hook rename, one-line constant fix, removing a single \`"use client"\` directive |
+| **Structural changes** — different component APIs, framework wrappers, routing overhaul, data-hook replacement | \`build_writeFile\`                               | page components whose data layer is being rewritten, server handlers being reshaped to \`api(...)\`, router file being regenerated               |
+
+**Heuristic:** if you cannot name the specific lines that need to change before reading the file, you have not earned \`build_writeFile\` yet — \`build_readFile\` first, then re-classify.
+
+**Asset directories never get a per-file ruling.** If \`public/\` (or the platform's equivalent — see the per-platform guide) exists in the source, it ships as a single \`build_copyDirectory\` regardless of contents. Do not enumerate, do not skip, do not selectively copy "the ones you think you'll need."
+
 ## When emitting code
 
 - **Server.** Default-export one \`api({ name, integrations, input, output, run })\` from \`@superblocksteam/sdk-api\`. The \`name\` and the registry key in \`server/apis/index.ts\` must equal \`<ApiName>\` verbatim — the client calls \`useApi("<ApiName>")\` by that exact string. Preserve the external response shape exactly so the migrated frontend keeps working. Use parameterized SQL only (\`$N\`); zero string interpolations. Throw the error classes the sdk-api README documents instead of returning HTTP status codes.

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

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