fimo 2.2.0-staging.8 → 2.2.0

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

@@ -0,0 +1,86 @@
+# Inbox
+
+The Inbox is what a project's agents tell the people on it: a run finished, a
+run left work for review, a merge conflicted, or a run stopped and is waiting
+for a decision. Only the last one can be acted on from the CLI.
+
+```bash
+fimo inbox list                              # unread first, then read
+fimo inbox list --topic agent_question --unread
+fimo inbox get <notification-id>             # the notification, plus the stored form when it is a question
+fimo inbox answer <notification-id> --body '<compact answer json>'
+```
+
+A notification id is the only id you ever hold. The question, its thread, the
+run it continues, and the Branch that run kept alive are resolved for you.
+
+Use `--project <id>` when there is no local `.fimo/project.json`. `--limit`,
+`--cursor`, and `--all-pages` page the list. `--archived` reads archived items;
+`--unread` stays in the unread stream instead of continuing into read items.
+
+## Answering is the person's decision, not yours
+
+**Never answer a question on someone's behalf.** A question exists because a run
+needed a human decision it could not make correctly. Answer only what the person
+in front of you explicitly chose.
+
+1. `fimo inbox list --topic agent_question --unread --json` to find waiting
+   questions, then `fimo inbox get <notification-id> --json` for the one to
+   answer. `data.question.form` is the stored form, verbatim.
+2. **Reproduce that form in the interface you are in** — the native form or
+   choice UI your harness offers, or a plain enumerated prompt when it offers
+   none. Keep the title, the description, the step order, the wording of every
+   question, every option label, the recommended option where one is marked,
+   image labels and URLs, and each capability's reason. The person is deciding
+   on what the agent actually asked, not on your summary of it.
+3. Collect only explicit answers. Do not default a step, infer one from earlier
+   conversation, or fill a step the person skipped. If the person already gave a
+   complete explicit answer, do not ask again — use what they said.
+4. **Never infer capability approval.** Selecting nothing on a capabilities step
+   is a deliberate deny-all, and omitting the step entirely is refused by the
+   CLI rather than read as a denial.
+5. Pass their notes through verbatim. The note is the one part of the answer
+   only they could write.
+6. Call `fimo inbox answer` once.
+
+## The compact answer
+
+Keyed by the step ids `inbox get` returned, in any order, one entry per step:
+
+```json
+{
+  "answers": [
+    { "stepId": "direction", "selected": ["Editorial studio"], "note": "Keep it calm." },
+    { "stepId": "access", "selected": [] },
+    { "stepId": "notes", "note": "Ship on Friday." }
+  ]
+}
+```
+
+- `selected` holds option **labels**, exactly as the form shows them.
+- `note` is free text. A step that offers options may be answered with a note
+  alone, with a selection alone, or with both.
+- A written step (`"type": "text"`) is answered with `note` only.
+- A capabilities step needs `selected`, empty or not. `[]` approves none.
+- Every step needs its own entry. Nothing is answered by omission.
+
+`--file <path>` and `--stdin` read the same JSON from a file or a pipe.
+
+## What the CLI refuses
+
+| Code                    | Why                                                                                                                                                                     |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `INBOX_ANSWER_INVALID`  | Unknown or missing step, unoffered option, too many selections on a single-select, a written step answered by picking, or a capabilities step with no explicit decision |
+| `INBOX_NOT_A_QUESTION`  | The notification is a run outcome, a review, or a conflict — there is nothing to answer                                                                                 |
+| `INBOX_QUESTION_CLOSED` | Already answered, expired, cancelled, or superseded                                                                                                                     |
+| `INBOX_UNKNOWN_TOPIC`   | `--topic` is not one of the four Inbox topics                                                                                                                           |
+| `INBOX_INVALID_CURSOR`  | `--cursor` was not the `nextCursor` from a previous page                                                                                                                |
+| `INBOX_NOT_FOUND`       | No notification with that id is addressed to you in this project                                                                                                        |
+
+A question is answered once. Answering it starts exactly one continuation run,
+and re-sending the same answer never starts a second one.
+
+## What the CLI does not do
+
+Marking read, archiving, restoring, reviewing retained work, and resolving merge
+conflicts happen in the Fimo Inbox UI. `fimo inbox` reads and answers.

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

@@ -23,7 +23,7 @@ Generated pnpm projects pin `pnpm@10.26.0` and carry project-owned `pnpm-workspa
 | `--project-id <id>`          | no                            | Set up the named Fimo project: scaffold and push a fresh site when it has no code yet, otherwise clone it.                                              |
 | `--org <id>`                 | no                            | Target organization **id** when creating (use the `ID` column from `fimo orgs list`, NOT the slug). Picker shown interactively if omitted and TTY.      |
 | `--branch <name>`            | no                            | Branch to check out when linking an existing project (defaults to `main`).                                                                              |
-| `--env <name>`               | no                            | Compatibility alias for `--branch <name>`.                                                                                                              |
+| `--env <name>`               | no                            | Rejected as a Branch selector; use `--branch <name>`.                                                                                                   |
 | `--framework <framework>`    | no                            | New-project scaffold: `nextjs` (App Router, default), `react-router`, `vite` (React SPA), `astro`, or `sveltekit`. Existing repositories are preserved. |
 | `--package-manager <pm>`     | no                            | `npm` \| `pnpm` \| `yarn` \| `bun`.                                                                                                                     |
 | `--install` / `--no-install` | yes in non-TTY                | Install deps after checkout (or skip it).                                                                                                               |
@@ -81,10 +81,11 @@ select it with `--framework react-router` when a project should use React Router
 instead of the default Next.js App Router shell.
 
 Set the primary locale from the request: when several are explicitly named, use the first as default;
-if none is requested, keep `en` and tell the user. Update `.fimo/config.json#i18n`, the framework-native
-locale boundary, matcher, and HTML language default. Do not keep `en` solely because the shell starts
-there. Do not add `/en`, a language picker, global path-prefix configuration, or localized schemas unless
-the site needs them.
+if none is requested, keep `en` and tell the user. After init, load `references/locales.md` and use its
+typed lifecycle commands to configure the locale set and default. Then update the framework-native locale
+boundary, matcher, and HTML language default. Do not keep `en` solely because the shell starts there.
+Do not add `/en`, a language picker, global path-prefix configuration, or localized schemas unless the
+site needs them.
 After init, load the project rules and `fimo-code` to build the requested site.
 If you replace a shell's code with a site that uses another framework or none,
 fix `runtime.framework` in the same change
@@ -94,7 +95,7 @@ For `--agents`, pass the AI tool you're running in: `--agents=claude-code` for C
 
 ## Setting up a project by ID
 
-Pass `--project-id <id>` to set up a known Fimo project. If the project has no code yet — for example, one just created in Fimo Studio — `init` scaffolds a fresh site into it and pushes the initial commit: the same create-new path, linked to the existing ID. If the project already has code, `init` clones it into `[dir]`, like `fimo clone`. Use `--branch <name>` to check out a specific Branch (defaults to `main`); `--env <name>` remains a compatibility alias. Without `--project-id`, `fimo init` creates a new project.
+Pass `--project-id <id>` to set up a known Fimo project. If the project has no code yet — for example, one just created in Fimo Studio — `init` scaffolds a fresh site into it and pushes the initial commit: the same create-new path, linked to the existing ID. If the project already has code, `init` clones it into `[dir]`, like `fimo clone`. Use `--branch <name>` to check out a specific Branch (defaults to `main`). Without `--project-id`, `fimo init` creates a new project.
 
 ## Linking an existing local application
 

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`.
@@ -22,7 +22,7 @@ fimo schedules resume <schedule>
 fimo schedules run <schedule>
 fimo schedules run <schedule> --no-wait
 fimo schedules runs <schedule> --limit 25 --status failed
-fimo schedules runs <schedule> --all
+fimo schedules runs <schedule> --all-pages
 fimo schedules runs show <run-id>
 fimo schedules delete <schedule>
 ```
@@ -59,9 +59,11 @@ Run history is cursor-paginated:
 fimo schedules runs nightly --limit 50
 fimo schedules runs nightly --cursor <cursor>
 fimo schedules runs nightly --status succeeded
-fimo schedules runs nightly --all
+fimo schedules runs nightly --all-pages
 ```
 
+`--all` remains a compatibility alias for existing scripts.
+
 Run detail includes status, timing, trigger, exit/error information, retained output, output retention metadata, and secret snapshot metadata. Output is capped and redacted before it is returned.
 
 ## JSON
@@ -70,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
 
@@ -121,6 +121,8 @@ fimo webhooks list
 fimo webhooks get <webhook-id>
 fimo webhooks test <webhook-id> --wait
 fimo webhooks deliveries <webhook-id> --limit 20
+fimo webhooks deliveries <webhook-id> --cursor <next-cursor>
+fimo webhooks deliveries <webhook-id> --all-pages
 fimo webhooks delivery <webhook-id> <delivery-id>
 ```
 

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