fimo 2.6.0 → 2.7.0-staging.2

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

@@ -44,7 +44,7 @@ A Fimo project is identified by `.fimo/project.json`, written by `fimo init`. Th
 
 ## Critical: commands target the Branch matching the current git branch
 
-A project can have multiple **Branches** — each is a git branch _plus_ its own DB, sandbox, preview, and assets. Project-scoped commands (`deploy`, `status`, `entries`, `diff`, …) operate on the Branch matching the **current git branch**, and print a one-line banner saying which one. New projects start on `main`. Override for a single command with the canonical `--branch <name>` flag; the removed `--env <name>` spelling is rejected. Never edit the link file to switch. The full git-shaped workflow (`branch` / `checkout` / `switch` / `pull` / `diff` / `merge` / `status` / `publish`) lives in `references/branches.md`.
+A project can have multiple **Branches** — each is a git branch _plus_ its own DB, sandbox, preview, and assets. Project-scoped commands (`deploy`, `status`, `entries`, `diff`, …) operate on the Branch matching the **current git branch**, and print a one-line banner saying which one. Analytics reads are the exception: they default to canonical `prod`, independent of the checkout; see `references/analytics.md`. Annotation writes keep the current or explicit Branch. New projects start on `main`. Override for a single command with the canonical `--branch <name>` flag; the removed `--env <name>` spelling is rejected. Never edit the link file to switch. The full git-shaped workflow (`branch` / `checkout` / `switch` / `pull` / `diff` / `merge` / `status` / `publish`) lives in `references/branches.md`.
 
 ## Quick Start
 

package/assets/skills/fimo-cli/references/agents.md

@@ -286,7 +286,7 @@ fimo agents report <name> [--session <id>] [--branch <branch>] [--project <id>]
 
 ## How triggers get wired
 
-Agents are not Branch-scoped: they belong to the project, are read from `main`, and their triggers are global. A Branch has no agents of its own — Studio's agents view shows main's agents whichever Branch you are on, and a bundle sitting only on a feature Branch appears nowhere until it reaches main.
+Agents are not Branch-scoped: they belong to the project, are read from `main`, and their triggers are global. Studio shows the deployed main agents on every Branch. When the selected Branch contains a new bundle that is not on main yet, Studio also shows it as disabled and explains that it becomes available after merge. Its triggers remain inactive until the bundle reaches main.
 
 Pushing `.fimo/agents/<name>/config.yaml` (or a legacy root bundle) to `main` is the whole enablement act — `fimo deploy` does it. The server reconciles the file into its trigger rows on every push: a `schedule` trigger gets a cron, a `webhook` trigger gets its path, and `manual` becomes runnable. Removing a trigger from the file deletes it (cron torn down, path released) on the next deploy; deleting the agent's directory removes the whole deployment.
 

package/assets/skills/fimo-cli/references/analytics.md

@@ -4,6 +4,19 @@ Pageview aggregates for the **published** site are stored in Fimo's analytics pi
 
 Analytics has a **retained preview for every org** — free included. The free default is a 7-day retention window, so short ranges (`today`, `yesterday`, `this_week`, `last_week`, `last_7_days`) work for everyone. **Extended date ranges and longer retention are paid** — `last_30_days`, `last_90_days`, `this_month`, `last_month`, `last_quarter`, `last_year`, and `custom` require the `canUseExtendedDateRanges` privilege, which only paid orgs have. Asking for an extended range as a free user returns a 403 with an upgrade hint.
 
+## Select published traffic
+
+For traffic, growth, or site-performance questions, read **`prod`**, regardless of the current Git branch, `FIMO_ENV`, or the source branch published to Production. Analytics reads (`pageviews`, `top`, `annotations list`) default to this canonical published target. On older CLI versions, select it explicitly:
+
+```bash
+fimo --branch prod analytics pageviews --days 7 --json
+fimo --branch prod analytics top countries --json
+```
+
+Structured read results include `branch` (`data.branch` in the CLI JSON envelope). Check it before interpreting metrics. An intentional `--branch <name>` overrides the default; zero traffic on `main` or a preview branch does **not** mean the published site has no traffic. Preview visits are not collected. If publication or access is unavailable, report that limitation; do not fall back to another branch or present the failure as zero traffic.
+
+SDK and hosted MCP reads also default omitted `branch` to `prod` and return the selected `branch`. Annotation **writes** keep the current/explicit Branch and its existing permissions; the read default does not grant permission to write to `prod`.
+
 ## Bot traffic is excluded
 
 Every number below is **humans only**. Bot hits — AI crawlers and headless browsers — are tagged
@@ -37,6 +50,7 @@ The headline command returns everything in one payload — KPIs, the visitors se
 
 ```json
 {
+  "branch": "prod",
   "range": { "preset": "last_30_days", "effectiveFrom": "...", "effectiveTo": "...", "groupBy": "day", ... },
   "deviceFilter": null,
   "visitors": 1240, "pageviews": 3870, "bounceRate": 42.5, "viewsPerVisit": 3.12, "averageVisitDurationSeconds": 95.4,

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

@@ -71,7 +71,7 @@ fimo entries create <TypeName> --body '<json>'
 fimo entries create <TypeName> --locale es --document-id <documentId> --body '<json>'
 fimo entries list <TypeName> [--limit N] [--cursor CURSOR] [--all-pages] [--search Q] [--where JSON] [--sort F] [--fields FIELDS] [--populate FIELDS]
 fimo entries list <TypeName> --locale es
-fimo entries get <TypeName> <id> [--locale es]
+fimo entries get <TypeName> <id> [--locale es] [--populate FIELDS]
 fimo entries update <TypeName> <id> [--locale es] --body '<json>'
 fimo entries delete <TypeName> <id> [--locale es]
 fimo entries query (--sql '<select>' | --file <path> | --stdin)
@@ -101,7 +101,7 @@ Use the canonical read query flags: `--search`, `--sort`, `--where`, `--limit`,
 Reference filters take the target `id` string (`{"author":"750e..."}`). On a to-many field, `$eq` and `$contains` mean membership, `$in` means any listed target is present, `$ne` and `$nin` mean none are present, and `$null: true` means empty or missing. Reference fields cannot be sorted; use `--sort field` / `--sort -field` on scalar fields.
 `--fields` is a comma-separated projection for list payloads. The API always keeps `id`, `entryId`, `documentId`, and `locale`; pass only the other fields your view needs, such as `slug,title,excerpt,coverImage`.
 
-`--populate` is a comma-separated list of reference fields to embed. Without it, reference fields return reference objects like `{ "id": "..." }`; with `--populate author,contributors`, those fields return the target entry objects for the requested locale. Only reference fields can be populated (scalar fields 400), and populate never selects which target fields come back. A populated target missing in the requested locale resolves to null unless you pass `localeFallbacks=true`, which falls back to the best available locale variant, marked by its `locale` field. Limits: 200 references per to-many write, 500 distinct populated documents per field per request (400 past either).
+`--populate` is a comma-separated list of top-level fields to embed, on `entries list`, `entries get`, and `singles get`. It accepts reference fields, media fields, and blocks fields that contain media; naming a blocks field populates every media value inside it. Nested paths such as `sections.image` are not supported, and other field types return 400. Run `fimo schemas get <TypeName> --json` to inspect field names and types. Without it, reference fields return `{ "id": "..." }` and media fields return the stored `{ "source", "id", "url", "alt" }`; with `--populate author,cover`, `author` returns the target entry for the requested locale and `cover` adds the asset's current `name`, `mime`, `width`, and `height`. Populate never selects which target fields come back. A populated target missing in the requested locale resolves to null unless you pass `localeFallbacks=true`, which falls back to the best available locale variant, marked by its `locale` field. Limits: 200 references per to-many write, 500 distinct populated documents per field per request (400 past either).
 
 Polymorphic references declare `targets: ["Post", "Product"]` instead of `target` (never both) and their values carry both parts: `{ "contentType": "Post", "id": "..." }`. Populate returns mixed full entries, and generated hooks expose `$type` on each populated value to branch on. `--where` on polymorphic fields is not supported yet and fails with a clear error. Fixed and polymorphic references also work inside blocks with these same write shapes (`id`, `documentId`, or `slug` selectors), but nested fields cannot be populated or filtered.
 

package/assets/skills/fimo-cli/references/hosting.md

@@ -33,6 +33,17 @@ Declare redirects, headers, rewrites, and URL shape in
 
 Every field is optional. Only what you declare is emitted.
 
+## Preview and security headers
+
+A restrictive application-owned CSP or `X-Frame-Options` policy can block Studio
+Preview. Do not assume automatic header rewriting; Next.js `withFimo` does not
+provide it. Inspect the served policy and scope any manual adaptation to Preview,
+preserving production protections and unrelated headers. `frame-ancestors`
+permits the Studio parent, not the framed app's preview origin. Never derive
+ancestor sources from a preview-origin variable. For `script-src`, `connect-src`,
+`frame-src`, and `form-action`, use resolved/observed Fimo resources and endpoints
+actually used by the iframe. Studio-parent WebSockets do not belong in app CSP.
+
 ## Matching
 
 `source` matches the pathname only, never the query string.

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

@@ -90,7 +90,7 @@ Write the locale into a route's path with the reserved `:locale` segment, never
 | `/:locale/blog/:slug` | `{ "type": "locale", "optional": false }` | `/en/blog/hello` and `/fr/blog/bonjour`             |
 | `/:locale/pricing`    | omitted                                   | `/pricing` for `en`, `/fr/pricing` for `fr`         |
 
-- `locale` is reserved. It is read from the URL, so it never takes `schema` or `queryField` and never becomes a CMS query. Every other param is content-backed and needs both.
+- `locale` is reserved. It is read from the URL, so it never takes `schema` or `queryField` and never becomes a CMS query. Every other param is an `entry` param that needs both, unless it declares `"type": "external"`: an external param takes no other keys, and the application owns its values.
 - `optional: true` means omit the configured default locale from the URL. With `i18n.defaultLocale: "en"`, `/pricing` is English and `/fr/pricing` is French.
 - `optional: false` prefixes every locale, including the default (`/en/pricing` and `/fr/pricing`). Changing `i18n.defaultLocale` chooses the fallback locale; it does not by itself change this prefix policy.
 - A route with no `:locale` segment stays application-owned. Studio shows it once and neither adds nor interprets a locale segment.
@@ -102,7 +102,7 @@ Register the same shape in the router. React Router spells the omittable segment
 route(':locale?/blog/:slug', './pages/BlogPost.tsx');
 ```
 
-These canonical entries are also the optional metadata used by Studio Pages. See `references/pages.md` for content-backed `params` and declared `sources`.
+These canonical entries are also the optional metadata used by Studio Pages. See `references/pages.md` for the three `params` types and declared `sources`.
 
 For every framework, the application owns its URL scheme, resolves the locale, and passes it into Fimo. Studio stores the locale the app reports for the current location — including when only the locale changed — and reads content in it. Route metadata is optional unless the project wants Fimo Studio route selection/navigation.
 

package/assets/skills/fimo-cli/references/pages.md

@@ -7,15 +7,27 @@ Pages can mirror the application's routes in Fimo Studio. It gives editors a rou
 A route has three separate parts:
 
 - `path` is the URL pattern, such as `/blog/:slug`.
-- `params` optionally binds path placeholders to Collection entries so Studio can select a concrete route in the page header.
+- `params` optionally describes each path placeholder: an entry bound to a Collection so Studio can select a concrete route in the page header, the reserved `locale` segment, or a value the application owns.
 - `sources` optionally names the Labels, Single, and Collection results editors manage after selecting a route.
 
-Each param key matches a `:placeholder` in `path`. `schema` selects the Collection, `queryField` is the entry field stored in the URL, and `displayField` is the field Studio shows to editors. Use `id` or the built-in `slug` for `queryField`; a custom URL field must set both `"required": true` and `"unique": true` in its schema. Params resolve in path order, so a later param query may use an earlier selection:
+Each param key matches a `:placeholder` in `path`. For an entry param, `schema` selects the Collection, `queryField` is the entry field stored in the URL, and `displayField` is the field Studio shows to editors. Use `id` or the built-in `slug` for `queryField`; a custom URL field must set both `"required": true` and `"unique": true` in its schema. Params resolve in path order, so a later param query may use an earlier selection:
 
 ```bash
 fimo pages set <id> --path '/shop/:category/:product' --params '{"category":{"schema":"Category","queryField":"slug","displayField":"name"},"product":{"schema":"Product","queryField":"slug","displayField":"name","query":{"where":{"category":"$params.category.id"},"sort":"name"}}}'
 ```
 
+A descriptor's `type` is optional and selects one of three param kinds:
+
+- `entry` (the default) binds the placeholder to a Collection with `schema`, `queryField`, `displayField`, and an optional `query`.
+- `locale` is the reserved `:locale` segment with an optional `optional` boolean. See `references/locales.md`.
+- `external` takes no other keys. The application owns the values: Fimo matches the segment from the URL and never looks it up in the CMS.
+
+```bash
+fimo pages set <id> --path '/cartes/:slug' --params '{"slug":{"type":"external"}}'
+```
+
+Declare a placeholder `external` when its values are not Fimo content — a catalogue synced from an upstream source and stored as a media asset, ids that exist only in the visitor's browser, computed archive or pagination segments, third-party ids. Never bind a placeholder to an unrelated Collection to make `fimo validate` pass. `fimo pages list` reports `dynamic:external` and `fimo pages list --expand` skips the route; `fimo/paths` and the generated sitemap emit nothing for it, so the application enumerates those URLs itself. A `$params.<name>.<field>` expression in a param query or a source may reference entry params only. A route may mix kinds: entry params keep their selectors in Studio, and an external param takes a typed value in the preview header.
+
 `sources` is a named object under `routes.<id>.sources`. It is not an array or a route definition. Keep its keys stable and descriptive:
 
 ```json

package/assets/skills/fimo-code/references/frameworks/astro.md

@@ -170,6 +170,8 @@ The new-project shell pairs unprefixed default-locale pages with a parallel `[lo
 }
 ```
 
+A dynamic segment whose values are not Fimo content takes `{ "type": "external" }` instead of a Collection binding; Fimo matches it from the URL, and the page's own `getStaticPaths` (or on-demand rendering) supplies those values.
+
 ## Client islands
 
 Generated content reads remain server-only. Preserve existing islands and do not add React or a client SDK to work around this boundary.

package/assets/skills/fimo-code/references/frameworks/next.md

@@ -46,11 +46,8 @@ own tenant URL.
 
 ## Hosted preview config
 
-Wrap the existing Next config once so `next dev` accepts Fimo's hosted preview
-origins without exposing the active preview provider to the application. If
-the application does not set Next's `devIndicators`, the wrapper hides it in
-hosted Preview while local `next dev` keeps Next's default. Any explicit
-`devIndicators` setting is preserved:
+Keep the generated `FimoProvider` and `withFimo` integration to render Fimo
+Preview in Fimo Studio and enable Edit Mode. Wrap the existing Next config once:
 
 ```ts
 import type { NextConfig } from 'next';
@@ -60,10 +57,16 @@ const nextConfig: NextConfig = {};
 export default withFimo(nextConfig);
 ```
 
-Preserve all existing config fields or config-function logic. Do not hardcode a
-preview domain in `allowedDevOrigins`; Fimo supplies it to the development
-sandbox. The wrapper changes nothing outside `next dev` and is not the
-application's Fimo connection.
+Preserve existing config fields and config-function logic. `withFimo` currently
+does not rewrite response headers or adapt application-owned CSP. A restrictive
+policy may need a manual Preview adaptation; inspect actual framing and blocked
+requests, preserve production protections, and verify the result in a browser.
+`frame-ancestors` permits the Studio parent, not the app's preview origin or a
+value derived from a preview-origin variable. `script-src`, `connect-src`,
+`frame-src`, and `form-action` concern resources/endpoints used by the iframe;
+use the resolved connection and observed requests. Never add a Studio-parent
+WebSocket to application CSP. Scope exceptions to Preview and keep unrelated
+security headers unchanged.
 
 ## Client dependency
 

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

@@ -53,7 +53,7 @@ Use `<StaticImage>` only when the image is deliberately not editor-managed.
 `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.
+- **MUST** normalize the wrapper before any JavaScript comparison, condition, attribute, or third-party API: `String(value)` for strings, `value.value` for booleans.
 
 ```ts
 fimoValue === 'build';         // false — an object never strict-equals a primitive
@@ -63,6 +63,11 @@ if (fimoFlag) { … }            // always runs — an object is truthy even whe
 if (fimoFlag.value) { … }      // correct
 ```
 
+Nothing catches `if (fimoFlag)` for you: an object is unconditionally truthy in
+JavaScript, and TypeScript reports no error. Read `.value` every time. A boolean
+field without `required: true` generates `flag?: FimoBoolean`, so read
+`flag?.value`.
+
 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

@@ -174,18 +174,18 @@ report the exact failed command and setup requirement.
   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`).
+- Before writing media or wiring `<Image>`, load
+  `fimo skills get fimo-migration --ref media` for the stored value, explicit
+  `populate`, and responsive-image checks (`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
+  `.fimo/migration/migration-report.md`. Use JSON for actual Fimo
+  schema/content import payloads and the rendered guardrail inventory and
+  capture response metadata required by `references/qa.md`. 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
@@ -378,6 +378,9 @@ writes go through the normal commands against the linked target:
 - `references/workers/content-execution.md` - data import and code-wiring
   contracts.
 - `references/workers/validator.md` - independent fan-in validation.
+- `scripts/check-rendered-guardrails.mjs` evaluates the cited guardrail
+  inventory against rendered HTML or a local server and fails closed on empty,
+  missing, redirected, or vacuous evidence.
 - `scripts/apply-decision.mjs` and `scripts/write-migration-report.mjs` replay
   an older JSON-ledger migration. A new migration writes the plain-text plan
   and report instead; do not invoke them unless the user asks for that replay.

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

@@ -99,8 +99,7 @@ Follow the target project's `fimo-code` Next.js reference and render its
 `FimoProvider` once at the application root. The provider uses an explicit
 host connection when one exists; otherwise it resolves the linked project and
 active git branch on the server and passes only the public connection to the
-browser. `withFimo` handles hosted preview origins, not the application
-connection.
+browser.
 
 Do not create or edit `.env` / `.env.local` for a linked project's Fimo
 connection. Run the project's normal `next dev`, `next build`, and `next start`
@@ -108,31 +107,29 @@ commands, then exercise at least one server read and one client-side data read.
 
 ## Preview embedding and response headers
 
-Fimo Preview loads the app in an iframe and drives it over the postMessage
-preview bridge, so development/preview responses must let the preview origin
-frame the app.
-
-- `withFimo` consumes `FIMO_PREVIEW_ALLOWED_ORIGINS` (platform-supplied,
-  comma-separated `**.<domain>` patterns) only to extend `allowedDevOrigins`
-  during `next dev`. It does not add, remove, or rewrite response headers;
-  wrapping the config never fixes a framing block by itself.
-- When the source `headers()` sends `X-Frame-Options` or a CSP
-  `frame-ancestors` directive, keep `X-Content-Type-Options`,
-  `Strict-Transport-Security`, and `Referrer-Policy` unchanged, and translate
-  the framing block in the migrated config. For a hosted/remote preview, while
-  `FIMO_PREVIEW_ALLOWED_ORIGINS` is set, omit `X-Frame-Options` and send
-  `Content-Security-Policy: frame-ancestors 'self' https://*.<domain>` derived
-  from each `**.<domain>` entry. For local `next dev`, when the platform
-  variable is absent, omit the framing block only while
-  `process.env.NODE_ENV !== 'production'`; keep the source framing policy in
-  production. Never hardcode a preview provider domain.
-- Record every translated or dropped header in the runtime report's Hosting
-  section.
-
-Without a browser, verify embeddability deterministically: with the variable
-set, request a route from the running dev server and assert the response
-headers carry no unconditional framing block, then mark visual proof
-unavailable in the QA report.
+Keep the generated `FimoProvider` and `withFimo` integration. It supports
+rendering Fimo Preview in Fimo Studio and enabling Edit Mode.
+
+The application owns response and security headers; `withFimo` currently does
+not rewrite them or adapt CSP automatically. A restrictive policy may still
+need a manual Preview adaptation. Inspect framing behavior and response headers
+first. Scope changes to Preview, preserve production protections and unrelated
+security headers, and record them in the runtime report's Hosting section.
+When the existing policy sends `X-Frame-Options` or an unconditional
+`frame-ancestors` block, condition or relax that framing control only for the
+verified Preview embedding context; retain it for non-Preview and production
+responses.
+
+- `frame-ancestors` controls which Fimo Studio parent may embed the app. The
+  incident's manual fix used the current Studio sources `https://fimo.ai` and
+  `https://*.fimo.ai`. Verify the Studio parent for the target environment;
+  these sources are not a universal resource allowlist. Never derive them from
+  a preview-origin variable. The sandbox or hosted preview origin identifies
+  the app being framed, not its ancestor.
+- `script-src` controls scripts, `connect-src` API and WebSocket connections,
+  `frame-src` frames embedded by the app, and `form-action` form submission
+  destinations. Base Fimo sources on the resolved connection and observed
+  requests made by the preview iframe, only for resources/endpoints it uses.
 
 ## Locales
 

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

@@ -18,7 +18,7 @@ Prefer local files from exports. Use remote URLs when no local file exists.
 
 ## Required Metadata
 
-Record what is available:
+Record what is available in the inventory and reports:
 
 - source URL or source path
 - filename
@@ -29,47 +29,50 @@ Record what is available:
 - sha256 or another stable hash when possible
 - source references and target references
 
+These are migration records, not extra fields to copy into entry media values.
+
 ## Alt Text Belongs To The Media
 
-Alt text is media metadata, not a content field. An image that has alt text in
-the source never justifies a standalone alt field in a collection or content
-schema; the alt travels with the media value.
+Preserve each source occurrence's alt on its media value, including an explicit
+empty alt. Do not add a separate schema field or use the filename as alt.
+
+Neither `fimo assets upload` nor `fimo assets bulk-upload` currently accepts
+alt metadata: keep the source alt on the value and note that upload limitation
+in the migration report. Population preserves the entry's alt; it does not
+synchronize it with asset alt metadata. If source alt is absent and you write
+a meaningful fallback, identify it as generated in the report.
 
-- Preserve the source alt on the media value alongside `source` and `url`, and
-  pass it through the asset upload metadata when the CLI exposes it. When the
-  upload command cannot carry it, keep it on the media value and record the
-  limitation as a note on the media item.
-- Never use the filename as alt text.
-- When the source has no alt, a meaningful generated alt is an explicit
-  fallback only: mark it with the media item's `altSource`
-  (`references/manifest.md`) so an editor can see which alt text the source did
-  not provide.
+Use the relevant worker report and `.fimo/migration/migration-report.md` for
+provenance and dispositions. New migrations do not create a canonical
+`manifest.json`; see `fimo skills get fimo-migration --ref manifest` for legacy
+manifest handling.
 
 ## Dedupe
 
-Deduplicate by hash when local bytes are available. If not, deduplicate by
-canonicalized URL plus filename. Keep all original references even when multiple
-sources point to one uploaded asset.
+Deduplicate by hash when local bytes are available. Otherwise use canonicalized
+URL plus filename. Keep every source occurrence and its alt even when several
+occurrences reuse one uploaded asset.
 
 ## Upload And Replacement
 
 Referenced media must be uploaded into the Fimo media library. Use
-`fimo assets bulk-upload --file <manifest.json>` for a batch and keep one
-unique `sourceId` per media item; use `fimo assets upload` for a single file.
-Never encode paths or names in whitespace-delimited shell input. Copying a file under `public/` so the deployed site can
-serve it is **not** a completed import: it has no Fimo asset id/URL, editors
-cannot manage it, and the QA gate treats a referenced-but-not-uploaded asset as
-failing. Either upload it (and record the Fimo target), or mark it `unresolved`
-with an owner action. "Bundled locally, upload later" is not an acceptable
-terminal state for referenced media.
-
-After upload, record the Fimo target asset ID/URL in the worker and migration
-reports.
-
-When using downloaded files from a Fimo migration pack, copy the recorded
-`localPath` from the media map exactly. Do not reconstruct local filenames from
-source URLs, because the downloader normalizes characters such as underscores,
-spaces, and encoded characters before writing files.
+`fimo assets bulk-upload --file <manifest.json>` for a batch or
+`fimo assets upload "<file-path>"` for a single file. The bulk-upload input is a
+JSON array with a unique `sourceId` and a `path` per item. Paths resolve from the
+project working directory, not the manifest's directory. Never encode paths or
+names in whitespace-delimited shell input. Load
+`fimo skills get fimo-cli --ref assets` for upload options and result details.
+This upload payload is separate from the migration's Markdown reports.
+
+Copying a file under `public/` is not a completed import: editors cannot manage
+it in Fimo and it has no Fimo asset ID/URL. Either upload it and record the Fimo
+target in the worker and migration reports, or mark it `unresolved` with an
+owner action. "Bundled locally, upload later" is not a terminal disposition.
+
+If a supplied Fimo migration pack includes a media map, copy its recorded
+`localPath` exactly. Do not reconstruct filenames from source URLs or undo
+normalization of underscores, spaces, or encoded characters. Verify the recorded
+path exists before upload.
 
 Replace source references in this order:
 
@@ -78,34 +81,60 @@ Replace source references in this order:
 3. page components
 4. form definitions or confirmation content
 
-Schema media should render through Fimo media primitives. Do not hardcode source
-URLs for editable media fields.
-
-The library asset and the media value stored in an entry are distinct concerns:
-the asset owns the uploaded bytes and their metadata, and the entry field holds
-the media value `{ source, url, alt }` that points at it. Keep both carrying the
-same alt text, and do not duplicate alt into a second schema field.
-
-Do not copy upload metadata into media values yourself. Writing `{ source, url,
-alt }` is enough: the write path resolves and persists the media-library ID, and
-a read that names the field in `populate` returns the asset's current URL, name,
-MIME type, and intrinsic dimensions from the library. A read that does not name
-it returns the stored reference. The ID lets you inspect the asset later with
-`fimo assets open <id> --download`.
-
-Treat intrinsic dimensions as source facts, not layout instructions. Choose the
-displayed size, crop, `sizes`, loading behavior, and fit from the migrated page's
-design and responsive behavior.
+Write each imported media field as `{ source, url, alt }`. For an uploaded
+asset, use `{ source: 'local', url, alt }` with the URL returned by Fimo. Do not
+copy the asset's ID, name, MIME type, width, height, or other upload metadata
+into the stored value. The write path resolves and persists the media-library
+ID; the asset owns the uploaded bytes and their metadata. Inspect an asset
+later with `fimo assets open <id> --download`.
+
+### Populate and render
+
+Use Fimo media primitives for schema media rather than hardcoded URLs. Load
+`fimo skills get fimo-code --ref ui` and the detected framework reference for
+component imports and usage.
+
+Explicitly populate the media field before wiring it to `<Image>`. Without
+`populate`, a read returns the stored reference `{ source, id, url, alt }`,
+including its fallback URL, but does not look up current asset metadata. With
+the field named in `populate`, it returns current asset facts from the library:
+URL, name, MIME type, and intrinsic width and height when available.
+
+For media inside blocks, name the top-level blocks field, for example
+`--populate sections` or
+`populate: ['sections'] as const`, not a nested image path. This populates all
+media inside that field.
+
+CLI examples:
+
+```bash
+fimo entries list BlogPost --limit 1 --populate cover --json
+fimo entries get BlogPost <entry-id> --populate cover --json
+```
+
+Generated-client example:
+
+```tsx
+const article = await BlogPost.getBySlug('hello', { populate: ['cover'] as const });
+return article ? <Image value={article.cover} sizes="100vw" /> : null;
+```
+
+Before completing the migration, verify that the populated raster has its
+intrinsic `width` and `height`. Render the page at desktop and mobile widths,
+then check the optimized responsive `srcset`. With optimization enabled on an
+eligible Fimo URL, `sizes` set, and no custom `srcSet`, its generated width
+candidates stop at the intrinsic width. Choose displayed size, crop, `sizes`,
+and fit from the source layout; intrinsic dimensions are source facts, not
+layout choices. Fix a missing `populate` request instead of copying metadata
+into the entry or hardcoding intrinsic dimensions. If a populated read still
+lacks dimensions, report the gap rather than inventing them.
 
 ## Failure Handling
 
-If a media asset cannot be downloaded or uploaded:
-
-- keep the source reference
-- mark the media item `unresolved` or `unsupported`
-- list every page/entry that references it
-- include a suggested action such as re-exporting the asset folder or providing
-  credentials
+If an asset cannot be downloaded or uploaded, keep its source reference,
+record `unresolved` or `unsupported` in the report, and list affected
+pages/entries, the failure reason, and an owner action, such as re-exporting the
+asset folder or providing credentials.
 
 ## Media obligations
 
@@ -115,8 +144,15 @@ terminal, the coordinator combines and deduplicates those findings into the
 complete media-obligation list. This consolidated list is the media worker's
 only input; do not make the content planner rescan the whole application.
 
-Record each obligation's source location, consuming route/entry, and intended
-target field or node. Give it a stable identity that includes its field or
-rich-text node path; a shared label or source URL is not unique. The media
-worker cannot report complete until every obligation has an uploaded or
-duplicate Fimo mapping, or an explicit unresolved/unsupported disposition.
+Keep one migration mapping per source occurrence: source file or page, field
+or rich-text node path, consuming route/entry, and target field or node plus
+the uploaded asset ID/URL. Use the source location and field or node path for
+stable identity. A shared URL or label is not a unique occurrence;
+retain every mapping even when occurrences reuse one uploaded asset.
+
+The media worker cannot report complete until every obligation has an uploaded
+or duplicate Fimo mapping, or an explicit unresolved/unsupported disposition.
+Reconcile the mappings against every discovery lane's findings, including
+schema media fields and nested richtext/Tiptap image nodes. Run the broader
+migration gate from `fimo skills get fimo-migration --ref qa` before claiming
+the migration is complete.