fimo 0.3.1 → 0.3.2-experimental.1783328062928

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

@@ -0,0 +1,114 @@
+# `fimo init`
+
+> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
+
+One-stop project setup: sign in, create a new Fimo project (or link an existing one), install dependencies, and optionally set up Fimo skills for your AI tools.
+
+## Command
+
+```bash
+fimo init [dir] [options]
+```
+
+`fimo init` runs the full onboarding in one shot:
+
+1. **Signs in automatically** — if there's no session it opens the browser loopback login. In `--json` / non-TTY with no session it fails with `NOT_AUTHENTICATED` (run `fimo login` first).
+2. **Resolves the project** — with `--project-id <id>` it links an EXISTING project (clones it); without it, it creates a NEW project. An interactive TTY shows a "Create new / Link existing" picker; non-interactive shells default to create-new.
+3. **Installs dependencies** — prompts for the package manager, or honor `--package-manager <pm>` / `--no-install`.
+4. **Optionally sets up Fimo skills** — confirm prompt, or `--skills` / `--no-skills`.
+
+| Flag                         | Required                      | Purpose                                                                                                                                            |
+| ---------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `[dir]` positional           | yes in non-TTY for create-new | Target directory (e.g. `my-site`)                                                                                                                  |
+| `--project-id <id>`          | no                            | Link an EXISTING project instead of creating one (clones 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. |
+| `--env <name>`               | no                            | Env to check out when linking an existing project (defaults to `main`).                                                                            |
+| `--package-manager <pm>`     | no                            | `npm` \| `pnpm` \| `yarn` \| `bun`.                                                                                                                |
+| `--install` / `--no-install` | yes in non-TTY                | Install deps after checkout (or skip it).                                                                                                          |
+| `--skills` / `--no-skills`   | yes in non-TTY                | Set up Fimo skills (or skip it).                                                                                                                   |
+| `--agents <list>`            | no                            | Comma-separated agent IDs (e.g. `claude-code,cursor`). Pass `none` to write only universal AGENTS.md.                                              |
+| `-a, --agent <id>`           | alternative                   | Repeatable form: `-a claude-code -a cursor`.                                                                                                       |
+| `--mode <symlink\|copy>`     | no                            | Project skill install method.                                                                                                                      |
+| `--template-root <path>`     | no                            | Override the bundled template (development only).                                                                                                  |
+| `-y, --yes`                  | no                            | Skip the skills install preview confirmation.                                                                                                      |
+
+In a non-TTY shell the create-new path requires `[dir]`, `--install` / `--no-install`, and `--skills` / `--no-skills` (and `--org` if you have no active org and belong to multiple orgs). Without them the command exits with `Cannot prompt in a non-interactive shell.`
+
+> **Zero-install:** run `npx fimo@latest init` — no global install needed. `fimo projects create` is also an alias of `fimo init` (create-new path).
+
+For `--agents`, pass the AI tool you're running in: `--agents=claude-code` for Claude Code, `--agents=cursor` for Cursor, `--agents=codex` for Codex, etc. When the flag is omitted, env-var detection of the invoking harness (e.g. `CLAUDECODE` / `CLAUDE_CODE_ENTRYPOINT` → claude-code) auto-targets that agent; other agents must be selected explicitly via `--agents`/`-a` or the interactive picker.
+
+## Linking an existing project
+
+Pass `--project-id <id>` to link an EXISTING project instead of creating one. This clones the project's git repo into `[dir]` and writes the local `.fimo.settings.json` + agent files, the same as `fimo clone` (init's `--project-id` path reuses it). Use `--env <name>` to check out a specific env (defaults to `main`). Without `--project-id`, `fimo init` creates a new project.
+
+## What gets written (create-new)
+
+`fimo init` (create-new path) scaffolds:
+
+- The project template (Vite + React 19 + TypeScript + Tailwind v4 + shadcn/ui + react-router)
+- `.fimo.settings.json` — links this directory to the remote project (read-only after creation)
+- `.env` — initial env vars (currently just `VITE_API_URL`)
+- `AGENTS.md` — project rules read by all agentskills.io-compatible AI tools (Codex, OpenCode, Aider, etc.)
+- Per-agent variants based on `--agents`:
+  - `claude-code` → `CLAUDE.md` + `.claude/settings.json`
+  - `cursor` → `.cursor/rules/fimo.mdc`
+  - `windsurf` → `.windsurfrules`
+  - `gemini-cli` → `GEMINI.md`
+  - codex / opencode / aider / others → no extra file; AGENTS.md is read natively
+- The project-scope `fimo` skill (npm package surface: schemas, forms, `t()`, `fimo/ui` components) copied into each selected agent's skill dir (`.claude/skills/fimo/`, `.cursor/skills/fimo/`, etc.). Version-locked to the bundled `fimo` package — the installed `SKILL.md` is stamped with `fimoVersion`. Refresh later with `fimo skills sync`. See `references/agent-setup.md`.
+- A git repository with `fimo` as the remote, an initial commit, and an initial push
+
+Codex, OpenCode, Aider, and similar AGENTS.md-native tools work directly off AGENTS.md without a per-agent variant.
+
+`.env` is only the bootstrap app env so local `pnpm dev` works immediately. User-managed public variables are stored with `fimo vars set` and synced into a managed `.env.local` block; hidden values use `fimo secrets set`. See `references/project-vars-and-secrets.md`.
+
+## Right after scaffolding
+
+Set a human-readable display name with `fimo rename "<Name>"`. Infer it from what the user is building (e.g. "Acme Coffee" for a café site, "Jane Doe Portfolio" for a personal site). The default post-`fimo init` name is an auto-generated slug; renaming updates the dashboard label and the SEO `siteName`.
+
+```bash
+cd my-site
+fimo rename "Acme Coffee"
+```
+
+**Then start the local dev loop and ask the developer what they want to build.** Run the app with the project's package-manager `dev` script — `pnpm dev`, `npm run dev`, `yarn dev`, or `bun dev` (match the lockfile) — in the background; it serves the site on localhost with live reload. Edit, show, iterate. You do not need to deploy to see local changes.
+
+```bash
+pnpm dev &            # or npm run dev / yarn dev / bun dev — the project's package manager
+```
+
+When a unit of work looks done, **offer** to deploy (`fimo deploy` for a hosted preview / shareable link, `fimo deploy --publish` to go live) and run it only after the developer confirms.
+
+**Optional — warm the sandbox early:** only if you already know a deploy is coming, kick off a background `fimo deploy -m "chore: init" &` so the one-time ~15-30s sandbox provision + dep install happens while you work. This is a perf optimization, not a required step — skip it while you're just iterating locally. See `references/deploy.md` § Warm the sandbox early in a session.
+
+## Load the project context
+
+After `fimo init` completes, the project root has:
+
+- `AGENTS.md` (universal) plus the per-agent variant for the AI tool you're running in (e.g. `CLAUDE.md` for Claude Code, `.cursor/rules/fimo.mdc` for Cursor)
+- `.claude/skills/fimo/SKILL.md` (or the equivalent per-agent path) — the project-scope `fimo` skill, version-locked to the installed `fimo` package
+
+**These files came into existence mid-session, so they may not be auto-loaded by the harness.** Explicitly:
+
+1. `cd <project-dir>` — switch into the new project.
+2. `Read` the project rules file: `AGENTS.md` (or `CLAUDE.md` if you're Claude Code).
+3. `Read` the project skill: `.claude/skills/fimo/SKILL.md` (or `.cursor/skills/fimo/SKILL.md` for Cursor, etc.).
+4. From the project skill's "load these references up front" section, batch-read `references/content.md`, `references/forms.md`, `references/assets.md`, `references/labels.md`, `references/locales.md`, `references/ui.md` before generating any significant code.
+
+Once those are in context, generation respects the project's conventions (schemas, `t()`, `fimo/ui` components, asset handling).
+
+## Adding another AI tool to an existing project later
+
+If a teammate joins on a different AI tool (e.g. Cursor) after the project was scaffolded for claude-code only:
+
+```bash
+fimo skills install --agents=cursor       # one command — global skill + project skill + rule file
+```
+
+Run from inside the project. The command detects the project context and wires up everything for the new agent in a single shot. See `references/agent-setup.md`.
+
+## Multi-org accounts
+
+If you belong to a single organization, `fimo init` defaults to it. If you belong to multiple and don't pass `--org`, the CLI shows an interactive picker. For `fimo init`, pass the org **id** (from the `ID` column of `fimo orgs list`) — not the slug. Use `fimo orgs switch --org <id-or-slug>` to set a default for future `fimo init` invocations. See `references/account.md`.
+</content>

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

@@ -1,5 +1,7 @@
 # Firecrawl Integration
 
+> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
+
 Use Firecrawl when an agent needs to inspect public websites: landing-page research, competitor structure analysis, migration prep, link extraction, and factual page snapshots. Do not use Firecrawl for private URLs, logged-in websites, or content the user has not asked you to fetch.
 
 Current execution support is `search`, `scrape`, `map`, `crawl`, and `monitor.*`.

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

@@ -1,5 +1,7 @@
 # Integrations
 
+> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
+
 Use integrations to enable external services for a Fimo project. API keys are stored by Fimo and never printed back to the CLI. Teammates and agents receive access to the integration, not the underlying token.
 
 ## Inspect

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

@@ -1,5 +1,7 @@
 # Invite users
 
+> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
+
 Invite collaborators to your Fimo organization or project. After deploying a website for the first time, suggest inviting team members so they can contribute.
 
 ## When to suggest inviting users

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

@@ -1,5 +1,7 @@
 # Labels workflow
 
+> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
+
 > For the `t()` helper signature, `useLabels()` hook, key naming rules, and the "wrap every user-facing string" rule, see **`fimo/references/labels.md`**.
 > For locale configuration and route-prefix validation, see **`references/locales.md`**.
 

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

@@ -1,5 +1,7 @@
 # Locales Workflow
 
+> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
+
 This file covers CLI-side locale configuration and validation. For code helpers such as `fimoRoutes()` and `FimoLink`, load `fimo/references/locales.md`.
 
 ## Configure Locales

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

@@ -1,5 +1,7 @@
 # Media generation
 
+> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
+
 > 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.

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

@@ -1,5 +1,7 @@
 # Preview URL (without deploying)
 
+> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
+
 **Use `fimo preview url` whenever you need the current preview link — to open it, screenshot it, hand it to another tool, or verify a change you've already deployed. Never trigger a `fimo deploy` just to refresh a URL.**
 
 `fimo deploy` is a milestone command: it commits, pushes, syncs the sandbox, and only then prints the preview URL. `fimo preview url` skips all of that. It calls the API directly, gets a fresh 15-min token, and prints the URL. No commit, no push, no restart. Sub-second on a warm sandbox.

package/assets/skills/fimo-cli/references/project-vars-and-secrets.md

@@ -1,5 +1,7 @@
 # Project Variables And Secrets
 
+> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
+
 Use project variables for values that are safe to expose to the browser. Use project secrets for hidden values such as API keys, tokens, webhooks, and service credentials.
 
 There is no private-variable mode. If leaking the value would be a problem, use `fimo secrets`.
@@ -40,7 +42,7 @@ Secrets are not written to `.env.local`, preview app env files, browser bundles,
 
 ## Local Env Files
 
-`fimo create` writes `.env` for bootstrap app runtime values such as `VITE_API_URL`. This lets `pnpm dev` work without a Fimo wrapper.
+`fimo init` writes `.env` for bootstrap app runtime values such as `VITE_API_URL`. This lets `pnpm dev` work without a Fimo wrapper.
 
 `fimo vars set` and `fimo vars pull` write public project variables to a managed block in `.env.local`.
 

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

@@ -1,12 +1,14 @@
 # Managing projects
 
+> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
+
 Commands for listing projects across an org, cloning a remote project locally, and managing the lifecycle of a single project (delete, publish, unpublish, rename). Most lifecycle commands operate on the **current project** (read from `.fimo.settings.json` in the cwd) by default; for `delete`, `publish`, and `unpublish` you can pass an explicit `[projectId]` to target another. (`rename` is local-only — it never targets a different project; see below.)
 
 ## The `fimo projects` namespace
 
 ```bash
 fimo projects list [--org <id>]                 # list projects in an org (defaults to active org)
-fimo projects create [dir] [--org <id>] [--install|--no-install]   # alias of `fimo create`
+fimo projects create [dir] [--org <id>] [--install|--no-install]   # alias of `fimo init` (create-new path)
 fimo projects clone [projectId] [dir] [--env <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)
@@ -15,7 +17,7 @@ fimo projects rename <name> [projectId] [-C <dir>]   # local-only: set seo.siteN
 ```
 
 - **`list`** — projects you can see in the org. Live projects are marked.
-- **`create`** — identical to `fimo create`; see `references/create.md`.
+- **`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.settings.json`/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 `--env <name>` to clone a specific env. 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). This is **not** the versioned release path — for that, see `fimo publish` in `references/branches.md`.
@@ -39,7 +41,7 @@ fimo unpublish [-C <dir>]        # unpublish the current project
 fimo rename "<Site Name>"        # local edit: set seo.siteName in fimo-config.json
 ```
 
-`fimo rename` sets the **site name** (`seo.siteName`) in the local `fimo-config.json` — it is a local edit, not a remote update, so it requires a follow-up commit + `fimo deploy` to take effect. It does **not** change the project's remote display name (the `displayName` shown by `projects list`), which is set once at creation time from the project directory name. See `references/create.md` and `references/deploy.md`.
+`fimo rename` sets the **site name** (`seo.siteName`) in the local `fimo-config.json` — it is a local edit, not a remote update, so it requires a follow-up commit + `fimo deploy` to take effect. It does **not** change the project's remote display name (the `displayName` shown by `projects list`), which is set once at creation time from the project directory name. See `references/init.md` and `references/deploy.md`.
 
 ## Three "publish" verbs — don't confuse them
 

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

@@ -1,5 +1,7 @@
 # Scheduled Commands
 
+> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
+
 `fimo schedules` manages recurring commands for a project env. A schedule is scoped to the env of the current checkout by default, or to `--env <name>` when passed.
 
 ## Commands

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

@@ -17,6 +17,8 @@ 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.
+
 ## Non-Negotiables
 
 - No source data may disappear silently. Every route, CMS export, entry, media
@@ -28,6 +30,9 @@ 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.
 - 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
@@ -57,7 +62,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
@@ -94,6 +107,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, relations, and source value rules.
 - `references/media.md` - media inventory, upload, dedupe, and replacement rules.

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/wrap-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
@@ -76,7 +111,6 @@ than first-party CSV/XML/JSON exports.
   "importedCount": 0,
   "fields": {
     "title": { "type": "string", "source": "Name" },
-    "slug": { "type": "string", "source": "Slug" },
     "body": { "type": "richtext", "source": "Post Body" },
     "coverImage": { "type": "media", "source": "Main Image" },
     "publishedAt": { "type": "datetime", "source": "Published On" }
@@ -85,6 +119,11 @@ than first-party CSV/XML/JSON exports.
 }
 ```
 
+> **Do not put reserved names in `fields`.** `id`, `documentId`, `slug`, `locale`,
+> `createdAt`, `updatedAt`, and `__fimo` are built-in entry metadata — declaring them as
+> schema fields makes `fimo schemas push` fail with a 400. Map a source "Slug" column onto
+> the entry's built-in `slug` (inside `data`) at import time, not onto a schema field.
+
 ## Entry Batch Item
 
 ```json

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,22 @@ 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, 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.

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

@@ -0,0 +1,155 @@
+# Wrap Mode
+
+Wrap mode is the default migration for a **source-backed, working JS codebase**
+(Next.js, Vite/React, React Router; other frameworks via the same contract).
+The user's stack stays. Nothing is rebuilt. The migration is a mechanical
+wrapping pass that makes existing content editable from Fimo, plus a mandatory
+content-seeding pass so Fimo becomes the source of truth.
+
+**Never rewrite routing, styling, structure, or component logic.** The final
+diff must contain only: the one-time wiring, wrapper components, label calls,
+config files, and lockfile/dependency changes. If a change does not make
+content editable, it does not belong in a wrap migration.
+
+## When wrap does NOT apply
+
+- URL-only migrations (no code) → rebuild path (`fimo migrate <url>`).
+- Builder exports / static HTML dumps → rebuild path.
+- Codebases that do not build/run as-is → fix-first is the owner's call;
+  wrap assumes a working site.
+- Non-JS backends (PHP/WordPress/Drupal) → not supported yet.
+
+## Phases
+
+### W1. Adopt
+
+Connect the existing site to a Fimo project. From the site directory:
+
+```bash
+fimo init        # interactive: detects the framework, confirms the adopt
+fimo init . -y   # non-interactive (agents/CI): explicit dir = consent
+```
+
+Adoption creates the project, writes `fimo-config.json` (`framework` +
+scanned `routes` for the Studio page switcher), `.fimo.settings.json`, the
+framework env flavor (`NEXT_PUBLIC_FIMO_API_URL`,
+`NEXT_PUBLIC_FIMO_PREVIEW_SCRIPT_URL` for Next), wires the `fimo` git remote
+into the existing repo, and pushes the site as-is. No template is copied.
+
+Next.js: ensure `next.config` allowlists the preview origin, or the sandbox
+preview serves a black iframe with failing HMR websockets:
+
+```ts
+allowedDevOrigins: ['*.preview.fimo.ai'],
+```
+
+If the user's config sets CSP headers with `frame-ancestors`, the Fimo Studio
+origins must be permitted or the preview iframe will be blocked.
+
+### W2. Scan + automatic wiring
+
+```bash
+fimo migrate        # inside an adopted JS codebase this IS the wrap flow
+```
+
+(`fimo migrate wrap` is the explicit form; `fimo migrate <url>` remains the
+crawl-and-rebuild path for URL-only migrations.)
+
+Writes `.fimo/migration/wrap-plan.json` (every unwrapped item with
+`kind`/`file`/`line`/`preview`) and `.fimo/migration/wrap/agent-prompt.md`.
+The scan finds hardcoded JSX text, `img`/`Image`/`video` sources, file links
+(pdf/zip/docx/…), and user-visible attribute strings (`placeholder`, `title`,
+`aria-label`). Content already inside Fimo wrappers or `t()` calls counts as
+covered.
+
+The command also performs the deterministic wiring itself: it adds the `fimo`
+dependency (platform-pinned) and, for Next.js, inserts `allowedDevOrigins`
+into the next config when missing. Run the project's package manager install
+afterwards.
+
+### W3. Wire the layout (one-time)
+
+- Root layout (Next.js app router):
+
+```tsx
+import { FimoNextProviders, FimoNextScripts } from 'fimo/next';
+import { loadFimoConfig, loadFimoLabels } from 'fimo/next/server';
+
+const config = loadFimoConfig();
+const labels = await loadFimoLabels();
+// <head><FimoNextScripts /></head>
+// <body><FimoNextProviders config={config} labels={labels}>{children}</FimoNextProviders></body>
+```
+
+- React (framework-agnostic) uses `fimo/react`; React Router projects keep
+  `fimo/react-router`.
+
+RSC rule: the wrapper primitives are client components. Server components may
+render them directly as JSX children; do not call hooks like `useLabels()`
+outside client components (`'use client'`).
+
+### W4. Wrap
+
+Work through `wrap-plan.json` item by item:
+
+| Item kind                           | Wrap with                                                                              |
+| ----------------------------------- | -------------------------------------------------------------------------------------- |
+| text (plain)                        | `<FimoText id="…">original text</FimoText>`                                            |
+| text (formatted: strong/em/u/links) | `<FimoRichTextBlock id="…">…original markup…</FimoRichTextBlock>` — marks must survive |
+| attribute                           | `const { t } = useLabels()` then `placeholder={String(t('key', 'original value'))}`    |
+| image                               | `<FimoMediaImage id="…" src="/original.png" …/>`                                       |
+| video                               | `<FimoMediaVideo id="…" src="/original.mp4" …/>`                                       |
+| file-link                           | `<FimoFileLink id="…" href="/original.pdf">…</FimoFileLink>`                           |
+
+Rules:
+
+- The original value always stays inline as the fallback (child or prop). Wrap
+  fallbacks are deliberate: they keep the site rendering without Fimo
+  connectivity. This differs from Fimo-template projects, where inline
+  fallbacks are forbidden by lint — do not "fix" wrap fallbacks to match.
+- Key naming: `<route>.<section>.<n>` — `home.hero.title`,
+  `pricing.plans.starter.description`. Stable, human-readable, no indexes
+  unless the content is genuinely a list.
+- Repeated hardcoded arrays of 3+ structurally identical items (cards, tiles)
+  are still collections: model a schema + entries as in
+  `references/content.md`, render from `fetchEntries` (`fimo/next/server`).
+  Wrapping each array literal string individually is acceptable only as a
+  first pass and must be recorded as an unresolved modeling item.
+
+### W5. Seed (MANDATORY)
+
+Fallbacks are resilience, not storage. Every wrapped item is seeded into Fimo:
+
+- Labels: every `FimoText`/`t()` key with its original string via
+  `fimo labels set-many --file <json>`.
+- Media/files: `fimo assets upload <path>` per item, then a `WrappedMedia`
+  entry per wrapper id (`key` = wrapper id, `image` = the asset) via
+  `fimo schemas push` + `fimo entries create`.
+- Rich text: `WrappedRichText` entries (`key`, `body` = TipTap JSON converted
+  from the original markup; bold/italic/underline/link marks preserved).
+
+A wrap migration whose labels/entries were never created in Fimo is
+`draft-only`, exactly like a rebuild migration with un-imported seed JSON.
+
+### W6. Verify
+
+- `fimo migrate wrap --check` exits zero (or every remaining item is an
+  explicit ignored/unresolved ledger entry with a reason).
+- The site builds and runs **with its own toolchain** (`next build`,
+  `npm run dev`, …) — never assume Vite.
+- Rendered output is identical to pre-migration: same text, same formatting
+  marks, same media. Diff rendered pages, not just code.
+- Diff audit: the migration diff contains only wiring, wrappers, label calls,
+  config, and dependency changes.
+- Then `fimo deploy` (allowed in wrap mode: it pushes the preview env and
+  boots the sandbox preview — it does not publish). Verify in Fimo Studio that
+  the preview renders and Edit mode can select and edit wrapped content, and
+  that an edited label round-trips (`fimo labels set <key> "new"` → reload →
+  rendered). `fimo publish` / `fimo deploy --publish` remain owner-only.
+
+## Manifest
+
+Record wrap mode in the canonical ledger (`references/manifest.md`): set
+`mode: "wrap"` and fill the `wrap` block (framework, coverage counts, seeded
+counts, wiring status). Routes/media/forms sections apply as usual — wrap mode
+changes how content becomes editable, not the accounting obligations.

package/assets/skills/fimo-studio/references/visual-editing.md

@@ -12,7 +12,9 @@ For text elements, the side panel shows editable fields where you can change the
 
 ### Editing Styles
 
-The side panel organizes style controls into these categories:
+Style controls are only available on projects created before July 2026. Newer projects edit styles through the AI chat instead (for example: "make the hero title larger and dark blue"). If the user does not see the style controls described below, their project is a newer one -- point them to the chat.
+
+On projects that have them, the side panel organizes style controls into these categories:
 
 - **Typography** -- Font family, font size, font weight, line height, letter spacing, text alignment, and bold/italic/underline/strikethrough toggles.
 - **Color** -- Text and foreground colors.
@@ -31,5 +33,5 @@ Click the **Edit mode** toggle again or close the side panel. The side editor cl
 
 ## When to Use Edit Mode vs. Chat
 
-- **Edit mode** is best for quick visual tweaks -- changing a color, adjusting spacing, updating text, or trying a different font.
-- **Chat** is better for bigger changes -- adding new sections, restructuring a page layout, or building new functionality.
+- **Edit mode** is best for content changes -- updating text (including bold, italic, underline, and links), and replacing images. On older projects it also covers quick style tweaks like colors and spacing.
+- **Chat** is better for style and structural changes -- changing colors or spacing (on newer projects), adding new sections, restructuring a page layout, or building new functionality.

package/dist/build/vite/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/build/vite/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAU,YAAY,EAAE,MAAM,MAAM,CAAC;AAyEjD,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;;;;;;;;OAUG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAGD,wBAAgB,IAAI,CAAC,IAAI,GAAE,eAAoB,GAAG,YAAY,EAAE,CAsB/D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/build/vite/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAU,YAAY,EAAE,MAAM,MAAM,CAAC;AA2EjD,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;;;;;;;;OAUG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAGD,wBAAgB,IAAI,CAAC,IAAI,GAAE,eAAoB,GAAG,YAAY,EAAE,CAsB/D"}

package/dist/build/vite/index.js

@@ -35,15 +35,17 @@ function bundleFimoIntoSsrPlugin() {
             ssr: { noExternal: ['fimo'] },
             optimizeDeps: {
                 include: ['fimo/ui'],
-                esbuildOptions: {
+                rolldownOptions: {
                     plugins: [
                         {
                             name: 'fimo-externalize-virtuals',
-                            setup(build) {
-                                build.onResolve({ filter: /^virtual:/ }, (args) => ({
-                                    path: args.path,
-                                    external: true,
-                                }));
+                            resolveId(id) {
+                                if (id.startsWith('virtual:')) {
+                                    return {
+                                        id,
+                                        external: true,
+                                    };
+                                }
                             },
                         },
                     ],

package/dist/build/vite/plugins/translations.d.ts

@@ -1,11 +1,5 @@
 import type { Plugin } from 'vite';
-interface LabelBundle {
-    dictionaries: Record<string, Record<string, string>>;
-    defaultLocale: string;
-    locales: string[];
-    updatedAt: string | null;
-}
+import { loadLabelBundle } from '../../../runtime/shared/labels-fetch.server.js';
 export default function translationsPlugin(): Plugin;
-export declare function loadLabelBundle(rootDir: string): Promise<LabelBundle>;
-export {};
+export { loadLabelBundle };
 //# sourceMappingURL=translations.d.ts.map