fimo 2.6.0-staging.2 → 2.6.0-staging.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-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,10 +174,9 @@ 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

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.

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

@@ -22,7 +22,8 @@ do not poll indefinitely.
 Start only after this batch's real records read back as non-empty. Own exactly
 the consumer files assigned by the planner.
 
-1. Load the active framework's `fimo-code` reference.
+1. Load the active framework's `fimo-code` reference. Before changing a media
+   read or image component, load `fimo skills get fimo-migration --ref media`.
 2. Establish the generated Fimo client/adapter needed by the batch.
 3. Replace every planned `sourceFile`/`sourceKey` at its existing consumer in
    place. Appending a disconnected duplicate section is not wiring.

package/assets/skills/fimo-studio/references/publish-and-deploy.md

@@ -31,6 +31,7 @@ The header **Publish** button itself only shows the label "Publish" (or a spinne
 - **"Publishing"** — Publishing is in progress. A spinner and a **Publishing** status badge show while it builds, and the button is disabled.
 - **"Published"** — Your site is live. A **Published** status badge appears, your live URL is listed under a **Published site** heading as a clickable link, and a **Last published** date and time is shown.
 - **"Couldn't publish · N issues"** — Project validation found issues that must be fixed first. Choose **Fix with Fimo** to send the safe issue list to the project chat and ask Fimo to repair it.
+- **"Latest update failed"** — The newest publication did not finish. The panel says what went wrong and, for a site that was published before, that the previous version remains the active release — so it can appear beside **Published**. It stays until a newer publication finishes. **View details** opens the reader's Inbox item about the failure, which offers **Open publishing** and **Contact support**. Studio never shows the build output; read it with `fimo publish logs <id>`, taking the id from `fimo publish list`. The person who published and the project's managers get that Inbox item, plus an email unless they turned off **Publication failures** in Account settings → Notifications.
 
 ## Key Concepts
 

package/dist/cli/bundle.json

@@ -1,7 +1,7 @@
 {
   "bundled": true,
   "bundler": "esbuild",
-  "bundledAt": "2026-09-11T13:07:25.428Z",
+  "bundledAt": "2026-09-14T08:59:44.223Z",
   "cliVersion": "2.5.1",
   "external": [
     "oxc-parser",