fimo 0.12.0 → 0.13.0-staging.1

package/assets/agent-templates/broken-link-sweeper/capabilities.yaml

@@ -1,6 +1,2 @@
 - net:fetch
-- files:read
-- files:write
-- git:branch
-- git:commit
 - fimo:analytics:read

package/assets/agent-templates/content-translator/capabilities.yaml

@@ -4,5 +4,3 @@
 - i18n:read
 - i18n:write
 - net:fetch
-- git:branch
-- git:commit

package/assets/agent-templates/seo-audit/capabilities.yaml

@@ -1,5 +1,4 @@
 # Read-only audit — no writes to project files or CMS.
-- files:read
 - cms:read
 - net:fetch
 - fimo:analytics:read

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,7 +2,7 @@
 name: fimo
 description: >-
   Working in or with a Fimo project (a content + media + forms + analytics
-  platform for React websites). Load the current Fimo skills on demand through
+  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.
 ---
@@ -23,7 +23,7 @@ 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`
 - 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`)

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

@@ -9,7 +9,7 @@ description: >-
 
 # 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, content / forms / media / labels / locale workflows, deploys, collaboration, account management, Fimo agents, 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`.
 
@@ -34,7 +34,7 @@ Every command accepts a global `--json` flag (or `FIMO_OUTPUT=json` env) and emi
 
 Branch on `error.code`, never on `error.message`. The envelope shape is versioned — `schema_version: 1` is stable; any breaking change bumps the version. Per-command `data` shapes are documented in `apps/cli/CLAUDE.md` (consumers of this skill don't normally need to read it, but it's the source of truth).
 
-For shell composition use plain pretty mode (`cd $(fimo …)`); for structured parsing use `--json`. JSON mode disables interactive prompts — commands that need a confirmation will fail fast with `NON_INTERACTIVE_REFUSAL` unless every required arg is on the command line (`--yes`, `--org`, etc.).
+For shell composition use plain pretty mode (`cd $(fimo …)`); for structured parsing use `--json`. JSON mode disables interactive prompts — commands that need a confirmation fail fast unless every required arg is on the command line (`--yes`, `--org`, etc.). Locale lifecycle commands use `CONFIRMATION_REQUIRED` and require `--yes`; other older commands may use `NON_INTERACTIVE_REFUSAL`.
 
 Pretty output may hide URLs behind clickable labels. Agents should use `--json` and read `data`.
 
@@ -73,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`
@@ -111,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

@@ -11,7 +11,7 @@ The rich skills (`fimo-code`, `fimo-cli`, `fimo-studio`, `fimo-migration`) are *
 
 ```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
 ```

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

@@ -60,15 +60,14 @@ used. See `references/integrations.md` for project setup, auth, and provider-spe
 
 ## Capabilities
 
-Capabilities describe the non-integration actions an agent may take. Start with the smallest set that matches the goal.
-If `capabilities.yaml` is absent or empty, the agent gets the read-only defaults: `files:read`, `cms:read`, and
-`assets:read`. Once you add a capabilities file, list every extra capability the agent needs.
+Capabilities describe the opt-in Fimo and network actions an agent may take. Managed agents always receive project
+filesystem access, a shell, and the ability to commit their task-environment changes; Fimo owns branch creation and
+publication. If `capabilities.yaml` is absent or empty, the agent has those project-worker tools but no Fimo API
+permissions or web-fetch tool. Once you add a capabilities file, list every Fimo or network permission the agent needs.
 There is no all-capabilities wildcard; keeping the list explicit makes each agent's power reviewable.
 
 | Capability                   | Allows the agent to                         | Risk         |
 | ---------------------------- | ------------------------------------------- | ------------ |
-| `files:read`                 | Read project files                          | Low          |
-| `files:write`                | Write or delete project files               | Medium       |
 | `cms:read`                   | Read CMS content                            | Low          |
 | `cms:write`                  | Create, update, or delete CMS entries       | Medium       |
 | `cms:schema:read`            | Read CMS schemas                            | Low          |
@@ -81,16 +80,11 @@ There is no all-capabilities wildcard; keeping the list explicit makes each agen
 | `webhooks:write`             | Create, modify, delete, or trigger webhooks | High         |
 | `schedules:read`             | Read schedule configs and run history       | Low          |
 | `schedules:write`            | Create, change, or trigger scheduled runs   | Critical     |
-| `git:read`                   | Read git state                              | Low          |
-| `git:branch`                 | Create an agent branch                      | Medium       |
-| `git:commit`                 | Commit changes to the agent branch          | Medium       |
-| `git:push`                   | Push changes to the project remote          | High         |
 | `fimo:logs:read`             | Read production logs                        | Low          |
 | `fimo:analytics:read`        | Read analytics data                         | Low          |
 | `fimo:preview:read`          | Read a current preview URL                  | Low          |
 | `fimo:deploy`                | Trigger a production deploy                 | Critical     |
 | `net:fetch`                  | Make outbound HTTP requests                 | Medium       |
-| `shell:exec`                 | Run arbitrary shell commands in the sandbox | High         |
 | `agent:delegate`             | Invoke declared sub-agents                  | Medium       |
 | `runtime:long_running`       | Run beyond the default time limit           | High         |
 | `runtime:auto_merge`         | Auto-merge trivial proposed branches        | Critical     |
@@ -99,10 +93,9 @@ If a capability is missing, the related command is denied and the agent should c
 blocker. Add the capability to `capabilities.yaml`, run `fimo agents validate <name>`, deploy the bundle, and start a
 new run. A denied capability does not grant access to anything else.
 
-Example for a content editor that can read and update entries but cannot change schemas or run shell commands:
+Example for a content editor that can read and update entries but cannot change schemas:
 
 ```yaml
-- files:read
 - cms:read
 - cms:write
 ```

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.
 
-> Package contract: run `npx fimo@latest skills get fimo-code --ref assets` for `FimoMedia`, and `--ref ui` for component integration.
+> 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, load the `fimo-code` UI reference — 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/branches.md

@@ -17,6 +17,7 @@ fimo --env <name> <command>     # peek at another env for one command (does not
 ```
 
 - **`--env <name>`** is a global override. `fimo --env main status` inspects `main` while you stay checked out on your feature branch.
+- Git-changing commands use the current branch; cross-branch status only reports the mismatch.
 - If the branch maps to no env, the CLI errors with a hint (`fimo branch` to list, `fimo branch <name>` to create) rather than guessing.
 - **`main`** is the default env and cannot be deleted.
 - **`release/*`** envs are **read-only** — they're tags produced by `fimo publish`, not branches you push to. `fimo deploy` refuses them.

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.
 
-> Package contract: run `npx fimo@latest skills get fimo-code --ref content` for the JSON shape, field types, Tiptap nodes, slug rules, and generated React Query hooks.
+> 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 the `fimo-code` content reference.
-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 the `fimo-code` content reference 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 the `fimo-code` content reference 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 the `fimo-code` content reference. **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 the `fimo-code` content reference. 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 the `fimo-code` content reference § 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 the `fimo-code` content reference 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 the `fimo-code` UI reference for the `<Text>`, `<Image>`, `<RichText>` components.
-7. Load the `fimo-code` labels reference 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/deploy.md

@@ -6,7 +6,9 @@
 
 > **Local vs hosted.** The local dev server is localhost only. The Fimo **dashboard preview** and the **shareable preview URL** are served by the deployed sandbox — so if the developer wants to see the site in the dashboard or send someone a link, that requires a `fimo deploy`.
 
-`fimo deploy` is **env-aware**: it targets the env of the current git branch (the same one `fimo status` reports on) and prints a one-line banner saying which. New projects are on `main`. It refuses to deploy to read-only `release/*` envs, and `--publish` only runs from `main`. The full multi-env workflow is in `references/branches.md`.
+`fimo deploy` uses the current branch. New projects start on `main`; `release/*` is read-only, and `--publish` only runs from `main`. See `references/branches.md` for the multi-env workflow.
+
+Before deploying, Fimo fast-forwards a clean checkout that is behind and stops on dirty-behind or diverged branches. This syncs the whole branch, including config commits from Studio or locale commands.
 
 > **Just need the current preview URL?** That's `fimo preview url` — sub-second, no commit, no push. See `references/preview.md`. `fimo deploy` is only for pushing code changes.
 
@@ -106,9 +108,9 @@ curl -H 'Accept: text/markdown' https://your-site/  # content negotiation
 curl https://your-site/?format=md                # query param
 ```
 
-## Recovering from a failed push
+## Recovering from Git drift
 
-If the push fails because the remote is ahead:
+Most stale states are caught before deploy changes or commits files. Follow the emitted hint: clean a dirty checkout, or reconcile a diverged branch. A push can still lose a race if the remote advances after preflight:
 
 ```bash
 git pull --rebase fimo <env>   # <env> = the branch you're deploying (e.g. main)

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.
 
-> Package contract: run `npx fimo@latest skills get fimo-code --ref forms` for the JSON spec, generated Zod schema, submit helper, and React usage.
+> 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 the `fimo-code` forms reference.
+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 the `fimo-code` forms reference 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 the `fimo-code` forms reference 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 the `fimo-code` forms reference for the generated `submitContactUs` + `ContactUsSchema` API.
-5. Load the `fimo-code` labels reference 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. Load only the `fimo-code` references needed for the first task, using `npx fimo@latest skills get fimo-code --ref <doc>`.
+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.
 
-> Package contract: run `npx fimo@latest skills get fimo-code --ref labels` for `t()`, `useLabels()`, key naming, and wrapping rules.
+> 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 the `fimo-code` labels reference 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 the `fimo-code` labels reference 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,11 +2,24 @@
 
 > **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`, run `npx fimo@latest skills get fimo-code --ref locales`.
+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
 
-Edit `.fimo/config.json`. Keep one locale unless the user asks for multilingual or localized output:
+Keep one locale unless the user asks for multilingual or localized output. Use typed lifecycle commands for the locale set and default:
+
+```bash
+fimo locales list --json
+fimo locales add es --yes --json
+fimo locales set-default es --yes --json
+fimo locales remove es --yes --json
+```
+
+These commands update the selected environment through the locale lifecycle API. The API commits `.fimo/config.json` to the Fimo branch, then the CLI synchronizes the **whole local branch** to that commit. They refuse a dirty config, a local-ahead branch, or a diverged branch before applying the remote change. `--yes` bypasses only the explanatory prompt.
+
+If a mutation exits with code `2` and `data.code` is `LOCALE_APPLIED_SYNC_REQUIRED`, the remote operation succeeded (`data.applied` is `true`) but the local fast-forward did not. **Do not retry the locale command.** Run the commands in `data.sync.recovery`, resolve the checkout, and confirm with `fimo status` or `fimo locales list`.
+
+Edit `.fimo/config.json` only for declarative routing behavior:
 
 ```jsonc
 {
@@ -21,12 +34,14 @@ Edit `.fimo/config.json`. Keep one locale unless the user asks for multilingual
 }
 ```
 
-- `defaultLocale` is the locale used by `fimo validate`, `fimo labels set` without `--locale`, and content commands without `--locale`.
-- `locales` must include `defaultLocale`. Do not add non-default locales unless the user asks for multiple languages, localized routes, translations, or a specific locale.
+- `defaultLocale` is the locale used by `fimo validate`, `fimo labels set` without `--locale`, and content commands without `--locale`. Change it with `fimo locales set-default`.
+- `locales` must include `defaultLocale`. Add and remove values with `fimo locales add` and `fimo locales remove`.
 - Locale tags should be structurally valid, for example `en`, `es`, `pt-BR`, or `zh-Hans`.
 - `routing.strategy` currently supports `path-prefix`.
 - If multiple locales are configured, create or update labels and localized content for every configured locale. Create schemas with `i18n: { "enabled": false }` only once.
 
+`fimo locales remove` permanently deletes that locale's stored entries and labels.
+
 ## Validate
 
 Run:
@@ -65,13 +80,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`.