fimo 0.2.4 → 0.2.5-experimental.1782379858530

package/README.md

@@ -50,13 +50,13 @@ npm install
 npm run dev
 ```
 
-Manage content, schemas, media, and translations from the CLI:
+Manage content, schemas, media, and labels from the CLI:
 
 ```bash
 fimo schemas push          # sync your content models
 fimo entries list          # browse content
 fimo assets upload <file>  # add media (or `fimo assets generate` with AI)
-fimo translations list     # manage locales
+fimo labels list           # manage labels and localized copy
 ```
 
 ## Deploying

package/assets/agent-templates/content-translator/GOAL.md

@@ -1,16 +1,15 @@
 # Content translator
 
-Translate CMS entries from the project's default locale into every
-non-default locale declared in `fimo.config.json`. Writes go through
-the `agent` branch and never directly to `main` — the M19 lifecycle
-engine picks the branch up and either auto-merges or proposes it for
-review.
+Translate CMS entries and DB-backed labels from the project's default
+locale into every non-default locale declared in `fimo-config.json`.
+Writes go through Fimo's content and label APIs. Do not create locale
+JSON files or put translated values in source code.
 
 ## Inputs
 
 - The list of CMS entries that have a non-empty default-locale field
   but an empty translation for any non-default locale.
-- The configured target locales (read from `fimo.config.json`).
+- The configured target locales (read from `fimo-config.json`).
 
 ## What to do
 
@@ -19,16 +18,14 @@ For each entry:
 1. Read the default-locale field via `cms:read`.
 2. Translate to every missing locale (via `net:fetch` to your translation
    provider of choice).
-3. Write the translation back to the entry via `cms:write`.
-4. Commit the change on the agent's branch.
+3. Write the translation back to the matching locale entry via `cms:write`.
+4. For static UI labels, update values with the i18n/labels API rather
+   than editing files.
 
 ## What NOT to do
 
 - Don't translate fields that the entry's schema marks `translate: false`.
 - Don't overwrite an existing translation, even if it looks lower quality.
-- Don't auto-merge to main — the lifecycle engine will propose a PR
-  when `agents.auto_merge.enabled` is true and the diff classifies as
-  `low_risk` or `trivial`.
 
 ## v1.x note
 

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

@@ -1,10 +1,8 @@
-# Reads CMS, writes translations + i18n + files. Net for the translation provider.
+# Reads CMS and writes DB-backed localized content / labels. Net is for the translation provider.
 - cms:read
 - cms:write
 - i18n:read
 - i18n:write
-- files:read
-- files:write
 - net:fetch
 - git:branch
 - git:commit

package/assets/agent-templates/content-translator/scripts/translate-entries.ts

@@ -1,9 +1,9 @@
 /**
  * Tool: translate-entries
  *
- * Walk every CMS entry, find translatable fields missing translations,
- * call the configured translation provider, and write back through the
- * Fimo API. Skips fields marked `translate: false` in the schema.
+ * Walk every default-locale CMS entry, find missing non-default-locale
+ * document rows, call the configured translation provider, and write back
+ * through the Fimo API. Skips fields marked `translate: false` in the schema.
  *
  * Provider is configured via env (FIMO_AGENT_TRANSLATE_PROVIDER) — the
  * runtime threads project secrets through when the v1.x secrets API
@@ -12,6 +12,8 @@
 
 interface Entry {
   id: string;
+  documentId: string;
+  locale: string;
   type: string;
   data: Record<string, unknown>;
 }
@@ -24,8 +26,8 @@ interface TranslateOptions {
 
 async function listMissing(_opts: TranslateOptions): Promise<Entry[]> {
   // Stub — wired to the Fimo API by the runtime. Returns entries with
-  // at least one non-default-locale field that's empty while the
-  // default-locale field is populated.
+  // at least one missing target-locale document row while the default-locale
+  // row is populated.
   return [];
 }
 
@@ -35,7 +37,8 @@ async function translate(text: string, _to: string): Promise<string> {
 }
 
 async function writeBack(_entry: Entry, _locale: string, _value: string): Promise<void> {
-  // Stub — PATCH the entry via `/api/management/projects/:id/envs/:env/cms/:type/:id`.
+  // Stub — create/update the target locale entry via
+  // `/api/management/projects/:id/envs/:env/tenant/entries/:type`.
 }
 
 async function main(): Promise<void> {
@@ -50,7 +53,7 @@ async function main(): Promise<void> {
   const entries = await listMissing({ fromLocale, toLocales, api });
   for (const entry of entries) {
     for (const locale of toLocales) {
-      const sourceValue = (entry.data[fromLocale] as Record<string, string> | undefined)?.title;
+      const sourceValue = typeof entry.data.title === 'string' ? entry.data.title : undefined;
       if (!sourceValue) {
         continue;
       }

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

@@ -9,7 +9,9 @@
 %>
 // AUTO-GENERATED ⚠️ – do not edit by hand
 import { useSuspenseQuery, useQuery, useMutation, useQueryClient, QueryKey } from "@tanstack/react-query";
-import { FimoString, FimoDate, FimoMedia, FimoBoolean, FimoRichText, type Fields, type Projected, type Query, type Sort, type Where } from "fimo/ui";
+import { FimoString, FimoDate, FimoMedia, FimoBoolean, FimoRichText, useLocale, type Fields, type Projected, type Query, type Sort, type Where } from "fimo/ui";
+// @ts-ignore - virtual module provided by Fimo's Vite plugin
+import fimoConfig from "virtual:fimo-config";
 
 /*───────────────────────────────────────────────────────────────*/
 /*  ────────────  📄  Type definitions  ────────────             */
@@ -18,12 +20,19 @@ import { FimoString, FimoDate, FimoMedia, FimoBoolean, FimoRichText, type Fields
 /**
  * <%= model.pascal %> entity interface
  */
+export interface <%= model.pascal %>FimoMeta {
+  contentType: string;
+  translationProgress: { state: "queued" | "translating"; fields?: string[] } | null;
+}
+
 export interface <%= model.pascal %> {
   id: string;
+  documentId: string;
   slug: FimoString;
-  contentType: string;
+  locale: string;
   createdAt: string;
   updatedAt: string;
+  __fimo: <%= model.pascal %>FimoMeta;
 <%
 // Generate interface properties based on fields
 if (model.fields) {
@@ -82,13 +91,19 @@ export type <%= model.pascal %>Result<TFields extends <%= model.pascal %>Fields
 function wrapWithSource(entry: Record<string, any>): <%= model.pascal %> {
   const id = entry.id;
   const sourcePrefix = `<%= model.pascal %>.${id}`;
+  const entryFimo = entry.__fimo && typeof entry.__fimo === "object" ? entry.__fimo : {};
 
   return {
     id,
+    documentId: entry.documentId,
     slug: entry.slug != null ? new FimoString(entry.slug, `${sourcePrefix}.slug`) : entry.slug,
-    contentType: entry.contentType,
+    locale: entry.locale,
     createdAt: entry.createdAt,
     updatedAt: entry.updatedAt,
+    __fimo: {
+      contentType: typeof entryFimo.contentType === "string" ? entryFimo.contentType : "<%= model.uid %>",
+      translationProgress: entryFimo.translationProgress && typeof entryFimo.translationProgress === "object" ? entryFimo.translationProgress as <%= model.pascal %>FimoMeta["translationProgress"] : null,
+    },
 <%
 if (model.fields) {
   Object.entries(model.fields).forEach(([key, field]) => {
@@ -137,6 +152,14 @@ if (model.fields) {
 // @ts-ignore - meta.env is a vite feature
 const base = import.meta.env.VITE_API_URL;
 
+function defaultLocale(): string {
+  return (fimoConfig as { i18n?: { defaultLocale?: string } }).i18n?.defaultLocale ?? "en";
+}
+
+function useQueryLocale(locale?: string): string {
+  return locale ?? useLocale().locale ?? defaultLocale();
+}
+
 function fimoHeaders(extra?: Record<string, string>): Record<string, string> {
   const h: Record<string, string> = { ...extra };
   // @ts-ignore
@@ -145,23 +168,47 @@ function fimoHeaders(extra?: Record<string, string>): Record<string, string> {
   return h;
 }
 
-export async function getById(id: string): Promise<<%= model.pascal %>> {
-  const res = await fetch(`${base}/entries/<%= model.uid %>/${id}`, { headers: fimoHeaders() });
+function withLocale(url: string, locale?: string): string {
+  const u = new URL(url, "http://fimo.local");
+  u.searchParams.set("locale", locale ?? defaultLocale());
+  return `${u.pathname}${u.search}`;
+}
+
+function splitWritePayload(payload: Partial<<%= model.pascal %>>): Record<string, unknown> {
+  const {
+    id,
+    documentId,
+    locale,
+    createdAt,
+    updatedAt,
+    ...data
+  } = payload as Record<string, unknown>;
+  delete data.__fimo;
+
+  return {
+    data,
+    ...(typeof locale === "string" && locale.length > 0 ? { locale } : {}),
+    ...(typeof documentId === "string" && documentId.length > 0 ? { documentId } : {}),
+  };
+}
+
+export async function getById(id: string, options: { locale?: string } = {}): Promise<<%= model.pascal %>> {
+  const res = await fetch(`${base}${withLocale(`/entries/<%= model.uid %>/${id}`, options.locale)}`, { headers: fimoHeaders() });
   if (!res.ok) throw new Error(await res.text());
   const data = await res.json();
   return wrapWithSource(data.data);
 }
 
-export async function getBySlug(slug: string): Promise<<%= model.pascal %> | null> {
-  const res = await fetch(`${base}/entries/<%= model.uid %>/slug/${encodeURIComponent(slug)}`, { headers: fimoHeaders() });
+export async function getBySlug(slug: string, options: { locale?: string } = {}): Promise<<%= model.pascal %> | null> {
+  const res = await fetch(`${base}${withLocale(`/entries/<%= model.uid %>/slug/${encodeURIComponent(slug)}`, options.locale)}`, { headers: fimoHeaders() });
   if (res.status === 404) return null;
   if (!res.ok) throw new Error(await res.text());
   const data = await res.json();
   return wrapWithSource(data.data);
 }
 
-export async function getByField(fieldName: string, value: string): Promise<<%= model.pascal %> | null> {
-  const res = await fetch(`${base}/entries/<%= model.uid %>/field/${encodeURIComponent(fieldName)}/${encodeURIComponent(value)}`, { headers: fimoHeaders() });
+export async function getByField(fieldName: string, value: string, options: { locale?: string } = {}): Promise<<%= model.pascal %> | null> {
+  const res = await fetch(`${base}${withLocale(`/entries/<%= model.uid %>/field/${encodeURIComponent(fieldName)}/${encodeURIComponent(value)}`, options.locale)}`, { headers: fimoHeaders() });
   if (res.status === 404) return null;
   if (!res.ok) throw new Error(await res.text());
   const data = await res.json();
@@ -189,6 +236,10 @@ function toQueryString<TFields extends <%= model.pascal %>Fields | undefined = u
     query.set("where", JSON.stringify(where));
   }
 
+  if (!query.has("locale")) {
+    query.set("locale", defaultLocale());
+  }
+
   return query.toString();
 }
 
@@ -204,7 +255,7 @@ export async function create(payload: Partial<<%= model.pascal %>>): Promise<<%=
   const res = await fetch(`${base}/entries/<%= model.uid %>`, {
     method: "POST",
     headers: fimoHeaders({ "Content-Type": "application/json" }),
-    body: JSON.stringify({ data: payload })
+    body: JSON.stringify(splitWritePayload(payload))
   });
   if (!res.ok) throw new Error(await res.text());
   const data = await res.json();
@@ -215,7 +266,7 @@ export async function update(id: string, payload: Partial<<%= model.pascal %>>):
   const res = await fetch(`${base}/entries/<%= model.uid %>/${id}`, {
     method: "PUT",
     headers: fimoHeaders({ "Content-Type": "application/json" }),
-    body: JSON.stringify({ data: payload })
+    body: JSON.stringify(splitWritePayload(payload))
   });
   if (!res.ok) throw new Error(await res.text());
   const data = await res.json();
@@ -233,42 +284,52 @@ export async function remove(id: string): Promise<void> {
 
 const qk = {
   root       : ["<%= model.pascal %>"] as const,
-  byId       : (id: string) => ["<%= model.pascal %>", id] as const,
-  bySlug     : (slug: string) => ["<%= model.pascal %>", "slug", slug] as const,
-  byField    : (field: string, value: string) => ["<%= model.pascal %>", field, value] as const,
+  byId       : (id: string, locale?: string) => ["<%= model.pascal %>", id, locale ?? defaultLocale()] as const,
+  bySlug     : (slug: string, locale?: string) => ["<%= model.pascal %>", "slug", slug, locale ?? defaultLocale()] as const,
+  byField    : (field: string, value: string, locale?: string) => ["<%= model.pascal %>", field, value, locale ?? defaultLocale()] as const,
   list       : (params: <%= model.pascal %>Query) => ["<%= model.pascal %>", params] as const
 };
 
-export function useGetById(id: string) {
-  return useQuery<<%= model.pascal %>, Error>({ queryKey: qk.byId(id), queryFn: () => getById(id) });
+export function useGetById(id: string, options: { locale?: string } = {}) {
+  const locale = useQueryLocale(options.locale);
+  return useQuery<<%= model.pascal %>, Error>({ queryKey: qk.byId(id, locale), queryFn: () => getById(id, { ...options, locale }) });
 }
 
-export function useGetBySlug(slug: string) {
-  return useQuery<<%= model.pascal %> | null, Error>({ queryKey: qk.bySlug(slug), queryFn: () => getBySlug(slug), enabled: !!slug });
+export function useGetBySlug(slug: string, options: { locale?: string } = {}) {
+  const locale = useQueryLocale(options.locale);
+  return useQuery<<%= model.pascal %> | null, Error>({ queryKey: qk.bySlug(slug, locale), queryFn: () => getBySlug(slug, { ...options, locale }), enabled: !!slug });
 }
 
-export function useGetByField(fieldName: string, value: string) {
-  return useQuery<<%= model.pascal %> | null, Error>({ queryKey: qk.byField(fieldName, value), queryFn: () => getByField(fieldName, value), enabled: !!value });
+export function useGetByField(fieldName: string, value: string, options: { locale?: string } = {}) {
+  const locale = useQueryLocale(options.locale);
+  return useQuery<<%= model.pascal %> | null, Error>({ queryKey: qk.byField(fieldName, value, locale), queryFn: () => getByField(fieldName, value, { ...options, locale }), enabled: !!value });
 }
 
 export function useGet<TFields extends <%= model.pascal %>Fields | undefined = undefined>(params: <%= model.pascal %>Query<TFields> = {} as <%= model.pascal %>Query<TFields>) {
-  return useQuery<<%= model.pascal %>Result<TFields>[], Error>({ queryKey: qk.list(params), queryFn: () => get(params) });
+  const locale = useQueryLocale(params.locale);
+  const localizedParams = { ...params, locale };
+  return useQuery<<%= model.pascal %>Result<TFields>[], Error>({ queryKey: qk.list(localizedParams), queryFn: () => get(localizedParams) });
 }
 
-export function useSuspenseGetById(id: string) {
-  return useSuspenseQuery<<%= model.pascal %>, Error>({ queryKey: qk.byId(id), queryFn: () => getById(id) });
+export function useSuspenseGetById(id: string, options: { locale?: string } = {}) {
+  const locale = useQueryLocale(options.locale);
+  return useSuspenseQuery<<%= model.pascal %>, Error>({ queryKey: qk.byId(id, locale), queryFn: () => getById(id, { ...options, locale }) });
 }
 
-export function useSuspenseGetBySlug(slug: string) {
-  return useSuspenseQuery<<%= model.pascal %> | null, Error>({ queryKey: qk.bySlug(slug), queryFn: () => getBySlug(slug) });
+export function useSuspenseGetBySlug(slug: string, options: { locale?: string } = {}) {
+  const locale = useQueryLocale(options.locale);
+  return useSuspenseQuery<<%= model.pascal %> | null, Error>({ queryKey: qk.bySlug(slug, locale), queryFn: () => getBySlug(slug, { ...options, locale }) });
 }
 
-export function useSuspenseGetByField(fieldName: string, value: string) {
-  return useSuspenseQuery<<%= model.pascal %> | null, Error>({ queryKey: qk.byField(fieldName, value), queryFn: () => getByField(fieldName, value) });
+export function useSuspenseGetByField(fieldName: string, value: string, options: { locale?: string } = {}) {
+  const locale = useQueryLocale(options.locale);
+  return useSuspenseQuery<<%= model.pascal %> | null, Error>({ queryKey: qk.byField(fieldName, value, locale), queryFn: () => getByField(fieldName, value, { ...options, locale }) });
 }
 
 export function useSuspenseGet<TFields extends <%= model.pascal %>Fields | undefined = undefined>(params: <%= model.pascal %>Query<TFields> = {} as <%= model.pascal %>Query<TFields>) {
-  return useSuspenseQuery<<%= model.pascal %>Result<TFields>[], Error>({ queryKey: qk.list(params), queryFn: () => get(params) });
+  const locale = useQueryLocale(params.locale);
+  const localizedParams = { ...params, locale };
+  return useSuspenseQuery<<%= model.pascal %>Result<TFields>[], Error>({ queryKey: qk.list(localizedParams), queryFn: () => get(localizedParams) });
 }
 
 export function useCreate() {

package/assets/skills/fimo/SKILL.md

@@ -3,7 +3,7 @@ name: fimo
 description: >-
   How to write code in a Fimo project — the npm package surface. Load when
   writing JSX that renders schema content, defining schemas or forms (JSON),
-  using `t()` for translations, plugging media into `fimo/ui` components,
+  using `t()` for labels, plugging media into `fimo/ui` components,
   or applying the project's code conventions. CLI commands and workflows
   (push, deploy, sync, etc.) live in the `fimo-cli` skill.
 ---
@@ -14,14 +14,14 @@ You are writing code in a Fimo project — a content + media + forms + analytics
 
 This skill is version-locked to this project's installed `fimo` package — the shapes here match what your code can actually use.
 
-For CLI commands and workflows (creating a project, pushing schemas/forms, deploying, syncing translations, etc.), the **`fimo-cli`** skill is the source of truth. If `fimo-cli` isn't loaded for your AI tool, run `fimo skills install` to register it.
+For CLI commands and workflows (creating a project, pushing schemas/forms, deploying, managing labels, etc.), the **`fimo-cli`** skill is the source of truth. If `fimo-cli` isn't loaded for your AI tool, run `fimo skills install` to register it.
 
 ## Critical: NEVER hardcode user-facing things
 
 This is the load-bearing rule for every code change. **Fimo's whole point is that content editors edit content in the dashboard, not in code.** Anything hardcoded breaks that.
 
 - **Content** (posts, products, pages, lists, anything structured) → declare a schema, render with the generated `useGet()` hook + `fimo/ui` components. **Never** write `const posts = [...]` in JSX.
-- **Strings** (labels, CTAs, headings, descriptions, any visible text) → wrap in `t('key', 'Default text')`. **Never** write `<h1>Welcome</h1>` directly — write `<Text value={t('home.title', 'Welcome')} as="h1" />`.
+- **Strings** (labels, CTAs, headings, descriptions, any visible text) → wrap in `t('key')` and create the default-locale value with `fimo labels set`. Use `--locale <locale>` only when intentionally writing a non-default locale. **Never** write `<h1>Welcome</h1>` directly — write `<Text value={t('home.title')} as="h1" />`.
 - **Media** (images, videos, files) → use `<Image>` / `<Video>` from `fimo/ui` for schema media, `<StaticImage>` for hard-coded URLs. **Never** use `<img src={...}>`.
 - **Forms** → use the generated Zod schema + `submitX` helper from `@/forms/<name>`. Never hand-roll fetch or validation.
 
@@ -29,15 +29,16 @@ If you find yourself about to hardcode anything user-facing, **stop and use the
 
 ## When starting code work, load these references up front
 
-These define the package surface for the load-bearing primitives. **Read all five before generating significant code:**
+These define the package surface for the load-bearing primitives. **Read all six before generating significant code:**
 
 - `references/content.md` — schema JSON shape, field types, Tiptap nodes, generated React Query hooks
 - `references/forms.md` — form JSON spec, generated Zod + `submitX` helper
 - `references/assets.md` — `FimoMedia` shape, how to render assets
-- `references/translations.md` — `t()` helper, `useTranslations()`, wrap rules
+- `references/labels.md` — `t()` helper, `useLabels()`, wrap rules
+- `references/locales.md` — locale routing helpers, `FimoLink`, custom-framework contract
 - `references/ui.md` — `fimo/ui` components + JSX code conventions + app code rules
 
-Workflow / CLI-side concerns (pushing schemas, generating images, syncing translations, deploying) live in the **`fimo-cli`** skill's matching references.
+Workflow / CLI-side concerns (pushing schemas, generating images, managing labels, deploying) live in the **`fimo-cli`** skill's matching references.
 
 ## Decision Tree (specific tasks)
 
@@ -47,7 +48,8 @@ Workflow / CLI-side concerns (pushing schemas, generating images, syncing transl
 - Writing schema JSON / picking field types / Tiptap richtext → `references/content.md`
 - Writing form JSON / generated form client / form code → `references/forms.md`
 - Plugging media into a component / `FimoMedia` shape → `references/assets.md`
-- ANY user-facing string in code → `references/translations.md`
+- ANY user-facing string in code → `references/labels.md`
+- Locale-aware routes, links, or framework adapters → `references/locales.md`
 - ANY JSX rendering schema content or `t()` output → `references/ui.md`
 - Major visual / redesign / hero section / brand → `references/design.md`
 
@@ -55,7 +57,7 @@ Workflow / CLI-side concerns (pushing schemas, generating images, syncing transl
 
 - **Hardcoding content in JSX** — `<h1>My Blog</h1>` + an array of posts in code. Use schemas + entries + `t()`.
 - **Raw HTML for schema content** — `<img src={post.coverImage.url}>` instead of `<Image value={post.coverImage}>`. The `fimo/ui` components carry metadata for inline editing in the admin.
-- **Raw `<a href>` for internal navigation** — causes full page reloads. Use `<Link>` / `<NavLink>` from react-router. Reserve `<a>` for external links.
+- **Raw `<a href>` for internal navigation** — causes full page reloads. Use `<FimoLink>` for locale-aware internal links or React Router `<Link>` when intentionally bypassing locale helpers. Reserve `<a>` for external links.
 - **Pulling stock photos from external URLs** — editors can't manage them. Use `fimo generate` (CLI).
 - **Editing generated `.ts` files** under `src/schemas/` or `src/forms/` — regenerated on every build.
 - **Writing raw HTML in `richtext` fields** — must be Tiptap JSONContent.

package/assets/skills/fimo/assets/react-router-locales/navigation.tsx

@@ -0,0 +1,13 @@
+import { FimoLink } from 'fimo/react-router';
+
+export function Navigation() {
+  return (
+    <nav>
+      <FimoLink to="/">Home</FimoLink>
+      <FimoLink to="/pricing">Pricing</FimoLink>
+      <FimoLink to="/pricing" locale="es">
+        Pricing in Spanish
+      </FimoLink>
+    </nav>
+  );
+}

package/assets/skills/fimo/assets/react-router-locales/routes.ts

@@ -0,0 +1,11 @@
+import type { RouteConfig } from '@react-router/dev/routes';
+import { index, route } from '@react-router/dev/routes';
+import { fimoRoutes } from 'fimo/react-router/routes';
+
+const routes = [
+  index('./pages/Index.tsx', { id: 'home' }),
+  route('pricing', './pages/Pricing.tsx', { id: 'pricing' }),
+  route('blog/:slug', './pages/BlogPost.tsx', { id: 'blog-post' }),
+] satisfies RouteConfig;
+
+export default fimoRoutes(routes) satisfies RouteConfig;

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

@@ -114,10 +114,15 @@ After pre-build (or `fimo deploy`), `src/schemas/{Uid}.ts` exports typed helpers
 ```ts
 interface BlogPost {
   id: string;
+  documentId: string;
   slug: FimoString;
-  contentType: string;
+  locale: string;
   createdAt: string;
   updatedAt: string;
+  __fimo: {
+    contentType: string;
+    translationProgress: { state: 'queued' | 'translating'; fields?: string[] } | null;
+  };
   title: FimoString;
   body: FimoRichText;
   coverImage: FimoMedia;
@@ -127,6 +132,34 @@ interface BlogPost {
 }
 ```
 
+Content fields live at the top level. Fimo-owned metadata that is not part of the user schema lives under `__fimo`, so a schema can safely define fields named `contentType`, `sourceLocale`, `translationStatus`, or `translationMeta`.
+
+## Schema i18n
+
+Content auto-translation uses `fimo-config.json#i18n.autoTranslateContent` as the global switch. Use schema-level `i18n.autoTranslate` for translatable content types and field-level `i18n.autoTranslate: false` for fields that must be copied exactly.
+
+```json
+{
+  "uid": "BlogPost",
+  "name": "Blog Post",
+  "isSingleton": false,
+  "i18n": {
+    "autoTranslate": true,
+    "translatePrompt": "Use friendly editorial Spanish and keep product names unchanged."
+  },
+  "fields": {
+    "title": { "type": "string" },
+    "summary": { "type": "string" },
+    "sku": {
+      "type": "string",
+      "i18n": { "autoTranslate": false }
+    }
+  }
+}
+```
+
+Use schema-level `translatePrompt` for wording rules that apply to the whole content type. Use field-level `i18n.autoTranslate: false` for fields that should be copied exactly.
+
 **Generated API:**
 
 ```ts
@@ -170,6 +203,7 @@ BlogPost.useGet({
     views: { $gte: 100 },
     title: { $contains: 'React' },
     coverImage: { $null: false },
+    __fimo: { contentType: { $eq: 'BlogPost' } },
   },
   sort: ['-publishedAt', 'title'],
   limit: 12,
@@ -210,7 +244,7 @@ Rules of thumb:
 - **Pass the whole primitive to the matching `fimo/ui` component** — `<Text value={post.title} />`, `<Image value={post.cover} />`, `<RichText value={post.body} />`, `<Boolean value={p.inStock} />`. Don't unwrap first; the component reads the source metadata so the field stays inline-editable in the dashboard.
 - **`FimoString extends String`**, so `typeof post.title === 'object'` and `post.title === 'Hi'` is `false`. It stringifies fine inside JSX and template literals; call `.toString()` only when something genuinely needs a primitive `string`.
 - **Never hand-construct** a `FimoString` / `FimoMedia` / etc. — that bypasses source tracking. For a literal string use `t()`; for a literal image use `<StaticImage>`.
-- `t()` also returns a `FimoString` (see `references/translations.md`).
+- `t()` also returns a `FimoString` (see `references/labels.md`).
 
 `FimoMedia` and `FimoBoolean` shapes:
 

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

@@ -99,7 +99,7 @@ export function ContactForm() {
 
 ## Labels and copy
 
-Wrap every visible string in `t('key', 'Default')` — see `references/translations.md`. This includes form labels, placeholders, button text, success/error messages.
+Wrap every visible string in `t('key')` and create the DB value with `fimo labels set` — see `references/labels.md`. This includes form labels, placeholders, button text, success/error messages.
 
 ## Forms vs. schemas
 

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

@@ -0,0 +1,106 @@
+# Labels — package surface
+
+> For the CLI workflow (`fimo validate`, `fimo labels set`, bulk updates), see **`fimo-cli/references/labels.md`**.
+> For locale-aware routing and links (`fimoRoutes`, `FimoLink`, custom framework contract), see **`references/locales.md`**.
+
+This file covers the **package surface**: the `t()` helper, the `useLabels()` hook, and the code-side rules for wrapping strings.
+
+## The rule
+
+Every piece of **user-facing static text** in the app (page titles, button labels, nav items, form placeholders, empty-state copy, alt text, meta tags) MUST be wrapped in `t('key')`.
+
+Raw string literals in JSX are a bug — they won't show up in the Fimo admin as editable content and won't be translatable. **Hard-coded JSX text (`<h1>Welcome</h1>`) skips the entire i18n + inline-editing pipeline and becomes invisible to the editor.**
+
+## Setup (already wired)
+
+Labels are wired automatically by the `fimo/vite` build plugin. `useLabels()` reads DB-backed label values for the active locale — there's no provider to add or remove. The app entry is `src/root.tsx`, which wraps the app in `<FimoProviders>` from `fimo/react-router`. Pages and components call `useLabels()`.
+
+`useTranslations()` is kept as a legacy alias for older projects. Use `useLabels()` in new code.
+
+In development, the generated app reloads when DB label values change. In production, the build embeds the DB-backed label bundle.
+
+## Locale behavior
+
+The default label locale is `i18n.defaultLocale` in `fimo-config.json`, falling back to `en` when it is not set. `fimo validate`, the generated app runtime, and `fimo labels set` without `--locale` all use that default locale.
+
+For non-default locales, create explicit DB values with `fimo labels set --locale <locale>` or `fimo labels set-many --locale <locale>`. Keep the code shape the same for every locale: `t('hero.title')` declares the key, and the DB decides which locale value is shown.
+
+`fimo-config.json` owns the locale list:
+
+```json
+{
+  "i18n": {
+    "defaultLocale": "en",
+    "locales": ["en"],
+    "autoTranslateLabels": false,
+    "autoTranslateContent": true
+  }
+}
+```
+
+- `locales` is the enabled locale list and must include `defaultLocale`. Do not add non-default locales unless the user asks for multiple languages, localized routes, translations, or a specific locale.
+- `autoTranslateLabels` is explicit opt-in. Runtime default is `false`; when the user asks for locales and does not opt out of automatic label translation, set it to `true`.
+- `autoTranslateContent` is the global content auto-translation switch. Set it to `false` to disable content auto-translation globally.
+- Content auto-translation can be narrowed or customized per schema and per field in `src/schemas/*.json`; see `references/content.md`.
+- Public locale routing is project/framework code. In React Router projects, prefer `fimoRoutes()` plus `FimoLink`; for custom frameworks, pass the active locale to `FimoProviders`. See `references/locales.md`.
+
+## Usage
+
+```tsx
+import { useLabels, Text } from 'fimo/ui';
+
+export function Hero() {
+  const { t } = useLabels();
+  return (
+    <section>
+      <h1>
+        <Text value={t('hero.title')} />
+      </h1>
+      <p>
+        <Text value={t('hero.subtitle')} />
+      </p>
+      <input placeholder={String(t('hero.emailPlaceholder'))} />
+      <img alt={String(t('hero.imageAlt'))} src="..." />
+    </section>
+  );
+}
+```
+
+- `t(key)` returns a `FimoString` (wrapped for source tracking). Render it via `<Text value={...} />` inside JSX.
+- For HTML attributes (`placeholder`, `alt`, `title`, `aria-label`) cast with `String(t(...))` — the attribute can't accept a `FimoString` object directly.
+- If a key is missing from the DB, it renders empty. Run `fimo validate` and add missing values with `fimo labels set`.
+
+## Hard rules (enforced by the pre-build linter)
+
+**The first argument to `t()` MUST be a string literal.** Dynamic keys break source tracking and fail the lint step.
+
+```tsx
+// ❌ BAD — variable key
+t(item.key);
+
+// ❌ BAD — template with expression
+t(`nav.${page}`);
+
+// ✅ GOOD — put the t() call where the literal lives
+const items = [{ label: t('nav.home') }, { label: t('nav.about') }];
+items.map((item) => <li>{item.label}</li>);
+```
+
+## Key naming
+
+- Dot-namespaced, lowercase, kebab or camelCase leaves: `hero.title`, `nav.signIn`, `footer.copyright`, `errors.required`.
+- Namespace by **page/section/component**, not by feature (`contact.form.submitLabel`, not `forms.contactSubmit`).
+- Values live in the DB. Do not put user-visible fallback copy in code.
+
+## What NOT to translate
+
+- Dynamic content from entries or forms — that's already stored in the DB (content via schemas, submissions via forms).
+- Content-type field values rendered via `fimo/ui` primitives (`<Text>`, `<RichText>`, …) — those carry their own admin-editing metadata.
+- Purely decorative / non-text (icons, logos).
+- Developer-only strings (`console.log`, error messages thrown for debugging).
+
+## Rule of thumb
+
+If a human reader sees the text AND the project owner might want to reword it in the admin, it goes through `t()`. When in doubt: wrap it.
+
+After adding or changing `t()` calls, run `fimo validate`, then fill missing values with `fimo labels set` or `fimo labels set-many`. See `fimo-cli/references/labels.md`.