fimo 0.2.4 → 0.2.5-experimental.1782327181771

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

@@ -10,6 +10,8 @@
 // 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";
+// @ts-ignore - virtual module provided by Fimo's Vite plugin
+import fimoConfig from "virtual:fimo-config";
 
 /*───────────────────────────────────────────────────────────────*/
 /*  ────────────  📄  Type definitions  ────────────             */
@@ -20,8 +22,13 @@ import { FimoString, FimoDate, FimoMedia, FimoBoolean, FimoRichText, type Fields
  */
 export interface <%= model.pascal %> {
   id: string;
+  documentId: string;
   slug: FimoString;
   contentType: string;
+  locale: string;
+  sourceLocale: string | null;
+  translationStatus: string;
+  translationMeta: Record<string, unknown> | null;
   createdAt: string;
   updatedAt: string;
 <%
@@ -85,8 +92,13 @@ function wrapWithSource(entry: Record<string, any>): <%= model.pascal %> {
 
   return {
     id,
+    documentId: entry.documentId,
     slug: entry.slug != null ? new FimoString(entry.slug, `${sourcePrefix}.slug`) : entry.slug,
     contentType: entry.contentType,
+    locale: entry.locale,
+    sourceLocale: entry.sourceLocale,
+    translationStatus: entry.translationStatus,
+    translationMeta: entry.translationMeta,
     createdAt: entry.createdAt,
     updatedAt: entry.updatedAt,
 <%
@@ -137,6 +149,10 @@ 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 fimoHeaders(extra?: Record<string, string>): Record<string, string> {
   const h: Record<string, string> = { ...extra };
   // @ts-ignore
@@ -145,23 +161,53 @@ 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,
+    contentType,
+    locale,
+    sourceLocale,
+    translationStatus,
+    translationMeta,
+    createdAt,
+    updatedAt,
+    ...data
+  } = payload as Record<string, unknown>;
+
+  return {
+    data,
+    ...(typeof locale === "string" && locale.length > 0 ? { locale } : {}),
+    ...(typeof documentId === "string" && documentId.length > 0 ? { documentId } : {}),
+    ...(typeof sourceLocale === "string" && sourceLocale.length > 0 ? { sourceLocale } : {}),
+    ...(typeof translationStatus === "string" && translationStatus.length > 0 ? { translationStatus } : {}),
+    ...(translationMeta && typeof translationMeta === "object" ? { translationMeta } : {}),
+  };
+}
+
+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 +235,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 +254,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 +265,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,38 +283,38 @@ 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 } = {}) {
+  return useQuery<<%= model.pascal %>, Error>({ queryKey: qk.byId(id, options.locale), queryFn: () => getById(id, options) });
 }
 
-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 } = {}) {
+  return useQuery<<%= model.pascal %> | null, Error>({ queryKey: qk.bySlug(slug, options.locale), queryFn: () => getBySlug(slug, options), 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 } = {}) {
+  return useQuery<<%= model.pascal %> | null, Error>({ queryKey: qk.byField(fieldName, value, options.locale), queryFn: () => getByField(fieldName, value, options), 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) });
 }
 
-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 } = {}) {
+  return useSuspenseQuery<<%= model.pascal %>, Error>({ queryKey: qk.byId(id, options.locale), queryFn: () => getById(id, options) });
 }
 
-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 } = {}) {
+  return useSuspenseQuery<<%= model.pascal %> | null, Error>({ queryKey: qk.bySlug(slug, options.locale), queryFn: () => getBySlug(slug, options) });
 }
 
-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 } = {}) {
+  return useSuspenseQuery<<%= model.pascal %> | null, Error>({ queryKey: qk.byField(fieldName, value, options.locale), queryFn: () => getByField(fieldName, value, options) });
 }
 
 export function useSuspenseGet<TFields extends <%= model.pascal %>Fields | undefined = undefined>(params: <%= model.pascal %>Query<TFields> = {} as <%= model.pascal %>Query<TFields>) {

package/assets/skills/fimo/SKILL.md

@@ -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.
 
@@ -37,7 +37,7 @@ These define the package surface for the load-bearing primitives. **Read all fiv
 - `references/translations.md` — `t()` helper, `useTranslations()`, wrap rules
 - `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)
 

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/translations.md`. This includes form labels, placeholders, button text, success/error messages.
 
 ## Forms vs. schemas
 

package/assets/skills/fimo/references/setup-plain-vite.md

@@ -45,7 +45,7 @@ pnpm add -D vite @vitejs/plugin-react @types/react @types/react-dom typescript
 
 Validate runs automatically during `fimo deploy` and API-side sandbox builds.
 For a purely local build, run `fimo validate` manually first when you need to
-sync schemas/forms/translations before `pnpm build`.
+regenerate schemas/forms or check missing labels before `pnpm build`.
 
 ## File: `vite.config.ts`
 

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

@@ -36,7 +36,7 @@ pnpm add -D @react-router/dev @react-router/node @tailwindcss/vite tailwindcss v
 
 Validate runs automatically during `fimo deploy` and API-side sandbox builds.
 For a purely local build, run `fimo validate` manually first when you need to
-sync schemas/forms/translations before `pnpm build`.
+regenerate schemas/forms or check missing labels before `pnpm build`.
 
 ## File: `vite.config.ts`
 

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

@@ -1,18 +1,45 @@
-# Translations — package surface
+# Labels — package surface
 
-> For the CLI workflow (`fimo validate`, when to run validation, what sync does), see **`fimo-cli/references/translations.md`**.
+> For the CLI workflow (`fimo validate`, `fimo labels set`, bulk updates), see **`fimo-cli/references/translations.md`**.
 
 This file covers the **package surface**: the `t()` helper, the `useTranslations()` 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', 'Default text')`.
+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)
 
-Translations are wired automatically by the `fimo/vite` build plugin. It exposes a `virtual:translations` module sourced from `<projectRoot>/translations/en.json`, and `useTranslations()` reads from that virtual module — 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`; you never import `translations/en.json` in app code. Pages and components only call `useTranslations()`.
+Labels are wired automatically by the `fimo/vite` build plugin. It exposes a `virtual:translations` module sourced from the tenant DB, and `useTranslations()` reads from that virtual module — 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 only call `useTranslations()`.
+
+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", "es"],
+    "autoTranslateLabels": true,
+    "autoTranslateContent": true
+  }
+}
+```
+
+- `locales` is the enabled locale list and must include `defaultLocale`.
+- `autoTranslateLabels` defaults to enabled when omitted. Set it to `false` to stop default-locale label edits from creating machine translations for other locales.
+- `autoTranslateContent` does the same for schema entries.
+- `seo.locale` is SEO/html metadata. It does not select the DB locale by itself.
+- Public locale routing is project/framework code. Do not assume `/es/...` exists unless the project has implemented that strategy.
 
 ## Usage
 
@@ -24,20 +51,21 @@ export function Hero() {
   return (
     <section>
       <h1>
-        <Text value={t('hero.title', 'Welcome to Acme')} />
+        <Text value={t('hero.title')} />
       </h1>
       <p>
-        <Text value={t('hero.subtitle', 'The fastest way to ship your idea.')} />
+        <Text value={t('hero.subtitle')} />
       </p>
-      <input placeholder={String(t('hero.emailPlaceholder', 'you@example.com'))} />
-      <img alt={String(t('hero.imageAlt', 'Team collaborating'))} src="..." />
+      <input placeholder={String(t('hero.emailPlaceholder'))} />
+      <img alt={String(t('hero.imageAlt'))} src="..." />
     </section>
   );
 }
 ```
 
-- `t(key, default)` returns a `FimoString` (wrapped for source tracking). Render it via `<Text value={...} />` inside JSX.
+- `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)
 
@@ -45,13 +73,13 @@ export function Hero() {
 
 ```tsx
 // ❌ BAD — variable key
-t(item.key, item.label);
+t(item.key);
 
 // ❌ BAD — template with expression
-t(`nav.${page}`, 'Page');
+t(`nav.${page}`);
 
 // ✅ GOOD — put the t() call where the literal lives
-const items = [{ label: t('nav.home', 'Home') }, { label: t('nav.about', 'About') }];
+const items = [{ label: t('nav.home') }, { label: t('nav.about') }];
 items.map((item) => <li>{item.label}</li>);
 ```
 
@@ -59,7 +87,7 @@ items.map((item) => <li>{item.label}</li>);
 
 - 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`).
-- The default (second arg) is the English copy — make it final, not a TODO; it ships to production if no translation exists for the active locale.
+- Values live in the DB. Do not put user-visible fallback copy in code.
 
 ## What NOT to translate
 
@@ -72,4 +100,4 @@ items.map((item) => <li>{item.label}</li>);
 
 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` (or rely on `fimo deploy` doing it). See `fimo-cli/references/translations.md`.
+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/translations.md`.

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

@@ -17,15 +17,15 @@ Use these to render content-type field values consistently. They carry source me
 | `<Video>`           | Schema `media` video fields                                         | `<Video value={post.heroVideo} />`                            |
 | `<Date>`            | Schema date fields                                                  | `<Date value={post.publishDate} />`                           |
 | `<Boolean>`         | Schema boolean fields                                               | `<Boolean value={product.inStock} />`                         |
-| `` fimo`...` ``     | Compose tracked values (mix `t()` + schema text)                    | ``<Text value={fimo`${t('by','By')} ${post.author}`} />``     |
-| `useTranslations()` | `t('key', 'Default')` hook                                          | see `references/translations.md`                              |
+| `` fimo`...` ``     | Compose tracked values (mix `t()` + schema text)                    | ``<Text value={fimo`${t('by')} ${post.author}`} />``          |
+| `useTranslations()` | `t('key')` hook                                                     | see `references/translations.md`                              |
 
 ### Rules of thumb
 
 1. **Schema text → `<Text>`**, never `<h1>{post.title}</h1>`.
 2. **Schema media → `<Image>` / `<Video>`**, never `<img src={post.coverImage.url} />`. Provide `width` / `height` when known so Fimo can optimize and reserve layout space.
 3. **Non-schema images** (decorative, hard-coded URLs, generated assets referenced directly) → `<StaticImage>`. Never hand-construct a `FimoMedia` to feed `<Image>`.
-4. **Translated text → `<Text value={t('key', 'Default')} />`**, not `<h1>{t(...)}</h1>`. See `references/translations.md`.
+4. **Label text → `<Text value={t('key')} />`**, not `<h1>{t(...)}</h1>`. Label values live in the DB for `i18n.defaultLocale` from `fimo-config.json` unless a non-default locale is explicitly targeted. Public locale routes such as `/es/...` only exist if the project has implemented that routing strategy. See `references/translations.md`.
 5. **Mixed schema + translated text** → the `` fimo`...` `` template literal inside `<Text>`.
 6. **Never hand-roll richtext rendering** — always `<RichText>`. To restyle a node, pass `components={{ heading: ..., link: ..., ... }}`.
 
@@ -77,7 +77,7 @@ The template uses **Vite + React 19 + TypeScript + Tailwind v4 + shadcn/ui + rea
 
 - Raw `<a href>` for internal nav → use `<Link>` / `<NavLink>`.
 - Raw `<img>` for schema media → use `<Image>` (with width/height).
-- Hardcoded strings in JSX → wrap in `t('key', 'Default')`.
+- Hardcoded strings in JSX → wrap in `t('key')` and add the DB value with `fimo labels set`.
 - Calling `t()` with a dynamic first argument → key must be a string literal.
 - Editing generated `.ts` files under `src/schemas/` or `src/forms/` → regenerated on every build.
 - Writing raw HTML into a `richtext` field → must be Tiptap JSONContent.

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

@@ -47,12 +47,12 @@ fimo create my-site --org <id>             # scaffold (writes .fimo.settings.jso
 fimo clone                                 # interactively choose an existing project to clone locally
 cd my-site                                 # the `fimo` project skill auto-loads from here
 fimo credits                               # inspect the owning org's AI credit balance (read-only)
-fimo validate                              # run all checks + sync schemas/forms/translations to DB
+fimo validate                              # run all checks + codegen; fails on missing DB labels
 fimo deploy                                # push to preview (runs validate internally)
 fimo deploy --publish                      # publish live (only when user says "ship it")
 ```
 
-`fimo validate` is the single entrypoint for "make local state match the backend" — it covers schema/form codegen, route metadata checks, lint, and translations sync. The underlying phases are also available individually under the hidden `fimo scripts` namespace for advanced/debug use.
+`fimo validate` is the single entrypoint for "prove this project is ready" — it covers schema/form codegen, route metadata checks, lint, and missing label checks for `i18n.defaultLocale` from `fimo-config.json` (fallback: `en`). Use `fimo labels set` / `set-many` to create or update label values in the DB. The underlying phases are also available individually under the hidden `fimo scripts` namespace for advanced/debug use.
 
 ## Decision Tree
 
@@ -64,7 +64,7 @@ Load the matching reference when the user's request fires its trigger. Recipes t
 - "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/references/assets.md` for the `FimoMedia` shape and rendering**
 - "Generate AI image / video / draft preview / image edit / cover from a prompt" → `references/media.md` (the `fimo generate <model>` surface — recipes, defaults, the one-verb shape) **+ load `fimo/references/assets.md` for the `FimoMedia` shape if you'll plug the result into UI**
-- "Sync translations / extract t() strings to the DB" → `references/translations.md` (workflow) **+ load `fimo/references/translations.md` for the `t()` helper and wrap rules**
+- "Add labels / update static copy / fix missing `t()` values" → `references/translations.md` (workflow) **+ load `fimo/references/translations.md` for the `t()` helper and wrap rules**
 - "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`

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

@@ -71,7 +71,7 @@ Use the canonical read query flags: `--search`, `--sort`, `--where`, `--limit`,
 The `fimo/vite` plugin auto-regenerates `src/schemas/*.ts` on `vite dev` / `vite build`. If you need to regen outside vite (e.g. CI, scripting), use:
 
 ```bash
-fimo validate                  # runs all phases: codegen, lint, route validation, translations sync
+fimo validate                  # runs all phases: codegen, lint, route validation, label checks
 ```
 
 Advanced/internal (hidden from `fimo --help`) — for the bare regen phase:

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

@@ -57,7 +57,7 @@ Use this when the user asks "who filled out the contact form?", "how many signup
 The `fimo/vite` plugin auto-regenerates `src/forms/*.ts`. To regen outside vite, use:
 
 ```bash
-fimo validate                  # runs all phases: codegen, lint, route validation, translations sync
+fimo validate                  # runs all phases: codegen, lint, route validation, label checks
 ```
 
 Advanced/internal (hidden from `fimo --help`) — for the bare regen phase: