fimo 2.2.0-staging.9 → 2.2.0

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

@@ -11,7 +11,7 @@ Invite collaborators to your Fimo organization or project. After deploying a web
 Typical scenarios where inviting is appropriate:
 
 - Multi-person projects (agencies, teams)
-- Client hand-off (invite client as `view` or `comment`)
+- Client hand-off (invite client as `view`)
 - Content editors (invite as `edit` for CMS access)
 - Developers (invite as `edit` or `full`)
 
@@ -30,12 +30,14 @@ fimo invite --project <project-id> --email "john@acme.com" --role full
 
 Project roles:
 
-| Role      | Access Level                                  | Use Case                    |
-| --------- | --------------------------------------------- | --------------------------- |
-| `view`    | Read-only                                     | Clients, stakeholders       |
-| `comment` | View + leave comments                         | Reviewers, approvers        |
-| `edit`    | Edit code, content, assets, use AI chat       | Developers, content editors |
-| `full`    | Full access including settings and publishing | Project leads               |
+| Role   | Access Level                                  | Use Case                         |
+| ------ | --------------------------------------------- | -------------------------------- |
+| `view` | Read-only                                     | Clients, stakeholders, reviewers |
+| `edit` | Edit code, content, assets, use AI chat       | Developers, content editors      |
+| `full` | Full access including settings and publishing | Project leads                    |
+
+`comment` is no longer offered. Fimo has no comment system, so it granted exactly what `view` grants. It is still
+accepted by `--role` and still held by anyone already assigned it, but do not hand it out — use `view`.
 
 ## Invite to an organization
 
@@ -76,8 +78,8 @@ Next steps:
 # Give client view-only access
 fimo invite --email "client@company.com" --role view
 
-# Give client comment access for feedback
-fimo invite --email "client@company.com" --role comment
+# Reviewers get the same read-only access
+fimo invite --email "reviewer@company.com" --role view
 ```
 
 ### Adding a developer

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

@@ -27,18 +27,10 @@ There is no `fimo translations` command. Use `fimo labels`.
 
 ## Locale config
 
-`.fimo/config.json` controls label/content locales:
-
-```json
-{
-  "i18n": {
-    "defaultLocale": "en",
-    "locales": ["en"]
-  }
-}
-```
+Use `references/locales.md` to change the supported locales or default.
 
-- `defaultLocale` is what `fimo validate` and label commands use when `--locale` is omitted.
+- `fimo validate` reads `defaultLocale` from the synchronized local config so it can run without a Fimo session.
+- Label writes with no `--locale` leave the locale unset; the selected Branch API resolves its configured default.
 - `locales` is the enabled locale list and must include `defaultLocale`. Do not add non-default locales unless the user asks for multiple languages, localized routes, translations, or a specific locale.
 - If multiple locales are configured, create or update label values for every configured locale.
 - For a non-default locale, pass `--locale <locale>` explicitly.

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

@@ -13,13 +13,13 @@ fimo locales set-default es --yes --json
 fimo locales remove es --yes --json
 ```
 
-Studio chat can run `locales list`. Manage the locale lifecycle through Studio Settings or the standalone CLI.
+In a linked project, change the locale set or default only through these commands or Studio Settings. Never edit `i18n.defaultLocale` or `i18n.locales` directly. Studio chat can run `locales list`.
 
 These commands update the selected Branch through the locale lifecycle API. The API commits `.fimo/config.json` to the Fimo Branch, then the CLI synchronizes the **whole local branch** to that commit. They refuse a dirty config, a local-ahead branch, or a diverged branch before applying the remote change. `--yes` bypasses only the explanatory prompt.
 
 If a mutation exits with code `2` and `data.code` is `LOCALE_APPLIED_SYNC_REQUIRED`, the remote operation succeeded (`data.applied` is `true`) but the local fast-forward did not. **Do not retry the locale command.** Run the commands in `data.sync.recovery`, resolve the checkout, and confirm with `fimo status` or `fimo locales list`.
 
-Edit `.fimo/config.json` only for declarative locale and route metadata:
+The synchronized `.fimo/config.json` remains the application runtime's declarative locale configuration:
 
 ```jsonc
 {
@@ -36,6 +36,8 @@ Edit `.fimo/config.json` only for declarative locale and route metadata:
 - New projects do not need a global routing strategy. The route contract declares locale placement with `/:locale`; legacy `i18n.routing.strategy` values are read only for compatibility while migrating.
 - If multiple locales are configured, create or update labels and localized content for every configured locale. Create schemas with `i18n: { "enabled": false }` only once.
 
+Edit application-owned settings such as `routes` directly in `.fimo/config.json`. Locale membership and the default use the lifecycle commands above because they must update the selected Fimo Branch and local checkout together.
+
 `fimo locales remove` permanently deletes that locale's stored entries and labels.
 
 ## Validate
@@ -108,7 +110,7 @@ Neither Astro nor Next supports an optional single-segment filesystem folder. As
 
 ## Migrate An Existing Locale System
 
-Inspect the existing locale provider, route table, switcher, redirects, and public URLs before editing configuration. Preserve working URL behavior during the migration.
+Inspect the existing locale provider, route table, switcher, redirects, and public URLs before changing locale behavior. Preserve working URL behavior during the migration.
 
 Preserve the existing locale provider, router, switcher, redirects, and public URLs. Next.js projects run `fimo skills get fimo-code --ref frameworks/next/locales`; React Router projects load the React Router setup reference and its focused route-ownership migration when upgrading; Astro projects run `fimo skills get fimo-code --ref frameworks/astro` and pass the page-resolved locale into server reads and `getLabels`.
 

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

@@ -14,7 +14,7 @@ fimo preview url --all                               # print every destination a
 curl -L "$(fimo preview url)"                        # fetch the raw sandbox preview
 ```
 
-`--env <name>` remains a deprecated alias for `--branch <name>`; the two disagreeing is an error, not a precedence rule. The JSON envelope carries `branch` and keeps `env` as a duplicate of it. Studio deep links still use the `/env/` path, which redirects to `/branch/`.
+`--env <name>` is rejected as a Branch selector; use `--branch <name>`. The JSON envelope carries the canonical `branch` field and may include a deprecated `env` compatibility duplicate. Studio deep links still use the `/env/` path, which redirects to `/branch/`.
 
 ## Human and machine behavior
 
@@ -32,7 +32,6 @@ curl -L "$(fimo preview url)"                        # fetch the raw sandbox pre
     "project_id": "prj_abc",
     "branch": "main",
     "env": "main",
-    "env": "main",
     "preview_url": "https://fimo.ai/preview/prj_abc/main",
     "sandbox_url": "https://preview.provider.example/session",
     "sandbox_expires_at": "2026-08-20T18:42:00.000Z",

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

@@ -9,16 +9,16 @@ fimo projects list [--org <id>]                 # list projects in an org (defau
 fimo projects create [dir] [--org <id>] [--framework react-router|astro|nextjs|sveltekit] [--install|--no-install]
 fimo projects clone [projectId] [dir] [--branch <name>] # clone an existing project locally
 fimo projects delete [projectId] [-C <dir>] [-y] # delete (defaults to current project)
-fimo projects publish [projectId] [-C <dir>]     # make the project live (publish from main)
+fimo projects publish [projectId] [-C <dir>]     # make the project live from its Production source Branch
 fimo projects unpublish [projectId] [-C <dir>]   # take the project offline
 fimo projects rename <name> [projectId] [-C <dir>]   # set seo.siteName in the linked project config
 ```
 
 - **`list`** — projects you can see in the org. Live projects are marked.
 - **`create`** — identical to `fimo init` (create-new path); see `references/init.md`.
-- **`clone`** — clone a remote Fimo project's git repo to your machine and write the local `.fimo/project.json` and agent files. Use `fimo clone <projectId>` when scripting or when the ID is known. In an interactive terminal, bare `fimo clone` opens a project picker for the active org; JSON mode and non-TTY shells require an explicit project ID and fail fast instead of prompting. By default it clones `main`; pass `--branch <name>` to clone a specific Branch. The legacy `--env <name>` spelling remains a compatibility alias. The target directory defaults to the project display name/name, or pass `[dir]` explicitly.
+- **`clone`** — clone a remote Fimo project's git repo to your machine and write the local `.fimo/project.json` and agent files. Use `fimo clone <projectId>` when scripting or when the ID is known. In an interactive terminal, bare `fimo clone` opens a project picker for the active org; JSON mode and non-TTY shells require an explicit project ID and fail fast instead of prompting. By default it clones `main`; pass `--branch <name>` to clone a specific Branch. The removed `--env <name>` spelling is rejected as a Branch selector. The target directory defaults to the project display name/name, or pass `[dir]` explicitly.
 - **`delete`** — destructive; prompts unless `-y`. Removes the remote project.
-- **`publish` / `unpublish`** — toggle the project's public visibility. `publish` flips the current `main` state live (the same "go live" as `fimo deploy --publish`, minus the git push).
+- **`publish` / `unpublish`** — toggle the project's public visibility. `publish` flips the configured Production source state live (the same "go live" as `fimo deploy --publish`, minus the git push).
 - **`rename`** — edits only the linked local project's `seo.siteName`. It does not commit or deploy. It requires a project marker in the cwd, and if you pass a `[projectId]` that doesn't match the linked project it errors and exits 1 (so you can't rename a different project). Later remote config commands may require reconciliation while the local config is dirty. Finish your local edits, then explicitly run `fimo deploy --no-wait` when ready for a quick sync.
 
 ## Top-level clone shortcut
@@ -43,10 +43,10 @@ fimo rename "<Site Name>"        # local edit: set seo.siteName in the project c
 
 ## Publish commands
 
-| Command                 | Effect                                                                  |
-| ----------------------- | ----------------------------------------------------------------------- |
-| `fimo deploy --publish` | Push current `main` + flip the project live in one shot.                |
-| `fimo projects publish` | Flip the project live (no git push).                                    |
-| `fimo publish`          | Flip the already-synced `main` revision live; optional label and notes. |
+| Command                 | Effect                                                                     |
+| ----------------------- | -------------------------------------------------------------------------- |
+| `fimo deploy --publish` | Push the current Production source + flip the project live in one shot.    |
+| `fimo projects publish` | Flip the project live (no git push).                                       |
+| `fimo publish`          | Flip the synced Production source revision live; optional label and notes. |
 
 See `references/deploy.md` and `references/branches.md` for the full picture.

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

@@ -2,7 +2,7 @@
 
 `fimo schedules` manages recurring commands for one project Branch. It uses the
 current checkout Branch by default, or the Branch passed with `--branch <name>`.
-The legacy `--env <name>` spelling remains a compatibility alias.
+The removed `--env <name>` spelling is rejected as a Branch selector.
 
 The command starts in that Branch's sandbox. Commands can still target another
 Branch explicitly, for example with `fimo schemas list --branch preview`.
@@ -72,6 +72,6 @@ All schedule commands support the CLI's global `--json` mode. List, detail, and
 
 ## Notes
 
-- Every operation is scoped to the active Branch unless `--branch` (or the legacy `--env` alias) is passed.
+- Every operation is scoped to the active Branch unless `--branch` is passed.
 - Pausing stops future cron runs. It does not delete history.
 - A failed or skipped manual run exits non-zero with its run ID and an exact `runs show` command for inspecting detail.

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

@@ -28,12 +28,13 @@ Run this before writing a custom payload. The list shows supported event types,
 - Publish: `publish.started`, `publish.succeeded`, `publish.failed`, `publish.unpublished`
 - Agents: run started/completed/failed/cancelled and review requested/resolved
 - Analytics: `analytics.report_ready`
-- Media: uploaded/updated/deleted/generated/processing_failed
+- Media: uploaded/updated/deleted
 - Entries: `entry.changed`
 - Domains: `domain.created`, `domain.deleted`
 - Labels: `label.changed`
 - Locales: `locale.created`, `locale.default_changed`, `locale.deleted`
-- Environment events (legacy wire names): `environment.created`, `environment.deleted`, `environment.merged`, `environment.restored`
+- Branch restore: `branch.restored`
+- Existing lifecycle wire names: `environment.created`, `environment.deleted`, `environment.merged`
 
 Do not guess variable paths. The common envelope is:
 
@@ -110,9 +111,8 @@ Available filters are event-specific:
 - `--agent <name>` for agent events
 - `--media-type <image|video|audio|document|other>` for media events
 - `--action <created|updated|deleted>`, `--content-type <name>`, and `--locale <locale>` for `entry.changed`
-- `--debounce-changes <immediate|5s|30s|1m>` for direct `entry.changed` delivery grouping
 
-`entry.changed` represents content accepted in the selected Environment. New entry webhooks wait 5 seconds after the last direct edit by default, then send one delivery with the combined `data.changes`. Exact repeated autosave changes appear once. Use `--debounce-changes immediate` to disable grouping. Accepted agent edits and environment merges already carry compact batches and send immediately. Operations above the delivery batch size share an `operationId` and include `{ index, total }` batch metadata. Every event includes scalar `environment` and `branch` context and keeps the legacy Branch value at `event.env.name`. Publish events always report Production on `main`.
+`entry.changed` represents content committed in the selected Environment. Each committed write sends one delivery whose `data.changes` lists every affected entry; environment merges arrive the same way with `reason: "environment_merge"`. Operations above the delivery batch size share an `operationId` and include `{ index, total }` batch metadata. Retries resend the same delivery (same event `id`), never a new one. Every event includes scalar `environment` and `branch` context and keeps the legacy Branch value at `event.env.name`. Publish events always report Production on `main`.
 
 ## Inspect before depending on it
 

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

@@ -1,12 +1,12 @@
-# Assets — package surface
+# Assets in code
 
 > For the CLI commands (`fimo assets upload`, `fimo image generate`, folder management) and the "when to generate AI images" workflow rules, see **`fimo-cli/references/assets.md`**.
 
-This file covers the package surface for working with assets in code: the `media` field value shape, rendering primitives, and URL format.
+This file covers media fields and the Fimo image components.
 
-## `media` field value (stored/wire shape)
+## Media field values
 
-Asset values returned from `fimo assets upload` or Fimo media tasks, and stored in `media` content-type fields:
+A media field stores a reference to an asset, not a copy of the asset metadata. Write the value returned by upload or generation:
 
 ```json
 {
@@ -16,11 +16,22 @@ Asset values returned from `fimo assets upload` or Fimo media tasks, and stored
 }
 ```
 
-- `source`: `"local"` for uploaded/generated assets in the Fimo media library. `"external"` for hard-coded third-party URLs (avoid when possible — editors can't manage these).
-- `url`: stable HTTPS URL, no auth required, safe to embed.
-- `alt`: optional alt text.
+- `source`: `"local"` for a Fimo media-library asset, or `"external"` for a third-party URL.
+- `url`: the public asset URL.
+- `alt`: optional text owned by the entry.
 
-Generated content reads wrap this stored value in `FimoMedia`, which exposes `url`, `alt`, `name`, `mime`, and optional `width`/`height`. It does not expose `source`; Fimo tracks that internally. Pass the whole entry value to `<Image>` / `<Video>`.
+For a local asset, Fimo stores its ID and keeps the URL as a fallback. Do not copy `name`, `mime`, `width`, or `height` into the value. Those facts belong to the asset and are removed from writes.
+
+By default, reads return the stored reference without an asset lookup. Name a media or blocks field in `populate` when the page needs the asset's current URL, name, MIME type, or intrinsic size:
+
+```ts
+const post = await Post.getBySlug('hello');
+const withAsset = await Post.getBySlug('hello', { populate: ['cover'] });
+```
+
+`populate` takes top-level field names. A blocks field populates every media value inside it. One lookup covers all selected media in the response. Media inside a populated reference target stays a reference. Use `fimo assets open <id> --download` to inspect the source file.
+
+Generated reads wrap media in `FimoMedia`. Its `id`, `alt`, `name`, `mime`, `width`, and `height` can be absent. A populated value has the current facts when the asset resolves; missing or external assets stay unchanged. `source` is internal. Pass the whole value to `<Image>` or `<Video>`.
 
 ## Rendering in application code
 
@@ -41,11 +52,11 @@ import { Image, StaticImage, Video } from 'fimo-next';
 <StaticImage src="https://assets.fimo.ai/<project>/<id>.jpg" alt="Hero" width={1200} height={630} />
 ```
 
-Fimo's `<Image>` is not Next's `next/image` component. Do not pass Next-only props such as `priority`, `fill`, `quality`, or `loader`; use only the props documented for the Fimo primitive. Preserve `next/image` for non-Fimo images when the application needs those Next-specific controls.
+Fimo's `<Image>` is not Next's `next/image`. Use the Fimo props documented here. Keep `next/image` for non-Fimo images that need its controls.
 
-**Provide `width` and `height` when known** so Fimo can optimize the asset and reserve layout space (prevents CLS).
+Choose dimensions, CSS, `sizes`, and `fit` from the page design. Do not copy the source file's intrinsic dimensions into layout props by default. When a read includes intrinsic size, Fimo uses it for aspect-ratio reservation and responsive candidates.
 
-**Never hand-construct a `FimoMedia` object** to pass into `<Image>` — that bypasses inline-editing metadata. If you have a raw URL, use `<StaticImage>` instead.
+**Never hand-construct a `FimoMedia` object** to pass into `<Image>`. That bypasses inline-editing metadata. If you have a raw URL, use `<StaticImage>` instead.
 
 See `references/ui.md` for the full component table and rules.
 

package/assets/skills/fimo-code/references/content/clients.md

@@ -125,7 +125,21 @@ const page = await Article.list({
 });
 ```
 
-Fimo always keeps `id`, `entryId`, `documentId`, and `locale`. Without `populate`, references are `{ id }`; with it, they become the target entry or `null`. Populate is depth-one and only accepts reference field names.
+Fimo always keeps `id`, `entryId`, `documentId`, and `locale`, plus every field named in `populate`.
+
+`populate` is depth-one and takes top-level field names of two kinds:
+
+| Field named          | Without `populate`       | With it                                                                                     |
+| -------------------- | ------------------------ | ------------------------------------------------------------------------------------------- |
+| reference            | `{ id }`                 | the target entry, or `null`                                                                 |
+| media                | the stored reference     | `FimoPopulatedMedia` with current asset facts when it resolves; asset facts remain optional |
+| blocks holding media | stored references inside | every media value inside it populated; item types unchanged                                 |
+
+Any other field name is a 400. A populated reference target carries its own media as stored references. Population does not recurse, and a missing or external asset keeps its stored media value.
+
+Even when media is populated, `id`, `name`, `mime`, `width`, and `height` can be absent for external, missing, or incomplete assets. The stored `url` remains the fallback, and `alt` is optional entry-owned text.
+
+Generated schema modules keep `FimoMediaRef` and `FimoPopulatedMedia` local. Their shapes depend on the schema, while the installed runtime package may be an older release.
 
 When a named type is needed, use the generated result type rather than typing populated data as the base entry:
 

package/assets/skills/fimo-code/references/content/schema.md

@@ -140,6 +140,7 @@ Use `schema.fields` for one repeated shape and `schema.oneOf` for selectable var
 - Fimo adds stable `_key` values; `oneOf` items also receive `_type`.
 - Nest blocks up to seven levels. One `oneOf` supports up to 40 variants and one blocks field up to 200 items.
 - Nested scalar values use the same source-tracked value type as top-level fields.
+- Fixed and polymorphic references work inside blocks with the same value shapes as top-level reference fields.
 - Nested reference population and filtering are not supported.
 
 ## References

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

@@ -115,7 +115,7 @@ export async function getStaticPaths() {
 
 Configure Astro i18n from `.fimo/config.json#i18n` and use `Astro.currentLocale` for content reads, `getLabels({ locale })`, and `<html lang>`. The standard starter keeps the configured default locale unprefixed and prefixes the others. Existing applications may instead resolve locale through middleware, domains, cookies, or another application-owned strategy. Astro needs no Fimo locale provider. Ownership rules: `references/locales.md`.
 
-The new-project shell pairs unprefixed default-locale pages with a parallel `[locale]` tree because Astro has no optional single-segment page filename. Add locales in `.fimo/config.json`; Astro's native i18n router validates the prefixed tree. Route metadata uses `/:locale` with `params.locale.optional: true`; Astro page files remain authoritative.
+The new-project shell pairs unprefixed default-locale pages with a parallel `[locale]` tree because Astro has no optional single-segment page filename. Add locales through the `fimo-cli` locale workflow; Astro's native i18n router reads the synchronized config and validates the prefixed tree. Route metadata uses `/:locale` with `params.locale.optional: true`; Astro page files remain authoritative.
 
 ## Studio route catalog
 

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

@@ -109,7 +109,18 @@ Do not add `'use client'` to a page solely because Fimo is present. Keep promise
 
 ## Metadata
 
-Next remains in control through `generateMetadata`. Resolve labels/content on the server and convert tracked strings only where Next expects primitives:
+Fimo owns the site-wide defaults; the application owns per-page overrides. Keep (or add) the starter wiring in the root layout — it maps `.fimo/config.json#seo` (Studio's Settings → SEO: title, description, favicon, share image, robots, theme color, canonical) onto Next `Metadata`/`Viewport`:
+
+```ts
+import { buildFimoMetadata, buildFimoViewport } from 'fimo-next';
+
+export const generateMetadata = () => buildFimoMetadata();
+export const generateViewport = () => buildFimoViewport();
+```
+
+If the root layout lacks this wiring, add it (updating the fimo packages if `fimo-next` does not export the helpers); without it, Settings → SEO never reaches the rendered head.
+
+Per-page `metadata`/`generateMetadata` exports override the defaults field by field. Resolve labels/content on the server and convert tracked strings only where Next expects primitives:
 
 ```ts
 export async function generateMetadata() {

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

@@ -35,7 +35,7 @@ When labels are not needed at that boundary, use `<FimoProvider locale={locale}>
 
 ## New-project boundary
 
-Choose the primary locale from the user's request before building pages. Put the first explicitly requested locale in `.fimo/config.json#i18n.defaultLocale` and keep all requested locales in `i18n.locales`. That is content and provider configuration: `src/locales.ts` reads the file, so the default locale passed to `FimoProvider` and the `<html lang>` follow it. It does not create locale URLs. If the user gives no locale signal, keep `en` and state that choice. Never add `NEXT_PUBLIC_FIMO_DEFAULT_LOCALE` or `FIMO_DEFAULT_LOCALE`; the runtime ignores them by design.
+Choose the primary locale from the user's request before building pages. Configure the supported locales and default through the `fimo-cli` locale workflow. `src/locales.ts` reads the synchronized config, so the default locale passed to `FimoProvider` and the `<html lang>` follow it. It does not create locale URLs. If the user gives no locale signal, keep `en` and state that choice. Never add `NEXT_PUBLIC_FIMO_DEFAULT_LOCALE` or `FIMO_DEFAULT_LOCALE`; the runtime ignores them by design.
 
 The starter is default-only: one ordinary root layout renders `<html lang={defaultLocale}>` and `FimoProvider`, `/` is the homepage, and unknown paths get Next's native 404. Implement a locale routing strategy only when the product asks for one — prefixed `[locale]` segments, middleware, cookies, domains, or an i18n library are all Next decisions — then resolve the locale in that strategy and pass it into Fimo server reads and `FimoProvider`. Do not install a top-level `[locale]` route or an optional catch-all speculatively: it captures `/favicon.ico` and every unknown top-level path, and Fimo never requires it.
 
@@ -45,7 +45,7 @@ When the app implements a localized URL shape, describe it in `.fimo/config.json
 
 With `next-i18next`, keep its routing and translation provider for the strings it owns. Pass the same resolved locale to Fimo; do not replace the library or duplicate its route structure.
 
-Before creating non-default Fimo labels or content variants, confirm that those locales are enabled for the linked Fimo project. Load `fimo-cli` with its `locales` reference and run `fimo locales add <locale> --yes --json`; `.fimo/config.json` documents the application's locale policy, but `fimo validate` does not add project locales.
+Before creating non-default Fimo labels or content variants, confirm that those locales are enabled for the linked Fimo project. Load `fimo-cli` with its `locales` reference and run `fimo locales add <locale> --yes --json`; `fimo validate` does not add project locales.
 
 ## Ownership boundary
 

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

@@ -2,7 +2,7 @@
 
 Use this reference when `fimo describe --json` reports `framework.slug: "nextjs"`, or the project uses an App Router (`app/` or `src/app/`) or Pages Router (`pages/` or `src/pages/`) tree.
 
-Fimo supports schema-first content in both routers across static generation, ISR, request-time rendering, and Client Components. The application owns routes, locale resolution, links, `<html lang/dir>`, and SEO. Fimo receives the resolved locale and supplies content, labels, source metadata, and client editing context.
+Fimo supports schema-first content in both routers across static generation, ISR, request-time rendering, and Client Components. The application owns routes, locale resolution, links, `<html lang/dir>`, and per-page SEO overrides. Fimo receives the resolved locale and supplies content, labels, source metadata, client editing context, and the site-wide SEO defaults (App Router: `buildFimoMetadata`/`buildFimoViewport` in the root layout — see the router reference's Metadata section).
 
 ## Choose the router reference
 

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

@@ -13,11 +13,13 @@ The application owns locale resolution and routing. Fimo consumes the resolved l
 }
 ```
 
-For new projects, derive the primary locale from the request; when several are explicit, the first one named is the default. Update `i18n.defaultLocale`, `i18n.locales`, the document language default, and any framework-native locale route boundary or matcher the application implements. If the user gives no locale signal, retain the starter default and state that choice.
+For a linked project, load `fimo-cli` with its `locales` reference and use the typed locale commands to change the supported locales or default. That reference owns the synchronization and recovery contract.
+
+For new projects, derive the primary locale from the request; when several are explicit, the first one named is the default. Configure that locale set through the lifecycle commands, then update the document language default and any framework-native locale route boundary or matcher the application implements. If the user gives no locale signal, retain the starter default and state that choice.
 
 Keep one locale unless the product asks for multilingual output. Keep it locale-ready without forcing `/en`, a language switcher, global path-prefix routing, or localized schemas. Locale tags should be structurally valid, such as `en`, `pt-BR`, or `zh-Hans`.
 
-For an already linked project, enable each locale in Fimo before writing non-default label or content variants. Load `fimo-cli` with its `locales` reference and run `fimo locales add <locale> --yes --json`; local config and `fimo validate` do not provision project locales. Do not change the application's route strategy to work around a missing locale.
+Enable each locale before writing non-default label or content variants. Run `fimo locales add <locale> --yes --json`; `fimo validate` does not provision project locales. Do not change the application's route strategy to work around a missing locale.
 
 ## Application responsibilities
 

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

@@ -34,6 +34,20 @@ 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.
 
+Before any source, target, Fimo, or remote write, inspect the available source
+read-only and follow [questions-and-improvements.md](references/questions-and-improvements.md).
+Use the coding agent's native structured-question UI when available. Ask one
+stacked batch of the decisions the source cannot answer instead of interrupting
+the migration for each question. A migration request never authorizes moving
+environment values or credentials.
+
+When migration replaces local or bundled content with Fimo reads, preserving
+content-delivery performance is part of fidelity. Keep build-time and
+server-rendered content off the browser request path, use direct generated-client
+lookups, avoid duplicate or sequential reads, and prove edit freshness. Do not
+ask a generic optimization question or bundle a framework upgrade into the
+migration.
+
 ## Execution environment
 
 Run this skill from a coding-agent process that has direct access to the
@@ -139,13 +153,18 @@ report the exact failed command and setup requirement.
   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.
+  When the source defines an active CMS but its deployed records are unavailable,
+  rebuild published content from the public site only after the user explicitly
+  chooses that lower-confidence path.
 - 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. If the source API URL or access
-  is missing or unreachable, stop and ask the user for it; do not guess, replace
-  the content, or mark the lane complete.
+  is missing or unreachable, stop and ask whether the owner wants to provide a
+  scoped export or read-only access, reconstruct the selected published routes
+  from public pages, or migrate code only and leave those records external. Never
+  infer permission to scrape, discover secrets, or contact private endpoints.
 - Model content before page code. Generated JSON is not imported content.
 - Model editorial content Fimo-natively: blocks for structured or repeatable
   sections, richtext for rich bodies, references for categories, authors,
@@ -190,9 +209,11 @@ report the exact failed command and setup requirement.
      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
+4. Read `references/questions-and-improvements.md`, finish its read-only
+   preflight, and collect the user's decisions before setup or implementation.
+5. Read `references/workflow.md` before implementation and create or update the
    plain-text migration plan.
-5. Load the references that apply:
+6. 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`.
@@ -227,9 +248,13 @@ 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>`
+  `fimo migrate init <target-dir> --project-id <projectId> --framework <framework> --source-platform <platform>`
 - Create a new project in an owner-supplied organization:
-  `fimo migrate init <target-dir> --org <organizationId> --framework <framework>`
+  `fimo migrate init <target-dir> --org <organizationId> --framework <framework> --source-platform <platform>`
+
+`--source-platform` names what the site is migrated from (`wordpress`, `nextjs`,
+`astro`, `react-router`, `webflow`, `framer`, `squarespace`, `wix`, `carrd`,
+`other`); pass what the source checkout proves, `unknown` only when nothing does.
 
 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
@@ -265,14 +290,20 @@ 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.
+  initial commit push described above. Pass `--source-platform <platform>`
+  (webflow, framer, squarespace, wix, carrd, wordpress, nextjs, astro,
+  react-router, other) when the source is known; URL crawls detect it.
+
 - `fimo link`: project creation or selection plus the in-place adoption of a
   copied source target.
 - `fimo deploy` / `fimo publish` — owner-approved only.
 
 ## Migration loop
 
-1. Run the setup path from "Initialized target precondition" and inspect the
+1. Inspect the source read-only, then ask the one preflight question batch from
+   `references/questions-and-improvements.md`. Do not initialize, link, import,
+   edit, or move environment values until the user answers every consent gate.
+2. Run the setup path from "Initialized target precondition" and inspect the
    initialized target before any worker edits it. A `fimo link` adoption keeps
    the source framework; the `fimo init` / `fimo migrate init` paths choose the
    target framework through the same canonical option as
@@ -284,7 +315,7 @@ Commands that perform actual data writes, all requiring the linked target:
    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
+3. Write a short `.fimo/migration/migration-plan.md` containing the chosen
    framework, source/target paths, worker owners, important dependencies, and
    known questions. Start the independent workers in `references/workers.md`:
    runtime/config, routes/SEO, content planning, and locales when those surfaces
@@ -293,25 +324,25 @@ Commands that perform actual data writes, all requiring the linked target:
    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. When
+4. The content planner reads every content-bearing source and consumer. When
    content comes from an API, it traces the active application client and
    retrieves the complete accessible dataset before pushing schemas. It then
    writes complete schemas and import payloads, recording source items,
    consumers, batches, and unresolved behavior in the text plan rather than a
    second orchestration format.
-4. Each discovery lane reports active media in its own surface. After the
+5. Each discovery lane reports active media in its own surface. After the
    runtime/framework, routes/SEO, and content discovery receipts are terminal,
    the coordinator performs one fan-in: combine and deduplicate them into the
    complete media-obligation list. Give only that list to the media worker; do
    not require a content-planner rescan. Once it returns every mapping, patch
    code and payload consumers. Start data after the asset gate and content code
    only after its imported records read back successfully.
-5. Fan in the workers' plain-text reports. Compare their claimed files with
+6. Fan in the workers' plain-text reports. Compare their claimed files with
    `git diff`, their Fimo writes with read-back CLI queries, and their source
    coverage with the content plan. Every source item must be migrated,
    deliberately preserved, or listed as unresolved with an owner action. A
    report that merely says “done” is not evidence.
-6. Validate against the real target with a validator that did not author the
+7. Validate against the real target with a validator that did not author the
    changes and starts only after every other worker report is terminal: read
    back schemas, entries, singles, labels, and assets through the CLI, build
    the project, render the migrated routes, and verify hosting compatibility
@@ -319,13 +350,15 @@ Commands that perform actual data writes, all requiring the linked target:
    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,
+8. Write `.fimo/migration/migration-report.md` with coverage, counts, mappings,
    unresolved items, timings from worker reports, and next actions.
 
 ## References
 
 - `references/workflow.md` - phase order, source intake, URL artifacts, and
   implementation loop.
+- `references/questions-and-improvements.md` - structured preflight questions,
+  integration consent, and content-delivery performance preservation.
 - `references/decision.md` - plain-text decision and schema guidance; no
   decision JSON is required.
 - `references/content.md` - CMS, entries, references, and source value rules.
@@ -359,10 +392,15 @@ Use one final status:
 - **draft-only**: imports or verification are incomplete, or the user asked for
   a draft.
 
-Never call a migration complete when CMS entries, media mappings, forms, or
-route coverage are unknown. Local QA remains the acceptance gate. If
+Never call a migration complete when CMS entries, media mappings, forms, route
+coverage, or migration-induced content-delivery regressions 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.
+
+Broader performance work and framework modernization are separate tasks. Start
+them only when the user explicitly asks, and never use them to hide a migration
+regression.

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

@@ -158,6 +158,14 @@ document, and a `public/` reference may become a media upload. The content
 planner decides the destination from the consuming route and data shape, rather
 than using a filename or extension as an automatic classification.
 
+Preserve how that content reaches the page. Local Markdown rendered during a
+Next build stays a Server Component or static-generation read after it moves to
+Fimo. Keep `generateStaticParams` when the source has known routes, list the
+required slugs once, and use the generated client's `getBySlug` for each detail
+page. Do not fetch the full post collection and filter it on every route, and do
+not introduce a Client Component solely to load Fimo content. Follow the shared
+evidence and freshness contract in `references/questions-and-improvements.md`.
+
 Create one source item per Markdown/MDX document and per independently handled
 construct inside it. Portable prose and an executable MDX component are
 different items even when they share one file. Read the custom component, its

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

@@ -86,6 +86,17 @@ 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.
+
 ## Failure Handling
 
 If a media asset cannot be downloaded or uploaded: