fimo 0.6.0 → 0.7.0-experimental.10

package/assets/skills/fimo/SKILL.md

@@ -14,7 +14,7 @@ You are writing code in a Fimo project — a content + media + forms + analytics
 
 This skill is version-locked to this project's installed `fimo` package — the shapes here match what your code can actually use.
 
-For CLI commands and workflows (creating a project, pushing schemas/forms, deploying, managing labels, etc.), the **`fimo-cli`** skill is the source of truth. Run every CLI command as `npx fimo@latest <command>` (always the latest, no global install). If `fimo-cli` isn't loaded for your AI tool, register it with `npx fimo@latest skills install --mode=copy`.
+For CLI commands and workflows (creating a project, pushing schemas/forms, deploying, managing labels, etc.), the **`fimo-cli`** skill is the source of truth. Run every CLI command as `npx fimo <command>` when the project declares a `fimo` dependency (it pins the version matching the project's backend); otherwise use `npx fimo@latest`. If `fimo-cli` isn't loaded for your AI tool, register it with `npx fimo skills install --mode=copy`.
 
 ## Critical: NEVER hardcode user-facing things
 
@@ -43,7 +43,7 @@ Workflow / CLI-side concerns (pushing schemas, generating images, managing label
 ## Decision Tree (specific tasks)
 
 - **Setting up Fimo in a new project** — pick the framework:
-  - React Router framework mode (new projects use React Router 8) → `references/setup-react-router.md`
+  - React Router 7 framework mode → `references/setup-react-router.md`
   - Plain Vite + React (or upgrading a legacy v3 project) → `references/setup-plain-vite.md`
 - Writing schema JSON / picking field types / Tiptap richtext → `references/content.md`
 - Writing form JSON / generated form client / form code → `references/forms.md`

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

@@ -67,14 +67,6 @@ This helper exists so the Fimo UI route selector, preview navigation, labels, an
 
 Copyable examples live in `assets/react-router-locales/routes.ts` and `assets/react-router-locales/navigation.tsx`.
 
-## Existing Custom Locale Systems
-
-Before changing a multilingual app, inspect its locale provider, route table, language switcher, redirects, and current public URLs. Preserve that behavior while migrating.
-
-For React Router projects, prefer converging on one locale contract owned by `fimo-config.json`, `fimoRoutes()`, and `FimoLink`. Move existing providers and language-switcher UI into the framework root instead of replacing them or adding a second locale context. Keep route metadata canonical and reuse page modules across locales.
-
-If adopting the standard helper would change established public URLs, do not silently rewrite them. Keep the custom router temporarily, pass its resolved locale to `<FimoProviders locale={locale}>`, and ask the user to choose the canonical URLs and redirects before normalizing the route table.
-
 ## Links
 
 Use `FimoLink` for internal links that should preserve or switch locale:

package/assets/skills/fimo/references/setup-react-router.md

@@ -1,4 +1,4 @@
-# Setup Fimo on React Router 8
+# Setup Fimo on React Router 7
 
 This recipe describes the canonical Fimo + React Router framework-mode setup.
 It mirrors what `fimo init` scaffolds today; you can also apply it to an
@@ -6,7 +6,7 @@ existing RR project.
 
 ## Prerequisites
 
-- Node 22.22+
+- Node 20+
 - A Fimo project created via `fimo init` (gives you `projectId`,
   `organizationId`, and an `apiUrl`).
 

package/assets/skills/fimo/references/ui.md

@@ -42,7 +42,7 @@ The template uses **Vite + React 19 + TypeScript + Tailwind v4 + shadcn/ui + rea
 
 ### Routing
 
-- This template uses React Router 8 framework mode (file-based route config in `src/routes.ts`). Use `<FimoLink>` from `fimo/react-router` for locale-aware internal links, especially in projects with more than one configured locale. Use React Router `<Link>` / `<NavLink>` only when you intentionally do not want Fimo's locale behavior. Never raw `<a href="/...">` for internal navigation because it causes full page reloads.
+- This template uses React Router v7 framework mode (file-based route config in `src/routes.ts`). Use `<FimoLink>` from `fimo/react-router` for locale-aware internal links, especially in projects with more than one configured locale. Use React Router `<Link>` / `<NavLink>` only when you intentionally do not want Fimo's locale behavior. Never raw `<a href="/...">` for internal navigation because it causes full page reloads.
 - Reserve `<a>` for external links, with `target="_blank" rel="noreferrer"`.
 
 ### Loading states

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

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.