fimo 0.7.0-experimental.3 → 0.7.0-experimental.4

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

@@ -3,7 +3,7 @@
 > **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
 
 > For how to plug returned media into UI components (`FimoMedia` shape, `<Image>` integration), see **`fimo/references/assets.md`** and **`fimo/references/ui.md`**.
-> For **generating** new images / videos with AI, see **`references/media.md`** for the task commands and recipes.
+> For **generating** new images / videos with AI, see **`references/media.md`** — the `fimo generate <model>` surface is documented there.
 
 This file covers the **CLI workflow** for media that already exists: uploading files, browsing the library, opening an asset to inspect it, moving / deleting items.
 
@@ -39,15 +39,15 @@ Use `--folder-path` when an agent needs a non-interactive upload target and does
 
 ## Generate AI media
 
-Moved to **`references/media.md`**. Choose the task that describes the outcome:
+Moved to **`references/media.md`**. The generation surface is one verb:
 
 ```bash
-fimo image generate --prompt "<prompt>"
-fimo image edit --prompt "<instruction>" --images <asset-id-or-url>
-fimo video generate --prompt "<prompt>"
+fimo generate <model-id-or-shortname> [--flag value ...]
 ```
 
-Task flags come from the API. Run `fimo <namespace> <task> --help` for the current options. Fimo owns the internal generation route.
+Per-model flags come from the API. `fimo models list` lists models;
+`fimo generate <model> --help` lists that model's flags. See `media.md` for
+the recipes block and the default-pick table.
 
 ### When to prefer generation over uploads / placeholders
 
@@ -59,6 +59,23 @@ Task flags come from the API. Run `fimo <namespace> <task> --help` for the curre
 - The user has already uploaded or referenced a specific file.
 - The image must be a real photo of a real thing (team photos, real product shots).
 
+## Browse models — `fimo models`
+
+```bash
+fimo models list                              # all, grouped by modality
+fimo models list --modality image             # filter by modality
+fimo models list --tag draft --tag fast       # filter by tag (repeatable, AND)
+fimo models list --provider pruna             # filter by provider
+fimo models list --json                       # machine-readable
+fimo models show pruna/p-image                # full detail + per-flag schema
+fimo models show gpt-image-2 --json           # JSON dump (for agents)
+```
+
+Model selection is **not** persisted per project. Picks live in
+`media.md` (baseline) → `CLAUDE.md` / `AGENTS.md` (project policy) → the
+prompt itself (highest priority). To target a specific model, name it on the
+command: `fimo generate <model> …`.
+
 ## Browse the library — `fimo assets list`
 
 ```bash
@@ -127,6 +144,6 @@ fimo assets delete <asset-id>
 
 ## End-to-end workflow
 
-1. Upload with `fimo assets upload` or generate with a task command such as `fimo image generate`.
+1. Upload (`fimo assets upload`) OR generate (`fimo generate <model> ...`) the asset.
 2. Keep the returned `url` (for direct use) or `id` (to attach to a `media` content-type field).
 3. To use in JSX, see `fimo/references/ui.md` — schema media → `<Image>` / `<Video>`, hardcoded URLs → `<StaticImage>`. **Never** use raw `<img src={asset.url}>`.

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

@@ -11,7 +11,7 @@ This file covers the **CLI workflow** for content. Use it when the user wants to
 1. Write `src/schemas/{Uid}.json` — PascalCase filename (e.g. `BlogPost.json`). For the JSON shape and field types, load `fimo/references/content.md`.
 2. Run `fimo schemas push {Uid}`. It generates `src/schemas/{Uid}.types.ts` and `src/schemas/{Uid}.ts`, then registers the schema with Fimo. It does not run whole-project validation.
 3. App code imports the generated client from `@/schemas/{Uid}`, not from `.types.ts` directly. See `fimo/references/content.md` for the hook API.
-4. Seed entries via `fimo entries create`. Generate cover images first with `fimo image generate` if needed (see `media.md` / `assets.md`).
+4. Seed entries via `fimo entries create`. Generate cover images first with `fimo generate <model>` if needed (see `media.md` / `assets.md`).
 5. Write React pages that import from `@/schemas/{Uid}` and render with `fimo/ui` components.
 
 Steps 1, 3, and 5 reference the project skill (`fimo`) for shape and React API. Steps 2 and 4 are CLI commands documented here.
@@ -20,9 +20,6 @@ Steps 1, 3, and 5 reference the project skill (`fimo`) for shape and React API.
 
 ```bash
 fimo schemas push [TypeName]      # push JSON to API (create or update). Omit TypeName to push all.
-                                  # Pushing all sends every schema as ONE atomic batch, so types that
-                                  # reference each other (even cycles) can be added in a single push.
-                                  # Files not present are never deleted — use `schemas delete` for that.
 fimo schemas list                 # list all registered schemas
 fimo schemas get <TypeName>       # get a single schema
 fimo schemas delete <TypeName>    # delete a schema
@@ -32,7 +29,7 @@ The command is `fimo schemas` (plural). There is no singular `fimo schema` alias
 
 All commands accept `-C, --cwd <dir>` to point at a different project directory.
 
-Schema transitions are automatic. Adding fields and changing labels preserve content. Removing a field removes only that field's values. One-to-many reference changes wrap existing references in arrays. Field type changes, scalar/reference changes, reference target changes, and many-to-one changes clear only the changed field. Collection-to-singleton removes that type's entries and cleans inbound references; singleton-to-collection preserves its entry. There are no reset or data-loss flags: changing the schema is the migration request. Run `fimo validate` after pushing to verify the regenerated client and whole project.
+Schema transitions are automatic. Adding fields and changing labels preserve content. Removing a field removes only that field's stored values. One-to-many reference changes wrap existing references in arrays. Field type changes, scalar/reference changes, reference target changes, and many-to-one changes clear only the changed field. Collection-to-singleton removes that type's entries and cleans inbound references; singleton-to-collection preserves its row. There are no reset or data-loss flags: changing the schema is the migration request. Run `fimo validate` after pushing to verify the regenerated client and whole project.
 
 ## Entries CLI commands
 
@@ -43,9 +40,9 @@ fimo entries create <TypeName> --body '<json>'
 fimo entries create <TypeName> --locale es --document-id <documentId> --body '<json>'
 fimo entries list <TypeName> [--limit N] [--offset N] [--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 update <TypeName> <id> [--locale es] --body '<json>'
-fimo entries delete <TypeName> <id> [--locale es]
+fimo entries get <TypeName> <id>
+fimo entries update <TypeName> <id> --locale es --body '<json>'
+fimo entries delete <TypeName> <id>
 ```
 
 `--body` is a **required** option on `create` and `update`. Its JSON shape (where `slug` goes, how `media` fields look, Tiptap richtext format) lives in `fimo/references/content.md`. **Always read that first before constructing an entry payload — slug must be inside `data`, media has a specific shape, richtext must be Tiptap JSONContent.**
@@ -65,12 +62,12 @@ fimo entries list BlogPost --fields slug,title,author --populate author
 Use the canonical read query flags: `--search`, `--sort`, `--where`, `--limit`, `--offset`, `--fields`, and `--populate`.
 `--where` is a JSON object keyed by schema field name. Simple values mean equality and stay typed inside the JSON (`{"featured":true}`, `{"category":"react"}`, `{"rank":{"$gte":3}}`); operator objects support `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$contains`, `$startsWith`, and `$null`, subject to the field type. Public Fimo-owned metadata lives under `__fimo`; currently `__fimo.contentType` is filterable.
 
-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`.
+Reference filters take the target `documentId` string even though stored values are objects (`{"author":"750e..."}`). On a to-many field, `$eq` and `$contains` mean membership, `$in` means any listed document 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`; pass only the 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 reference fields to embed. Without it, reference fields return reference objects like `{ "documentId": "..." }`; 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).
 
-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.
+Polymorphic references declare `targets: ["Post", "Product"]` instead of `target` (never both) and their values carry both parts: `{ "contentType": "Post", "documentId": "..." }`. 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.
 
 In generated React code, the equivalent is `populate: ['author', 'contributors'] as const` in the schema hook/query params. Let hooks infer the result when possible; if a named TypeScript shape is needed, use the generated `BlogPostResult<TFields, TPopulate>` type documented in `fimo/references/content.md`. Writes use the separate generated `BlogPostInput` type.
 
@@ -85,30 +82,30 @@ For reference schema JSON and entry value shape, load `fimo/references/content.m
 }
 ```
 
-Entry bodies use reference objects with target `id` values:
+Entry bodies store reference objects with target `documentId` values:
 
 ```bash
-fimo entries create BlogPost --body '{"data":{"slug":"hello","title":"Hello","author":{"id":"750e8400-e29b-41d4-a716-446655440000"},"contributors":[]}}'
+fimo entries create BlogPost --body '{"data":{"slug":"hello","title":"Hello","author":{"documentId":"750e8400-e29b-41d4-a716-446655440000"},"contributors":[]}}'
 ```
 
-Do not add `localized` or field-level `i18n` to reference fields. The reference value belongs to the entry variant containing it.
+Do not add `localized` or field-level `i18n` to reference fields. The reference value belongs to the entry variant that stores it.
 
 ## Localized and shared content
 
-Schemas are localized by default. Omit `--locale` to use the project default. Pass it explicitly when reading, updating, or deleting a non-default variant: public identity is stable `id` plus `locale`.
+Schemas are localized by default. Omit `--locale` for default-locale entries. Pass `--locale <locale>` when creating, listing, reading, or updating a specific non-default locale.
 
 When creating a localized variant of an existing entry, pass the source entry's `documentId` with `--document-id`. Keep projects single-locale unless the user asks for multilingual or localized output; when multiple locales are configured, create and update every locale explicitly.
 
-For content shared across locales, define `"i18n": { "enabled": false }` at the schema root and create each entry once. Do not pass `--document-id` to manufacture locale variants. Raw API and CLI responses omit `locale`; generated collection models add the effective active/default locale without creating per-locale variants. No other `i18n` options and no field-level localization settings are supported.
+For content shared across locales, define `"i18n": { "enabled": false }` at the schema root and create each entry once. Do not pass `--document-id` to manufacture locale variants. Shared entry responses omit `locale`; a read locale is only used to resolve populated references that target localized schemas. No other `i18n` options and no field-level localization settings are supported.
 
 Use `"isSingleton": true` for a type with exactly one logical document. Generated singleton clients expose `get`/`update` and their React Query hooks, not collection create/remove APIs.
 
 ## "Add a blog" recipe
 
 1. Load `fimo/references/content.md` for the JSON shape and field types.
-2. Write `src/schemas/BlogPost.json` with fields `title`, `body` (richtext), `coverImage` (media), etc. Do NOT declare a `slug` field — `slug` (and `id`, `entryId`, `documentId`, `locale`, `createdAt`, `updatedAt`, `__fimo`) is reserved entry metadata and will be rejected; every entry gets a `slug` for free.
+2. Write `src/schemas/BlogPost.json` with fields `title`, `body` (richtext), `coverImage` (media), etc. Do NOT declare a `slug` field — `slug` (and `id`, `documentId`, `locale`, `createdAt`, `updatedAt`, `__fimo`) is reserved entry metadata and will be rejected; every entry gets a `slug` for free.
 3. Run `fimo schemas push BlogPost`.
-4. Generate cover images: `fimo image generate --prompt "..." --aspect-ratio 16:9` (see `media.md`).
+4. Generate cover images: `fimo generate pruna/p-image --prompt "..."` (per-model flags come from `fimo models show <model>`; see `media.md`).
 5. Seed entries: `fimo entries create BlogPost --body '{"data": {"slug": "first-post", "title": "...", "coverImage": {...}}}'`.
 6. Load `fimo/references/ui.md` for the `<Text>`, `<Image>`, `<RichText>` components.
 7. Load `fimo/references/labels.md` for wrapping labels in `t()`.

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

@@ -132,7 +132,7 @@ Propagation: typically 15–30 minutes, up to 48 hours rarely.
 
 ## Web app equivalent
 
-For users on the dashboard, the same workflow lives at **Settings → Domains** (custom domain) and **Organization → Domains** (buy/owned). See `fimo-studio/references/custom-domains.md` and the [public docs](https://fimo.ai/docs/publish/custom-domains).
+For users on the dashboard, the same workflow lives at **Settings → Domains** (custom domain) and **Organization → Domains** (buy/owned). See `fimo-studio/references/custom-domains.md` and the [public docs](https://docs.fimo.ai/publish/custom-domains).
 
 ## Anti-patterns
 

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

@@ -67,12 +67,6 @@ import { fimoRoutes } from 'fimo/react-router/routes';
 
 For custom frameworks, the project may implement its own URL scheme, but it still needs to pass the active locale into Fimo and keep canonical route metadata if it wants Fimo Studio route selection to work.
 
-## 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.
-
-For React Router projects, prefer one contract based on `fimo-config.json`, `fimoRoutes()`, and `FimoLink`; migrate existing wrappers into the framework root instead of layering a second locale context. If that would change established URLs, keep the custom router temporarily, pass its active locale to `FimoProviders`, and ask the user to choose canonical URLs and redirects before rewriting routes.
-
 ## Labels And Content
 
 Labels and content are separate translated surfaces:

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

@@ -1,171 +1,181 @@
-# AI media tasks
+# Media generation
 
-> **Run via `npx fimo@latest <command>`** so the task catalog and CLI stay aligned.
+> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
 
-Use task commands for AI media. The command describes the outcome; Fimo chooses and can change the underlying generation route without changing agent instructions.
+> For uploading existing files, browsing the library, and opening assets, see
+> `references/assets.md`. This file is **only** about generating new media
+> via AI — the `fimo generate <model>` surface.
+
+The CLI exposes **one verb** for all media generation. The model is positional;
+every other input is a flag declared by that model's schema.
 
 ```bash
-fimo image generate --prompt "<prompt>"
-fimo image edit --prompt "<instruction>" --images <asset-id-or-url>
-fimo image remove-background --image <asset-id-or-url>
-fimo image upscale --image <asset-id-or-url>
-
-fimo video generate --prompt "<prompt>"
-fimo video animate --video <asset-id-or-url> --image <asset-id-or-url>
-fimo video replace --video <asset-id-or-url> --images <asset-id-or-url>
+fimo generate <model-id-or-shortname> [--flag value ...] [--json] [--dry-run]
 ```
 
-Use only task commands in new workflows. Internal routing details are not part of the public interface.
+`<model>` is either a canonical id (`pruna/p-image`) or its terminal-friendly
+shortName (`pruna-p-image`, `gpt-image-2`). The CLI fetches each model's flags
+and base price from the API (`GET /api/models`); the server validates the
+options. So flags, defaults, enum values, and pricing all come from one source
+and can't drift — `fimo models show <model>` prints them.
 
-## Shared behavior
+---
 
-- Run `fimo <namespace> <task> --help` for the current task flags.
-- Add `--dry-run` to validate inputs and get a cost estimate without creating media.
-- Add `--json` for structured output.
-- Add `--name "..."` to set the media-library name.
-- Add `--parent <folder-id>` to save into a folder.
-- Source media can be a Fimo asset ID or an absolute URL.
-- Repeat `--images` for tasks that accept multiple references.
-- The response returns the created asset, cost, credits, task, and quality when applicable. Keep the asset `id` for content fields or the public `url` for direct use.
+## Models
 
-## Quality
+Deliberately small, curated catalog (8 image + 3 video). This file documents the **defaults and recipes** below; for the live list with prices, tags, best-for, and flags, run `fimo models list --extended` (or `fimo models show <model>` for one model's options).
 
-Tasks that expose `--quality` accept:
+---
 
-- `draft`: faster and cheaper for iteration.
-- `standard`: default for ordinary work.
-- `premium`: higher quality for final, prominent media.
+## Defaults — pick the cheapest model that does the job
 
-Start with `standard`. Use `draft` for disposable exploration. Use `premium` only when the user asks for the best result or the media is especially prominent.
+**Default to `pruna/p-image` (images) and `pruna/p-video` (video).** The cheap baseline covers the large majority of requests. For anything it can't do — img2img edit, vector/SVG, background removal, upscale, virtual try-on, image-to-video — see the **Recipes** below; each names its model.
 
-Preview the choice before spending credits:
+**Don't reach for the expensive models (`openai/gpt-image-2`, `fal-ai/bytedance/seedream`) unless explicitly asked** (e.g. a hero or other prominent image), or the project's `AGENTS.md` / `CLAUDE.md` sets a different default.
 
-```bash
-fimo image generate \
-  --prompt "editorial illustration of a quiet coastal town at sunrise" \
-  --quality standard \
-  --aspect-ratio 16:9 \
-  --dry-run
-```
+Model selection lives here (and in project `AGENTS.md` / `CLAUDE.md`). Run `fimo models list` for the live catalog, and
+**`fimo models show <model>` to read a model's options before you use it** —
+options are NOT standardized across models (e.g. pruna takes `--aspect-ratio`,
+while `gpt-image-2` / `seedream` size via `--image-size`). Don't assume a flag
+exists on a model you haven't inspected.
 
-## Image recipes
+### Parameters for the default (pruna) models
 
-### Generate an image
+Inlined so you don't need `models show` for the common path. For **any other
+model**, run `fimo models show <model>` — its options will differ. (This list is
+a convenience snapshot; `models show` is the live source of truth.)
 
-```bash
-fimo image generate \
-  --prompt "editorial illustration of a quiet coastal town at sunrise" \
-  --quality standard \
-  --aspect-ratio 16:9 \
-  --name "Coastal sunrise hero"
-```
+**`pruna/p-image`** — text-to-image
 
-Supported aspect ratios are `1:1`, `16:9`, `9:16`, `4:3`, and `3:4`.
+- `--prompt <string>` · **required** · generation prompt
+- `--aspect-ratio <1:1|16:9|9:16|4:3|3:4>` · default `1:1`
 
-### Edit one or more images
+**`pruna/p-image-edit`** — img2img / prompt-driven edit
 
-```bash
-fimo image edit \
-  --prompt "change the background to a warm sunset while preserving the subject" \
-  --images <asset-id-or-url> \
-  --aspect-ratio 16:9
-```
+- `--prompt <string>` · **required** · editing instruction
+- `--source-images <asset-id|url>` · **required** · repeatable, up to 5 (an `ast_*` asset id or an absolute URL)
+- `--aspect-ratio <1:1|16:9|9:16|4:3|3:4>` · default `1:1`
 
-Repeat `--images` to provide up to five references.
+**`pruna/p-video`** — text-to-video (add `--source-images` to do image-to-video)
 
-### Remove a background
+- `--prompt <string>` · **required**
+- `--source-images <asset-id>` · optional · one `ast_*` asset id; passing it flips to image-to-video
+- `--aspect-ratio <1:1|16:9|9:16|4:3|3:4|3:2|2:3>` · default `16:9`
+- `--duration <int 1–10>` · default `5` (seconds)
+- `--resolution <720p|1080p>` · default `720p`
+- `--include-audio` · default off (pass the flag to enable)
 
-```bash
-fimo image remove-background --image <asset-id-or-url>
-```
-
-### Upscale an image
+**`pruna/p-video-draft`** — same flags as `pruna/p-video`; ~4× cheaper, lower quality.
 
-```bash
-fimo image upscale \
-  --image <asset-id-or-url> \
-  --target-megapixels 8 \
-  --output-format png \
-  --enhance-details
-```
+---
 
-Use `--enhance-realism` for photographic material. Use `--no-enhance-details` when preserving the original texture matters more than reconstruction.
+## Recipes — user intent → exact command
 
-## Video recipes
-
-### Generate from text
+Each recipe is **one** command. The "Why" line tells the agent when to reach
+for this vs. an alternative.
 
 ```bash
-fimo video generate \
-  --prompt "slow camera push through a greenhouse after rain" \
-  --quality standard \
-  --duration 6 \
-  --aspect-ratio 16:9
+# "Generate an image" (default — cheapest workhorse)
+fimo generate pruna/p-image --prompt "<prompt>"
+# Why: fast, cheap, good enough for most cases.
+
+# "Generate a high-quality / typography / hero image"
+fimo generate openai/gpt-image-2 --prompt "<prompt>" --quality high
+# Why: premium quality, typography + realism. ~10–40× the baseline cost — use
+# only on an explicit request (e.g. hero / prominent media), never by default.
+# --quality low/medium saves cost (metered: ~$0.22 high → ~$0.02 low).
+
+# "Generate a 4K image" (native high resolution, no upscale needed)
+fimo generate fal-ai/bytedance/seedream/v4.5/text-to-image \
+  --prompt "<prompt>" --image-size auto_4K
+# Why: outputs at 4K natively — skip the clarity-upscaler step.
+
+# "Edit an existing image with a prompt"
+fimo generate pruna/p-image-edit \
+  --prompt "<edit instruction>" --source-images <asset-id-or-url>
+# Why: img2img with prompt-driven transforms. Style changes,
+# object swaps, scene relighting.
+
+# "Try a garment on a person" (e-commerce / fashion)
+fimo generate fal-ai/flux-pro/v1/vto \
+  --prompt "<styling instruction>" \
+  --human-image-url <person-url> --garment-image-url <garment-url>
+# Why: virtual try-on. Specific to fashion; don't use for general edits.
+
+# "Remove the background of an image"
+fimo generate fal-ai/bria/background/remove --source-images <image-url>
+# Why: deterministic transparent-PNG cutout. No prompt needed.
+# Note: this fal model takes an image URL, not a library asset-id.
+
+# "Upscale an image to higher resolution"
+fimo generate fal-ai/clarity-upscaler \
+  --source-images <image-url> --upscale-factor 4
+# Why: 2×/3×/4× super-resolution. Best quality at 2×. Takes a URL, not an asset-id.
+
+# "Generate a vector illustration / SVG / icon"
+fimo generate fal-ai/recraft/v3/text-to-image \
+  --prompt "<prompt>" --style vector_illustration/bold_stroke
+# Why: only model that returns SVG. Six style variants
+# (bold_stroke, line_art, cutout, infographical, marker_outline, seamless).
+
+# "Generate a video from text"
+fimo generate pruna/p-video --prompt "<prompt>" --duration 6 --aspect-ratio 16:9
+# Why: baseline video model. Add --include-audio for sound.
+
+# "Quick rough video preview"
+fimo generate pruna/p-video-draft --prompt "<prompt>" --duration 4
+# Why: ~4× cheaper than pruna/p-video. Same shape; switch to pruna/p-video for final.
+
+# "Generate a video from an existing image"
+fimo generate pruna/p-video \
+  --prompt "<motion description>" --source-images <asset-id-or-url>
+# Why: same Pruna model — passing --source-images flips it to image-to-video mode.
+
+# "Cheap image-to-video alternative"
+fimo generate fal-ai/minimax/hailuo-02/standard/image-to-video \
+  --prompt "<motion>" --source-images <image-url> --duration 6
+# Why: cheap i2v. Source is an image URL (not an asset-id); duration is 6 or 10.
+# Output aspect comes from the source image.
 ```
 
-Add `--include-audio` when the result should contain generated audio.
-
-### Generate from an image
-
-```bash
-fimo video generate \
-  --prompt "subtle wind moves the leaves, locked camera" \
-  --image <asset-id-or-url> \
-  --duration 5 \
-  --aspect-ratio 16:9
-```
+---
 
-### Make a loop
+## Universal flags (every model)
 
-```bash
-fimo video generate \
-  --prompt "gentle water movement, seamless return to the first frame" \
-  --image <asset-id-or-url> \
-  --loop \
-  --duration 5
-```
+| Flag                  | Default        | Meaning                                                    |
+| --------------------- | -------------- | ---------------------------------------------------------- |
+| `--name <str>`        | slug of prompt | Asset display name in the library                          |
+| `--parent <asset-id>` | —              | Library placement (folder asset-id)                        |
+| `-C, --cwd <dir>`     | current dir    | Project directory to resolve the env from                  |
+| `--json`              | —              | Machine-readable output (jq-friendly)                      |
+| `--dry-run`           | —              | Validate flags + show resolved request, don't call the API |
 
-`--loop` requires `--image` and cannot be combined with `--include-audio`.
+> Cost: there is no cost flag on `generate`. Pricing lives in discovery and is
+> shown as the provider's **per-unit rate** (e.g. `$0.045 / second`,
+> `$0.04 / image`), not a synthesized total. `fimo models list` shows the rate
+> per model; `fimo models show <model>` prints a `PRICING` block. With `--json`,
+> each model carries `price: { unitPrice, unit, confidence }` (or `null`). A `~`
+> prefix means even the rate is approximate (metered).
 
-### Transfer motion from a video to an image
+---
 
-```bash
-fimo video animate \
-  --video <motion-source-asset-id-or-url> \
-  --image <subject-image-asset-id-or-url> \
-  --quality standard \
-  --duration 5
-```
+## Discovery — read a model's options before you use it
 
-### Replace people in a video
+Options are **not standardized across models** — each model declares its own
+flags. Before generating with a model you haven't used, read its options to
+understand what it can do (and what it expects): `fimo models show <model>`
+prints every flag with its type, default, enum values, description, and a usage
+example; `fimo generate <model> --help` prints the same flag list. Both come
+from the API (introspected server-side from the model's schema), so they can't
+drift. **Don't assume a flag carries across models** — e.g. `--aspect-ratio`
+exists on pruna but not on `gpt-image-2` / `seedream` (which size via
+`--image-size`).
 
 ```bash
-fimo video replace \
-  --video <source-video-asset-id-or-url> \
-  --images <identity-image-asset-id-or-url> \
-  --quality standard \
-  --duration 5
+fimo generate openai/gpt-image-2 --help
+fimo models list --modality video
+fimo models list --tag draft         # filter by tag (repeatable, AND semantics)
+fimo models list --extended          # per-model card: alias, provider, tags, price, best-for, flags
+fimo models show fal-ai/flux-pro/v1/vto          # PRICING rate + per-flag docs with usage examples
+fimo models show fal-ai/flux-pro/v1/vto --json   # same, machine-readable (price.unitPrice / price.unit + flags)
 ```
-
-Repeat `--images` for up to three identities. Add `--prompt` when placement needs clarification.
-
-## When to generate
-
-Generate when the page needs original artwork, a hero, a card thumbnail, an avatar, an empty-state illustration, or a short motion asset and the user has not supplied one.
-
-Do not generate when:
-
-- the user supplied or named a specific asset;
-- the result must depict a real person, team, product, or place accurately;
-- an existing media-library asset already fits the request.
-
-Upload real files with `fimo assets upload`. Browse reusable media with `fimo assets list` before spending credits.
-
-## Verification
-
-After generation:
-
-1. Confirm the command exited successfully and returned an asset ID.
-2. Open or download the asset with `fimo assets open <id>`.
-3. Verify it matches the request before inserting it into content or UI.
-4. Use the whole media value with Fimo's `<Image>` or `<Video>` components rather than raw HTML elements.

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

@@ -17,7 +17,10 @@ exports, source repositories, CMS exports, media folders, or any hybrid of those
 It owns intake, source inventory, URL crawl bootstrapping, ledger normalization,
 imports, and QA so any LLM can run the work without silently dropping content.
 
-> Run every `fimo` command as `npx fimo@latest <command>` — always the latest CLI, no global install.
+> Run every `fimo` command as `npx fimo <command>` when the project declares a
+> `fimo` dependency (adopted/wrapped projects pin an exact version tied to their
+> backend — never override it with `@latest`). Only fall back to
+> `npx fimo@latest` when the project has no `fimo` dependency.
 
 ## Non-Negotiables
 
@@ -30,6 +33,13 @@ imports, and QA so any LLM can run the work without silently dropping content.
   ledger.
 - Source exports beat inferred crawls. If CSV/XML/JSON exports, media folders, or
   source code exist, treat the public URL as visual/SEO reference only.
+- A working JS codebase is wrapped, not rewritten. Wrap mode
+  (`references/wrap.md`) keeps the user's routing, styling, and components
+  untouched; the diff is wiring + wrappers + config only. As the coding
+  agent you own the whole wrap loop — run `npx fimo migrate` yourself and
+  follow `references/wrap.md` § W0 (relay the recorded data-source
+  decisions to the user, then loop `npx fimo migrate wrap --check` to
+  exit 0).
 - Builder HTML is evidence, not the final runtime. Rebuild with Fimo conventions,
   schemas, forms, media primitives, translations, and routes.
 - Do not report completion until the QA gate passes or every failed check is
@@ -59,7 +69,15 @@ imports, and QA so any LLM can run the work without silently dropping content.
      pack.
    - **hybrid**: source files plus public URL. Use source-backed as truth and URL
      for route, SEO, visual, and behavior comparison.
-4. Create or update the canonical ledger described in
+4. Pick the mode:
+   - **wrap** (default for a source-backed, working JS codebase — Next.js,
+     Vite/React, React Router): keep the user's stack, adopt the repo with
+     `fimo init`, and make content editable by wrapping it in place. Never
+     rewrite routing, styling, or components. Follow `references/wrap.md`.
+   - **rebuild**: url-only sources, builder exports/HTML dumps, non-JS
+     backends, or codebases that do not build. Follow the standard workflow
+     phases.
+5. Create or update the canonical ledger described in
    `references/manifest.md`.
 
 ## Workflow
@@ -96,6 +114,8 @@ node <this-skill>/scripts/write-migration-report.mjs <project-root>
 ## References
 
 - `references/workflow.md` - full decision tree and phase order.
+- `references/wrap.md` - wrap mode: adopt a working JS codebase and wrap its
+  content in place (default for source-backed JS sites).
 - `references/manifest.md` - canonical migration ledger schema.
 - `references/content.md` - CMS, entries, references, and source value rules.
 - `references/media.md` - media inventory, upload, dedupe, and replacement rules.

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

@@ -18,6 +18,14 @@ ways:
    news teasers, and feature lists are almost always collections even when the
    source renders them inside one page.
 
+> **Rebuild path only.** These rules apply when Fimo re-authors the site
+> (URL/export migrations): the rebuilt code is disposable, so content belongs
+> in collections aggressively. **Wrap mode is deliberately stricter** — the
+> user's code stays primary, page furniture and nav stay in code with `t()`
+> labels, and every collection candidate is confirmed with the user first.
+> See `wrap.md` (W0 and the generated agent-prompt) — in wrap mode that
+> guidance overrides this section.
+
 After the source-faithful rebuild, treat **any hardcoded array of 3+ items with
 the same shape** as a collection candidate. Do not leave it hardcoded.
 

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

@@ -34,6 +34,7 @@ follow-up agents, and import/QA checks.
   "seo": [],
   "unsupported": [],
   "unresolved": [],
+  "wrap": null,
   "qa": {
     "status": "not-run|passed|failed|passed-with-unresolved",
     "checks": []
@@ -41,6 +42,40 @@ follow-up agents, and import/QA checks.
 }
 ```
 
+## Wrap Block (wrap mode only)
+
+When the migration is a wrap (see `references/wrap.md`), set
+`source.mode: "source-backed"` and fill the `wrap` block; leave it `null` for
+rebuild migrations:
+
+```json
+{
+  "wrap": {
+    "mode": "wrap",
+    "framework": "next|react-router|vite",
+    "adopted": true,
+    "wired": true,
+    "coverage": {
+      "wrappable": 0,
+      "wrapped": 25,
+      "ignored": 0,
+      "unresolvedItems": 0
+    },
+    "seeded": {
+      "labels": 21,
+      "wrappedMedia": 3,
+      "wrappedRichText": 1
+    },
+    "planPath": ".fimo/migration/plan.json"
+  }
+}
+```
+
+`coverage` mirrors the final `fimo migrate wrap --check` output: `wrappable`
+must be 0 (or fully accounted for by `ignored` + `unresolvedItems`, each with a
+ledger entry). `seeded` counts must match what `fimo labels list` /
+`fimo entries list` report — fallback-only content is not seeded.
+
 ## Required Item Fields
 
 Every route, content type, entry batch, media asset, form, redirect, locale, SEO