fimo 0.17.0 → 0.19.0

package/assets/skills/fimo-code/references/migrations/react-router-route-ownership.md

@@ -0,0 +1,93 @@
+# React Router locale route ownership upgrade
+
+Use this guide to move an existing project from the deprecated
+`fimo/react-router/routes` compatibility adapter to application-owned React
+Router routes. Existing projects can upgrade before completing this migration,
+but new projects should not use the adapter and a future breaking release may
+remove it.
+
+## Identify the installed contract
+
+Run the project-local CLI with the package manager selected by the lockfile:
+
+```bash
+pnpm exec fimo --version
+```
+
+Then inspect `package.json`, the lockfile, `src/routes.ts`, the locale layout or
+provider, `.fimo/config.json` (or legacy `fimo-config.json`), the language
+selector, redirects, and SEO/static-generation setup. The installed package is
+authoritative. Do not use a newer globally installed CLI to rewrite the app.
+
+Choose the path by the installed and target contracts, not by a guessed
+version number:
+
+| Installed project                     | Target project  | Action                                                                    |
+| ------------------------------------- | --------------- | ------------------------------------------------------------------------- |
+| Uses `fimo/react-router/routes`       | Current release | Upgrade safely, then follow this guide to leave the deprecated adapter.   |
+| Already uses application-owned routes | Later release   | Keep the app-owned routes; no routing migration is needed.                |
+| Uses another router or framework      | Any release     | Keep that framework's locale system and pass its resolved locale to Fimo. |
+
+The package export and `pnpm exec fimo --version` are the reliable boundary
+until release notes assign concrete version numbers.
+
+## Replace the deprecated route wrapper
+
+Remove the `fimo/react-router/routes` import and declare each localized path
+directly. React Router uses `:locale?`; route metadata uses `/:locale` with an
+optional locale descriptor:
+
+```ts
+import type { RouteConfig } from '@react-router/dev/routes';
+import { layout, route } from '@react-router/dev/routes';
+
+export default [
+  layout('./pages/LocaleLayout.tsx', [
+    route(':locale?/pricing', './pages/Pricing.tsx'),
+    route(':locale?/blog/:slug', './pages/BlogPost.tsx'),
+  ]),
+] satisfies RouteConfig;
+```
+
+Keep the public URL matrix unchanged:
+
+| URL             | route     | active locale      |
+| --------------- | --------- | ------------------ |
+| `/pricing`      | pricing   | configured default |
+| `/es/pricing`   | pricing   | `es`               |
+| `/blog/hello`   | blog post | configured default |
+| `/es/blog/hola` | blog post | `es`               |
+
+Do not add a default-locale prefix. Read the optional route locale in an
+application-owned layout and pass it to `<FimoProviders locale={locale}>`.
+When it is omitted, FimoProviders resolves the configured default locale.
+Preserve existing redirects, link behavior, document language/direction, and
+locale validation.
+
+The copyable boundary is:
+
+```tsx
+import { FimoProviders } from 'fimo/react-router';
+import { Outlet, useParams } from 'react-router';
+
+export default function LocaleLayout() {
+  const { locale } = useParams();
+  return (
+    <FimoProviders locale={locale}>
+      <Outlet />
+    </FimoProviders>
+  );
+}
+```
+
+## Verify before finishing
+
+Run the project-local `fimo validate`, then verify all four URL shapes in the
+preview. Switch languages in the application selector and in Studio, and check
+that both report the same locale. Confirm canonical URLs, `hreflang`, sitemap or
+prerender output, and locale-specific metadata/content remain correct.
+
+If the installed version has no exact matching reference, preserve every
+existing public URL and routing behavior. Report the installed version, the
+pattern found, the checks completed, and any uncertainty instead of guessing a
+new route shape.

package/assets/skills/fimo-code/references/ui.md

@@ -9,7 +9,8 @@ Use Fimo components for source-tracked schema and label values so Studio can ide
 | media as `FimoMedia`             | `Image`                        | schema media images                                                |
 | non-schema URL                   | `StaticImage`                  | decorative/static image URLs                                       |
 | media as `FimoMedia`             | `Video`                        | schema media videos                                                |
-| date as `FimoString`             | `Date`                         | schema dates                                                       |
+| date as `FimoString`             | `Date`                         | schema dates; `<time datetime>` is the calendar day                |
+| datetime as `FimoString`         | `DateTime`                     | schema instants; `<time datetime>` keeps the time                  |
 | boolean as `FimoBoolean`         | `Boolean`                      | schema booleans                                                    |
 | source-tagged plain JSON         | `Json`                         | schema JSON                                                        |
 | number                           | normal JSX; SvelteKit `Number` | numbers stay plain; SvelteKit `Number` formats display-only values |
@@ -21,6 +22,7 @@ Use Fimo components for source-tracked schema and label values so Studio can ide
 <RichText value={article.body} />
 <Image value={article.cover} width={1200} height={630} />
 <Date value={article.publishedAt} />
+<DateTime value={article.lastReviewedAt} />
 ```
 
 Pass the tracked value directly. Do not replace `<Text>` with `<h1>{article.title}</h1>`, unwrap media into raw `<img>`, or hand-roll richtext rendering.
@@ -44,7 +46,24 @@ Blocks do not change this rule. Every visible nested scalar is source-tracked to
 
 Do not render those values as `{program.title}` or `{highlight.label}`. That displays text but bypasses the primitive that Studio uses to resolve the exact nested edit target.
 
-Use `<StaticImage>` only when the image is deliberately not editor-managed. Use `String(value)` for attributes/third-party APIs that cannot accept a `FimoString`; keep editable visible text in `<Text>`.
+Use `<StaticImage>` only when the image is deliberately not editor-managed.
+
+## Wrapper values in JavaScript logic
+
+`FimoString`, `FimoBoolean`, and the other tracked values are objects, not primitives: a plain string or boolean cannot carry the source field, locale, and edit-target metadata Fimo editing needs. That gives one two-sided rule:
+
+- **MUST** pass the wrapper directly to Fimo rendering primitives (`Text`, `Boolean`, …). Unwrapping first removes the edit target.
+- **MUST** normalize the wrapper before any JavaScript comparison, condition, attribute, or third-party API: `String(value)` for strings, `value.value` (or `value.valueOf()`) for booleans.
+
+```ts
+fimoValue === 'build';         // false — an object never strict-equals a primitive
+String(fimoValue) === 'build'; // true
+
+if (fimoFlag) { … }            // always runs — an object is truthy even when the value is false
+if (fimoFlag.value) { … }      // correct
+```
+
+Keep editable visible text in `<Text>`; normalized primitives are for logic and APIs only, never a substitute for rendering through the primitive.
 
 Numeric fields stay plain JavaScript numbers, so they do not carry Studio source metadata. SvelteKit's `Number` component is an optional display/formatting helper; it is not source-editable. Other framework surfaces should render numeric fields normally until a shared tracked-number contract exists.
 

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

@@ -14,24 +14,156 @@ description: >-
 Move published URLs, exports, source repositories, CMS data, media, and forms
 into a real Fimo project without silently dropping source material.
 
-> **Experimental:** migration support is limited. Assess what can be preserved, explain unsupported parts, and never promise source-framework preservation.
+> **Experimental:** migration support is limited. Assess what can be preserved,
+> explain unsupported parts, record every gap as an owner-visible unresolved
+> item, and do not promise behavior that the target cannot prove. When the CLI
+> supports the source framework, preserve it explicitly and verify the runtime
+> before importing data.
 >
 > Use the CLI invocation selected for this flow for every `fimo` command in the migration. Otherwise use `npx fimo@latest`; do not install it globally.
 
+The first pass is a faithful migration, not a framework conversion. Detect the
+source framework before creating the target and pass it explicitly to
+`fimo migrate init`. For a Next.js source, use `--framework nextjs`; never rely
+on the React Router default. The setup receipt must report the target runtime
+framework, and a mismatch is a setup failure before any schemas, entries,
+assets, labels, or forms are imported.
+
+Keep third-party integrations when Fimo does not reproduce their behavior
+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.
+
+## Execution environment
+
+Run this skill from a coding-agent process that has direct access to the
+migration checkout. The process must be able to read and write source files,
+run bounded shell scripts, spawn its own subagents, and invoke the selected
+standalone Fimo CLI. The root agent owns the complete loop: fan out workers,
+fan in their reports, repair what they missed, and validate the real target.
+
+A plan, an evidence pack, or a generated report without source changes and
+verified Fimo state is only a draft. Do not finish with an explanation when the
+migration request requires an implementation.
+
+## CLI provenance
+
+Run every `fimo` command in the migration through one released, pinned CLI
+artifact, and record which one.
+
+- Use the exact CLI invocation selected for this flow. If none was provided,
+  stop and request an exact released version or immutable package URL. Never
+  default to `latest` or another moving dist-tag, never install it globally,
+  and never switch artifacts mid-run.
+- Never run the migration through a `file:`-linked workspace CLI from a Fimo
+  source checkout: the workspace binary skips the publish-time bundle and can
+  miss bundled workspace packages such as `@fimo/cli-kit`. When the migration
+  must exercise unreleased CLI changes, publish a pinned dev artifact from that
+  checkout first (`pnpm -F fimo publish-cli -- --id <task-name>`, or
+  `node scripts/remote-dev-publish-cli.mjs --id <task-name>` when the checkout
+  runs on a Dev Remote box) and use the exact package the publish recorded in
+  that checkout's `.fimo/dev.json`.
+- Record the provenance in the migration report - the `fimo --version` output
+  plus the artifact source (an npm version, or the pinned artifact URL from
+  `.fimo/dev.json`).
+
+## Initialized target precondition
+
+Before workers start, the root process must establish a real Fimo project and
+environment, link the migration checkout to it, and prove the data plane is
+reachable with a read such as `fimo schemas list -C <target> --env <env>` using
+the selected pinned CLI. Give workers the project id, environment, exact CLI
+invocation, and verification command. Generated `.fimo` JSON without a
+successful platform read is not initialization.
+
+For an existing non-empty application, reuse the CLI's real flow: create or
+select the Fimo project with `fimo init`, then run
+`fimo link <project-id> -C <target> --env <env>` and verify the data plane.
+`fimo migrate init <url> <dir>` is only usable when the target directory is
+empty or already linked.
+If authentication, organization selection, project creation, environment
+resolution, linking, or the verification read fails, stop before workers and
+report the exact failed command and setup requirement.
+
 ## Core contract
 
+- Migrate 1:1, not a compact approximation. Keep the source's route surface
+  and user-visible behavior: do not refactor routes merely to make the
+  migration easier, and do not replace many source pages with one generic
+  static shell. Every source page, content construct, array item, Markdown or
+  MDX block, imported component, and meaningful UI behavior ends with a
+  consuming target route or component, or with an explicit
+  unresolved/incompatible item in the text plan/report.
+- The first migration produces a working Fimo app with minimal refactoring.
+  Source-backed migrations preserve the detected source framework, router,
+  runtime, provider structure, and configuration by default: React Router/Vite
+  stays React Router/Vite, and Next.js stays Next.js. Framework conversion is
+  always an explicit user choice. URL-only and rebuild migrations have no
+  source framework to preserve, so the user must choose the target framework
+  explicitly; do not silently inherit a scaffold default. An explicit
+  conversion is still a faithful first pass: the framework conversion worker
+  ports the source's APIs, loaders, hardcoded content, integrations, and
+  visible behavior into the new framework unchanged, and Fimo schemas,
+  payloads, imports, and code wiring happen later through the content workers
+  (`references/workers/content-execution.md`). If the framework or hosting
+  setup is unclear or unsupported, stop and ask instead of guessing,
+  converting it, or deleting provider-specific files.
+- Inventory provider-specific files and rules before editing them. Classify each
+  as `preserved`, `replaced`, `safely-unnecessary-implementation-detail`, or
+  `unresolved`, with source evidence and affected behavior. Delete only after
+  proving redundancy or recording the user's acceptance of the loss.
+- Preserve an existing third-party integration (email, marketing, payments,
+  analytics) unless Fimo reproduces its exact user-visible behavior end to
+  end. When behavior is not 1:1 - a Brevo newsletter flow, for example - keep
+  the original integration wired and record the credential environment keys it
+  needs by name, without reading secret values. A missing secret is a user
+  follow-up in the report, never a reason to delete behavior or to block
+  local build, evaluation, or QA checks.
 - Record every route, CMS record, media asset, form, locale, redirect, SEO
   field, and unsupported behavior as imported, deliberately ignored with a
   reason, or unresolved.
+- When Fimo cannot support a source feature, do not silently drop or simplify
+  it. Preserve the original behavior when possible; otherwise leave the
+  existing source behavior or its documented fallback in place and record an
+  unresolved item with the source evidence, the owner action, and the
+  user-visible impact. Never claim completion while source content is
+  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.
+- 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. Missing access stops only that
+  data lane and becomes unresolved; never invent replacement content.
 - Model content before page code. Generated JSON is not imported content.
-- Keep migration evidence in the canonical ledger from
-  `references/manifest.md`.
+- Model editorial content Fimo-natively: blocks for structured or repeatable
+  sections, richtext for rich bodies, references for categories, authors,
+  related items, and repeated taxonomies, and singleton content types for
+  editable header, footer, navigation, and site settings. A `json` field is the
+  last resort for opaque or application-owned data and carries a recorded
+  reason. Better modeling never redesigns the site: preserve the source's
+  content shape and behavior, and record the source-to-Fimo mapping
+  (`references/content.md`).
+- Media owns its alt text. Preserve the source alt on the media value and pass
+  it to asset metadata when the upload command supports it; never add a
+  standalone alt field to a content schema. Record the limitation when the
+  command cannot carry it (`references/media.md`).
+- Every write is create-or-update, so any step can be rerun without duplicating
+  a schema, entry, asset, single, or label.
+- Every decision cites the source file (and line when it matters) that proves
+  it. What no worker could prove stays unresolved with an owner action.
+- Keep coordination evidence in the plain-text files
+  `.fimo/migration/migration-plan.md` and
+  `.fimo/migration/migration-report.md`. Use JSON only for actual Fimo
+  schema/content payloads that a data-plane command needs to import. Do not
+  create a target description, worker plan, decision registry, or JSON receipt
+  just to describe the filesystem or agent work.
 - Do not report completion until the QA gate passes or every failed check is
   present in the migration report.
-- Do not deploy while migrating. Import through the data-plane commands,
-  verify locally, and propose one final owner-approved deployment.
+- Import through the data-plane commands and verify locally before deployment.
+  Propose one preview deployment after a successful run, but deploy or publish
+  only after an explicit user request.
 
 ## Orient and route
 
@@ -41,70 +173,160 @@ into a real Fimo project without silently dropping source material.
    framework APIs.
 3. Classify the available evidence:
    - **source-backed**: source repository, export, downloaded HTML, CMS data,
-     or media folder. Treat the source files as truth and run the relevant
-     bounded inventory helpers when available. After the canonical manifest
-     records `source.rootPath` and `source.inventoryPath`, run
-     `fimo migrate inventory [project-root]` for deterministic framework,
-     runtime, package, locale, and message-file evidence.
+     or media folder. The source files are truth; the workers read them
+     directly.
    - **url-only**: only a published URL. Run `fimo migrate <url> [dir]` to
      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
-   canonical ledger.
-5. Load only the framework and inventory references that apply:
+   plain-text migration plan.
+5. 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`.
+   - Content data/code workers -> `references/workers/content-execution.md`.
+   - Independent validator -> `references/workers/validator.md`.
    - Next.js source -> `references/frameworks/nextjs.md`.
-   - Locale or dictionary evidence -> `references/inventory/locales.md`.
-   - Declared next-intl dependency ->
-     `references/inventory/locales/next-intl.md`.
-   - Deterministic inventory coordination ->
-     `references/inventory/coordinator.md`.
+   - React Router/Vite source -> load the target project's `fimo-code`
+     `frameworks/react-router`, `frameworks/vite-react`, and
+     `frameworks/hosting` references as applicable.
+   - Next.js implementation -> load the target project's `fimo-code`
+     `frameworks/next` and `frameworks/hosting` references. Those references
+     describe available equivalents; verify hosting support instead of assuming
+     every Next.js rule or runtime behavior is automatic.
+     Framework, provider, and rendering-primitive rules live in the `fimo-code`
+     skill; this skill routes to them and does not restate them.
+
+## Target setup
+
+The target is its own Fimo project directory. The client source checkout is
+read-only evidence: never run setup inside it, never modify it, and never
+hand-write a `.fimo/project.json` marker to fake a link.
+
+`fimo migrate init` is the migration setup gate. For a source-backed migration
+it validates the target and CLI auth, then delegates project selection and
+creation to the standard `fimo init` flow (same options, no separate creation
+path), and returns a setup receipt covering auth, the target link, the
+migration directory, and readiness. It fails with a structured error when auth
+is missing, the target is missing or invalid, or the project or organization
+is inaccessible. Both forms need a real 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>`
+- Create a new project in an owner-supplied organization:
+  `fimo migrate init <target-dir> --org <organizationId> --framework <framework>`
+
+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
+Next runtime/configuration (`next.config.*` and the source router shape), not a
+React Router scaffold.
+
+Setup scaffolds the target and pushes its initial commit; that is the only
+remote write it performs — it never pushes schemas, uploads assets, or imports
+entries. `fimo deploy` and `fimo publish` stay separate and are never run
+automatically (see Completion and deployment).
+
+## Command surface
+
+Plan-only commands operate on local artifacts and work before the target is
+linked:
+
+- `fimo migrate init <url> [dir]` — URL migrations only: crawl the live site
+  into the draft evidence pack.
+- `fimo migrate inspect` — summarize the URL draft or an existing legacy ledger.
+- `fimo migrate import` — print the import plan; it writes no data.
+- `fimo migrate apply` / `fimo migrate refine` — URL-draft-only scaffold and
+  refinement handoff; they play no role in a source-backed migration. `apply`
+  must never run against an initialized non-React-Router target: it is the
+  legacy React Router scaffold path and must fail instead of downgrading a
+  Next.js (or another framework) project.
+- `fimo migrate manifest` / `fimo migrate report` — legacy URL-draft helpers.
+  New source-backed migrations use the plain-text migration plan, worker
+  reports, and final migration report; they do not bootstrap another JSON
+  registry.
+
+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.
+- `fimo deploy` / `fimo publish` — owner-approved only.
 
 ## Migration loop
 
-1. Prepare the deterministic inventory plan first. When independent workers
-   are available, create one read-only subagent per planned lane; otherwise run
-   the same lanes sequentially. Every worker returns its fragment, never a
-   prose claim. Run reconcile after every fan-out, then use targeted file reads
-   for evidence the inventory leaves unresolved. Use a validator worker that
-   produced no fragments to compare the plan, source evidence, fragments, and
-   unresolved claims. Reopen only affected lanes when validation finds a gap.
-2. Normalize CMS, media, forms, routes, redirects, locales, and unsupported
-   behavior into the canonical ledger.
-3. Model content and references before writing pages.
-4. Generate or update schemas, entries, media mappings, forms, routes, and
-   application code with native Fimo contracts.
-5. Import reviewed media, schemas, entries, and forms in the order required by
-   `references/import-contract.md`.
-6. Run the local QA gate in `references/qa.md`.
-7. Write `.fimo/migration/migration-report.md` with coverage, counts,
-   mappings, unresolved items, and next actions.
-
-Use the bundled deterministic helpers whenever their contract fits. If a
-helper cannot prove a source fact, follow the bounded fallback in the relevant
-inventory reference instead of treating the whole inventory as failed.
+1. Run `fimo migrate init` and inspect the initialized target before any worker
+   edits it. Choose the target framework through the same canonical option as
+   `fimo init`: pass the detected source framework for a source-backed
+   migration, the framework the user explicitly chose for a conversion, and —
+   for a URL-only or rebuild migration — the framework the user selected (ask
+   when they have not). `--template-root` is a development/test
+   override only; normal migration prompts must not select a framework by
+   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
+   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
+   exist. When the user explicitly chose a framework conversion,
+   one framework conversion worker replaces the runtime and routes lanes, owns
+   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, writes
+   and pushes complete schemas, and writes the content import payloads required
+   by the Fimo CLI. It records source items, consumers, batches, and unresolved
+   behavior in the text plan; it does not create a second orchestration format.
+4. Once the content plan is ready, upload every planned asset and patch its
+   target payload references. After the asset gate passes (and, in conversion
+   mode, the framework gate), run data workers per schema/locale. Start content
+   code workers only after their imported records read back successfully, so
+   they can prove real values render through the native Fimo APIs.
+5. 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
+   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
+   (local startup, Fimo Preview embeddability, build). Record `browserProof`
+   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,
+   unresolved items, timings from worker reports, and next actions.
 
 ## References
 
 - `references/workflow.md` - phase order, source intake, URL artifacts, and
   implementation loop.
-- `references/manifest.md` - canonical migration ledger schema.
+- `references/decision.md` - plain-text decision and schema guidance; no
+  decision JSON is required.
 - `references/content.md` - CMS, entries, references, and source value rules.
-- `references/media.md` - media inventory, upload, dedupe, and replacement.
+- `references/media.md` - media obligations, upload, dedupe, and replacement.
 - `references/forms.md` - form classification and Fimo replacement.
 - `references/import-contract.md` - import obligations for media, entries, and
   forms.
 - `references/platforms.md` - platform-specific source-of-truth and rebuild
   notes.
 - `references/qa.md` - acceptance gate and report format.
-- `references/frameworks/nextjs.md` - Next.js source inventory routing.
-- `references/inventory/locales.md` - locale evidence and agent fallback.
-- `references/inventory/locales/next-intl.md` - next-intl strategy and support
-  boundary.
-- `references/inventory/coordinator.md` - deterministic inventory fan-out,
-  worker, and fan-in commands.
-- `scripts/build-canonical-manifest.mjs` - bootstrap the canonical ledger.
-- `scripts/write-migration-report.mjs` - update QA state and write the report.
+- `references/frameworks/nextjs.md` - Next.js routes, config, locales, and
+  Markdown or MDX content.
+- `references/workers.md` - coordinator schedule, ownership, and gates.
+- `references/workers/framework.md` - explicit framework-conversion contract.
+- `references/workers/content-planner.md` - discovery, schemas, payloads, and
+  handoff contract.
+- `references/workers/content-execution.md` - data import and code-wiring
+  contracts.
+- `references/workers/validator.md` - independent fan-in validation.
+- Existing manifest/decision helper scripts are legacy compatibility tools for
+  older migration artifacts. Do not invoke them in a new migration unless the
+  user explicitly asks to replay an older artifact.
 
 ## Completion and deployment
 
@@ -117,6 +339,9 @@ Use one final status:
   a draft.
 
 Never call a migration complete when CMS entries, media mappings, forms, or
-route coverage are unknown. Never run `fimo deploy` or `fimo publish` as a
-preview or QA step. After local QA passes, propose one final deployment and run
-it only when the owner explicitly approves it in the current turn.
+route coverage 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.