fimo 0.7.0-experimental.2 → 0.7.0-experimental.4

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

@@ -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,28 +82,28 @@ 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 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": {...}}}'`.

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

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

@@ -18,8 +18,11 @@ Run this gate before reporting completion.
 ## Behavior
 
 - Dependencies are installed in the target project.
-- The project builds successfully.
-- Local dev starts without Vite loader/schema/form generation errors.
+- The project builds successfully **with its own toolchain** (`next build`,
+  `vite build`, …) — wrapped sites are not Vite/React-Router projects; never
+  assume Fimo-template tooling.
+- Local dev starts without loader/schema/form generation errors (Vite errors
+  apply to rebuild-mode projects only).
 - Primary routes render without console/runtime errors.
 - Collection listing/detail pages work with imported data, seed data, or explicit
   empty states.
@@ -33,6 +36,25 @@ Run this gate before reporting completion.
 - Remove generated placeholder copy from visible UI.
 - Verify media aspect ratios and no broken images on primary routes.
 
+## Wrap Mode (additional blocking checks)
+
+When the manifest says `mode: "wrap"`:
+
+- `fimo migrate wrap --check` exits zero — it enforces coverage (zero
+  unwrapped items), render parity (rendered text/marks/media/links identical
+  to the pre-wrap baseline), and seeding (every wrapped key exists in the
+  database) — or every remaining item is an explicit ignored/unresolved
+  ledger entry with a reason.
+- Labels are seeded: every `FimoText`/`t()` key exists in `fimo labels list`
+  with the original string. Fallback-only content fails the gate.
+- Wrapped media/rich text have their `WrappedMedia`/`WrappedRichText` entries
+  created and assets uploaded.
+- Render parity: pages render identically to pre-migration — same text, same
+  formatting marks (bold/italic/underline/links), same media.
+- Diff audit: the migration diff contains only wiring, wrappers, label calls,
+  config, and dependency changes. Any routing/styling/component rewrite fails
+  the gate.
+
 ## Import Verification
 
 Record:

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

@@ -2,6 +2,14 @@
 
 Use this as the phase contract for complete migrations.
 
+> **Mode fork.** For a source-backed, WORKING JS codebase (Next.js, Vite/React,
+> React Router), wrap mode is the default: skip Phases 0 and 6 below and follow
+> `references/wrap.md` (adopt via `fimo init`, scan via `fimo migrate wrap`,
+> wrap in place, seed, verify). Phases 3–5 (content model, media/forms, import)
+> and Phase 8 (QA + report) still apply — wrap changes how content becomes
+> editable, not the accounting obligations. Everything else here is the rebuild
+> path.
+
 ## Phase 0: Target Safety
 
 1. Confirm the target path.
@@ -119,7 +127,10 @@ Required order:
 Record target IDs, import counts, failures, and unresolved items in the
 canonical ledger. Generated JSON without import counts is still draft state.
 
-## Phase 6: Fimo Implementation
+## Phase 6: Fimo Implementation (rebuild mode)
+
+In wrap mode this phase is replaced by `references/wrap.md` phases W3–W5
+(wire, wrap, seed); do not rebuild pages for a wrapped site.
 
 Implement routes, schemas, forms, entries, media, redirects, translations, and
 React pages with Fimo conventions.