fimo 0.17.0 → 0.18.0

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

@@ -29,6 +29,22 @@ Record what is available:
 - sha256 or another stable hash when possible
 - source references and target references
 
+## Alt Text Belongs To The Media
+
+Alt text is media metadata, not a content field. An image that has alt text in
+the source never justifies a standalone alt field in a collection or content
+schema; the alt travels with the media value.
+
+- Preserve the source alt on the media value alongside `source` and `url`, and
+  pass it through the asset upload metadata when the CLI exposes it. When the
+  upload command cannot carry it, keep it on the media value and record the
+  limitation as a note on the media item.
+- Never use the filename as alt text.
+- When the source has no alt, a meaningful generated alt is an explicit
+  fallback only: mark it with the media item's `altSource`
+  (`references/manifest.md`) so an editor can see which alt text the source did
+  not provide.
+
 ## Dedupe
 
 Deduplicate by hash when local bytes are available. If not, deduplicate by
@@ -45,7 +61,8 @@ failing. Either upload it (and record the Fimo target), or mark it `unresolved`
 with an owner action. "Bundled locally, upload later" is not an acceptable
 terminal state for referenced media.
 
-After upload, update the manifest with the Fimo target asset ID/URL.
+After upload, record the Fimo target asset ID/URL in the worker and migration
+reports.
 
 When using downloaded files from a Fimo migration pack, copy the recorded
 `localPath` from the media map exactly. Do not reconstruct local filenames from
@@ -62,6 +79,11 @@ Replace source references in this order:
 Schema media should render through Fimo media primitives. Do not hardcode source
 URLs for editable media fields.
 
+The library asset and the media value stored in an entry are distinct concerns:
+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.
+
 ## Failure Handling
 
 If a media asset cannot be downloaded or uploaded:
@@ -71,3 +93,13 @@ If a media asset cannot be downloaded or uploaded:
 - list every page/entry that references it
 - include a suggested action such as re-exporting the asset folder or providing
   credentials
+
+## Planner obligations
+
+The content planner enumerates every media obligation before fan-out: route and
+SEO media, every schema media field, and every image node nested in richtext or
+Tiptap JSON. Record its source location, consuming route/entry, and intended
+target field or node. Give each obligation a stable identity that includes its
+field or rich-text node path; a shared label or source URL is not unique. The
+asset worker cannot report complete until every obligation has an uploaded or
+duplicate Fimo mapping, or an explicit unresolved/unsupported disposition.

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

@@ -50,5 +50,29 @@ Use these notes to decide what is source of truth and what must be rebuilt.
 
 - Search for structured data before assuming static content: CSV, JSON, MD/MDX,
   frontmatter, CMS SDK calls, route loaders, API fixtures.
-- Identify the current framework only to understand routing/data, not to copy
-  implementation patterns into Fimo.
+- Identify the current framework to understand routing and data. A source
+  repository keeps its framework, router, and runtime for the first migration.
+  If detection or hosting compatibility stays unclear, stop and ask. Do not
+  select Next.js as a fallback; a conversion happens only after the user's
+  explicit choice, through the framework conversion worker and gate in
+  `references/workers.md`.
+
+## Provider-specific hosting
+
+- A provider file is evidence, not disposable scaffolding. Inventory its rules
+  and classify each one as preserved, replaced, safely unnecessary
+  implementation detail, or unresolved.
+- Preserve the file until its externally observable behavior has an accepted,
+  verified replacement. Delete it only when redundancy is proven or the user
+  explicitly accepts the loss.
+- Cloudflare cache storage, purge, and revalidation code may be safely
+  unnecessary when it has no external caller and no accepted freshness
+  contract depends on it. Do not copy provider mechanics merely to imitate the
+  implementation.
+- Redirects, security headers, route and 404 behavior, Markdown negotiation,
+  feeds, sitemap, `llms.txt`, social metadata, and forms are public behavior.
+  Preserve them or replace them with an equivalent and verify the result.
+- A React Router/Vite site can remain React Router/Vite even when Cloudflare-only
+  hosting features are conditional or unresolved. Hosting uncertainty is not
+  permission to convert the application; only the user's explicit choice
+  starts a conversion.

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

@@ -1,19 +1,117 @@
 # Migration QA Gate
 
-Run this gate before reporting completion.
+Run this gate before reporting completion. The gate is read-only: it starts
+only after every other worker has returned a terminal report, and it never
+repairs what it finds — failures become bounded repair tasks or unresolved
+items.
 
 ## Coverage
 
 - Every intended source route is implemented, ignored with a reason, or unresolved.
+- The source route surface is preserved: routes were not restructured to
+  shrink the migration, and no group of source pages was replaced by a generic
+  static shell.
+- Every imported schema, entry, single, and label has a consuming target route
+  or component. Content that exists in Fimo but is not rendered by the
+  application is unwired, not covered.
+- Every source content item is represented in the target: a content type, a
+  field, a block, a reference, a label, or an explicit unresolved item.
+- The editorial model is Fimo-native and not silently flattened. Structured or
+  repeatable editorial sections are blocks, rich bodies are richtext, and
+  categories, authors, related items, and repeated taxonomies are references -
+  not hardcoded strings, raw IDs, or opaque JSON. Every `json` field carries a
+  recorded reason that no Fimo-native model fits.
+- Editable shared chrome (header, footer, navigation, site settings) has a
+  singleton or other content model an owner can edit, and labels are limited to
+  small UI copy and reusable translations.
+- Content type, field, and block names are semantic and editor-facing: no markup
+  tags, HTML attributes, locale suffixes, or column indexes.
+- Modeling did not redesign the site: the migrated routes render the same
+  content, order, and copy as the source, and the text plan records the
+  source-to-Fimo mapping.
+- Media alt text is attached to the media (asset metadata and media value), with
+  no standalone alt field in a content schema. Alt is never the filename, and a
+  generated fallback is recorded as generated.
+- Every planner `sourceFile`/`sourceKey` maps to its original consumer. Imported
+  labels or prose that are only appended elsewhere, including an additive
+  “Page content” section, are unwired gaps. Use existing literal-key extraction
+  for a bounded read-only comparison when it is sound; otherwise report every
+  unmapped key from the planner consumer map. Do not build a generic AST or
+  codemod system for this check.
 - Every CMS export file is mapped to a schema, ignored with a reason, or unresolved.
 - Source entry counts match imported counts (entries created in Fimo), excluding
   documented skips/unresolved. Generated seed JSON alone does not satisfy this.
 - Every media item referenced by routes, CMS entries, SEO, or forms is uploaded to
   the Fimo media library (Fimo asset id/URL) or has an unresolved item. A local
   `public/` copy is not an upload mapping.
-- Every visible form has a Fimo replacement, third-party plan, or unsupported note.
+- Every planner media obligation, including schema media fields and nested
+  richtext/Tiptap image nodes, has a mapping or explicit disposition; the asset
+  worker's completion claim alone is not evidence.
+- Every visible form has a Fimo replacement, a preserved third-party
+  integration, or an unsupported note. A form became Fimo-native only when the
+  Fimo form matches the source behavior 1:1.
+- The detected source framework, router, runtime, and configuration are
+  preserved. React Router/Vite remains React Router/Vite; any Next.js conversion
+  has the user's explicit choice. Unsupported or unclear hosting is unresolved,
+  not hidden by a conversion or deleted configuration.
+- In conversion mode, the framework gate passed before content code work: the
+  conversion worker's self-checks and the coordinator's independent rerun of
+  the build and representative route checks are both recorded. A gate failure
+  caps the status at draft-only or leaves the affected routes unresolved; no
+  route was replaced by a generic shell or another framework as a fallback.
+- Every preserved third-party integration keeps its original wiring, and the
+  credential environment keys it needs are recorded by name. A missing secret
+  is an unresolved user follow-up, never silently removed behavior.
 - SEO title, description, canonical URL, share image, slugs, dates, authors,
   categories, tags, redirects, and locales are preserved when present.
+- Existing SEO, OG, and social behavior - including dynamic OG image routes -
+  is preserved or explicitly reported as a gap.
+- When the source has no low-risk SEO or social value, safe defaults derived
+  from verified page/site data are present or the missing behavior is reported;
+  the migration must not invent marketing claims.
+- Redirects and security headers stay in the source framework config when the
+  target keeps the source runtime and host, or are translated with a recorded
+  note in the text migration report when the target runtime or host requires
+  it.
+- Every provider-specific rule is classified as preserved, replaced, safely
+  unnecessary implementation detail, or unresolved. A deletion has evidence of
+  redundancy or the user's accepted loss.
+- Public behavior is verified independently: blog routes and 404s, Markdown
+  negotiation, RSS, sitemap, `llms.txt`, OG/social metadata, redirects,
+  security headers, and forms where present. Cloudflare cache storage, purge,
+  and revalidation internals need no copy when proven externally irrelevant.
+- Each content/data lane records its source-access class. Local files/exports
+  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.
+
+For linked Next.js targets, `withFimo` derives `FIMO_CONTENT_API_URL` and
+`NEXT_PUBLIC_FIMO_API_URL` from `.fimo/project.json` during `next dev`,
+`next build`, and `next start`. Both aliases resolve to the same tenant API,
+while non-empty user overrides remain untouched; no committed env file is
+required.
+
+## Hosting
+
+Owned by the runtime lane; verified here read-only.
+
+- The target starts locally: the dev server responds without startup errors.
+- The target is embeddable in Fimo Preview, which frames the app in an iframe
+  and drives it over the postMessage preview bridge. Development/preview
+  responses carry no unconditional `X-Frame-Options` or CSP `frame-ancestors`
+  block; protective headers (nosniff, HSTS, referrer policy) stay. The
+  translation goes through `FIMO_PREVIEW_ALLOWED_ORIGINS`; `withFimo` alone
+  does not solve headers — it only extends `allowedDevOrigins` during
+  `next dev`.
+- The runtime report covers local startup, preview embedding, build, derived
+  aliases, header translations, and integration env-key names, with every
+  claim backed by evidence.
+- With a browser available, record `browserProof` (rendered route plus console
+  state) for startup and embedding. Without one, use deterministic HTTP
+  status/header/process/log checks and mark visual proof explicitly
+  unavailable in the report.
+- Deployment smoke is explicit owner opt-in; never run deploy or publish as a
+  QA step.
 
 ## Behavior
 
@@ -21,13 +119,49 @@ Run this gate before reporting completion.
 - The project builds successfully.
 - Local dev starts without Vite loader/schema/form generation errors.
 - Primary routes render without console/runtime errors.
+- In conversion mode, every route in the conversion worker's route map renders
+  locally with the expected status (including 404) and shows its source text
+  landmarks, and the target has exactly one app tree.
 - Collection listing/detail pages work with imported data, seed data, or explicit
   empty states.
+- 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.
 - 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
+  follow-up.
 - Unsupported app behavior is not hidden behind broken UI.
 
+## Browser smoke (required)
+
+Build success and HTTP 200 responses are not sufficient evidence: a page can
+build, return 200, and still render blank labels or an empty collection. Run
+one bounded, scriptable browser pass (Playwright, agent-browser, or
+equivalent):
+
+1. Start the app and wait for hydration, not just the HTTP response.
+2. Open a representative set of pages: home, one collection listing, one
+   collection detail, one static page.
+3. Exercise one representative interaction (open the nav menu, an accordion,
+   or a filter) and assert its visible result.
+4. Assert expected visible text on each opened page and at least one dynamic
+   collection item rendered from imported Fimo data.
+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.
+
+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
+remains a separate spot check.
+
 ## Visual
 
+Visual checks need a browser. When none is available, run the deterministic
+Hosting checks instead and mark visual proof explicitly unavailable in the
+report; never claim a visual check that did not run.
+
 - Compare source and migrated site at desktop and mobile sizes.
 - Prioritize layout, typography, content hierarchy, media, and brand tokens.
 - Remove generated placeholder copy from visible UI.
@@ -42,8 +176,11 @@ Record:
 - media uploaded/failed
 - forms pushed
 - redirects/locales imported or unresolved
+- the exact CLI used for the run, recorded in the report's Source section (see
+  "CLI provenance" in `SKILL.md`)
 
-Counts must be written into `.fimo/migration/manifest.json`.
+Counts belong in `.fimo/migration/migration-report.md` and the relevant worker
+reports. Do not create a JSON QA registry just to store them.
 
 Media, entries, and forms are blocking checks. Entries generated as seed JSON but
 not created in Fimo, and media bundled under `public/` but not uploaded to the
@@ -66,15 +203,25 @@ complete | complete-with-unresolved | draft-only
 
 ## Source
 
+## Coverage by dimension
+
 ## Routes
 
-## CMS
+## Content
 
 ## Media
 
 ## Forms
 
-## SEO, Redirects, Locales
+## SEO and OG
+
+## Redirects and Headers
+
+## Integrations
+
+## Hosting
+
+## Timing
 
 ## Checks
 
@@ -83,15 +230,22 @@ complete | complete-with-unresolved | draft-only
 ## Next Actions
 ```
 
+`Coverage by dimension` is one row per migration surface (routes, content,
+forms, SEO/OG, redirects/headers, integrations, hosting, media, labels, and
+locales) with `gate`,
+`discovered`, `migrated`, `verified`, `unresolved`, `unsupported`,
+`denominator`, and `coverage`. Never collapse it into a single score: full route
+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.
+
 Use `complete` only when all required checks pass. Use
 `complete-with-unresolved` when the migrated site is usable and all gaps are
 owner-visible. Use `draft-only` when import or verification has not happened.
 
-The bundled script can update `qa.status` and write the report:
-
-```bash
-node <this-skill>/scripts/write-migration-report.mjs <project-root>
-```
-
-If it fails, read the generated report and either complete the missing work or
-add precise unresolved items with owner-friendly suggested actions.
+Write the report directly as text. A later evaluator may calculate the table
+from it, but the migration does not need a manifest or report-generation
+registry to run.

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

@@ -0,0 +1,39 @@
+# Content execution workers
+
+Execute the content planner's text handoff. Do not rediscover the source,
+reclassify values, redesign schemas, or edit files outside the assigned batch.
+If the handoff is incomplete, report the missing item to the coordinator so the
+planner can repair it.
+
+## Data worker
+
+Own one bounded schema/locale payload. Start only after every referenced asset
+has a confirmed Fimo mapping and, during conversion, the framework gate passes.
+Perform create-or-update writes and read the batch back before returning.
+
+For entry batches, use
+`fimo entries bulk-create <Uid> --file <payload> --upsert-by slug` and report
+per-chunk created, updated, reconciled, and conflict counts. Do not leave a
+payload as evidence of an import. An unavailable dependency blocks promptly;
+do not poll indefinitely.
+
+## Code worker
+
+Start only after this batch's real records read back as non-empty. Own exactly
+the consumer files assigned by the planner.
+
+1. Load the active framework's `fimo-code` reference.
+2. Establish the generated Fimo client/adapter needed by the batch.
+3. Replace every planned `sourceFile`/`sourceKey` at its existing consumer in
+   place. Appending a disconnected duplicate section is not wiring.
+4. Preserve executable React/MDX children in order around editable prose.
+5. Render at least one real imported item through every Server-to-Client or
+   plain-JSON boundary in the batch. Use the framework's generated
+   serialization/hydration contract; do not partially unwrap tracked values.
+6. Confirm each original literal or data source is gone only where its Fimo
+   replacement now renders once.
+
+A loader that reads Fimo while the consuming markup is missing, an imported
+entry no route consumes, or a successful build over empty data is incomplete.
+Return source items wired, files changed, read-back/render evidence, and any
+unresolved item in plain text.

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

@@ -0,0 +1,64 @@
+# Content planning worker
+
+Own semantic discovery, schema authoring, payload preparation, and the text
+handoff. Do not import entries or rewrite application consumers.
+
+1. Inspect every content-bearing source and consumer: Markdown/MDX bodies and
+   frontmatter, JSX/TSX modules, hardcoded arrays and objects, imports, data
+   clients, and call sites. Read local exports and public APIs directly. A
+   private API requires a user-provided export or narrowly scoped server-side
+   credential; never recover or copy secret values.
+2. Classify each value as collection content, single content, an
+   editor-visible label, or application-owned code. Repetition is evidence,
+   not an automatic collection rule. Assistive text, identifiers, and values
+   that drive behavior are not labels.
+3. Define complete schemas from source evidence: types, requiredness, defaults,
+   uniqueness, locale behavior, media constraints, references, and
+   cardinalities. Do not invent constraints. Load `references/decision.md` and
+   the target project's Fimo schema guidance.
+4. Trace every item to the route, component, loader, query, or render module
+   that consumes it. Record its `sourceFile`, `sourceKey`, target files, payload
+   file, and worker batch. Finding data without consumers is incomplete.
+5. Enumerate every media field and rich-text image node as an asset obligation.
+6. Write and push `src/schemas/*.json`, generate required clients/types, and
+   write self-contained JSON payloads for the data workers.
+7. Write `.fimo/migration/content-plan.md` before any entry, label, single, or
+   content-driven code rewrite begins.
+
+The text plan has one source item per independently migrated construct and
+groups them into non-overlapping data and code batches. Every object in a
+hardcoded content array is an item. MDX prose and executable imports/components
+are separate items when needed; executable JSX cannot disappear inside a
+rich-text conversion.
+
+Keep the handoff short:
+
+```md
+## BlogPost
+
+- Source: `content/blog/post.mdx`
+- Schema: `src/schemas/BlogPost.json` (pushed)
+- Payload: `.fimo/migration/content/BlogPost.en.json`
+- Items: title, body, cover, `CoverageChart` behavior
+- Consumers: `src/app/blog/[slug]/page.tsx`
+- Data worker: `BlogPost/en`
+- Code worker: `blog-rendering`, owns the consumer above
+
+## Unresolved
+
+- `content/blog/post.mdx:11`: `CoverageChart` implementation is absent; owner
+  must restore it. Do not remove the node silently.
+```
+
+A construct is unresolved only when it genuinely cannot be migrated. Include
+its exact source, user-visible impact, reason, and owner action; "custom" is not
+a reason.
+
+## Optional extraction helpers
+
+Start with `rg` and targeted reads. A bounded read-only helper under
+`.fimo/migration/tmp/` may parse repeated frontmatter, JSON/YAML exports, or
+literal structures while preserving source locations. Spot-check its output.
+The agent still owns classification, schema design, and consumer tracing. Do
+not build a generic codemod system or let the helper write Fimo data or app
+code.

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

@@ -0,0 +1,37 @@
+# Framework conversion worker
+
+Use this worker only after the user explicitly chose a framework conversion.
+Preserve mode never uses it.
+
+`fimo migrate init` creates the target first. Inspect the initialized template
+and its real paths before writing. Own all structural target code: dependencies,
+framework config, root layout and providers, app tree, route modules, 404,
+redirects, headers, middleware, sitemap/robots/OG structure, and locale-routing
+structure. There is no separate runtime or route writer during conversion.
+
+Port the source APIs, loaders, hardcoded content, integrations, and visible
+behavior into the new framework unchanged. Do not migrate those values to Fimo
+in this pass; schemas, data, and Fimo consumer wiring belong to later content
+workers. The content planner may inspect the source in parallel but must not
+edit structural target code.
+
+Load the target framework's `fimo-code` and hosting references. For Next.js,
+also load `references/frameworks/nextjs.md` and translate portable hosting
+behavior before declaring provider-specific behavior unresolved.
+
+## Framework gate
+
+Before returning, self-check and report:
+
+- dependencies install cleanly;
+- the framework build succeeds;
+- every source route maps to a target route and renders locally with its
+  expected status, including 404 behavior;
+- representative source text landmarks appear;
+- exactly one app tree and one root layout exist; and
+- primary routes have no runtime or console errors.
+
+Return a plain-text route map, files changed, check results, preserved behavior,
+and unresolved behavior. The coordinator independently reruns the build and
+representative route checks. Content data cannot start until this gate and the
+asset gate pass.

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

@@ -0,0 +1,25 @@
+# Migration validator
+
+The validator is an independent read-only worker. It did not author the
+migration and starts only after all writers return.
+
+Compare the source, content plan, actual `git diff`, real Fimo state, and local
+application behavior. A worker report is a claim, not evidence.
+
+Verify:
+
+- every source route renders with expected status and representative content;
+- schemas, entries, singles, labels, media, forms, and locales exist through
+  CLI read-back;
+- every planned source item is consumed at its original behavior path, not in
+  an appended duplicate section;
+- media URLs load as their expected media type;
+- native Fimo APIs are used without migration-only wrappers;
+- imports are safe to rerun;
+- build and representative browser interactions pass; and
+- every unsupported item names its impact and owner action.
+
+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.

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

@@ -0,0 +1,82 @@
+# Migration workers
+
+The root coding agent is the coordinator. It inspects the initialized target,
+writes a short text plan, starts independent workers through its native
+subagent mechanism, and fans their results back in. If subagents are
+unavailable, run the same lanes sequentially; never skip a surface silently.
+
+The CLI does not start language models. JSON is reserved for Fimo schemas and
+content payloads. Worker ownership, dependencies, reports, and unresolved work
+stay in `.fimo/migration/*.md` or the agents' plain-text responses.
+
+## Schedule
+
+Plan a lane only when the source proves that surface exists:
+
+| worker          | owns                                            | starts when              |
+| --------------- | ----------------------------------------------- | ------------------------ |
+| runtime         | framework/runtime files and provider config     | immediately              |
+| routes          | route modules, redirects, SEO and host behavior | immediately              |
+| content planner | schemas, content payloads, and content handoff  | immediately              |
+| locales         | locale setup and translated UI copy             | immediately              |
+| assets/forms    | media uploads and form behavior                 | after content planner    |
+| 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        |
+
+This is preserve mode, the default. When the user explicitly chose a framework
+conversion, one framework worker replaces runtime and routes and owns all
+structural target code. The content planner may run beside it. Data then waits
+for both the asset and framework gates, and code waits for real imported-data
+read-back.
+
+## Ownership
+
+- **runtime** preserves the detected framework, router, runtime, dependencies,
+  provider setup, environment wiring, and provider-specific configuration. An
+  unclear or unsupported setup produces a question, not a silent conversion.
+- **routes** preserves every route, redirect, 404, SEO/OG/social output,
+  sitemap, robots, feeds, headers, and other observable host behavior. A file
+  that consumes migrated content belongs to its later content-code worker.
+- **content planner** discovers and models all editable content, labels,
+  consumers, schemas, payloads, media obligations, and execution batches. It
+  never imports entries or rewrites consumers. Read
+  `references/workers/content-planner.md`.
+- **assets/forms** uploads every planner media obligation and patches payload
+  references. It replaces a form or integration only when Fimo preserves its
+  behavior end to end; otherwise it preserves or reports it.
+- **content data and code** execute the planner handoff without rediscovering
+  or redesigning it. Read `references/workers/content-execution.md`.
+- **locales** owns locale configuration, locale routing, and translated
+  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`.
+
+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.
+
+## Coordinator gates
+
+1. Run `fimo migrate init` and inspect the real target paths before workers
+   write.
+2. Start runtime/routes/content-planner/locales together, or the framework
+   worker plus content planner/locales in conversion mode.
+3. After the content plan, upload every planned asset and patch payloads.
+4. Start data workers only after the asset gate and, in conversion mode, the
+   framework gate.
+5. Start each code worker only after its own imported records read back as
+   non-empty. A build over empty data proves nothing.
+6. Start the independent validator only after every writer has returned.
+
+Each prompt names the worker's source paths, exact target ownership, applicable
+reference above, and dependencies. Each report states status, duration, source
+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.
+
+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.