fimo 0.15.0 → 0.16.0-experimental.2

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

@@ -32,7 +32,7 @@ const items = [
 
 Do not use variables or interpolated expressions as label keys. Namespace literal keys by page/section/component, such as `hero.title`, `nav.signIn`, or `contact.form.submit`.
 
-Missing keys render as an empty tracked value. Run `fimo validate`, then create values with `fimo labels set` or `set-many`; do not add fallback copy to code.
+Missing keys render as an empty tracked value. Run `fimo validate`, then create values with `fimo labels set` or `set-many`; do not add fallback copy to code (the one exception is a component that cannot mount under the provider — see "Provider mount" below).
 
 ## Framework adapters
 
@@ -46,6 +46,14 @@ The label contract is shared; acquisition differs by runtime:
 
 Load the matching framework reference before choosing a provider or server reader.
 
+## Provider mount
+
+Components that render `Label` or call `useLabels()` MUST be mounted below the framework's `FimoProvider` (or the framework integration that supplies label context). Globally mounted components — cookie banners, toasts, consent dialogs injected near the document root — are the common escapees: outside the provider they render blank labels with no error.
+
+If a component genuinely cannot be moved under the provider, use an explicit hardcoded, non-editable fallback and report that tradeoff to the user. Never ship silently blank copy.
+
+When a label renders empty, check in order: (1) the key exists (`fimo validate`, `fimo labels list`), (2) the active locale has a value, (3) the component is under the provider. Add fallback copy only after those checks, and only in the cannot-mount case above.
+
 ## Locale behavior
 
 `.fimo/config.json#i18n.defaultLocale` selects the default (fallback `en`). The application resolves the active locale and gives it to the framework adapter. Create explicit label values for each configured locale the product supports.

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

@@ -13,7 +13,9 @@ The application owns locale resolution and routing. Fimo consumes the resolved l
 }
 ```
 
-Keep one locale unless the product asks for multilingual output. Locale tags should be structurally valid, such as `en`, `pt-BR`, or `zh-Hans`.
+For new projects, derive the primary locale from the request; when several are explicit, the first one named is the default. Update `i18n.defaultLocale`, `i18n.locales`, the framework-native route boundary and matcher, and the document language default. If the user gives no locale signal, retain the starter default and state that choice.
+
+Keep one locale unless the product asks for multilingual output. Keep it locale-ready without forcing `/en`, a language switcher, global path-prefix routing, or localized schemas. Locale tags should be structurally valid, such as `en`, `pt-BR`, or `zh-Hans`.
 
 For an already linked project, enable each locale in Fimo before writing non-default label or content variants. Load `fimo-cli` with its `locales` reference and run `fimo locales add <locale> --yes --json`; local config and `fimo validate` do not provision project locales. Do not change the application's route strategy to work around a missing locale.
 
@@ -22,6 +24,8 @@ For an already linked project, enable each locale in Fimo before writing non-def
 - Resolve locale from its router, route parameters, domain, request headers, middleware, cookie, existing i18n library, or user preference.
 - Keep its existing public URLs, redirects, links, `<html lang/dir>`, and SEO behavior.
 - Pass the resolved locale to Fimo's server reads and client provider.
+- Keep the default locale separate from the URL prefix policy. `optional: true` means omit the configured default locale from the URL: with `defaultLocale: "en"`, `/pricing` is English and `/fr/pricing` is French. With `optional: false`, every locale is prefixed (`/en/pricing` and `/fr/pricing`).
+- Treat routes without a `:locale` segment as application-owned. Fimo does not add or interpret a locale prefix for them.
 - Treat any optional Studio route catalog as framework-adapter-specific; load the framework reference before creating or changing one.
 
 ## Fimo responsibilities
@@ -39,4 +43,6 @@ For an already linked project, enable each locale in Fimo before writing non-def
 - React Router standard locale routing → load `references/frameworks/react-router.md`.
 - Vite + React/custom React router → load `references/frameworks/vite-react.md` and pass locale through its existing provider seam.
 
-Do not replace an existing locale system merely to add Fimo. Do not duplicate localized routes in the Studio catalog. Do not assume Fimo's route helpers are universal framework APIs.
+Do not replace an existing locale system merely to add Fimo. Do not duplicate localized routes in the Studio catalog. Every framework resolves its active locale and passes it to Fimo through that framework's provider or server-read seam.
+
+Astro and Next implement an optional locale boundary with paired native filesystem route trees: one unprefixed tree for the default locale and one prefixed tree for the other locales. Neither framework has an optional single-segment filesystem folder.

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,158 @@ 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, except for
+  the versioned URL-only Source Evidence Pack in
+  `.fimo/migration/source-evidence/`. That pack records observed source facts
+  and pointers to raw browser artifacts; it is not a worker plan, target
+  description, decision registry, or completion receipt.
 - 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 +175,177 @@ 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.
-   - **url-only**: only a published URL. Run `fimo migrate <url> [dir]` to
-     create the draft evidence pack.
+     or media folder. The source files are truth; the workers read them
+     directly.
+   - **url-only**: only a published URL. Use the URL form of
+     `fimo migrate init` to create the target and static draft, then read
+     `references/url-evidence.md` and build the rendered Source Evidence Pack
+     before reconstruction. Do not run the legacy apply/refine path first.
+     Static HTML, settled screenshots, or a late DOM snapshot alone are
+     incomplete source evidence.
    - **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`.
+   - URL-only rendered capture and browser acquisition ->
+     `references/url-evidence.md`.
+   - URL observation workers -> `references/workers/url-observer.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. For URL-only migrations, run the observation crew in
+   `references/workers/url-observer.md` before any reconstruction worker. The
+   crew produces `.fimo/migration/source-evidence/index.json`, compact
+   normalized route evidence, and pointers to sanitized raw browser artifacts.
+   Do not hand-write a replacement source summary or let reconstruction begin
+   while the pack reports incomplete capture.
+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
+   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.
+4. 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.
+5. 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.
+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.
+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
+   (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`.
+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/manifest.md` - canonical migration ledger schema.
+- `references/url-evidence.md` - rendered-browser capability, capture, Source
+  Evidence Pack, and normalization contract for URL-only sources.
+- `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/url-observer.md` - route scout, shared-system observer,
+  page observer, and evidence normalizer contracts.
+- `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 +358,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.

package/assets/skills/fimo-migration/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: 'Fimo Migration'
-  short_description: 'Migrate complete websites into Fimo with verified CMS, media, and forms.'
-  default_prompt: 'Migrate this website into a clean, editable Fimo project and verify routes, CMS entries, media, forms, and unresolved gaps.'
+  short_description: 'Migrate complete websites into Fimo with rendered behavior and editable content preserved.'
+  default_prompt: 'Migrate this website into a clean, editable Fimo project and verify routes, rendered layout and motion, CMS entries, media, forms, and unresolved gaps.'