fimo 2.2.0-staging.8 → 2.2.0

package/assets/skills/fimo-migration/SKILL.md

@@ -34,6 +34,20 @@ end-to-end. Preserve the original code path and record required environment
 variable names only; never read or copy secret values. A missing secret is a
 follow-up for the owner, not permission to silently remove the integration.
 
+Before any source, target, Fimo, or remote write, inspect the available source
+read-only and follow [questions-and-improvements.md](references/questions-and-improvements.md).
+Use the coding agent's native structured-question UI when available. Ask one
+stacked batch of the decisions the source cannot answer instead of interrupting
+the migration for each question. A migration request never authorizes moving
+environment values or credentials.
+
+When migration replaces local or bundled content with Fimo reads, preserving
+content-delivery performance is part of fidelity. Keep build-time and
+server-rendered content off the browser request path, use direct generated-client
+lookups, avoid duplicate or sequential reads, and prove edit freshness. Do not
+ask a generic optimization question or bundle a framework upgrade into the
+migration.
+
 ## Execution environment
 
 Run this skill from a coding-agent process that has direct access to the
@@ -139,13 +153,18 @@ report the exact failed command and setup requirement.
   unwired.
 - Prefer source code and exports over inferred crawl data. Use a public URL as
   visual, SEO, route, and behavior evidence when better source material exists.
+  When the source defines an active CMS but its deployed records are unavailable,
+  rebuild published content from the public site only after the user explicitly
+  chooses that lower-confidence path.
 - Read local files and exports directly and public APIs without credentials.
   Private APIs and CMSs require a user-provided export or a narrowly scoped
   server-side credential. Never read credentials from browser code or copy
   them into browser code, migration artifacts, or reports. Target-project
   authentication does not grant source access. If the source API URL or access
-  is missing or unreachable, stop and ask the user for it; do not guess, replace
-  the content, or mark the lane complete.
+  is missing or unreachable, stop and ask whether the owner wants to provide a
+  scoped export or read-only access, reconstruct the selected published routes
+  from public pages, or migrate code only and leave those records external. Never
+  infer permission to scrape, discover secrets, or contact private endpoints.
 - Model content before page code. Generated JSON is not imported content.
 - Model editorial content Fimo-natively: blocks for structured or repeatable
   sections, richtext for rich bodies, references for categories, authors,
@@ -190,9 +209,11 @@ report the exact failed command and setup requirement.
      create the draft evidence pack.
    - **hybrid**: source material plus a public URL. Treat source material as
      truth and the URL as comparison evidence.
-4. Read `references/workflow.md` before implementation and create or update the
+4. Read `references/questions-and-improvements.md`, finish its read-only
+   preflight, and collect the user's decisions before setup or implementation.
+5. Read `references/workflow.md` before implementation and create or update the
    plain-text migration plan.
-5. Load the references that apply:
+6. Load the references that apply:
    - Coordinator ownership and dependency gates -> `references/workers.md`.
    - Framework conversion worker -> `references/workers/framework.md`.
    - Content planner -> `references/workers/content-planner.md`.
@@ -227,9 +248,13 @@ ID supplied by the owner — without one, stop with an unresolved owner action
 instead of inventing an ID:
 
 - Link an owner-supplied (empty) project:
-  `fimo migrate init <target-dir> --project-id <projectId> --framework <framework>`
+  `fimo migrate init <target-dir> --project-id <projectId> --framework <framework> --source-platform <platform>`
 - Create a new project in an owner-supplied organization:
-  `fimo migrate init <target-dir> --org <organizationId> --framework <framework>`
+  `fimo migrate init <target-dir> --org <organizationId> --framework <framework> --source-platform <platform>`
+
+`--source-platform` names what the site is migrated from (`wordpress`, `nextjs`,
+`astro`, `react-router`, `webflow`, `framer`, `squarespace`, `wix`, `carrd`,
+`other`); pass what the source checkout proves, `unknown` only when nothing does.
 
 After setup, check `.fimo/config.json#runtime.framework` and the scaffold's
 framework files before starting workers. A Next.js target must still have its
@@ -265,14 +290,20 @@ Commands that perform actual data writes, all requiring the linked target:
 - `fimo schemas push`, `fimo assets upload`, `fimo entries create|update`,
   `fimo singles update`, `fimo labels set|set-many`, `fimo forms push`.
 - `fimo migrate init` (source-backed form): the project link/creation and
-  initial commit push described above.
+  initial commit push described above. Pass `--source-platform <platform>`
+  (webflow, framer, squarespace, wix, carrd, wordpress, nextjs, astro,
+  react-router, other) when the source is known; URL crawls detect it.
+
 - `fimo link`: project creation or selection plus the in-place adoption of a
   copied source target.
 - `fimo deploy` / `fimo publish` — owner-approved only.
 
 ## Migration loop
 
-1. Run the setup path from "Initialized target precondition" and inspect the
+1. Inspect the source read-only, then ask the one preflight question batch from
+   `references/questions-and-improvements.md`. Do not initialize, link, import,
+   edit, or move environment values until the user answers every consent gate.
+2. Run the setup path from "Initialized target precondition" and inspect the
    initialized target before any worker edits it. A `fimo link` adoption keeps
    the source framework; the `fimo init` / `fimo migrate init` paths choose the
    target framework through the same canonical option as
@@ -284,7 +315,7 @@ Commands that perform actual data writes, all requiring the linked target:
    copying an arbitrary template path. The target's real files and directories
    are the authority for framework paths; do not invent a second `app/` or
    `src/app/` tree from an example.
-2. Write a short `.fimo/migration/migration-plan.md` containing the chosen
+3. Write a short `.fimo/migration/migration-plan.md` containing the chosen
    framework, source/target paths, worker owners, important dependencies, and
    known questions. Start the independent workers in `references/workers.md`:
    runtime/config, routes/SEO, content planning, and locales when those surfaces
@@ -293,25 +324,25 @@ Commands that perform actual data writes, all requiring the linked target:
    all structural target code, and must pass the framework gate in
    `references/workers/framework.md` before content data and code workers
    start. Worker prompts and worker reports are plain text.
-3. The content planner reads every content-bearing source and consumer. When
+4. The content planner reads every content-bearing source and consumer. When
    content comes from an API, it traces the active application client and
    retrieves the complete accessible dataset before pushing schemas. It then
    writes complete schemas and import payloads, recording source items,
    consumers, batches, and unresolved behavior in the text plan rather than a
    second orchestration format.
-4. Each discovery lane reports active media in its own surface. After the
+5. Each discovery lane reports active media in its own surface. After the
    runtime/framework, routes/SEO, and content discovery receipts are terminal,
    the coordinator performs one fan-in: combine and deduplicate them into the
    complete media-obligation list. Give only that list to the media worker; do
    not require a content-planner rescan. Once it returns every mapping, patch
    code and payload consumers. Start data after the asset gate and content code
    only after its imported records read back successfully.
-5. Fan in the workers' plain-text reports. Compare their claimed files with
+6. Fan in the workers' plain-text reports. Compare their claimed files with
    `git diff`, their Fimo writes with read-back CLI queries, and their source
    coverage with the content plan. Every source item must be migrated,
    deliberately preserved, or listed as unresolved with an owner action. A
    report that merely says “done” is not evidence.
-6. Validate against the real target with a validator that did not author the
+7. Validate against the real target with a validator that did not author the
    changes and starts only after every other worker report is terminal: read
    back schemas, entries, singles, labels, and assets through the CLI, build
    the project, render the migrated routes, and verify hosting compatibility
@@ -319,13 +350,15 @@ Commands that perform actual data writes, all requiring the linked target:
    when a browser is available; otherwise use deterministic
    HTTP/header/process/log checks and mark visual proof unavailable. Then run
    the QA gate in `references/qa.md`.
-7. Write `.fimo/migration/migration-report.md` with coverage, counts, mappings,
+8. Write `.fimo/migration/migration-report.md` with coverage, counts, mappings,
    unresolved items, timings from worker reports, and next actions.
 
 ## References
 
 - `references/workflow.md` - phase order, source intake, URL artifacts, and
   implementation loop.
+- `references/questions-and-improvements.md` - structured preflight questions,
+  integration consent, and content-delivery performance preservation.
 - `references/decision.md` - plain-text decision and schema guidance; no
   decision JSON is required.
 - `references/content.md` - CMS, entries, references, and source value rules.
@@ -359,10 +392,15 @@ Use one final status:
 - **draft-only**: imports or verification are incomplete, or the user asked for
   a draft.
 
-Never call a migration complete when CMS entries, media mappings, forms, or
-route coverage are unknown. Local QA remains the acceptance gate. If
+Never call a migration complete when CMS entries, media mappings, forms, route
+coverage, or migration-induced content-delivery regressions are unknown. Local
+QA remains the acceptance gate. If
 `fimo migrate init` created a new Fimo project, run one `fimo deploy` after QA
 and return its preview and dashboard links; skip it when the user said not to
 deploy or `FIMO_MIGRATION_NO_DEPLOY=1` is set. For an existing linked project,
 offer the deployment and wait for approval. Never run `fimo publish` without an
 explicit request.
+
+Broader performance work and framework modernization are separate tasks. Start
+them only when the user explicitly asks, and never use them to hide a migration
+regression.

package/assets/skills/fimo-migration/references/frameworks/nextjs.md

@@ -158,6 +158,14 @@ document, and a `public/` reference may become a media upload. The content
 planner decides the destination from the consuming route and data shape, rather
 than using a filename or extension as an automatic classification.
 
+Preserve how that content reaches the page. Local Markdown rendered during a
+Next build stays a Server Component or static-generation read after it moves to
+Fimo. Keep `generateStaticParams` when the source has known routes, list the
+required slugs once, and use the generated client's `getBySlug` for each detail
+page. Do not fetch the full post collection and filter it on every route, and do
+not introduce a Client Component solely to load Fimo content. Follow the shared
+evidence and freshness contract in `references/questions-and-improvements.md`.
+
 Create one source item per Markdown/MDX document and per independently handled
 construct inside it. Portable prose and an executable MDX component are
 different items even when they share one file. Read the custom component, its

package/assets/skills/fimo-migration/references/media.md

@@ -86,6 +86,17 @@ the asset owns the uploaded bytes and their metadata, and the entry field holds
 the media value `{ source, url, alt }` that points at it. Keep both carrying the
 same alt text, and do not duplicate alt into a second schema field.
 
+Do not copy upload metadata into media values yourself. Writing `{ source, url,
+alt }` is enough: the write path resolves and persists the media-library ID, and
+a read that names the field in `populate` returns the asset's current URL, name,
+MIME type, and intrinsic dimensions from the library. A read that does not name
+it returns the stored reference. The ID lets you inspect the asset later with
+`fimo assets open <id> --download`.
+
+Treat intrinsic dimensions as source facts, not layout instructions. Choose the
+displayed size, crop, `sizes`, loading behavior, and fit from the migrated page's
+design and responsive behavior.
+
 ## Failure Handling
 
 If a media asset cannot be downloaded or uploaded:

package/assets/skills/fimo-migration/references/qa.md

@@ -85,6 +85,16 @@ items.
   and public APIs were read under their simple access rules; private sources
   used a user export or narrowly scoped server-side credential. Missing access
   is unresolved for that lane, and no content was guessed.
+- Each content family moved from local or bundled files to Fimo records its
+  build-time, request-time, or browser delivery mode before and after migration.
+  Build-time and server-rendered source content did not become a browser API
+  waterfall.
+- Detail routes use a direct generated-client lookup when available. Indexes use
+  bounded pagination and projection. Shared reads are deduplicated, independent
+  reads start together, and page-only reads do not block a shared root layout.
+- Production evidence labels cold and warm navigation separately and records
+  observable Fimo/API request counts, duplicates, order, and longest blocking
+  read. Development-only timing is never presented as production proof.
 
 For linked Next.js targets, the root `FimoProvider` resolves an explicit host
 connection first, otherwise `.fimo/project.json` plus the active git branch,
@@ -124,6 +134,8 @@ Owned by the runtime lane; verified here read-only.
 ## Behavior
 
 - Dependencies are installed in the target project.
+- The recorded CLI and companion package specifiers are reproducible outside
+  the current package-manager cache and match the selected runtime channel.
 - The project builds successfully.
 - Local dev starts without Vite loader/schema/form generation errors.
 - Primary routes render without console/runtime errors.
@@ -135,6 +147,10 @@ Owned by the runtime lane; verified here read-only.
 - Every content-code batch exercised at least one non-empty imported item
   through each Server-to-Client or plain-JSON boundary it introduced; build
   success over an empty query result does not pass this check.
+- Server-rendered source content remains in the initial server result and is not
+  fetched again after hydration. A new client waterfall, repeated full-list
+  read, avoidable sequential request chain, or stale edit fails the responsible
+  migration lane.
 - Navigation and footer links point to migrated routes or documented external URLs.
 - Missing integration secrets do not block these checks: build, dev, and route
   render run with the integration inert, and the missing key is a recorded
@@ -160,7 +176,9 @@ equivalent):
 5. Assert globally rendered label/button text (header/footer nav, CTAs, cookie
    banner) is non-empty; blank text usually means the component is mounted
    outside the label provider.
-6. Inspect the browser console and server output for runtime errors.
+6. Assert visible text and attributes contain no source-absent serialization
+   sentinels such as `undefined`, `null`, `[object Object]`, or `NaN`.
+7. Inspect the browser console and server output for runtime errors.
 
 Keep it bounded: representative pages and one interaction, not an interactive
 walk of every route or a multi-hour visual audit. The Visual section below
@@ -176,6 +194,11 @@ report; never claim a visual check that did not run.
 - Prioritize layout, typography, content hierarchy, media, and brand tokens.
 - Remove generated placeholder copy from visible UI.
 - Verify media aspect ratios and no broken images on primary routes.
+- Compare representative component bounds; whole-page height can hide a local
+  geometry regression.
+- Compare image loading before and after scroll. Record eager/lazy and preload
+  counts, response formats, and representative transfer sizes; an optimizer
+  URL alone is not delivery proof.
 
 ## Import Verification
 
@@ -231,6 +254,8 @@ complete | complete-with-unresolved | draft-only
 
 ## Hosting
 
+## Content Delivery
+
 ## Timing
 
 ## Checks
@@ -248,9 +273,10 @@ locales) with `gate`,
 coverage must not average away a missing entry or an unuploaded asset. Timing is
 a separate section copied from the worker reports, so it never dilutes coverage.
 
-Cache freshness is a report check only when the source or user made freshness an
-accepted observable requirement; do not fail a migration for omitted provider
-cache mechanics alone.
+Cache freshness is a report check whenever migration changes the content
+transport or rendering mode. Do not fail a migration for omitted provider cache
+mechanics alone, but do fail stale Fimo edits caused by the target's migrated
+read path.
 
 Use `complete` only when all required checks pass. Use
 `complete-with-unresolved` when the migrated site is usable and all gaps are

package/assets/skills/fimo-migration/references/questions-and-improvements.md

@@ -0,0 +1,188 @@
+# Migration questions and content delivery
+
+## Inspect before asking
+
+Start with read-only source inspection. Find the framework, router, version,
+content sources, integrations, API routes, environment variable names, and
+obvious runtime constraints. Do not initialize or link the target, edit files,
+write Fimo data, contact private services, deploy, or publish yet.
+
+Do not ask the user to explain facts the source already proves. Ask only when
+the answer changes authorization or forces a real choice:
+
+- an integration may be removed, replaced, disconnected, or moved;
+- environment configuration or credentials may need to move into Fimo;
+- the source framework is unknown or the user requested a conversion;
+- the source defines CMS content but the deployed records are unavailable;
+- two systems could own the same content or behavior; or
+- the requested migration includes a destructive or mutually exclusive choice.
+
+Preserve the source's visible behavior by default. Do not ask the user to list
+the routes, metadata, feeds, forms, locales, analytics, or content that must
+survive. Discovering and preserving them is the migration job. Do not ask a
+generic speed, optimization, or framework-upgrade question during migration.
+
+## Ask one stacked batch
+
+Use the coding agent's native structured-question UI when it has one. The tool
+name differs between Codex, Claude Code, and other hosts.
+
+- Collect decisions from the same inspection and ask one preflight batch. Aim
+  for one to three questions.
+- Include setup blockers already visible at that point, such as a missing target
+  choice, organization or project, URL-only framework choice, or pinned CLI
+  artifact. Do not save them for separate follow-up turns.
+- Give each question a short subject and two or three concrete choices. Put the
+  recommended safe default first and state the consequence of each choice.
+- Write for the site owner, who may not know Fimo or the migration process. Do
+  not put evaluator terms such as faithful acceptance, frozen result, or probe
+  in a user-facing question. Explain Fimo terms the first time they matter.
+- Group environment keys by the integration they enable. Never ask one question
+  per key.
+- Use multi-select for independent choices when the host supports it. Otherwise
+  offer a few useful bundles.
+- Restate the accepted contract once after the answers, then start. Ask again
+  only when new evidence creates a safety or consent decision that the initial
+  inspection could not reveal.
+- When the host has no structured-question UI, send the whole batch as one
+  numbered message. Do not drip questions across turns.
+
+## Protect integrations and environment values
+
+Detect integration and environment key names without printing or reading their
+values. A request to migrate the website is not consent to move any environment
+value.
+
+- Keep third-party behavior wired when Fimo does not replace it exactly.
+- Never silently remove, replace, or partly imitate an integration.
+- Ask before changing its owner, credential store, or runtime behavior.
+- Without consent, leave current environment references unchanged. Mark live
+  verification blocked when credentials are unavailable.
+- When the user chooses Fimo storage, load the current `fimo-cli`
+  `project-vars-and-secrets` reference. Browser-safe configuration uses project
+  variables. Hidden API keys and tokens use project secrets. Never turn a
+  secret into a public variable.
+- When the owner chooses Fimo-managed secrets, ask them to add the values to
+  Fimo. Never read existing secret values from env files, logs, browser code,
+  migration artifacts, or worker transcripts.
+
+## Ask before reconstructing missing CMS content
+
+Source repositories often contain CMS schemas and rendering code without the
+deployed records. A public website can recover what visitors can see, but it
+cannot prove drafts, unlinked records, editorial metadata, hidden relations, or
+private fields. Do not silently substitute scraped pages for the missing CMS.
+
+When required CMS records are unavailable, ask one question with these choices:
+
+- **Provide CMS access or an export (Recommended).** Use a scoped read-only
+  credential or export to preserve the selected records, relations, locales,
+  SEO, and media as completely as the source allows.
+- **Rebuild from the public website.** Use credential-free public APIs when
+  available, then the rendered pages for the user-approved route slice. Treat
+  the run as hybrid, import only published evidence, and report everything the
+  public site cannot reveal.
+- **Migrate code only.** Keep the CMS integration and its records outside Fimo;
+  do not claim that editorial content moved.
+
+The question should sound like this:
+
+> The repository contains the CMS structure, but not the content currently
+> published on the site. Should I use a read-only CMS export, rebuild the
+> selected pages from the public website, or migrate only the code and leave the
+> content where it is?
+
+If the owner chooses the public website, stay inside the selected route scope.
+Public retrieval does not authorize private endpoint discovery, credential use,
+or a broader crawl. Record the URL, retrieval time, redirects, and every field
+or relation that remains unknown.
+
+## Ask what happens outside a partial migration
+
+When the request selects only part of a website and does not say what should
+happen to the remaining pages, ask in the same preflight batch:
+
+> We're moving only part of the site. What should happen when someone follows
+> a link to a page we aren't moving?
+
+Offer these choices:
+
+- **Keep opening the current site.** Preserve working absolute source URLs for
+  pages outside the selected slice.
+- **Remove those pages.** Remove their navigation links and redirect known old
+  routes to the migrated homepage instead of leaving broken relative links.
+
+Do not ask when every route is migrating or the request already settles this
+behavior. If the coordinator discovers an omitted route only after preflight,
+preserve its working absolute source URL and report it. Do not interrupt the
+migration with a late preference question.
+
+## Preserve content delivery performance
+
+Replacing local Markdown, MDX, JSON, or hardcoded content with Fimo reads must
+not add an avoidable runtime wait. This is migration correctness, so apply it
+without asking an optimization question.
+
+First record how the source delivers each content family: at build time, on the
+server per request, or in the browser. Load the current `fimo-code` framework
+and generated-client references, then keep the same rendering and freshness
+semantics unless the target framework requires a documented equivalent.
+
+- Keep build-time or server-rendered source content on the server. Do not turn
+  a local Markdown page into a client-side loading state or browser API
+  waterfall.
+- Preserve known-route generation. For a static blog, list slugs once for route
+  generation, then use `getBySlug` or another direct generated-client lookup for
+  each detail route. Do not list the whole collection and filter it again on
+  every page request.
+- Start independent reads together. Keep page-only content out of shared root
+  layouts, and deduplicate the same read when metadata, a layout, and a page
+  need it during one render.
+- Query only the fields, relations, and page of records the route consumes.
+  Populate required references explicitly. Avoid unbounded collection reads and
+  N+1 relation lookups.
+- Keep framework links and their normal prefetch behavior. Do not add broad
+  forced prefetching that turns a page list into a burst of Fimo requests.
+- Preserve edit freshness. Static generation, revalidation, or caching is valid
+  only when a normal rebuild or the source's normal refresh path shows the new
+  Fimo value. Cold-build once as a diagnostic when the normal result is stale.
+- Do not upgrade the framework, change routers, add loading placeholders, or
+  redesign the page to satisfy this rule. Those are separate changes unless the
+  user explicitly requested them.
+
+Examples:
+
+- **Static Markdown blog:** import every post into Fimo, generate the known
+  routes from a bounded slug list, read each post on the server during static
+  generation, and ship the article in the initial HTML. A browser fetch for the
+  article body is a migration regression.
+- **Large collection:** use a paginated, projected list for the index and a
+  direct slug lookup for the detail page. Fetching every full record for every
+  navigation is a migration regression even when the page eventually matches.
+- **Fresh request-time page:** keep the Fimo read in the framework's server
+  loader or Server Component. Stream only when the source already tolerated
+  partial rendering or a new wait would otherwise block the whole page.
+
+## Prove the transport did not regress
+
+Run the production build and production server. Development mode may include
+compilation and may disable prefetching, so label any development observation
+as development-only.
+
+For every content family moved from local or bundled source files to Fimo:
+
+1. Record whether the source and target reads happen at build time, request
+   time, or in the browser.
+2. Check one cold navigation and one warm navigation separately.
+3. Capture Fimo/API request count, duplicate reads, request order, and the
+   longest blocking read when observable.
+4. Verify that server-rendered source content remains in the initial server
+   result and is not fetched again after hydration.
+5. Run the normal edit, render, and revert proof. When caching or static output
+   is involved, record normal-build and cold-build freshness separately.
+
+Do not invent a universal millisecond budget. Timing starts as evidence. Fail
+the migration when it introduces an objective transport regression, such as a
+new client waterfall, repeated full-list reads, avoidable sequential requests,
+or stale edits. A broader performance review or framework upgrade is separate
+work and starts only when the user explicitly asks for it.

package/assets/skills/fimo-migration/references/workers/content-planner.md

@@ -66,15 +66,20 @@ data workers start:
    REST endpoints. Ask for an owner-provided export or narrowly scoped
    server-side token only when website-required records are not public. Never
    recover, log, persist, or copy secret values. If required access is missing
-   or unreachable, stop before planning schemas or payloads.
+   or unreachable, stop before planning schemas or payloads until the owner
+   chooses scoped access, public-site reconstruction, or a code-only migration.
 3. Fetch every required page, locale, and referenced record. For a few bounded
    endpoints, direct requests are enough. For repeated or paginated reads,
    write a temporary source-specific read-only script under
    `.fimo/migration/tmp/`, then spot-check counts and references.
-4. Preserve the retrieved responses as source evidence and payload inputs;
+4. When the owner chose public-site reconstruction, retrieve only the approved
+   published routes. Use credential-free public APIs when available and rendered
+   HTML otherwise. Mark drafts, unlinked records, hidden relations, and private
+   fields unknown instead of inventing them.
+5. Preserve the retrieved responses as source evidence and payload inputs;
    normalize transport details only. Do not create a provider registry or a
    universal CMS model.
-5. Design Fimo schemas from both the retrieved values and the code that uses
+6. Design Fimo schemas from both the retrieved values and the code that uses
    them. Keep uncertain fields optional unless authoritative evidence requires
    them; sampled enum-like values are strings, and private or absent fields
    remain unknown. Never invent replacement content when access is unavailable.

package/assets/skills/fimo-migration/references/workers/validator.md

@@ -1,7 +1,16 @@
 # Migration validator
 
-The validator is an independent read-only worker. It did not author the
-migration and starts only after all writers return.
+Validation is one independent read-only wave after all writers return. The
+coordinator gives every validator the accepted migration scope and deliberate
+user-approved differences, but no producer findings, repair reasoning,
+transcript, or expected verdict. A validator checks the finished target against
+the source within that contract. It does not report an explicitly excluded
+route, integration, or control as migration drift.
+
+When subagents are available, launch separate workers for build and runtime,
+Fimo data and content, and rendered browser behavior. Run them concurrently
+after their prerequisites pass. They may inspect overlapping files because none
+of them writes.
 
 Compare the source, content plan, actual `git diff`, real Fimo state, and local
 application behavior. A worker report is a claim, not evidence.
@@ -29,7 +38,12 @@ representative page responds. After an approved deploy, browser QA must:
 
 Optional development-tool failures do not fail a rendered, stable application.
 
-Return a plain-text report with status, duration, checks run, counts, failing
-source items, and suggested bounded repair surface. The coordinator may run one
-repair for that surface and rerun validation. It does not restart every worker
-or loop indefinitely.
+Each lane continues through independent assertions and returns status,
+duration, checks run, counts, failing source items, blocked descendants, and
+suggested repair ownership. Stop only when a failed prerequisite makes a check
+meaningless.
+
+The coordinator fans every lane into one finding set before editing. It assigns
+disjoint repair owners, waits for the whole repair wave, then reruns one central
+validation wave. It does not restart every worker, repair findings one at a
+time, or loop indefinitely.

package/assets/skills/fimo-migration/references/workers.md

@@ -22,7 +22,7 @@ Plan a lane only when the source proves that surface exists:
 | assets/forms    | media uploads and form behavior                 | after discovery fan-in   |
 | content data    | one schema/locale import                        | after assets             |
 | content code    | listed consuming files                          | after its data read-back |
-| validator       | read-only final checks                          | after all writers        |
+| validation wave | read-only build, data, and rendered checks      | after all writers        |
 
 This is preserve mode, the default. When the user explicitly chose a framework
 conversion, one framework worker replaces runtime and routes and owns all
@@ -55,7 +55,7 @@ read-back.
   visitor-visible labels.
 - **framework conversion** is used only after explicit user choice. Read
   `references/workers/framework.md`.
-- **validator** authors nothing. Read `references/workers/validator.md`.
+- **validation wave** authors nothing. Read `references/workers/validator.md`.
 
 If two lanes need one file, name one owner in the text plan and sequence the
 other after it. Do not add a metadata format for a small overlap.
@@ -76,7 +76,9 @@ other after it. Do not add a metadata format for a small overlap.
    framework gate.
 6. Start each code worker only after its own imported records read back as
    non-empty. A build over empty data proves nothing.
-7. Start the independent validator only after every writer has returned.
+7. After every writer returns, start one read-only validation wave. When
+   subagents are available, run build and runtime, Fimo data and content, and
+   rendered browser checks concurrently after their prerequisites pass.
 
 Each prompt names the worker's source paths, exact target ownership, applicable
 reference above, and dependencies. Each report states status, duration, source
@@ -84,8 +86,17 @@ evidence, files changed, Fimo writes, source items handled, unresolved work,
 and the next action. The coordinator verifies those claims against `git diff`,
 CLI read-back, and rendered routes.
 
+Validation prompts also carry the accepted migration scope and user-approved
+differences, including selected routes, behavior for routes outside a partial
+migration, excluded integrations, and the deploy boundary. This is task context,
+not an expected verdict. Do not give validators producer findings, repair
+reasoning, transcripts, or instructions to accept a difference.
+
 A source item is covered only when its target value exists and the application
 consumes it at the original behavior path, or when an explicit unresolved item
-names the impact and owner action. If validation fails, create one bounded
-repair task for that surface and rerun the validator; do not restart every
-worker.
+names the impact and owner action. Collect the complete finding set before
+repair. Fan it into one repair graph, run disjoint repair owners together, wait
+for all of them, then rerun one central validation wave. A failed prerequisite
+blocks only dependent checks; it does not stop unrelated diagnostics. Do not
+restart every worker or alternate one finding with one repair when the next
+validation pass could have exposed the full set.