fimo 0.16.0 → 0.18.0

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.

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

@@ -2,24 +2,72 @@
 
 Model CMS content before page implementation.
 
+## Editorial Modeling
+
+Model editorial content the way an editor should see it in Fimo, and keep the
+source's behavior and content shape. A better model never silently redesigns the
+site: the same routes render the same content, in the same order, with the same
+copy. Record the source-to-Fimo mapping - source file, frontmatter key, or
+export column -> content type, field, block, or reference - in the canonical
+manifest and the content plan.
+
+- **Blocks first.** Repeatable or structured editorial sections (hero, feature
+  grid, FAQ, testimonial list, pricing tiers, a page's section stack) become a
+  `blocks` field with named variants; rich bodies become `richtext`. Blocks and
+  references are content-editable, so model the structure instead of flattening
+  a section stack into loose strings or one opaque value.
+- **JSON is the last resort.** Use `json` only for opaque or
+  application-owned data that no Fimo-native model fits, and record the concise
+  reason in the content plan and the report. A `json` blob holding editorial
+  copy is unmodeled content, not a migrated model.
+- **Global chrome is content.** Header, footer, navigation, and site settings an
+  owner edits become singleton content types (navigation items as blocks or
+  references, not one label per link). Labels stay for genuinely small UI copy
+  and reusable translations.
+- **Names are editor-facing.** `heroHeading`, not `H1`; `features`, not
+  `field_04`; `Navigation`, not `NavigationEs`. Never name a content type,
+  field, or block variant after a markup tag, an HTML attribute, a locale code,
+  or a source column index, and group related fields in the order an editor
+  reads them.
+
+## Markdown/MDX is source evidence, not a runtime source
+
+Markdown/MDX files in the source tree or under `.fimo/migration/` are evidence
+for the migration, never the migrated app's runtime content source. Claiming
+content was migrated requires that the content was pushed to Fimo and the
+consuming pages read it back through the Fimo content APIs. A page still
+reading `.md`/`.mdx` files at build or request time is unmigrated content, not
+a covered item.
+
+- Long prose bodies belong in `richtext` fields and must render through the
+  Fimo rich-text primitives, not a Markdown pipeline.
+- Custom MDX/React components embedded in prose are application code: preserve
+  them as components rendered by the consuming page, or record them as
+  unresolved. Never silently drop them during HTML-to-richtext conversion.
+- Split editable prose around executable React/MDX children. Keep the children
+  in their original render order and wire the surrounding text to Fimo; do not
+  flatten or replace executable nodes with one additive “Page content” block.
+
 ## Detecting Dynamic Collections (no CMS export)
 
 When there is no first-party CMS export (most url-only and website-builder
 migrations), dynamic content still exists and must be modeled. It shows up two
 ways:
 
-1. **Repeated route groups** - many sibling routes share a path prefix
-   (`/blog/*`, `/vr-games/*`, `/locations/*`). Each group is a collection.
-   Ignore locale prefixes (`/en-be/`, `/fr/`): a locale segment is never a
-   collection name.
-2. **Repeated in-page blocks** - a single page renders an array of
-   structurally-identical items: card grids, list rows, tiles, carousels, logo
-   walls. Games, locations, team members, testimonials, pricing tiers, FAQs,
-   news teasers, and feature lists are almost always collections even when the
-   source renders them inside one page.
-
-After the source-faithful rebuild, treat **any hardcoded array of 3+ items with
-the same shape** as a collection candidate. Do not leave it hardcoded.
+1. **Repeated route groups** - many sibling routes may share a path prefix
+   (`/blog/*`, `/vr-games/*`, `/locations/*`). Treat the group as a collection
+   candidate and inspect the route modules, identity, and editability before
+   deciding. Ignore locale prefixes (`/en-be/`, `/fr/`): a locale segment is
+   never a collection name.
+2. **Repeated in-page sections** - a single page may render an array of
+   structurally-identical items: card grids, list rows, tiles, carousels, or
+   logo walls. Read the consuming code and source intent before deciding whether
+   the values are a collection, a `blocks` field on a single, labels, or
+   application-owned data.
+
+Repetition is evidence, not an automatic threshold. Do not convert every array
+or object into content, and do not leave a collection-shaped source structure
+hardcoded after the worker has established that editors should manage it.
 
 For each candidate:
 
@@ -27,35 +75,67 @@ For each candidate:
   `location`/Locations, `newsPost`/News, `testimonial`/Testimonials,
   `pricingPlan`/Pricing). Never name a collection after a locale code or a
   generic page route (no `EnBe`, no `Page`).
-- infer fields from the item shape using the Field Mapping below.
+- infer fields from the item shape using the Field Mapping below, while keeping
+  source-specific constraints and rationale in the plain-text migration plan.
 - push the schema, then create one entry per item.
 - upload each item's image with `fimo assets upload` and store the returned Fimo
   asset URL in the entry's `media` field (never the source URL or a local
   `public/` path).
 - wire the component to render from the collection (Fimo content
   query/primitives) with a seed/empty state. The hardcoded array is removed.
-- record source/generated/imported counts per content type in the manifest.
+- record source/generated/imported counts per content type in the migration
+  plan/report.
 
-Genuinely one-off blocks (a single hero, the footer) stay static. If unsure
-whether a block is a collection, prefer modeling it as one when items share a
-clear repeated shape and could plausibly be edited or extended.
+A genuinely one-off section with no editorial owner may stay in application
+code, but shared chrome - header, footer, navigation, site settings - belongs in
+a singleton content type. If the evidence is ambiguous, preserve the source
+value and record the decision or unresolved question rather than forcing a
+schema merely because a shape repeats.
 
 ## Field Mapping
 
-Use source headers, values, and repeated patterns:
+Choose from source semantics and the editing experience, not the source
+container type. An object or array is not by itself a reason to use generic
+JSON.
+
+- Editor-authored prose, Markdown, HTML, or other portable formatted content ->
+  `richtext`; convert it to the current Fimo richtext contract and render it
+  with the corresponding Fimo primitive.
+- Repeatable editor-authored structures such as FAQs, cards, features, pricing
+  items, testimonials, and page sections -> `blocks`, with nested richtext,
+  media, or references where their semantics require them.
+- Reusable, independently editable categories, tags, authors, and similar
+  concepts -> `reference`, or blocks containing references, only when stable
+  source records or clear independent management prove the relationship.
+- Opaque or unconstrained metadata, third-party payloads, and intentionally
+  non-editor-authored data -> generic `json`, with a concise rationale in the
+  content plan and worker report.
+
+Then use source headers, values, and repeated patterns:
 
 - title/name/heading -> `string`
 - slug/path/url/permalink -> `string`
-- body/content/post/html/description -> `richtext`
+- body/content/post/html/description -> `richtext` when editor-authored prose
 - excerpt/summary/dek -> `text`
-- image/photo/thumbnail/media/asset/file -> `media`
-- date/published/created/updated/event time -> `datetime`
+- image/photo/thumbnail/media/asset/file -> `media`, carrying the source alt on
+  the media value; never add a separate alt field (`references/media.md`)
+- date/published/created/updated -> `date`; use `datetime` only when the crawled
+  values carry a time and a UTC offset, which `datetime` requires
+- event start/end time -> `datetime`
 - price/amount/rating/order/count -> `number`
 - featured/draft/published/enabled/archived -> `boolean`
-- category/tag/author/reference -> `reference` only when verified, otherwise
-  `string` or tag-like text
-
-If unsure, preserve the raw value in the migration artifacts and add a note.
+- repeated section/section stack/nested item list -> `blocks` with one named
+  variant per distinct section shape
+- category/tag/author/related item/shared entity -> `reference` to the content
+  type that models it (see References below)
+- structured data with no Fimo-native equivalent -> `json`, with the reason
+  recorded
+
+Keep media as `media`, including inside blocks, and preserve proven relationship
+targets, direction, and cardinality. Do not turn a fixed enum, application-owned
+taxonomy, or accidental string match into a reference. If unsure, preserve the
+exact raw value in the migration artifacts and record the mapping as unresolved
+or incompatible rather than losing content.
 
 ## Entries
 
@@ -65,33 +145,37 @@ For every content type:
 - preserve slugs
 - preserve SEO title, description, share image, canonical URL when available
 - preserve publish status and dates
-- preserve authors, categories, and tags
+- preserve authors, categories, and tags as references to their content types
+- preserve each media value's source alt text on the media value itself
 - convert rich HTML to the current Fimo rich text representation
 - keep source count, generated count, imported count, and skipped count in the
-  manifest
+  migration plan/report
 
 Do not wire a page to remote Fimo content until the matching schema exists and
 the page has a seed/empty state for local development.
 
 ## References
 
-Create references only when:
-
-- exports contain stable reference IDs
-- repeated values clearly match another exported collection
-- the user confirms the relationship
+Model categories, tags, authors, related items, shared entities, and repeated
+taxonomies as `reference` fields pointing at their own content type. An editor
+picks an entry; they do not retype a string, maintain a list of raw IDs, or edit
+an opaque JSON array. When the source has no schema for that entity, infer a
+clean editor-facing one from the values themselves - a `Category` with `name`
+and `slug` - instead of leaving the value hardcoded.
 
 Use a two-pass import for references:
 
 1. import all referenced entries with source IDs and slugs
 2. resolve reference fields to target IDs/slugs
 
-If reference confidence is low, keep a string/tag field and record an unresolved
-item.
+The source still bounds the model. A repeated value is proof of a shared entity;
+it is not proof of a link the source never makes. Keep free text that has no
+shared identity as a string, and leave an unproven relationship unresolved with
+an owner action rather than synthesizing an ID.
 
 ## Skips
 
-Skipped fields or entries require a manifest note with:
+Skipped fields or entries require a note in the migration plan/report with:
 
 - source location
 - reason