fimo 0.12.0-staging.2 → 0.12.0-staging.4

package/assets/content-templates/types-template.eta

@@ -225,15 +225,21 @@ function isOptionalOutputField(field) {
 function isConditionalField(field) {
   return field.showIf !== undefined || field.showIfAny !== undefined;
 }
+
+const populatedReferenceFields = Object.entries(model.fields || {}).filter(([, field]) => {
+  if (field.type !== 'reference') {
+    return false;
+  }
+  return (Array.isArray(field.targetRefs) && field.targetRefs.length > 0) || typeof field.targetPascal === 'string';
+});
 -%>
 
+<% if (populatedReferenceFields.length === 0) { -%>
+export type <%= model.pascal %>References = Record<never, never>;
+<% } else { -%>
 export interface <%= model.pascal %>References {
 <%
-if (model.fields) {
-  Object.entries(model.fields).forEach(([key, field]) => {
-    if (field.type !== 'reference') {
-      return;
-    }
+populatedReferenceFields.forEach(([key, field]) => {
     // Polymorphic populated values form a discriminated union on $type —
     // the generated wrapper stamps it, so `switch (item.$type)` narrows.
     if (Array.isArray(field.targetRefs) && field.targetRefs.length > 0) {
@@ -252,10 +258,10 @@ if (model.fields) {
 -%>
   <%= key %>: <%= type %>;
 <%
-  });
-}
+});
 -%>
 }
+<% } -%>
 
 export type <%= model.pascal %>Populate = Populate<<%= model.pascal %>>;
 

package/assets/skills/fimo/SKILL.md

@@ -2,15 +2,15 @@
 name: fimo
 description: >-
   Working in or with a Fimo project (a content + media + forms + analytics
-  platform for React websites). Load the real, version-locked Fimo skills on
-  demand through the `fimo` CLI before doing Fimo work — writing schema-driven
+  platform for web applications). Load the current Fimo skills on demand through
+  the `fimo` CLI before doing Fimo work — writing schema-driven
   code, running CLI/deploy workflows, using the dashboard, or migrating a site.
 ---
 
 # Fimo
 
-Fimo ships its skills through its CLI so they always match the installed `fimo` version. This file is
-just a pointer — do not rely on cached instructions. Fetch the real skill from the CLI when you need it.
+Fimo ships its skills through its CLI. `fimo-code` resolves from the project's installed `fimo` package;
+workflow skills resolve from the CLI you run. This file is only a pointer — fetch the real skill when needed.
 
 When you are about to do Fimo work:
 
@@ -23,9 +23,11 @@ not files in the project. Load them through the CLI, for example
 
 Pick by task:
 
-- Writing code — schema-driven JSX, schemas/forms JSON, `t()` labels, `fimo/ui` media → `fimo-code`
+- Writing code — schemas/forms, generated clients, labels, framework adapters, rendering primitives → `fimo-code`
 - CLI commands and workflows — push, deploy, sync, labels, domains, analytics → `fimo-cli`
-- Project MCP setup — configure `fimo mcp` for a local AI client → `fimo-cli` (`references/mcp.md`)
+- Fimo agents — create, configure, validate, deploy, run, or inspect them → `fimo-cli` (`references/agents.md`)
+- AI agent setup — connect Claude Code, Codex, Cursor, or another agent → `fimo-cli` (`references/agent-setup.md`)
+- Project MCP setup — configure `fimo mcp` for a local agent → `fimo-cli` (`references/mcp.md`)
 - The Fimo Studio dashboard / web app UI → `fimo-studio`
 - Migrating an existing site into Fimo → `fimo-migration`
 

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

@@ -1,23 +1,15 @@
 ---
 name: fimo-cli
 description: >-
-  The `fimo` CLI scaffolds and manages Fimo projects from the command line.
-  Load when the user wants to create a new Fimo project, build content
-  (schemas, entries, forms, media, labels/locales), deploy a site, manage
-  custom domains, configure outbound webhooks and event-driven integrations,
-  check site traffic/analytics, inspect or restore project history, invite collaborators, inspect AI credits,
-  connect an AI coding client to a Fimo project through MCP,
-  report a failing or slow Fimo API, rejected documented argument,
-  undocumented workaround, missing capability that blocks work, forces a
-  fragile or heavily manual workaround, or would materially accelerate a
-  recurring workflow, or other Fimo platform problem to support, log in or
-  switch organizations, or set up Fimo for their AI tool. Most "do X with
-  Fimo" tasks go through this skill.
+  Use the `fimo` CLI to create or operate a Fimo project: content, forms,
+  media, labels/locales, deploys, environments, domains, analytics,
+  integrations, Fimo agents, collaboration, accounts, and credits. Also use
+  for AI agent or MCP setup and confirmed Fimo platform blockers.
 ---
 
 # Fimo CLI
 
-The `fimo` CLI is the workflow surface for Fimo. Fimo is a content + media + forms + analytics platform for React websites with a CMS dashboard. The CLI handles project creation, all content / forms / media / labels / locale workflows, deploys, collaboration, account management, AI credit inspection, and AI agent setup.
+The `fimo` CLI is the workflow surface for Fimo. Fimo connects content, media, forms, analytics, editing, and hosting to web applications. The CLI handles project creation, content / forms / media / labels / locale workflows, deploys, collaboration, account management, Fimo agents, AI credit inspection, and AI agent setup.
 
 This skill describes **what the CLI does and the workflows it drives**. For the package surface used IN code (component props, generated hooks, JSON shapes, code-side rules), load the `fimo-code` skill on demand with `npx fimo@latest skills get fimo-code`.
 
@@ -81,13 +73,13 @@ The working loop is local: run the app with the project's package-manager `dev`
 Load the matching reference when the user's request fires its trigger. Recipes that involve writing code also need the `fimo-code` skill's package references — they're called out where relevant.
 
 - "Create a new Fimo project / scaffold a site / start a new website / add the opt-in content starter / link an existing project locally" → `references/init.md`
-- "Add a content type / blog / products / pages / CMS" → `references/content.md` (workflow) **+ load `fimo-code/references/content.md` for the JSON shape and React hooks**
-- "Add a contact / signup / feedback / newsletter form" → `references/forms.md` (workflow) **+ load `fimo-code/references/forms.md` for the JSON spec and generated client**
+- "Add a content type / blog / products / pages / CMS" → `references/content.md` (workflow) **+ run `npx fimo@latest skills get fimo-code --ref content/schema` and load the detected framework reference**
+- "Add a contact / signup / feedback / newsletter form" → `references/forms.md` (workflow) **+ run `npx fimo@latest skills get fimo-code --ref forms` for the JSON spec and generated client**
 - "View form submissions / who filled out the contact form / inspect what users sent / how many signups" → `references/forms.md` § Reading submissions
-- "Upload an image / hero / cover / existing media file" → `references/assets.md` (workflow: upload, browse, open, delete) **+ load `fimo-code/references/assets.md` for the `FimoMedia` shape and rendering**
-- "Generate AI image / video / draft preview / image edit / cover from a prompt" → `references/media.md` (task commands, quality, recipes, and verification) **+ load `fimo-code/references/assets.md` for the `FimoMedia` shape if you'll plug the result into UI**
-- "Add labels / update static copy / fix missing `t()` values" → `references/labels.md` (workflow) **+ load `fimo-code/references/labels.md` for the `t()` helper and wrap rules**
-- "Enable locales / configure default locale / route by locale prefix / fix locale route validation" → `references/locales.md` **+ load `fimo-code/references/locales.md` for code helpers**
+- "Upload an image / hero / cover / existing media file" → `references/assets.md` (workflow: upload, browse, open, delete) **+ run `npx fimo@latest skills get fimo-code --ref assets` for the `FimoMedia` shape and rendering**
+- "Generate AI image / video / draft preview / image edit / cover from a prompt" → `references/media.md` (task commands, quality, recipes, and verification) **+ run `npx fimo@latest skills get fimo-code --ref assets` for the `FimoMedia` shape if you'll plug the result into UI**
+- "Add labels / update static copy / fix missing `t()` values" → `references/labels.md` (workflow) **+ run `npx fimo@latest skills get fimo-code --ref labels` and load the detected framework reference**
+- "Enable locales / configure default locale / integrate an existing locale system" → `references/locales.md` **+ run `npx fimo@latest skills get fimo-code --ref locales` and load the detected framework locale reference**
 - "What's in this project / show the project structure / describe the project / what schemas does it have / how many routes / project tree / show me what's here" → `references/describe.md`
 - "Deploy / publish / go live / push my changes" → `references/deploy.md`
 - "Get the preview URL / open the preview / what's the URL for this env / refresh the preview link / I just want to see the site / the preview URL stopped working" → `references/preview.md`
@@ -107,9 +99,9 @@ Load the matching reference when the user's request fires its trigger. Recipes t
 - "Invite a collaborator / add Marc / share with client" → `references/invite.md`
 - "Login / log out / who am I / switch organization" → `references/account.md` — note: switching **org** is `fimo orgs switch`; bare `fimo switch` switches **env** (see `references/branches.md`)
 - "Create / scaffold / run / validate an agent / agent bundle / wire or enable its triggers / list agent templates / view agent runs, reports, or logs (`fimo agents *`)" → `references/agents.md`
-- "Install Fimo for my AI tool / fimo skills install / set up Claude Code or Cursor for Fimo / add an agent to this project" → `references/agent-setup.md`
-- "Connect an AI coding client to a Fimo project through MCP / configure `fimo mcp` / expose Fimo tools to a local MCP client" → `references/mcp.md`
-- "Refresh / update installed Fimo skills / fimo skills sync / agent missing the latest fimo conventions" → `references/agent-setup.md`
+- "Install Fimo for my agent / fimo skills install / set up Claude Code, Codex, or Cursor for Fimo" → `references/agent-setup.md`
+- "Connect an agent to a Fimo project through MCP / configure `fimo mcp` / expose Fimo tools to a local MCP client" → `references/mcp.md`
+- "Refresh / update installed Fimo skills / fimo skills sync / agent missing the latest Fimo conventions" → `references/agent-setup.md`
 - "Report a Fimo problem or blocking feature request / contact Fimo support / a Fimo API or command keeps failing / a documented argument is rejected / a supported operation needs an undocumented workaround / a Fimo API is abnormally slow / a confirmed missing capability blocks completion or forces a fragile or heavily manual workaround" → `references/support.md`
 - "Regenerate rule files / I edited AGENTS.md / fimo rules sync" → `references/agent-setup.md`
 - "Show analytics / visitor stats / traffic / pageviews / how is my site performing / top pages / where do visitors come from" → `references/analytics.md` (7-day preview free for all; longer ranges require paid)
@@ -119,7 +111,7 @@ Load the matching reference when the user's request fires its trigger. Recipes t
 
 These fire at specific moments in the project lifecycle. **Surface them proactively** rather than waiting for the user to ask:
 
-- **Right after `fimo init`** → `cd` into the new directory, then `Read` the project's `AGENTS.md` (or `CLAUDE.md` for Claude Code) to load the project context, and run `npx fimo@latest skills get fimo-code` to load the code skill before generating any code. The `AGENTS.md`/`CLAUDE.md` came into existence mid-session and may not be auto-loaded by the harness. See `references/init.md` § Load the project context.
+- **Right after `fimo init`** → `cd` into the new directory, read the project's `AGENTS.md` (or `CLAUDE.md` for Claude Code), run `fimo describe --json`, then load `fimo-code` and only the task/framework references it routes to. The rules file came into existence mid-session and may not be auto-loaded by the harness. See `references/init.md` § Load the project context.
 - **Right after `fimo init`** → suggest `fimo rename "<Display Name>"` to set a human-readable name (the default post-init name is an auto-generated slug). Infer the name from what the user is building (e.g. "Acme Coffee" for a café, "Jane Doe Portfolio" for a personal site). See `references/init.md`.
 - **Right after `fimo init`** → start the app locally with the project's package-manager `dev` script (`pnpm dev` / `npm run dev` / `yarn dev` / `bun dev`) in the background, then ask the developer what they want to build. This localhost server with live reload is your iteration loop — edit, show, repeat. No deploy is needed to see local changes.
 - **When a user-visible 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 — or immediately if they ask. Never deploy on your own. See `references/deploy.md`.

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

@@ -2,16 +2,16 @@
 
 > **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
 
-Fimo wires up to AI coding tools in two layers:
+Fimo connects agents in two layers:
 
-1. **One global bootstrap skill** — a tiny, generic `fimo` skill installed once per user, machine-wide (symlinked into each agent's global skills dir). It doesn't contain workflow content itself; it tells the agent to load the real, version-locked skills on demand from the CLI. It never goes stale because it just points at `fimo skills get`.
-2. **Per-project rule files** — `AGENTS.md` (universal) and `CLAUDE.md` ship in the project template. `fimo rules sync` regenerates the other agents' variants (`.cursor/rules/fimo.mdc`, `.windsurfrules`, `GEMINI.md`) from `AGENTS.md`.
+1. **One global bootstrap skill** — a tiny, generic `fimo` skill installed once per user, machine-wide (symlinked into each agent's global skills directory). It contains no workflow content; it routes the agent to skills fetched through `fimo skills get`.
+2. **Per-project rule files** — `AGENTS.md` (universal) and `CLAUDE.md` ship in the project template. `fimo rules sync` generates other agents' variants (`.cursor/rules/fimo.mdc`, `.windsurfrules`, `GEMINI.md`) from `AGENTS.md`.
 
-The rich skills (`fimo-code`, `fimo-cli`, `fimo-studio`, `fimo-migration`) are **never installed as files**. They're served on demand straight from the CLI, so they always match the installed version and never land in the project:
+The rich skills (`fimo-code`, `fimo-cli`, `fimo-studio`, `fimo-migration`) are **never installed as files**. They are served on demand and never land in the project. `fimo-code` resolves from the project's installed package; the others resolve from the CLI being run:
 
 ```bash
 npx fimo@latest skills list            # what's available
-npx fimo@latest skills get fimo-code   # writing code: schemas, forms, labels, fimo/ui
+npx fimo@latest skills get fimo-code   # writing code: schemas, generated clients, labels, framework adapters
 npx fimo@latest skills get fimo-cli    # CLI + workflows (this skill)
 npx fimo@latest skills get fimo-cli --ref deploy   # a reference doc
 ```
@@ -40,15 +40,15 @@ fimo skills sync                               # re-ensure the bootstrap + clean
 fimo skills uninstall                          # remove the global bootstrap
 ```
 
-`fimo skills install` installs the single global `fimo` bootstrap skill for the selected agents (symlinked into each agent's global skills dir; it transparently falls back to a copy when a symlink can't be created, e.g. under `npx`). It writes **nothing** into your project — the working tree stays clean.
+`fimo skills install` installs the single global `fimo` bootstrap skill for the selected agents (symlinked into each agent's global skills directory; it transparently falls back to a copy when a symlink can't be created, e.g. under `npx`). It writes **nothing** into your project — the working tree stays clean.
 
-Once installed, the agent discovers everything else through the bootstrap: it runs `fimo skills get <name>` to load the real skill for the task at hand.
+Once installed, the agent discovers everything else through the bootstrap: it runs `fimo skills get <name>` to load the skill for the task at hand.
 
-**`fimo skills sync`** re-ensures the global bootstrap for whichever agents already have it, and cleans up stale global skills that older CLI versions used to copy in (`fimo-cli`, `fimo-studio`, `fimo-migration`, and legacy migration skills). You rarely need it: the bootstrap is a symlink, so it always tracks the running CLI, and the real skills are fetched fresh via `fimo skills get`. Run it after upgrading from an old CLI to clear leftovers.
+**`fimo skills sync`** re-ensures the global bootstrap for whichever agents already have it, and cleans up stale global skills that older CLI versions used to copy in (`fimo-cli`, `fimo-studio`, `fimo-migration`, and legacy migration skills). You rarely need it: the bootstrap is a symlink, so it tracks the running CLI, and the real skills are fetched fresh via `fimo skills get`. Run it after upgrading from an old CLI to clear leftovers.
 
 **`fimo skills uninstall`** removes the global bootstrap for the selected agents.
 
-## `fimo rules sync` — rule files only
+## `fimo rules sync` — agent rule files only
 
 `fimo init` scaffolds `AGENTS.md` (the universal-spec file) and `CLAUDE.md` from the template. Other agents' variants are generated on demand:
 
@@ -60,7 +60,7 @@ Once installed, the agent discovers everything else through the bootstrap: it ru
 | gemini-cli                        | `GEMINI.md`                           |
 | codex / opencode / aider / others | none — they read `AGENTS.md` natively |
 
-`fimo rules sync` regenerates these variants from the current `AGENTS.md`. Use it when:
+`fimo rules sync` generates these variants from the current `AGENTS.md`. Use it when:
 
 - You edited `AGENTS.md` and want variants refreshed (delete the variant first — see below).
 - You added an agent that needs its own rule file generated.
@@ -81,15 +81,15 @@ Every command that takes agents accepts the same selection inputs:
 - `--agents=claude-code,cursor` — comma-separated list (headless)
 - `-a claude-code -a cursor` — repeatable short form
 - No flag → interactive multi-select. The picker has two sections:
-  - **Universal** — agents that read `AGENTS.md` natively (codex, opencode, aider, …). Always covered, not toggleable.
+  - **Universal** — agents that read `AGENTS.md` natively (Codex, OpenCode, Aider, …). Always covered, not toggleable.
   - **Additional** — agents that get the global bootstrap skill installed. The 6 popular ones (`claude-code`, `cursor`, `codex`, `opencode`, `windsurf`, `gemini-cli`) appear at the top of an 8-item scrollable viewport; the full list of 50+ supported agents is below the fold. Agents already set up on the machine are pre-checked.
 - `--agents=none` (only `fimo init`) — skip the global skill entirely.
 
-In headless contexts (CI, AI-tool-spawned commands), pass the flag explicitly. Env-var detection (only Claude Code's `CLAUDECODE` / `CLAUDE_CODE_ENTRYPOINT`) silently targets `claude-code` if the flag is omitted; every other agent must be named explicitly with `--agents` in a headless shell, or the command exits with "No agents detected and no --agents flag passed."
+In headless contexts (CI, agent-spawned commands), pass the flag explicitly. Env-var detection (only Claude Code's `CLAUDECODE` / `CLAUDE_CODE_ENTRYPOINT`) silently targets `claude-code` if the flag is omitted; every other agent must be named explicitly with `--agents` in a headless shell, or the command exits with "No agents detected and no --agents flag passed."
 
 ## Always current, never stale
 
-Because the only installed artifact is a generic pointer, and the real skills are fetched with `fimo skills get`, the content an agent reads always matches the running CLI. There's no version stamp to check and no cached copy to refresh — re-run `fimo skills get <name>` any time to get the current instructions.
+Because the only installed artifact is a generic pointer, the agent fetches current instructions with `fimo skills get`. `fimo-code` resolves from the project's installed package; the workflow skills resolve from the CLI being run. Re-run `fimo skills get <name>` any time to refresh them.
 
 ## When to use which
 
@@ -98,4 +98,4 @@ Because the only installed artifact is a generic pointer, and the real skills ar
 - "Clean up skills left by an old CLI version" → `fimo skills sync`
 - "I edited `AGENTS.md` and want variants regenerated" → delete the stale variant + `fimo rules sync`
 - "I'm done with Fimo on this machine" → `fimo skills uninstall`
-- For a fresh project, `fimo init` installs the global skill for the AI tools you select at scaffold time.
+- For a fresh project, `fimo init` installs the global skill for the agents you select at scaffold time.

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

@@ -2,7 +2,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`**.
+> Package contract: run `npx fimo@latest skills get fimo-code --ref assets` for `FimoMedia`, `--ref ui` for rendering primitives, and load the detected framework reference for framework-specific integration.
 > For **generating** new images / videos with AI, see **`references/media.md`** for the task commands and recipes.
 
 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.
@@ -129,4 +129,4 @@ fimo assets delete <asset-id>
 
 1. Upload with `fimo assets upload` or generate with a task command such as `fimo image generate`.
 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}>`.
+3. To use in application code, run `npx fimo@latest skills get fimo-code --ref ui` and load the detected framework reference: schema media → `<Image>` / `<Video>`, deliberate non-schema URLs → `<StaticImage>`. Never use raw `<img src={asset.url}>` for tracked media.

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

@@ -2,19 +2,19 @@
 
 > **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
 
-> For the JSON shape, field types, Tiptap node spec, slug rules, and generated React Query hooks — these are package surface (version-locked to the project's `fimo`). See **`fimo/references/content.md`**.
+> Package contract: load the version-locked `fimo-code` skill with `npx fimo@latest skills get fimo-code`, then fetch its nested content and detected-framework references for schema JSON, entry values, generated clients, and imports.
 
 This file covers the **CLI workflow** for content. Use it when the user wants to add a content type (blog, products, pages) or manage Singles and entries.
 
 ## Flow
 
-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.
+1. Write `src/schemas/{Uid}.json` — PascalCase filename (e.g. `BlogPost.json`). Run `npx fimo@latest skills get fimo-code --ref content/schema` for the JSON contract.
+2. Run `fimo schemas push {Uid}`. It registers the schema and generates the framework-specific public modules. It does not run whole-project validation.
+3. App code imports generated public modules, never `.types.ts` directly. Load the detected framework reference before choosing server modules, client modules, hooks, or a registry.
 4. Seed collections via `fimo entries create`, or update one-off content via `fimo singles update`. Generate cover images first with `fimo image generate` if needed (see `media.md` / `assets.md`).
-5. Write React pages that import from `@/schemas/{Uid}` and render with `fimo/ui` components.
+5. Render tracked fields with the detected framework's Fimo primitives.
 
-Steps 1, 3, and 5 reference the `fimo-code` skill (`npx fimo@latest skills get fimo-code`) for shape and React API. Steps 2 and 4 are CLI commands documented here.
+Steps 1, 3, and 5 use `fimo-code`; steps 2 and 4 are CLI workflows documented here.
 
 ## Schema CLI commands
 
@@ -34,9 +34,9 @@ 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.
 
-Blocks schemas support at most 7 nested `blocks` levels, 40 variants in one `schema.oneOf`, and `min` or `max` values up to 200 items per blocks field. Load `fimo/references/content.md` for the complete blocks JSON shape.
+Blocks schemas support at most 7 nested `blocks` levels, 40 variants in one `schema.oneOf`, and `min` or `max` values up to 200 items per blocks field. Run `npx fimo@latest skills get fimo-code --ref content/schema` for the complete blocks JSON shape.
 
-Schema transitions are automatic. Adding optional fields and changing labels preserve content. A new required field backfills its `default` only where existing values need it; the push fails safely when no default can satisfy existing content. Removing a nested field or block variant removes only those values. `string` and `text` preserve values in both directions. Other primitive changes convert safe values and reject unsafe ones without changing the schema or entries. Lowering block `max` trims from the end; raising `min` fills from the blocks `default` templates. A reference target change clears its connections. Use repeatable `--rename old.path=new.path` arguments when a field moved by name so the one-time migration preserves its values; the operation is not stored in schema JSON. Collection-to-Single removes that type's entries and cleans inbound references; Single-to-collection preserves its entry. Run `fimo validate` after pushing.
+Schema transitions are automatic. Adding optional fields and changing labels preserve content. A new required field backfills its `default` only where existing values need it; the push fails safely when no default can satisfy existing content. Removing a nested field or block variant removes only those values. `string` and `text` preserve values in both directions. Other primitive changes convert safe values and reject unsafe ones without changing the schema or entries. Lowering block `max` trims from the end; raising `min` fills from the blocks `default` templates. A reference target change clears its connections. Use repeatable `--rename old.path=new.path` arguments when a field moved by name so the one-time migration preserves its values; the operation is not stored in schema JSON. Collection-to-Single removes that type's entries and cleans inbound references; Single-to-collection preserves its entry.
 
 ## Singles CLI commands
 
@@ -76,7 +76,7 @@ fimo entries bulk-update <TypeName> (--file <path> | --stdin)
 fimo entries bulk-delete <TypeName> (--ids <id1>,<id2> | --where '<json>') [--locale es]
 ```
 
-`--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.**
+`--body` is a **required** option on `create` and `update`. Run `npx fimo@latest skills get fimo-code --ref content/richtext` before constructing an entry payload: slug belongs inside `data`, media has a specific shape, and richtext must be Tiptap JSONContent.
 
 `entries list` accepts the same read query surface as generated hooks:
 
@@ -100,7 +100,7 @@ Reference filters take the target `id` string (`{"author":"750e..."}`). On a to-
 
 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.
 
-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.
+In generated application code, the equivalent is `populate: ['author', 'contributors'] as const` in query params. Let the generated client infer the result when possible; if a named TypeScript shape is needed, use `BlogPostResult<TFields, TPopulate>` as documented by `npx fimo@latest skills get fimo-code --ref content/clients`. Writes use `BlogPostInput`.
 
 ### Read-only SQL
 
@@ -191,7 +191,7 @@ fimo entries bulk-delete BlogPost --where '{"archived":true}'
 
 Each bulk request handles at most 1,000 entries. Missing requested IDs do not fail valid work: the CLI prints a warning, and `--json` includes both a top-level `warnings` array and the exact IDs in `data.meta.missing`. Bulk writes use the same validation, locale, reference, and content-change paths as singular entry writes. They apply entries one at a time. Recoverable create and update errors report how many earlier entries were already changed.
 
-For reference schema JSON and entry value shape, load `fimo/references/content.md` § Reference fields. The short version:
+For reference schema JSON and entry value shape, run `npx fimo@latest skills get fimo-code --ref content/schema`. The short version:
 
 ```json
 {
@@ -253,32 +253,18 @@ Rules:
 
 Turning an existing field shared is destructive when the languages currently hold different values. The push collapses each document to its default-locale value and discards the others; there is no prompt and no undo. Most documents already agree, so most collapses change nothing — but tell the user what will happen before adding `"i18n": false` to a field that already holds content, and check whether the languages differ if you are unsure.
 
-Use `"isSingleton": true` for a Single with exactly one set of content. Generated Single clients expose `get`/`update` and their React Query hooks, not collection create/remove APIs.
+Use `"isSingleton": true` for a Single with exactly one set of content. Generated Single clients expose `get`/`update` and client hooks where the framework supports them, not collection create/remove APIs.
 
 ## "Add a blog" recipe
 
-1. Load `fimo/references/content.md` for the JSON shape and field types.
+1. Run `npx fimo@latest skills get fimo-code --ref content/schema` 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.
 3. Run `fimo schemas push BlogPost`.
 4. Generate cover images: `fimo image generate --prompt "..." --aspect-ratio 16:9` (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()`.
-8. Write the React page using the generated `useGet()` hook from `@/schemas/BlogPost`.
-
-## When to run sync manually
-
-`fimo schemas push`, `fimo validate`, and the `fimo/vite` development watcher all reuse the same schema generator. Production builds do not rewrite generated source files. `schemas push` does not run route, label, agent, form, or project-wide checks. For a full local validation and codegen pass without updating the remote schema, use:
-
-```bash
-fimo validate                  # runs all phases: codegen, lint, route validation, label checks
-```
-
-Advanced/internal (hidden from `fimo --help`) — for the bare regen phase:
-
-```bash
-fimo scripts sync-schemas      # regenerate src/schemas/*.types.ts and src/schemas/*.ts
-```
+6. Run `npx fimo@latest skills get fimo-code --ref ui` and load the detected framework reference for rendering primitives.
+7. Run `npx fimo@latest skills get fimo-code --ref labels` and load the detected framework reference for labels.
+8. Load the detected framework reference, then build the page with its generated server or client surface.
 
 ## Non-interactive use
 

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

@@ -77,5 +77,5 @@ The scoped view still emits the project-level metadata header (name, framework,
 ## Notes for AI tools
 
 - The JSON shape is stable; parse it rather than scraping the human output when you need a specific field.
-- The `framework` field is detected from `package.json#dependencies` (v1 detector). For multi-framework projects or unusual setups, the field may be `null` — fall back to reading `package.json` yourself.
+- The `framework` field uses Fimo's shared Vercel filesystem detector, which considers package dependencies, configuration files, and framework-specific file layout. For unusual or deliberately mixed projects it may be `null`; inspect `package.json` and the application tree before choosing a framework reference.
 - The command runs in any directory that contains `.fimo/project.json` or one of its ancestors. If you're not in a Fimo project, `describe` will run against whatever directory you point it at (it doesn't require Fimo credentials).

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

@@ -2,16 +2,16 @@
 
 > **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
 
-> For the JSON spec, generated Zod schema, submit helper signature, and React usage patterns — these are package surface (version-locked to the project's `fimo`). See **`fimo/references/forms.md`**.
+> Package contract: run `npx fimo@latest skills get fimo-code --ref forms` for the JSON spec, generated Zod schema, submit helper, and application usage.
 
 This file covers the **CLI workflow** for forms. Use it when the user wants to add a contact form, signup, feedback form, etc.
 
 ## Flow
 
-1. Write `src/forms/{name}.json` — kebab-case filename (e.g. `contact-us.json`). For the JSON spec and field types, load `fimo/references/forms.md`.
+1. Write `src/forms/{name}.json` — kebab-case filename (e.g. `contact-us.json`). For the JSON spec and field types, run `npx fimo@latest skills get fimo-code --ref forms`.
 2. Register with `fimo forms push {name}` — creates the form, obtains its `id`, patches it back into the JSON file.
-3. Pre-build generates `src/forms/{name}.ts` (Zod schema + `submitX` helper). See `fimo/references/forms.md` for the generated API.
-4. Write a React component that imports from `@/forms/{name}`.
+3. Pre-build generates `src/forms/{name}.ts` (Zod schema + `submitX` helper). Use the same `fimo-code` reference for the generated API.
+4. Write the application form using the generated `@/forms/{name}` module and the existing framework conventions.
 
 Steps 1, 3, and 4 reference the `fimo-code` skill (`npx fimo@latest skills get fimo-code`). Step 2 is the CLI command.
 
@@ -45,12 +45,12 @@ Use this when the user asks "who filled out the contact form?", "how many signup
 
 ## "Add a contact form" recipe
 
-1. Load `fimo/references/forms.md` for the JSON spec.
+1. Run `npx fimo@latest skills get fimo-code --ref forms` for the JSON spec.
 2. Write `src/forms/contact-us.json` with the required fields.
 3. Run `fimo forms push contact-us` — the `id` is patched back into the JSON automatically.
-4. Load `fimo/references/forms.md` for the generated `submitContactUs` + `ContactUsSchema` API.
-5. Load `fimo/references/labels.md` for wrapping form labels in `t()`.
-6. Write the React form component that imports from `@/forms/contact-us`.
+4. Use the same `fimo-code` forms reference for the generated `submitContactUs` + `ContactUsSchema` API.
+5. Run `npx fimo@latest skills get fimo-code --ref labels` and load the detected framework reference for form labels.
+6. Write the application form using the generated `@/forms/contact-us` module.
 
 **Register BEFORE writing app code that depends on the form** — otherwise the generated `.ts` doesn't exist and the runtime fetch 404s.
 

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

@@ -74,7 +74,7 @@ Pass `--project-id <id>` to link an EXISTING project instead of creating one. Th
 - `.fimo/project.json` — links this directory to the remote project (read-only after creation)
 - `.fimo/config.json` — project, route, locale, SEO, and agent policy
 - `.fimo/agents/` — versioned agent bundles
-- `.env` — initial env vars (currently just `VITE_API_URL`)
+- `.env` — tenant content API URLs for Vite and Next runtimes
 - `AGENTS.md` + `CLAUDE.md` — project rules (from the template) read by AGENTS.md-compatible tools and Claude Code. Both point the agent at `fimo skills get` to load the real skills on demand.
 - A git repository with `fimo` as the remote, and — after dependencies install — an initial commit (including the lockfile) plus an initial push
 
@@ -119,10 +119,11 @@ After `fimo init` completes, the project root has `AGENTS.md` (universal) and `C
 
 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. Load the code skill on demand: `npx fimo@latest skills get fimo-code`.
-4. From the `fimo-code` skill's "load these references up front" section, batch-read the referenced docs (`npx fimo@latest skills get fimo-code --ref content`, `--ref forms`, `--ref assets`, `--ref labels`, `--ref locales`, `--ref ui`) before generating any significant code.
+3. Run `npx fimo@latest describe --json` and read the detected framework, schemas, locales, and tree.
+4. Load the code skill on demand: `npx fimo@latest skills get fimo-code`.
+5. Follow its decision tree and load only the task reference plus the detected framework reference. For Next.js, start with `npx fimo@latest skills get fimo-code --ref frameworks/next`, then load App Router, Pages Router, or locales only when the project shape requires it.
 
-Once those are in context, generation respects the project's conventions (schemas, `t()`, `fimo/ui` components, asset handling).
+Do not batch-load every reference. Progressive disclosure keeps unrelated framework and product guidance out of the coding context.
 
 ## Adding another AI tool to an existing project later
 

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

@@ -2,14 +2,14 @@
 
 > **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`**.
+> Package contract: run `npx fimo@latest skills get fimo-code --ref labels` for the `t()` contract and key rules, then load the detected framework reference for its label readers.
 > For locale configuration and route-prefix validation, see **`references/locales.md`**.
 
 This file covers the **CLI workflow** for labels: static UI copy such as nav items, buttons, headings, placeholders, alt text, and SEO strings.
 
 ## What validate does
 
-`fimo validate` scans `src/**/*.{ts,tsx,js,jsx}` for `t('literal-key')` calls (skipping `src/ui` and `node_modules`) and verifies every key has a value in the tenant DB for the default locale.
+`fimo validate` scans `src/**/*.{ts,tsx,js,jsx}` for literal `t('key')` calls, including server readers such as `labels.t('key')` (skipping `src/ui` and `node_modules`), and verifies every key has a value in the tenant DB for the default locale.
 
 The database is the source of truth for visible label values. Code declares keys; it does not create visible copy.
 
@@ -61,9 +61,9 @@ Prefer `fimo validate` — this primitive is for narrow debugging/test use.
 
 ## Workflow
 
-1. Write JSX with `t('key')` calls. Load `fimo/references/labels.md` for the rules.
+1. Write code with literal `t('key')` calls. Run `npx fimo@latest skills get fimo-code --ref labels` and load the detected framework reference.
 2. Run `fimo validate`.
 3. Add missing values with `fimo labels set` or `fimo labels set-many`.
 4. Editors can now change copy in the Fimo admin without code changes.
 
-For the helper signatures, hooks, and code patterns, **always** load `fimo/references/labels.md` before writing code that uses `t()`.
+For helper signatures and code patterns, run `npx fimo@latest skills get fimo-code --ref labels` before writing code that uses `t()`.

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

@@ -2,7 +2,7 @@
 
 > **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`.
+This file covers CLI-side locale configuration and validation. For code integration, run `npx fimo@latest skills get fimo-code --ref locales` plus the detected framework's locale reference.
 
 ## Configure Locales
 
@@ -65,13 +65,13 @@ Do not add `/es/pricing` as a second Fimo route. The route selector localizes ca
 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.
+For every framework, the application owns its URL scheme and passes the resolved locale into Fimo. Canonical route metadata is optional unless the project wants Fimo Studio route selection/navigation.
 
 ## 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.
+Preserve the existing locale provider, router, switcher, redirects, and public URLs. Use framework helpers only when they fit that architecture. Next.js projects run `npx fimo@latest skills get fimo-code --ref frameworks/next/locales`; React Router projects load the React Router setup reference.
 
 ## Labels And Content
 

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

@@ -45,7 +45,7 @@ Secrets are not written to `.env.local`, preview app env files, browser bundles,
 
 ## Local Env Files
 
-`fimo init` 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` with tenant content API URLs for Vite and Next runtimes. This lets the framework's normal dev command work without a Fimo wrapper.
 
 `fimo vars add`, `fimo vars update`, and `fimo vars pull` write public project variables to a managed block in `.env.local`.