fimo 2.6.0 → 2.7.0-staging.1

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/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.