@superblocksteam/vite-plugin-file-sync 1.99.99-next.2 → 2.0.0-SNAPSHOT.2143e2e95d0107ab

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

@@ -0,0 +1,312 @@
+// Auto-generated from src/ai-service/skills/system/superblocks-migration/SKILL.md
+// Do not edit directly - edit the .md file instead
+export const content = `---
+name: superblocks-migration
+description: |
+  Convert legacy Superblocks 2.0 YAML APIs ("block-chain" format) to the new 3.0 sdk-api TypeScript format.
+  Load when executing a v2→v3 migration turn — the runtime prompt will tell you to.
+readOnly: true
+metadata:
+  author: superblocks
+  version: "1.0"
+---
+
+# v2 → v3 API Translation
+
+You are converting **legacy Superblocks "block-chain" YAML APIs** into the **new code-mode \`@superblocksteam/sdk-api\` TypeScript format**. Each YAML file under \`scratch/v2-backup/apis/<ApiName>/api.yaml\` must be emitted as a single TypeScript file at \`server/apis/<ApiName>/api.ts\` that compiles, typechecks, and preserves behavior exactly.
+
+## Meta-rule: ZERO judgment calls
+
+If any situation below is not resolved deterministically by this document, **STOP** for that API. Do **not** pick a default. Do **not** guess a factory, a shape, or an import. Skip it, continue with other APIs, and mark the checklist item as \`failed\` via \`build_manageChecklist\` with a short \`failureReason\` describing the exact ambiguity (failing rule, block name if any, what would be needed to proceed). This rule overrides everything else.
+
+Corollary: do not add \`// TODO\` comments that silently ship. Unresolved items live only as \`failed\` checklist entries.
+
+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 \`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)
+
+Authoritative. If a rule here conflicts with your priors, these win.
+
+1. \`node_modules/@superblocksteam/sdk-api/README.md\` — whole thing (api() contract, execution model, \`ctx.*\`, exports, error classes, performance best practices, \`useApi\` frontend hook, integration method table).
+2. \`node_modules/@superblocksteam/sdk-api/src/index.ts\` (the **barrel**) — the authoritative list of exported factory names. Integration factory names are whatever this file exports, not whatever the directory name is. Never invent or case-fold a factory name without confirming it here.
+3. The README for **every integration** referenced by the YAMLs you convert:
+   - \`node_modules/@superblocksteam/sdk-api/src/integrations/<kind>/README.md\`
+   - If a vendor-specific factory exists for the target service (e.g., a dedicated one for a given LLM provider), prefer it over a generic HTTP one.
+4. \`skills/system/superblocks-migration/references/yaml-block-mapping.md\` — full YAML → TS mapping for each legacy block type.
+
+There is **no \`javascript\` integration** in sdk-api — inline JS/TS lives directly inside \`run(ctx, input)\`. Any block whose YAML key is \`javascript:\` becomes plain TypeScript in \`run()\`. 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:
+
+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.
+
+Hard constraints:
+
+- Do **not** rely on prior conversation memory, "knowledge" summaries, or inferred export names.
+- 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
+
+- One API per file, default export: \`export default api({ ... });\`.
+- Use ESM-style relative \`.js\` specifiers in imports.
+- File path: \`server/apis/<ApiName>/api.ts\` where \`<ApiName>\` is the YAML \`metadata.name\` (for example, \`GetFloors\` → \`server/apis/GetFloors/api.ts\`).
+- The \`api({ name })\` string and the registry key must both equal the YAML \`metadata.name\` verbatim — frontends call \`useApi("<metadata.name>")\`.
+
+### Registry registration (conditional)
+
+- If \`server/apis/index.ts\` exists in the target tree: add an import + entry for each new module. Do not reorder existing entries.
+- If it does **not** exist: do **not** create it, do not create scaffolding. Mark the checklist item \`failed\` with a \`failureReason\` noting the missing registry.
+
+## Critical rules
+
+1. **Integration IDs are opaque per-YAML.** Extract each distinct \`step.integration\` UUID to a named \`const\` at the top of the file. Never carry UUIDs across files.
+2. **SQL: parameterize always.** Zero \`\${…}\` interpolations may remain inside any SQL string. Dynamic lists use \`= ANY($N::<type>[])\` — never string-building \`IN (…)\`.
+3. **\`query\` vs \`execute\`.** Rows returned → \`query\` with Zod schema. Nothing actionable → \`execute\`.
+4. **Output shape preservation.** Mirror the legacy API's externally-visible response exactly — shape, nullability, cardinality. Do not wrap in envelopes.
+5. **Default is sequential.** \`TYPE_FOREACH\` → \`for ... of\` with sequential \`await\`. \`Promise.all\` only when YAML explicitly used a \`parallel:\` block.
+6. **Determinism, no slop.** No retries, no caching, no extra logging beyond a single \`ctx.log.info("<ApiName> start", {...})\` at the top of \`run\`. No narrative code comments.
+7. **Never invent client methods.** If the integration README only documents \`apiRequest\`, use \`apiRequest\`.
+
+## Security / user identity
+
+- \`authorization.type: AUTHORIZATION_TYPE_APP_USERS\` is enforced by the server; rely on \`ctx.user\` in TS.
+- If the YAML accepts \`userId\` / \`email\` / etc. as API input, remove that input and read from \`ctx.user\` instead.
+
+## Observability
+
+- One \`ctx.log.info("<ApiName> start", { <safe-ids> })\` at the top of \`run\` is allowed. Never log secrets, tokens, or PII.
+
+## Verification before you hand off
+
+Runtime verification (required):
+
+1. \`build_debug\` passing is required but not sufficient. Do not treat compile/typecheck success as proof that runtime behavior is correct.
+2. Use risk-based runtime checks: run \`testApi\` for APIs with integrations (REST/vendor/SQL), multi-step control flow, transformed outputs, or any uncertainty. For obviously simple APIs, you may skip \`testApi\`.
+3. If \`testApi\` output appears stale or mismatched, run \`build_reloadFile\` once and re-test. If runtime still fails after documented-method verification + one reload/retest cycle, record a concrete \`failureReason\` and continue.
+
+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\` → \`build_navigatePreview\` with that path → \`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\`.
+2. Zero \`\${…}\` interpolations remain in any SQL string.
+3. No SQL \`IN (…)\` built by concatenation; dynamic lists use \`= ANY($N::<type>[])\`.
+4. Every prior block's \`.output\` read is replaced by an actual result \`const\`.
+5. Input is the minimal union of identifiers the YAML references that are not produced by earlier blocks or \`Variables\`.
+6. Output shape exactly mirrors the legacy API's external response.
+7. If \`server/apis/index.ts\` exists, it registers the new module under \`metadata.name\`.
+8. **sdk-api integration wiring:** declare each integration in an \`integrations: { … }\` block and call it via \`ctx.integrations.<key>\` — never call \`postgres(ID)\` / \`github(ID)\` / etc. inside \`run()\` as if they were clients.
+9. **\`input\` / \`output\` schemas:** both are Zod schemas (\`input: z.object({…})\`, \`output: z.…\`). Do not use plain \`{ field: { type: "string" } }\` objects.
+10. **\`run\` signature:** \`async run(ctx, input)\` (or destructured input fields as the second argument). Never import \`ctx\` from the module scope.
+
+## Parallelization policy
+
+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\`.
+  - Split pending APIs into batches of ~5 (aim for 4–5 per batch; 4 workers × 5 APIs = 20, the hard cap), with a hard cap of **4 sub-agents** and **20 APIs** in this spawn. If more APIs remain pending, leave them for a **later spawn round** after this one returns — never enlarge a worker's share.
+  - The spawn tool will reject oversized batches and will refuse to fan out under heap pressure. If it errors because the batch is too large, shrink the batch and retry. If it refuses because of heap pressure, do not retry spawn in this turn — wait for a later turn after memory has dropped. Do not fall back to migrating remaining APIs yourself while the pending count is still ≥ 8.
+  - For each batch, craft an \`instructions\` string that:
+    - Names the exact \`<ApiName>\` values that sub-agent owns, verbatim, as a bulleted list.
+    - **Directs the sub-agent to \`build_readFile\` \`skills/system/superblocks-migration/SKILL.md\` (and the integration README(s) for the APIs it owns) before writing any files.** Do not inline a shortened sdk-api contract — keep a single source of truth.
+    - 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.
+    - **Restates the vacuous-pass rule and the sentinel explicitly**: the sub-agent must apply the \`passed\` outcome's vacuous-pass check itself (source real inputs before accepting a sad-path-only pass), and when it marks an API \`completed\` on an exhausted sourcing attempt it MUST set \`failureReason\` to \`vacuous_pass_accepted: <reason>\`. This is the only signal that reaches you — you run the final sweep without the sub-agents' chat context, so an unflagged vacuous pass is invisible to you.
+  - **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\`. Then re-count pending APIs; if any remain, repeat this batching step with another \`spawnCodingSubagents\` call. Do not proceed to the final sweep until every API item is \`completed\` or \`failed\`.
+
+## Per-API procedure
+
+For APIs you migrate yourself, or that you embed in a sub-agent's \`instructions\`:
+
+1. Call \`build_manageChecklist\` with \`action: "update"\`, \`itemId: "api_<ApiName>"\`, \`status: "in_progress"\`.
+2. Read \`scratch/v2-backup/apis/<ApiName>/api.yaml\` and any sibling files the blocks reference.
+3. Produce the TypeScript module at \`server/apis/<ApiName>/api.ts\`, overwriting the stub. Use the YAML block → TS mapping in \`skills/system/superblocks-migration/references/yaml-block-mapping.md\`.
+4. If \`server/apis/index.ts\` exists, update it to register the new module.
+5. 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 (\`apiInputs\` / externally-declared parameters) and the v3 TS from step 3 (\`input\` schema on \`run(ctx, input)\`). Every name the caller must supply must appear as a top-level key in \`inputs\` with a realistic value — a mock, or a real value harvested per the "Sourcing input values" rules below — matching its expected type. This includes two categories — do not conflate them:
+   - **API parameters** — names declared in \`apiInputs\` (v2) or the v3 \`input\` shape (e.g. \`sourceContext\`, \`currentDocument\`, \`messages\`). Pass each parameter name directly as a key in \`inputs\`. These are what the frontend passes when it invokes the API; they are not unavailable "runtime bindings."
+   - **UI bindings and caller context** — values the API reads from the app that are not API parameters (component values like \`Input1.value\`/\`Select1.selectedItem.id\`, table selections like \`Table1.selectedRow\`, state variables, workflow \`body\`/\`params\` not declared as \`apiInputs\`). Mock each binding the API references that isn't produced by an earlier block.
+
+   Both v2 and v3 receive the same \`inputs\`, so this is what makes the diff meaningful — \`{}\` for an API that expects parameters or bindings produces a vacuous \`both_failed\` that tells you nothing. Errors like \`'sourceContext' is not defined\` (v2) or v3 input-validation failures for missing required fields mean you omitted keys from \`inputs\`; synthesize mocks and retry. That is not an environmental failure.
+
+   **Sourcing input values — real app data over invented data.** A value is only "realistic" if the system the API talks to actually accepts it. Invented values are fine for self-contained inputs (a search string, a page size, a boolean flag). But when an input must reference something that already exists — any key the target system looks up, such as a row/record ID, a resource name, or an uploaded-file reference — do NOT invent it: an invented identifier either fails on both sides or exercises only the not-found/guard-clause path, and neither proves the API works. Source a real value instead, in this order:
+   1. **Harvest from the app's own APIs.** Find a read-only API in this app (prefer zero-input "list"/"get all" APIs) whose output contains the identifier you need, run it via \`testApi\`, and take a value from its real response. Chain as needed: a list API yields a real ID → pass it to the detail API → its response yields the next identifier. Prefer migrating and verifying zero-input read-only APIs first so their outputs become your pool of real test data.
+   2. **Follow the client code.** The \`useApi\`/\`useApiData\`/\`executeApi\` call sites under \`client/\` (and the v2 pages under \`scratch/v2-backup/\`) show where the app gets each input — a table's selected row, a route param, a select populated by another API. Trace that source to a concrete real value.
+   3. Only if neither path yields a value, fall back to an invented mock — and treat any resulting not-found/empty output as unverified (see the vacuous-pass rule under \`passed\` below).
+
+   Outcomes and how to resolve them:
+   - **\`passed\`**: \`passed\` only proves v2 and v3 agree on the inputs you supplied. Before accepting it, check what actually ran: if the shared output is a sad-path/guard-clause result — a not-found or error object from a caught exception, a validity flag that came back false, an empty result from a lookup that should have matched — the API's core logic never executed and the pass is vacuous. In that case source real inputs (per the sourcing rules above) and re-run \`runMigrationVerification\`; only accept a sad-path-only pass after the sourcing steps genuinely produced no usable value. Once a non-vacuous \`passed\` is in hand, call \`build_manageChecklist\` with \`status: "completed"\`. Done. If instead you are marking \`completed\` on an exhausted sourcing attempt (the pass stayed vacuous), you MUST also set \`failureReason\` to a string beginning \`vacuous_pass_accepted:\` followed by a one-line reason — this sentinel is the only durable signal that survives into the final sweep (and across sub-agents, whose chat context the orchestrator cannot see).
+
+   **Platform gate:** the checklist store rejects \`status: "completed"\` on \`api_<ApiName>\` items until verification has run at least once (\`lastVerificationAt\` is set — normally via this tool). You cannot bulk-mark APIs complete without calling \`runMigrationVerification\` per API.
+   - **\`skipped_mutation\`**: the runtime marks the checklist item \`completed\` with \`verificationSkippedReason: "mutation"\` automatically. Do **NOT** keep it \`in_progress\` or ask the user a grouped decision. Continue translating each API as well as you can from the code; the user will verify mutation-skipped APIs manually at finalize time.
+
+   - **\`v2_unrunnable\`**: the v2 backup itself couldn't execute, so there is no baseline to match. Call \`build_manageChecklist\` with \`status: "completed"\` and continue.
+
+   - **\`timeout\`**: a pipeline stalled past the reporting timeout (\`side\` says which one). This is transient environment noise — a dropped editor connection or a backgrounded browser tab — NOT evidence about the API. Do **NOT** mark the item \`completed\`. Retry \`runMigrationVerification\` after finishing your current API. If it times out repeatedly, tell the user verification is stalling (likely tab backgrounded / connection dropped), ask them to keep the app tab focused, and retry — never convert repeated timeouts into \`completed\`.
+
+   - **\`disconnected\`**: the editor connection was down when the pipeline tried to run (\`side\` says which one) — the app tab is closed, backgrounded, or reconnecting. Unlike \`timeout\` this diagnosis is certain, and it says nothing about the API. Do **NOT** mark the item \`completed\`. Tell the user the app tab must stay open and focused during verification, then retry \`runMigrationVerification\` — never convert \`disconnected\` into \`completed\`.
+
+   - **\`both_failed\`**:
+     - If you passed \`inputs: {}\` or omitted declared API parameters / bindings: synthesize real \`inputs\` (per the bullet above) and retry. Do NOT mark completed here — missing inputs caused this, not a real failure.
+     - If the error names a symbol that appears in \`apiInputs\` or the v3 \`input\` schema: add that key to \`inputs\` with a realistic mock and retry. Do NOT classify this as environmental — the parameter is available; you did not supply it.
+     - 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\`.
+
+## Updating integration write policy (Clark-only, with user consent)
+
+During migration, integration write policy (\`allow\` / \`deny\` per integration UUID) lives in \`scratch/migration-state.json\` → \`integrationWritePolicy\`. The pre-migration modal sets it once; **there is no mid-migration UI for the user to change it.**
+
+- **Only Clark can update write policy mid-migration**, and only when the user **explicitly asks** (e.g. "test this API even though I set Don't test", "go ahead and run writes against Postgres").
+- **Never** tell the user to update write policy in the UI — they cannot.
+- **Never** hand-edit \`scratch/migration-state.json\` with \`build_writeFile\` / \`build_editFile\` to change write policy. Use \`updateMigrationWritePolicy\` instead; it validates input and shows a permission card when granting \`allow\`.
+- To find integration ids: read the \`const\` UUID at the top of \`server/apis/<ApiName>/api.ts\`, or read existing keys from \`scratch/migration-state.json\` → \`integrationWritePolicy\`.
+- After updating policy to \`allow\` (with user approval), call \`testApi\` or \`runMigrationVerification\` again for the affected APIs.
+
+If \`testApi\` is blocked by access control because an integration is still \`deny\`, explain that the user previously chose "Don't test" for that integration and ask whether they want you to update the policy and retry — do not suggest they change settings in the UI.
+
+## User-reported manual verification
+
+Some APIs are marked \`completed\` without automatic testing — write-policy "Don't test" (\`verificationSkippedReason: "mutation"\`) or a \`testApi\` permission denial (\`verificationSkippedReason: "testing_denied"\`). The user is expected to verify these by using the app themselves.
+
+### When the user asks how to test a skipped API
+
+If the user requests manual test instructions for a specific API (including when the UI sends a prompt referencing \`skills/system/migration-api-verification/SKILL.md\`):
+
+1. Read \`skills/system/migration-api-verification/SKILL.md\` and follow it.
+2. Produce UI click-through steps for that API — do **NOT** call \`testApi\` or \`runMigrationVerification\`.
+
+### When the user confirms they verified an API
+
+If the user tells you they have checked such an API and it works (e.g. "I clicked through the app and GetOrders works, mark it complete"), call \`markApiManuallyVerified({ apiName })\`. Do **NOT** call \`testApi\` or \`runMigrationVerification\` for it — the user opted out of automatic testing. This records the API as user-verified so it no longer appears in the list of APIs needing manual verification.
+
+If the user instead asks you to **test** a denied or skipped API (not merely confirm they tested it manually), call \`updateMigrationWritePolicy\` first to grant \`allow\` for the relevant integration ids, then run \`testApi\` or \`runMigrationVerification\`.
+
+## 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, including the "Sourcing input values" rule (harvest real IDs from the app's read-only APIs; do not invent identifiers).
+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 and the final sweep below is done.
+
+## Final sweep: retry unverified happy paths with real app data (required once per run)
+
+If your closing summary would say "I could not verify the happy path for X" — that sentence is a trigger to do more work, not a conclusion to hand the user. Before marking the overall checklist completed/failed, do one last pass:
+
+1. From the checklist, collect every API that (a) is \`failed\` or unresolved because its test never succeeded, or (b) was marked \`completed\` but carries the \`vacuous_pass_accepted:\` sentinel in \`failureReason\` (set by you or by a sub-agent when a sad-path-only pass was accepted after exhausting sourcing).
+
+   Note on the parallel path: for APIs a sub-agent migrated, you cannot see its chat context or reconstruct its verification outputs — \`verificationOutcome\` records only the outcome type (\`auto_passed\`), not whether the pass was vacuous. The \`vacuous_pass_accepted:\` sentinel is therefore the ONLY way a sub-agent's vacuous pass surfaces here; APIs a sub-agent completed without it are treated as genuinely verified. This is why the sub-agent \`instructions\` MUST restate the vacuous-pass rule and the sentinel (see Parallelization policy). If you have specific reason to distrust a sub-agent's \`completed\` items (e.g. its batch reported many \`both_failed\` retries), re-verify them here with harvested real inputs rather than trusting the bare \`completed\`.
+
+2. For each, harvest real inputs from the app itself per the "Sourcing input values" rule in the per-API procedure: run the app's read-only APIs via \`testApi\` (zero-input list APIs first) and chain their real outputs into the inputs of the API under test.
+3. Re-run \`runMigrationVerification\` with those real inputs and resolve the outcome per the normal per-API rules.
+4. Only APIs whose sourcing steps genuinely produced no usable value (or whose failures are environmental per the \`both_failed\` rules) may finish the run without a happy-path verification — and each needs a \`failureReason\` or verification record saying so.
+`;
+//# sourceMappingURL=skill.generated.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"skill.generated.js","sourceRoot":"","sources":["../../../../../src/ai-service/skills/system/superblocks-migration/skill.generated.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,mDAAmD;AAEnD,MAAM,CAAC,MAAM,OAAO,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoTtB,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\n**Durable identifiers** (use these to recognize Claude Design even when layout is non-canonical):\n\n- No `package.json`, no `node_modules`, no `vite.config.*`, no `tsconfig.json` \u2014 a frontend-only prototype, not a Node/Vite project.\n- An HTML shell loading React, ReactDOM, and `@babel/standalone` from a CDN (commonly `unpkg.com`) and referencing JSX via `<script type=\"text/babel\" src=\"...\">`.\n- `/*EDITMODE-BEGIN*/ ... /*EDITMODE-END*/` markers around defaults blocks (e.g. `TWEAK_DEFAULTS` in `app.jsx`).\n- `useTweaks`, `TweaksPanel`, `TweakSection`, `TweakSlider`, `TweakRadio`, `TweakColor`, `TweakToggle` as window globals (often in `tweaks-panel.jsx`); postMessage protocol `__activate_edit_mode` / `__deactivate_edit_mode`.\n- `<html lang=\"...\" data-theme=\"light\">` (or `\"dark\"`) with CSS variables under `:root[data-theme=\"light\"]` / `:root[data-theme=\"dark\"]` (e.g. `--bg`, `--ink`, `--accent`).\n- Sample data hung off `window.*` from a `data.js`, `data.jsx`, or similarly named sibling; components may declare `/* global React, ReactDOM, ORDERS, ... */`.\n- Mounting via `ReactDOM.createRoot(document.getElementById(\"root\")).render(<App />);` against `<div id=\"root\"></div>` in the HTML body.\n- Inline `<style>` in `<head>` with hand-rolled component classes (`.topbar`, `.kpi`, etc.) \u2014 no Tailwind or shadcn in the source.\n\n**Common layout (hints, not rules):** a flat archive with one top-level `<Name>.html` plus sibling `app.jsx`, `data.js`, and `tweaks-panel.jsx`. Real exports often deviate \u2014 see _Non-canonical shapes you will encounter_ below.\n\nIf the user gave a path, use it. Otherwise walk the archive tree and match the durable identifiers above. If you see `EDITMODE-BEGIN` markers and a CDN-loaded React shell, treat it as Claude Design even when files are nested or duplicated. If anything is genuinely ambiguous (e.g. someone hand-built a similar HTML+JSX shell), ask before assuming Claude Design conventions.\n\n## Non-canonical shapes you will encounter\n\nUse best judgment when the tree deviates from the flat-archive textbook. Do not force files into a canonical layout \u2014 explore, reconcile, and ask on ambiguity.\n\n- **Nested project directory** \u2014 modules live under a subdirectory (e.g. `planning/`) with multiple `.jsx` files instead of flat siblings at the archive root. The real app usually lives in the nested dir; enumerate every module there.\n- **Bundler standalone HTML at the archive root** \u2014 a large minified `.html` (often multi-MB) that is a build artifact or preview bundle, not the editable entry. Prefer the human-authored shell that loads `<script type=\"text/babel\" src=\"...\">` with readable paths over a single-file bundle.\n- **Duplicate or stale files at the root vs nested dir** \u2014 root-level `app.jsx` / `data.js` may be outdated while the nested copy is canonical (or vice versa). Compare `<script type=\"text/babel\">` references in the entry HTML, `EDITMODE-BEGIN` blocks, and which files the globals comment lists before choosing what to port.\n- **Embedded design-system bundle** \u2014 directories such as `_ds/` with local fonts, tokens, or component CSS. Treat as vendored assets (`build_copyDirectory` for fonts/static CSS); they are not the app logic.\n- **`data.jsx` or other names** \u2014 fixture data may be `data.jsx`, `fixtures.js`, etc., not literally `data.js`. Follow whichever file the entry HTML and globals comment reference.\n- **Spec or guidance HTML inside the export** \u2014 e.g. `* - Spec.html`, README, or `.md` files describing product intent. Read these **before** mapping (see discovery checklist); they override misleading domain vocabulary in code (e.g. Jira/sprint terms in a quarterly-planning tool).\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` or `data.jsx` 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- **Guidance and intent first:** read the user's prompt and search the archive for spec/guidance artifacts (`*spec*`, `README*`, `*.md`, product-doc HTML such as `* - Spec.html`). Summarize product purpose, personas, and explicit non-goals before mapping UI. Do not infer product intent from domain vocabulary in code alone (e.g. Jira, sprint, ticket labels in a capacity-planning tool).\n- **True runtime entry HTML** \u2014 which `.html` file is the editable shell (loads `<script type=\"text/babel\" src=\"...\">` with readable paths)? Explicitly rule out large bundler-style standalone HTML decoys at the archive root.\n- **Nested vs root layout** \u2014 list every directory that contains `.jsx` / `.js` modules; note duplicate or stale files at the root vs nested dirs and which set the entry HTML references.\n- **Design-system bundles** \u2014 any `_ds/`, local font dirs, or vendored CSS trees; plan to copy as assets, not as app logic.\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 `.jsx` / `.js` file in the canonical module set and its purpose: which is the entry (`app.jsx` or equivalent), which are feature/UI modules loaded before it (e.g. `capacity.jsx`, `priorities.jsx`), which is the tweaks shell (`tweaks-panel.jsx`), which holds data fixtures (`data.js`, `data.jsx`, or similar). Derive the canonical set from the entry HTML's `<script type=\"text/babel\" src=\"...\">` tags in load order \u2014 do not assume a flat trio of `app.jsx` / `data.js` / `tweaks-panel.jsx` only.\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 canonical module set reads (look for `/* global ... */` comments at the top of each referenced `.jsx` / `.js` file) \u2014 these are the data fixtures and shared helpers to recreate.\n- Every exported component function across the canonical module set and its responsibility (tables, modals, gauges, admin panels, etc.) \u2014 not only functions defined in `app.jsx`. Nested exports often split UI across sibling modules (`capacity.jsx`, `priorities.jsx`, \u2026) that `app.jsx` composes. The migrated app keeps the same component breakdown and must port every module the entry HTML loads.\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 inferred product intent (from user prompt and/or in-archive spec), which HTML is the true entry, which module directory is canonical, the full list of `<script type=\"text/babel\">` modules in load order, what every tweak controls, and what each component in every referenced module renders, you haven't discovered enough.\n\n## Core mapping\n\n- **The HTML shell + canonical babel module set \u2192 one Superblocks page** at `client/pages/<Name>/index.tsx`, wired into `client/router.tsx` (commonly as the `index: true` route). `app.jsx` is usually the composition root, but the page must incorporate every sibling module the entry HTML loads (e.g. `data.jsx`, `capacity.jsx`, `priorities.jsx`, `health.jsx`, `inputs.jsx`, `admin.jsx`, \u2026). 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` / `data.jsx` / `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.** Port every function component defined in the canonical module set \u2014 each `.jsx` / `.js` file referenced by the entry HTML's `<script type=\"text/babel\" src=\"...\">` tags. Each becomes a sibling file under `client/pages/<Name>/components/<Name>.tsx` (or stays inline in `index.tsx` if tiny). `app.jsx` often composes modules defined elsewhere; do not port only `app.jsx` and drop sibling modules such as `capacity.jsx` or `priorities.jsx`. 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, wire cross-module references as ESM imports, 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\">` load order + `window.*` globals \u2192 ESM imports between `client/pages/...` files; each referenced source module maps to a migrated component or data module; `data.js` / `data.jsx` 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,qzlBAwHnB,CAAC"}

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

@@ -0,0 +1,124 @@
+// 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
+
+**Durable identifiers** (use these to recognize Claude Design even when layout is non-canonical):
+
+- No \`package.json\`, no \`node_modules\`, no \`vite.config.*\`, no \`tsconfig.json\` — a frontend-only prototype, not a Node/Vite project.
+- An HTML shell loading React, ReactDOM, and \`@babel/standalone\` from a CDN (commonly \`unpkg.com\`) and referencing JSX via \`<script type="text/babel" src="...">\`.
+- \`/*EDITMODE-BEGIN*/ ... /*EDITMODE-END*/\` markers around defaults blocks (e.g. \`TWEAK_DEFAULTS\` in \`app.jsx\`).
+- \`useTweaks\`, \`TweaksPanel\`, \`TweakSection\`, \`TweakSlider\`, \`TweakRadio\`, \`TweakColor\`, \`TweakToggle\` as window globals (often in \`tweaks-panel.jsx\`); postMessage protocol \`__activate_edit_mode\` / \`__deactivate_edit_mode\`.
+- \`<html lang="..." data-theme="light">\` (or \`"dark"\`) with CSS variables under \`:root[data-theme="light"]\` / \`:root[data-theme="dark"]\` (e.g. \`--bg\`, \`--ink\`, \`--accent\`).
+- Sample data hung off \`window.*\` from a \`data.js\`, \`data.jsx\`, or similarly named sibling; components may declare \`/* global React, ReactDOM, ORDERS, ... */\`.
+- Mounting via \`ReactDOM.createRoot(document.getElementById("root")).render(<App />);\` against \`<div id="root"></div>\` in the HTML body.
+- Inline \`<style>\` in \`<head>\` with hand-rolled component classes (\`.topbar\`, \`.kpi\`, etc.) — no Tailwind or shadcn in the source.
+
+**Common layout (hints, not rules):** a flat archive with one top-level \`<Name>.html\` plus sibling \`app.jsx\`, \`data.js\`, and \`tweaks-panel.jsx\`. Real exports often deviate — see _Non-canonical shapes you will encounter_ below.
+
+If the user gave a path, use it. Otherwise walk the archive tree and match the durable identifiers above. If you see \`EDITMODE-BEGIN\` markers and a CDN-loaded React shell, treat it as Claude Design even when files are nested or duplicated. If anything is genuinely ambiguous (e.g. someone hand-built a similar HTML+JSX shell), ask before assuming Claude Design conventions.
+
+## Non-canonical shapes you will encounter
+
+Use best judgment when the tree deviates from the flat-archive textbook. Do not force files into a canonical layout — explore, reconcile, and ask on ambiguity.
+
+- **Nested project directory** — modules live under a subdirectory (e.g. \`planning/\`) with multiple \`.jsx\` files instead of flat siblings at the archive root. The real app usually lives in the nested dir; enumerate every module there.
+- **Bundler standalone HTML at the archive root** — a large minified \`.html\` (often multi-MB) that is a build artifact or preview bundle, not the editable entry. Prefer the human-authored shell that loads \`<script type="text/babel" src="...">\` with readable paths over a single-file bundle.
+- **Duplicate or stale files at the root vs nested dir** — root-level \`app.jsx\` / \`data.js\` may be outdated while the nested copy is canonical (or vice versa). Compare \`<script type="text/babel">\` references in the entry HTML, \`EDITMODE-BEGIN\` blocks, and which files the globals comment lists before choosing what to port.
+- **Embedded design-system bundle** — directories such as \`_ds/\` with local fonts, tokens, or component CSS. Treat as vendored assets (\`build_copyDirectory\` for fonts/static CSS); they are not the app logic.
+- **\`data.jsx\` or other names** — fixture data may be \`data.jsx\`, \`fixtures.js\`, etc., not literally \`data.js\`. Follow whichever file the entry HTML and globals comment reference.
+- **Spec or guidance HTML inside the export** — e.g. \`* - Spec.html\`, README, or \`.md\` files describing product intent. Read these **before** mapping (see discovery checklist); they override misleading domain vocabulary in code (e.g. Jira/sprint terms in a quarterly-planning tool).
+
+## 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\` or \`data.jsx\` 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:
+
+- **Guidance and intent first:** read the user's prompt and search the archive for spec/guidance artifacts (\`*spec*\`, \`README*\`, \`*.md\`, product-doc HTML such as \`* - Spec.html\`). Summarize product purpose, personas, and explicit non-goals before mapping UI. Do not infer product intent from domain vocabulary in code alone (e.g. Jira, sprint, ticket labels in a capacity-planning tool).
+- **True runtime entry HTML** — which \`.html\` file is the editable shell (loads \`<script type="text/babel" src="...">\` with readable paths)? Explicitly rule out large bundler-style standalone HTML decoys at the archive root.
+- **Nested vs root layout** — list every directory that contains \`.jsx\` / \`.js\` modules; note duplicate or stale files at the root vs nested dirs and which set the entry HTML references.
+- **Design-system bundles** — any \`_ds/\`, local font dirs, or vendored CSS trees; plan to copy as assets, not as app logic.
+- The HTML shell file (\`<Name>.html\`) and the \`<title>\` it sets — that is the prototype's name and should anchor your \`<PageName>\`.
+- Every \`.jsx\` / \`.js\` file in the canonical module set and its purpose: which is the entry (\`app.jsx\` or equivalent), which are feature/UI modules loaded before it (e.g. \`capacity.jsx\`, \`priorities.jsx\`), which is the tweaks shell (\`tweaks-panel.jsx\`), which holds data fixtures (\`data.js\`, \`data.jsx\`, or similar). Derive the canonical set from the entry HTML's \`<script type="text/babel" src="...">\` tags in load order — do not assume a flat trio of \`app.jsx\` / \`data.js\` / \`tweaks-panel.jsx\` only.
+- 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 canonical module set reads (look for \`/* global ... */\` comments at the top of each referenced \`.jsx\` / \`.js\` file) — these are the data fixtures and shared helpers to recreate.
+- Every exported component function across the canonical module set and its responsibility (tables, modals, gauges, admin panels, etc.) — not only functions defined in \`app.jsx\`. Nested exports often split UI across sibling modules (\`capacity.jsx\`, \`priorities.jsx\`, …) that \`app.jsx\` composes. The migrated app keeps the same component breakdown and must port every module the entry HTML loads.
+- 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 inferred product intent (from user prompt and/or in-archive spec), which HTML is the true entry, which module directory is canonical, the full list of \`<script type="text/babel">\` modules in load order, what every tweak controls, and what each component in every referenced module renders, you haven't discovered enough.
+
+## Core mapping
+
+- **The HTML shell + canonical babel module set → one Superblocks page** at \`client/pages/<Name>/index.tsx\`, wired into \`client/router.tsx\` (commonly as the \`index: true\` route). \`app.jsx\` is usually the composition root, but the page must incorporate every sibling module the entry HTML loads (e.g. \`data.jsx\`, \`capacity.jsx\`, \`priorities.jsx\`, \`health.jsx\`, \`inputs.jsx\`, \`admin.jsx\`, …). 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\` / \`data.jsx\` / \`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.** Port every function component defined in the canonical module set — each \`.jsx\` / \`.js\` file referenced by the entry HTML's \`<script type="text/babel" src="...">\` tags. Each becomes a sibling file under \`client/pages/<Name>/components/<Name>.tsx\` (or stays inline in \`index.tsx\` if tiny). \`app.jsx\` often composes modules defined elsewhere; do not port only \`app.jsx\` and drop sibling modules such as \`capacity.jsx\` or \`priorities.jsx\`. 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, wire cross-module references as ESM imports, 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">\` load order + \`window.*\` globals → ESM imports between \`client/pages/...\` files; each referenced source module maps to a migrated component or data module; \`data.js\` / \`data.jsx\` 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwHtB,CAAC"}

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

@@ -0,0 +1,2 @@
+export declare const content = "# Lovable-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's specific to a Lovable source.\n\n> Lovable is not a fixed stack. Unlike Replit, there is no canonical template to assume. A Lovable app may talk to Lovable Cloud / Supabase directly from the client, may have edge functions, may call arbitrary third-party APIs, may have no backend at all, or may mix all of the above. **Discover before you map.** Do not assume Supabase, do not assume an Express server, and do not invent integrations the source does not use.\n\n## Where the source lives\n\nHallmarks: `src/integrations/supabase/client.ts`, `src/integrations/supabase/types.ts`, `supabase/config.toml`, `supabase/functions/<name>/index.ts`, `supabase/migrations/`, a `lovable-tagger` entry in `vite.config.ts`, or a Lovable-flavored README.\n\nIf the user gave a path, use it. Otherwise look for the hallmarks above in the working tree. If ambiguous, ask.\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**: React 18 + Vite + TypeScript + Tailwind + shadcn/ui. Routing via `react-router-dom` (v6 or v7) or sometimes `wouter`. Data fetching via `@tanstack/react-query`. Forms via `react-hook-form` + `zod`.\n- **Backend (when present)** \u2014 pick whichever the source actually uses:\n  - **Lovable Cloud / Supabase** is the default. Surfaces in the source as `src/integrations/supabase/client.ts`, `src/integrations/supabase/types.ts`, a top-level `supabase/` dir with `migrations/` and/or `functions/<name>/index.ts` (Deno edge functions), and direct `supabase.from(\"table\").select(...)` calls from React components.\n  - **Edge functions** (Deno-style): `supabase/functions/<name>/index.ts`. Each is its own HTTP endpoint, may use `Deno.serve`, often reads `Deno.env.get(...)`.\n  - **Third-party APIs** called from the client (Stripe, OpenAI, Resend, etc.) \u2014 frequently with secrets that should never have been on the client.\n  - **No backend at all** \u2014 pure static app, possibly with localStorage state. The framework's \"Don't fabricate a backend\" rule applies; the migrated app stays frontend-only.\n- **Auth**: `supabase.auth` from the client (`signInWithPassword`, `onAuthStateChange`, `getSession`). Sometimes wrapped in an `AuthContext`.\n- **Storage**: `supabase.storage.from(bucket).upload(...)` or third-party upload services.\n- **Realtime**: `supabase.channel(...).on(\"postgres_changes\", ...)` subscriptions. **Superblocks has no realtime equivalent in this template \u2014 flag and degrade to polling or one-shot fetches; do not silently drop.**\n\n## Discovery checklist\n\nThis is the most important step for a Lovable migration \u2014 get it wrong and the rest is rework. In addition to the framework's discovery requirements, build a list of:\n\n- Every distinct backend interaction: Supabase table queries (grouped by table + operation), Supabase RPC calls, edge functions, third-party API calls (each endpoint), storage operations, realtime subscriptions, auth calls.\n- Every env var and where it's used (client vs. server, whether it's a secret).\n- Every Supabase migration file and the schema it implies.\n- Every RLS policy you can find \u2014 these become explicit `WHERE` clauses post-migration.\n- Every leaked secret found on the client side (`VITE_*`, hardcoded keys) \u2014 these go into the security note at the end.\n\nIf the discovery summary doesn't tell you what every API will look like, you haven't discovered enough.\n\n## Core mapping\n\n- **Each client-side Supabase call \u2192 one Superblocks API**, then call it via `useApi`/`useApiData`. Direct database access from the client is not how Superblocks apps work \u2014 every read and write flows through `server/apis/<ApiName>/api.ts`.\n  - `supabase.from(\"table\").select(...)` \u2192 `api()` with a Postgres integration and `ctx.integrations.db.query(...)`. Translate the PostgREST filter chain (`.eq`, `.in`, `.order`, `.range`, `.limit`) into parameterized SQL \u2014 never string-interpolate user input.\n  - `supabase.from(\"table\").insert/update/upsert/delete(...)` \u2192 `.execute(...)` with parameterized SQL.\n  - `supabase.rpc(\"<fn>\", { ... })` \u2192 `SELECT * FROM <fn>(...)` via `.query` if it returns rows, else `.execute`.\n  - **RLS / row-level-security policies** in Lovable do not transfer automatically. The Superblocks API runs as the integration's service user, not the end user. You must enforce per-user filtering in SQL using `ctx.user.userId` (or another claim) explicitly. Audit every ported query \u2014 if the original relied on `auth.uid()` in an RLS policy, the ported SQL needs an equivalent `WHERE user_id = $N` clause. Missing filters are a security bug. Write a one-line comment above the clause noting which RLS policy it replaces, since the _why_ is non-obvious to a future reader.\n  - **Schema**: Postgres tables exist on the integration the user binds. Do not run Lovable's `supabase/migrations/*.sql` against the target DB. Read them to understand schema and surface a summary; if the integration's DB is empty or schema-mismatched, stop and ask the user how they want to proceed (apply migrations manually, point to an existing DB, or defer).\n- **Each `supabase/functions/<name>/index.ts` edge function \u2192 one Superblocks API** at `server/apis/<NameInPascalCase>/api.ts`. Translate `Deno.serve`'s request handler the same way as any other handler: body/query/params \u2192 unified `input` schema, response \u2192 `return { ... }` from `run`. `Deno.env.get(...)` \u2192 `ctx.env`. Edge-function-specific helpers (CORS headers, JWT verification middleware) \u2192 drop; the platform handles them.\n- **Each third-party API call \u2192 integration**. `fetch(\"https://api.stripe.com/...\")` becomes a declared integration plus `apiRequest(...)`. Secrets from `import.meta.env.VITE_*`, hardcoded keys, or `Deno.env.get` move into the integration definition. A `VITE_OPENAI_API_KEY` on the client side is also a security finding worth surfacing in the migration summary.\n- **`supabase.auth` \u2192 `ctx.user`**. Drop `AuthContext` providers, sign-in pages, password-reset flows, and magic-link handlers \u2014 they have no role in a Superblocks app.\n- **`supabase.storage` \u2192 integrations**. If the source uses Supabase storage, ask the user which target storage integration to use (S3, GCS, etc.) \u2014 there is no Lovable-flavored \"storage\" integration. Surface the buckets used in the discovery summary.\n- **`supabase.channel(...)` realtime subscriptions** \u2192 not supported in this template. Flag as a `failed` checklist item with `failureReason: \"realtime subscription on <table> has no Superblocks equivalent\"`, and ask the user before silently rewriting to polling.\n\n## Ask-before-guessing \u2014 Lovable specifics\n\n- \"The source uses Supabase for both database and auth \u2014 bind to an existing Postgres integration, or do you want to point at a different DB? Auth is platform-managed in Superblocks regardless.\"\n- \"I see direct calls to `<third-party API>` from the client with secrets in `VITE_*` env vars. I'll move these server-side via an integration \u2014 confirm which integration to bind, or whether to create a new one.\"\n- \"The source has Postgres migrations under `supabase/migrations/`. I will not run them against your integration's database. How do you want the schema to land?\"\n- \"I see realtime subscriptions on `<table>`. Superblocks has no realtime in this template \u2014 degrade to polling, drop the feature, or stop and let you decide?\"\n- \"RLS policy `<policy>` filtered by `auth.uid()`. I'll replace it with `WHERE user_id = $N` keyed off `ctx.user.userId`. Is that the right user-claim mapping?\"\n\n## Page port \u2014 what changes vs. what doesn't\n\nFor each Lovable page, only these change:\n\n- **Data hooks**: direct Supabase calls + `@tanstack/react-query` \u2192 `useApi` / `useApiData`.\n- **Auth touchpoints**: `supabase.auth` / custom `AuthContext` \u2192 platform-managed (drop the provider; consume `ctx.user` server-side).\n- **Router primitives**: if the source uses `wouter` or v6 patterns, adapt to `react-router` v7. The router is statically parsed by the editor \u2014 bind page components only via static imports or `lazy(() => import(\"...\"))` (see \"Router shape\" in the framework SKILL). Lovable sources commonly emit a long `<Routes>` block with `<Route element={<Page />} />` JSX; rewrite this as a `createBrowserRouter([...])` array using `Component:` (or inline `lazy:`), keeping the `const Page = lazy(() => import(\"./pages/Page/index.tsx\"))` declarations intact.\n\nEverything else \u2014 JSX structure, Tailwind classes, shadcn variants, custom CSS, theme tokens, fonts, layout containers \u2014 transfers unchanged. If the diff goes beyond data + auth + routing, you are over-editing.\n\n## Done \u2014 Lovable specifics\n\nIn the final report, additionally surface:\n\n- Any unsupported features that became `failed` items (realtime subscriptions, Supabase storage without a target integration, etc.).\n";
+//# sourceMappingURL=lovable.generated.d.ts.map

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

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