fimo 0.9.0 → 0.10.0-staging.1

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

@@ -48,9 +48,9 @@ export interface <%= model.pascal %> extends WithReferences<<%= model.pascal %>R
 // Generate interface properties based on fields
 if (model.fields) {
   Object.entries(model.fields).forEach(([key, field]) => {
-    const type = getTypeForField(field);
+    const type = isNullableRichTextField(field) ? `${getTypeForField(field)} | null` : getTypeForField(field);
 -%>
-  <%= key %>: <%= type %>;
+  <%= key %><%= isOptionalOutputField(field) ? '?' : '' %>: <%= type %>;
 <%
   });
 }
@@ -68,7 +68,9 @@ export interface <%= model.pascal %>Input {
 <%
 if (model.fields) {
   Object.entries(model.fields).forEach(([key, field]) => {
-    const type = getInputTypeForField(field);
+    const type = isNullableRichTextField(field)
+      ? `${getInputTypeForField(field)} | null`
+      : getInputTypeForField(field);
 -%>
   <%= key %><%= isRequiredField(field) ? '' : '?' %>: <%= type %>;
 <%
@@ -85,6 +87,7 @@ if (model.fields) {
 function getTypeForField(field) {
   switch(field.type) {
     case 'string':
+      return getStringLiteralUnion(field) || 'FimoString';
     case 'text':
       return 'FimoString';
     case 'richtext':
@@ -113,6 +116,7 @@ function getTypeForField(field) {
 function getInputTypeForField(field) {
   switch(field.type) {
     case 'string':
+      return getStringLiteralUnion(field) || 'string';
     case 'text':
       return 'string';
     case 'richtext':
@@ -143,6 +147,7 @@ function getInputTypeForField(field) {
 function getNestedFieldType(field, input) {
   switch(field.type) {
     case 'string':
+      return getStringLiteralUnion(field) || 'string';
     case 'text':
       return 'string';
     case 'richtext':
@@ -195,9 +200,31 @@ function getBlocksType(field, input) {
   return `${item}[]`;
 }
 
+function getStringLiteralUnion(field) {
+  if (!Array.isArray(field.options) || field.options.length === 0) {
+    return null;
+  }
+  return field.options.map((option) => JSON.stringify(String(option))).join(' | ');
+}
+
 function isRequiredField(field) {
+  if (isConditionalField(field)) {
+    return false;
+  }
   return Boolean(field.required || (field.type === 'blocks' && Number(field.min || 0) > 0));
 }
+
+function isNullableRichTextField(field) {
+  return field.type === 'richtext' && !isRequiredField(field);
+}
+
+function isOptionalOutputField(field) {
+  return isConditionalField(field) || isNullableRichTextField(field);
+}
+
+function isConditionalField(field) {
+  return field.showIf !== undefined || field.showIfAny !== undefined;
+}
 -%>
 
 export interface <%= model.pascal %>References {

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

@@ -94,9 +94,46 @@ fimo entries query --file query.sql
 cat query.sql | fimo entries query --stdin
 ```
 
-SQL exposes the raw internal representation. `document_id` is the stable ID used by `fimo entries`, content tools, references, and the API. `id` is the internal ID of one exact locale variant. When query results will feed another Fimo command or tool, select `document_id AS id`; use `locale` to select a variant.
+SQL exposes the raw internal representation. `document_id` is the stable ID used by `fimo entries`, content tools, references, and the API. `id` is the internal ID of one exact locale variant. Localized variants share one `document_id` and have one row per locale; non-localized entries have a null `locale`. When query results will feed another Fimo command or tool, select `document_id AS id`; use `locale` to select a variant.
+
+The supported content columns are `id`, `document_id`, `content_type`, `locale`, `slug`, `data`, `created_at`, and `updated_at`. Schema fields live inside the JSONB `data` column. Fimo may add internal columns, so select the fields you need instead of `SELECT *` and do not depend on other columns. If a safe read is blocked because a SQL function is unavailable, tell the user which function is missing and use the built-in `supportReport` tool when the platform gap materially blocks the task. Do not bypass the restriction with a write.
+
+For example, find English blog posts that do not yet have a Spanish variant:
+
+```sql
+SELECT source.document_id AS id, source.data
+FROM entries source
+WHERE source.content_type = 'BlogPost'
+  AND source.locale = 'en'
+  AND NOT EXISTS (
+    SELECT 1
+    FROM entries target
+    WHERE target.content_type = source.content_type
+      AND target.document_id = source.document_id
+      AND target.locale = 'es'
+  )
+```
+
+Find Spanish variants whose English source was edited later:
+
+```sql
+SELECT
+  target.document_id AS id,
+  target.content_type,
+  target.slug,
+  source.updated_at AS source_updated_at,
+  target.updated_at AS target_updated_at
+FROM entries source
+JOIN entries target
+  ON target.content_type = source.content_type
+  AND target.document_id = source.document_id
+WHERE source.locale = 'en'
+  AND target.locale = 'es'
+  AND source.updated_at > target.updated_at
+ORDER BY source.updated_at DESC
+```
 
-The available columns are `id`, `document_id`, `content_type`, `locale`, `slug`, `data`, `created_at`, and `updated_at`. Schema fields live inside the JSONB `data` column. If a safe read is blocked because a SQL function is unavailable, tell the user which function is missing and use the built-in `supportReport` tool when the platform gap materially blocks the task. Do not bypass the restriction with a write.
+Treat these results as possibly stale, not proof of a bad translation. The query only proves that the source row was edited later; an agent should review the content and link each target with its stable `id`.
 
 ### Bulk mutations
 
@@ -150,7 +187,7 @@ Entry bodies use reference objects with target `id` values:
 fimo entries create BlogPost --body '{"data":{"slug":"hello","title":"Hello","author":{"id":"750e8400-e29b-41d4-a716-446655440000"},"contributors":[]}}'
 ```
 
-Do not add `localized` or field-level `i18n` to reference fields. The reference value belongs to the entry variant containing it.
+`localized` is not a supported spelling anywhere. A reference field may carry `"i18n": false` to point every locale of the document at the same target — see Localized and shared content below.
 
 ## Localized and shared content
 
@@ -158,7 +195,42 @@ Schemas are localized by default. Omit `--locale` to use the project default. Pa
 
 When creating a localized variant of an existing entry, pass the source entry's `documentId` with `--document-id`. Keep projects single-locale unless the user asks for multilingual or localized output; when multiple locales are configured, create and update every locale explicitly.
 
-For content shared across locales, define `"i18n": { "enabled": false }` at the schema root and create each entry once. Do not pass `--document-id` to manufacture locale variants. Raw API and CLI responses omit `locale`; generated collection models add the effective active/default locale without creating per-locale variants. No other `i18n` options and no field-level localization settings are supported.
+For content shared across locales, define `"i18n": { "enabled": false }` at the schema root and create each entry once. Do not pass `--document-id` to manufacture locale variants. Raw API and CLI responses omit `locale`; generated collection models add the effective active/default locale without creating per-locale variants. No other schema-root `i18n` options are supported.
+
+### Shared fields inside a localized type
+
+A localized type can still hold fields that are the same in every language. Mark the field `"i18n": false`. Use it for anything that is not translated — a price, a SKU, a product photo, a reference to the same target everywhere. Without it those values are re-entered per locale and drift apart.
+
+```json
+{
+  "uid": "Product",
+  "name": "Products",
+  "fields": {
+    "title": { "type": "string" },
+    "description": { "type": "richtext" },
+    "sku": { "type": "string", "i18n": false, "unique": true },
+    "price": { "type": "number", "i18n": false },
+    "photo": { "type": "media", "i18n": false },
+    "brand": { "type": "reference", "target": "Brand", "i18n": false }
+  }
+}
+```
+
+Writing a shared field through any locale updates every locale of that document:
+
+```bash
+fimo entries update Product <id> --locale es --body '{"data":{"title":"Silla","price":120}}'
+```
+
+That sets the Spanish title and moves the price to `120` for every language. An update that does not mention a shared field leaves it untouched, so partial writes are safe.
+
+Rules:
+
+- `i18n` belongs on top-level scalar and reference fields only. Fields inside `blocks` follow the locale of the entry containing them and are rejected.
+- On a non-localized type the flag is inert — there is one row already.
+- `"i18n": true` is the default and never needs writing.
+
+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 type with exactly one logical document. Generated singleton clients expose `get`/`update` and their React Query hooks, not collection create/remove APIs.
 

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

@@ -81,3 +81,5 @@ Labels and content are separate translated surfaces:
 - content: schema entries, managed with `fimo entries`
 
 Omit `--locale` for default-locale writes. Pass `--locale <locale>` for each non-default localized entry you need to create or update. Shared schemas (`i18n.enabled: false`) have one locale-free entry instead.
+
+Inside a localized schema, a single field can still be shared across every language with `"i18n": false` — use it for values that are not translated, such as a price or a SKU, so they are written once instead of per locale. See `content.md` § Shared fields inside a localized type.

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

@@ -24,6 +24,10 @@ Run this before writing a custom payload. The list shows supported event types,
 - Analytics: `analytics.report_ready`
 - Media: uploaded/updated/deleted/generated/processing_failed
 - Entries: `entry.changed`
+- Domains: `domain.created`, `domain.deleted`
+- Labels: `label.changed`
+- Locales: `locale.created`, `locale.default_changed`, `locale.deleted`
+- Environments: `environment.created`, `environment.deleted`, `environment.merged`, `environment.restored`
 
 Do not guess variable paths. The common envelope is:
 

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

@@ -27,7 +27,21 @@ This file covers the **package surface**: the JSON shape you write, the generate
 
 **Required**: `uid` (PascalCase, matches filename), `name`, `fields`.
 
-`i18n` is an optional type-level policy. Omit it or use `{ "enabled": true }` for localized content. Use `{ "enabled": false }` for one shared entry that appears in every locale, such as an Author, Category, or Settings type. No other `i18n` keys and no field-level localization settings are supported.
+`i18n` is an optional type-level policy. Omit it or use `{ "enabled": true }` for localized content. Use `{ "enabled": false }` for one shared entry that appears in every locale, such as an Author, Category, or Settings type. No other schema-root `i18n` keys are supported.
+
+Inside a localized type, an individual top-level scalar or reference field may carry `"i18n": false`. That field then holds one value for the whole document: writing it through any locale updates all of them. Use it for values that are not translated, such as a price, a SKU, a product photo, or a reference that should point at the same target everywhere. Fields inside `blocks` follow the locale of the entry containing them and reject the flag.
+
+```json
+{
+  "uid": "Product",
+  "name": "Products",
+  "fields": {
+    "title": { "type": "string" },
+    "sku": { "type": "string", "i18n": false },
+    "price": { "type": "number", "i18n": false }
+  }
+}
+```
 
 ### Reserved field names — do NOT declare these in `fields`
 
@@ -61,6 +75,48 @@ something else (e.g. `handle`, `permalink`).
 
 A `date` field currently generates as `any` in the TS client, so for typed access (and the `<Date>` component) prefer a `string` field holding an ISO date — which is what the `publishDate` examples below do.
 
+## Enumerated strings
+
+A `string` field may declare `options` to close its value set. The CMS renders a select, the API validates the value as an enum, and the generated client types the field as a literal union instead of `string`.
+
+```json
+"layout": { "type": "string", "options": ["article", "video"], "default": "article" }
+```
+
+- Values must be unique. Set a `default` that is one of them.
+- `options` cannot be combined with `regex`, `minLength`, or `maxLength`, and is rejected on every field type other than `string`.
+- Writes are validated against the set: a value outside it is rejected with a 400. An optional field also accepts `""` and `null` so the editor can clear the choice; a `required` one only accepts a declared value.
+- Removing an option that entries still hold fails the push, the same way an unsafe type change does. Migrate those entries to a remaining value first.
+
+## Conditional fields
+
+A field may declare `showIf` (every clause must match) or `showIfAny` (one clause is enough) to apply only in some entries. A clause names a sibling field and a value.
+
+```json
+{
+  "layout": { "type": "string", "options": ["article", "video"], "default": "article" },
+  "body": { "type": "richtext", "showIf": { "field": "layout", "equals": "article" } },
+  "videoUrl": { "type": "string", "required": true, "showIf": { "field": "layout", "equals": "video" } },
+  "transcript": {
+    "type": "text",
+    "showIfAny": [
+      { "field": "layout", "equals": "video" },
+      { "field": "hasAudio", "equals": true }
+    ]
+  }
+}
+```
+
+- A clause is `{ "field": "<sibling>", "equals": <value> }` or `{ "field": "<sibling>", "in": [<values>] }`. Use `in` for several values of one field.
+- `showIf` accepts one clause or an array of clauses, and every clause must match. `showIfAny` takes an array and one match is enough. A field declares one key or the other, never both.
+- **A hidden field is not rendered and not validated, so `required` does not apply to it.** An entry whose condition never held can be saved without ever filling the field.
+- **Hiding a field changes nothing about storage or reads.** The value stays in the entry and the API keeps returning it, so an editor who flips the trigger back gets their work back. Narrow on the trigger in site code rather than trusting the value.
+- Because a conditional field can be absent, it is always optional in the generated types even when `required` is set.
+- Conditions resolve against siblings in the same object. A field inside a block variant may only reference fields in that same block item.
+- A clause may reference a `boolean`, `number`, or `string` field. A `string` trigger must declare `options`, which is what lets `fimo validate` reject a clause value that could never match.
+- A trigger cannot itself be conditional — conditions are one level deep, so a chain like A shows B shows C is rejected.
+- `fimo validate` and `fimo schemas push` reject an unknown trigger name, a trigger of the wrong type, a value outside the trigger's `options`, and a trigger that is itself conditional.
+
 ## Blocks
 
 `blocks` is the only nested structured-content type and always stores an array. Use `schema.fields` for one homogeneous block shape. Set `max: 1` when the field is a single optional group. Use `schema.oneOf` when editors choose a variant for each item.
@@ -139,7 +195,7 @@ Rules:
 - Self-references are allowed, e.g. a `Category` schema can have `parent: { "type": "reference", "target": "Category" }`.
 - Entry values use the target's stable `id`, never the variant `entryId`: `{ "id": "..." }`.
 - Do not include `contentType` for normal fixed-target references; the schema's `target` already defines it.
-- Do not add `localized` or field-level `i18n` to a reference. The reference value belongs to the entry variant that stores it.
+- `localized` is not a supported spelling. A reference may carry `"i18n": false` so every locale of the document points at the same target; without it the reference belongs to the entry variant that stores it.
 - Use `null` for an empty to-one reference and `[]` for an empty to-many reference.
 - The API validates that referenced target documents exist and rejects duplicate values in to-many reference arrays.
 
@@ -272,7 +328,7 @@ interface BlogPost {
   };
   title: FimoString;
   summary: FimoString;
-  body: FimoRichText;
+  body?: FimoRichText | null;
   coverImage: FimoMedia;
   publishDate: FimoString;
   featured: FimoBoolean;
@@ -282,6 +338,8 @@ 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`.
 
+Optional richtext fields are nullable in generated read and write types. `<RichText>` accepts the generated value directly and renders nothing when it is null or undefined. A non-conditional required richtext field stays non-null; conditional fields remain optional because their condition may not apply.
+
 ## Localized and shared content
 
 Localized content has one variant per locale. Generated hooks read the active Fimo locale automatically.
@@ -296,7 +354,7 @@ For shared content, set `i18n: { "enabled": false }` on the schema and create ea
 - ignore locale on owner reads and writes;
 - still use the active/requested locale when a populated reference targets a localized schema.
 
-Do not duplicate shared entries across locales or add field-level localization settings.
+Do not duplicate shared entries across locales. This section is about a whole type being shared; a single shared field inside a localized type is the separate `"i18n": false` field flag described above.
 
 A populated reference whose target has no variant in the requested locale resolves to null. Reads accept an opt-in `localeFallbacks: true` that resolves those to the best available variant instead (project default first), marked by its `locale` field — never implement fallbacks by hand; public reads stay strict unless the option is passed.
 

package/assets/skills/fimo-studio/references/cms.md

@@ -36,6 +36,17 @@ When you open a Collection, the entry list provides several tools:
 - **Columns** dropdown (the eye button) next to the search bar to show/hide columns and reorder them by dragging each column row by its grip handle.
 - **Pagination** at the bottom when there are many entries.
 
+## Completing Missing Translations
+
+Localized Collections show only entries for the locale selected beside the Collection name. When that locale is missing translations that exist in the project's default locale:
+
+1. Click the amber **N missing** warning beside the locale selector.
+2. Review the source and target languages in the popover.
+3. Choose **Create missing translations**.
+4. Review or edit the prompt placed in AI chat, then send it when ready.
+
+Fimo does not send the prompt automatically. After the AI finishes, translated entries appear in the selected locale and the warning updates.
+
 ## Creating a New Entry
 
 1. Navigate to the Collection you want to add content to.
@@ -53,6 +64,8 @@ Your edits save automatically as you change each field (the save is debounced),
 
 If a field is invalid, the editor keeps the change unsaved and pins a status bar below the header. Choose **Review issues** to jump to the first invalid field, then **Next issue** to move through the remaining fields. Collapsed blocks open automatically. Once every issue is fixed, the editor confirms that all fields are valid and resumes saving.
 
+A field labelled with a padlocked globe is shared across languages: it holds one value for the whole entry, so editing it in any language changes it in all of them. Fields without that marker are per language and only affect the language you are editing. Hover the icon for the same explanation in context.
+
 ## Editing Text
 
 - Short text such as titles, names, and slugs uses one compact line.

package/assets/skills/fimo-studio/references/webhooks.md

@@ -15,7 +15,7 @@ Only project members with Full Access can see Webhooks in Settings or manage its
 5. Optionally narrow form, agent, media, or entry events with the filter shown for that event.
 6. Review the request and select **Save**.
 
-The event groups are Entries, Forms, Publish, Agents, Analytics, and Media. Webhooks belong to the project, with up to 20 configurations. They listen to main by default or can include every environment.
+The event groups are Entries, Forms, Publish, Agents, Analytics, Media, Domains, Labels, Locales, and Environments. Webhooks belong to the project, with up to 20 configurations. They listen to main by default or can include every environment.
 
 Entry webhooks show **Combine rapid changes**. The default waits 5 seconds after direct editing stops and sends one delivery with the combined changes. Immediate, 30-second, and 1-minute windows are also available. Bulk edits and environment merges already produce batches and send immediately.
 

package/dist/cli/bundle.json

@@ -1,7 +1,7 @@
 {
   "bundled": true,
   "bundler": "esbuild",
-  "bundledAt": "2026-07-24T11:14:53.290Z",
+  "bundledAt": "2026-07-27T07:55:40.361Z",
   "cliVersion": "0.9.0",
   "external": [
     "oxc-parser",