fimo 2.10.1-staging.1 → 2.10.1-staging.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/assets/skills/fimo-cli/SKILL.md +57 -139
  2. package/assets/skills/fimo-cli/SKILL.studio.md +42 -0
  3. package/assets/skills/fimo-cli/references/branches.md +43 -106
  4. package/assets/skills/fimo-cli/references/content/bulk.md +48 -0
  5. package/assets/skills/fimo-cli/references/content/entries.md +54 -0
  6. package/assets/skills/fimo-cli/references/content/localized.md +56 -0
  7. package/assets/skills/fimo-cli/references/content/schemas.md +29 -0
  8. package/assets/skills/fimo-cli/references/content/sql.md +57 -0
  9. package/assets/skills/fimo-cli/references/content.md +33 -272
  10. package/assets/skills/fimo-cli/references/deploy.md +35 -126
  11. package/assets/skills/fimo-cli/references/domains.md +38 -131
  12. package/assets/skills/fimo-cli/references/forms.md +1 -1
  13. package/assets/skills/fimo-cli/references/init.md +36 -170
  14. package/assets/skills/fimo-cli/references/locales.md +2 -2
  15. package/assets/skills/fimo-cli/references/projects.md +1 -1
  16. package/assets/skills/fimo-code/references/design.md +42 -126
  17. package/assets/skills/fimo-migration/SKILL.md +114 -408
  18. package/assets/skills/fimo-migration/references/content-delivery.md +67 -0
  19. package/assets/skills/fimo-migration/references/frameworks/nextjs.md +1 -1
  20. package/assets/skills/fimo-migration/references/qa/browser.md +41 -0
  21. package/assets/skills/fimo-migration/references/qa/guardrails.md +95 -0
  22. package/assets/skills/fimo-migration/references/qa/results.md +78 -0
  23. package/assets/skills/fimo-migration/references/qa.md +102 -383
  24. package/assets/skills/fimo-migration/references/questions-and-improvements.md +77 -168
  25. package/assets/skills/fimo-migration/references/setup.md +90 -0
  26. package/assets/skills/fimo-migration/references/workers/validator.md +2 -2
  27. package/assets/skills/fimo-migration/references/workers.md +1 -1
  28. package/assets/skills/fimo-migration/references/workflow.md +117 -171
  29. package/assets/skills/fimo-studio/SKILL.md +12 -11
  30. package/assets/skills/fimo-studio/references/ai-chat/agents.md +46 -0
  31. package/assets/skills/fimo-studio/references/ai-chat/default-agents.md +57 -0
  32. package/assets/skills/fimo-studio/references/ai-chat/routines.md +53 -0
  33. package/assets/skills/fimo-studio/references/ai-chat.md +39 -76
  34. package/assets/skills/fimo-studio/references/custom-domains.md +2 -2
  35. package/assets/skills/fimo-studio/references/publish-and-deploy.md +1 -1
  36. package/dist/cli/bundle.json +1 -1
  37. package/dist/cli/index.js +38 -17
  38. package/package.json +8 -8
  39. package/templates/astro/package.json +3 -3
  40. package/templates/nextjs/package.json +4 -4
  41. package/templates/react-router/package.json +5 -5
  42. package/templates/sveltekit/package.json +3 -3
  43. package/templates/vite/package.json +5 -5
@@ -0,0 +1,56 @@
1
+ # Localized and shared content
2
+
3
+ Load this page to add a locale variant of an entry, or to work with fields or types that are the same in every language.
4
+
5
+ ## Locale variants
6
+
7
+ Schemas are localized by default. Without `--locale`, a command uses the project default locale. To read, update, or delete another variant, pass `--locale`: an entry is its stable `id` plus a `locale`.
8
+
9
+ To add a variant of an existing entry, create it with the source entry's `documentId`:
10
+
11
+ ```bash
12
+ fimo entries list Story --where '{"slug":"spring-notes"}' --fields slug,title # gives "id" and "documentId"
13
+ fimo entries create Story --locale es --document-id <documentId> --body '{"data":{"title":"Notas de primavera"}}'
14
+ ```
15
+
16
+ - When the create names a missing shared (`"i18n": false`) field, send its current value: a shared value applies to every locale.
17
+ - Keep a project single-locale unless the user asks for more languages. When the project has more locales, create and update each locale explicitly.
18
+ - To find missing or stale translations, use SQL (`--ref content/sql`).
19
+
20
+ ## Non-localized types
21
+
22
+ For content that is the same in every locale, set `"i18n": { "enabled": false }` at the schema root and create each entry once. Do not pass `--document-id` to make locale variants. Raw API and CLI responses then omit `locale`; generated collection models add the active or default locale, with no per-locale variants. The schema root accepts no other `i18n` options.
23
+
24
+ ## Shared fields in a localized type
25
+
26
+ Mark a field `"i18n": false` when its value is not translated, such as a price, a SKU, a product photo, or a reference to the same target. Without it, editors enter the value once per locale, and the values drift apart.
27
+
28
+ ```json
29
+ {
30
+ "uid": "Product",
31
+ "name": "Products",
32
+ "fields": {
33
+ "title": { "type": "string" },
34
+ "description": { "type": "richtext" },
35
+ "sku": { "type": "string", "i18n": false, "unique": true },
36
+ "price": { "type": "number", "i18n": false },
37
+ "photo": { "type": "media", "i18n": false },
38
+ "brand": { "type": "reference", "target": "Brand", "i18n": false }
39
+ }
40
+ }
41
+ ```
42
+
43
+ A write to a shared field through any locale changes it in every locale of the document:
44
+
45
+ ```bash
46
+ fimo entries update Product <id> --locale es --body '{"data":{"title":"Silla","price":120}}'
47
+ ```
48
+
49
+ This sets the Spanish title, and sets the price to `120` in every language. An update that does not name a shared field does not change it.
50
+
51
+ - Only top-level scalar and reference fields accept `i18n`. Fields inside `blocks` follow the locale of their entry, and the push rejects `i18n` on them.
52
+ - On a non-localized type, the flag has no effect.
53
+ - `"i18n": true` is the default. Do not write it.
54
+ - `localized` is not a valid key anywhere.
55
+
56
+ **Making a field with content shared deletes data** when the languages hold different values. The push keeps the default-locale value of each document and discards the others, with no prompt and no undo. Before you add `"i18n": false` to a field that has content, tell the user what happens. If you are not sure, check whether the languages differ.
@@ -0,0 +1,29 @@
1
+ # Schema commands and changes
2
+
3
+ Load this page to change a schema that already has content, or to list, read, or delete schemas. The schema JSON itself is in fimo-code `content/schema`.
4
+
5
+ ```bash
6
+ fimo schemas push [<Type>] # create or update from src/schemas; no type pushes all
7
+ fimo schemas push <Type> --rename <old.path>=<new.path> # repeat --rename for each moved field
8
+ fimo schemas list
9
+ fimo schemas get <Type> [--json]
10
+ fimo schemas delete <Type>
11
+ ```
12
+
13
+ - The command is `fimo schemas` (plural). There is no `fimo schema`.
14
+ - A push of all schemas sends them as one atomic batch, so types that reference each other, also in a cycle, can go in one push.
15
+ - A push never deletes a schema whose file is missing. Use `fimo schemas delete <Type>`.
16
+ - Blocks allow at most 7 nested levels, 40 variants in one `schema.oneOf`, and 200 items per blocks field (`min` and `max`).
17
+
18
+ ## What a push does to existing content
19
+
20
+ Fimo migrates content on push. A failed push changes nothing.
21
+
22
+ - Adding an optional field and changing labels keep all content.
23
+ - A new required field fills its `default` only where existing values need it. When no default can satisfy the existing content, the push fails.
24
+ - Removing a nested field or a block variant removes only those values.
25
+ - `string` and `text` values convert both ways. Other type changes convert safe values and reject unsafe ones, with no change to the schema or entries.
26
+ - Lowering a blocks `max` trims items from the end. Raising `min` adds items from the blocks `default` templates.
27
+ - Changing a reference target clears its links.
28
+ - When a field moves to a new name, pass `--rename old.path=new.path` so the one-time migration keeps its values. The rename is not stored in the schema JSON.
29
+ - Collection to Single removes the entries of that type and cleans the references to them. Single to collection keeps its entry.
@@ -0,0 +1,57 @@
1
+ # Read-only SQL over entries
2
+
3
+ Use `fimo entries query` when SQL is clearer than list filters, for example to group, count, or compare entries across types and locales.
4
+
5
+ ```bash
6
+ fimo entries query --sql "SELECT content_type, count(*) AS total FROM entries GROUP BY content_type"
7
+ fimo entries query --sql "SELECT document_id AS id, data->>'title' AS title FROM entries WHERE content_type = 'BlogPost' LIMIT 20"
8
+ fimo entries query --file query.sql
9
+ cat query.sql | fimo entries query --stdin
10
+ ```
11
+
12
+ `fimo entries query --help` lists the columns and limits. Rows that feed another command select `document_id AS id`.
13
+
14
+ ## Rules
15
+
16
+ - Common aggregate, JSON, text, date, and window functions work. A query needs content view access.
17
+ - **Never use SQL for content writes.** The API rejects them, because a SQL write skips schema validation, locale and reference handling, content-change events, and webhooks. Use `entries create`, `entries update`, `entries delete`, or their bulk variants (`--ref content/bulk`).
18
+ - If a safe read needs a SQL function that is not available, tell the user which function is missing, and use the `supportReport` tool when that gap blocks the task. Do not work around it with a write.
19
+
20
+ ## Examples
21
+
22
+ English blog posts that have no Spanish variant:
23
+
24
+ ```sql
25
+ SELECT source.document_id AS id, source.data
26
+ FROM entries source
27
+ WHERE source.content_type = 'BlogPost'
28
+ AND source.locale = 'en'
29
+ AND NOT EXISTS (
30
+ SELECT 1
31
+ FROM entries target
32
+ WHERE target.content_type = source.content_type
33
+ AND target.document_id = source.document_id
34
+ AND target.locale = 'es'
35
+ )
36
+ ```
37
+
38
+ Spanish variants whose English source changed later:
39
+
40
+ ```sql
41
+ SELECT
42
+ target.document_id AS id,
43
+ target.content_type,
44
+ target.slug,
45
+ source.updated_at AS source_updated_at,
46
+ target.updated_at AS target_updated_at
47
+ FROM entries source
48
+ JOIN entries target
49
+ ON target.content_type = source.content_type
50
+ AND target.document_id = source.document_id
51
+ WHERE source.locale = 'en'
52
+ AND target.locale = 'es'
53
+ AND source.updated_at > target.updated_at
54
+ ORDER BY source.updated_at DESC
55
+ ```
56
+
57
+ These rows are possibly stale, not proof of a bad translation: the query shows only that the source changed later. Review the content, and use each row's `id` to update the variant.
@@ -1,286 +1,47 @@
1
- # Content workflow (schemas + Singles + entries)
1
+ # Content: schemas, Singles, and entries
2
2
 
3
- > Package contract: load the version-locked `fimo-code` skill with `fimo skills get fimo-code`, then fetch its nested content and detected-framework references for schema JSON, entry values, generated clients, and imports.
3
+ This page covers the CLI workflow. The `fimo-code` skill has the schema JSON and reference values (fimo-code `content/schema`), and the rich text and media values (fimo-code `content/richtext`). Load one with `fimo skills get fimo-code --ref <name>`. For page routes that Studio shows, load `--ref pages`.
4
4
 
5
- This file covers the **CLI workflow** for content schemas, Singles, and entries. Use it when the user wants to add a content type (blog, products, reusable content) or manage content records. For route metadata shown in Studio Pages, load `references/pages.md`.
5
+ ## Choose the write path
6
6
 
7
- ## Choose the write path first
7
+ - One homepage, settings document, About page, or campaign page → a Single: set `"isSingleton": true` and write it with `fimo singles update`.
8
+ - Repeated posts, products, team members, or other records → a collection: write rows with `fimo entries create`.
8
9
 
9
- - Exactly one homepage, settings document, About page, or campaign page → declare `"isSingleton": true` and write it with `fimo singles update <TypeName>`.
10
- - Repeated posts, products, team members, or other reusable records → keep a collection and create rows with `fimo entries create <TypeName>`.
10
+ `entries` and `singles` are different commands. When `fimo entries create` rejects a Single, use `fimo singles update`. Do not remove `isSingleton`.
11
11
 
12
- Never remove `isSingleton: true` merely because `fimo entries create` rejects the type. `entries` and `singles` are separate command namespaces; inspect `fimo singles --help` when the content is one-off.
12
+ ## Add a content type (for example, a blog)
13
13
 
14
- ## Flow
14
+ 1. Write `src/schemas/<Uid>.json` with a PascalCase name, for example `BlogPost.json`, as fimo-code `content/schema` shows. Do not declare `slug`, `id`, `entryId`, `documentId`, `locale`, `createdAt`, `updatedAt`, or `__fimo`: every entry already has them.
15
+ 2. Run `fimo schemas push <Uid>`. It registers the schema and generates the public modules for the framework. Push changes before you build against them. A push does not validate the whole project: run `fimo validate` too.
16
+ 3. If entries need cover images, generate them first with `fimo image generate` (`--ref media`).
17
+ 4. Write the entries (next section).
18
+ 5. Build the page with the generated clients and primitives: fimo-code `ui`, `labels`, and the detected framework reference. App code imports the generated public modules, never `.types.ts`.
15
19
 
16
- 1. Write `src/schemas/{Uid}.json` — PascalCase filename (e.g. `BlogPost.json`). Run `fimo skills get fimo-code --ref content/schema` to decide what becomes editor-managed content (Single, collection, blocks, references, labels, or `json`) and for the JSON contract.
17
- 2. Run `fimo schemas push {Uid}`. It registers the schema and generates the framework-specific public modules. It does not run whole-project validation.
18
- 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.
19
- 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`).
20
- 5. Render tracked fields with the detected framework's Fimo primitives.
21
-
22
- Steps 1, 3, and 5 use `fimo-code`; steps 2 and 4 are CLI workflows documented here.
23
-
24
- ## Schema CLI commands
25
-
26
- ```bash
27
- fimo schemas push [TypeName] # push JSON to API (create or update). Omit TypeName to push all.
28
- fimo schemas push <TypeName> --rename old.path=new.path
29
- # preserve a renamed field; repeat --rename for multiple fields.
30
- # Pushing all sends every schema as ONE atomic batch, so types that
31
- # reference each other (even cycles) can be added in a single push.
32
- # Files not present are never deleted — use `schemas delete` for that.
33
- fimo schemas list # list all registered schemas
34
- fimo schemas get <TypeName> # get a single schema
35
- fimo schemas delete <TypeName> # delete a schema
36
- ```
37
-
38
- The command is `fimo schemas` (plural). There is no singular `fimo schema` alias.
39
-
40
- All commands accept `-C, --cwd <dir>` to point at a different project directory.
41
-
42
- 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 `fimo skills get fimo-code --ref content/schema` for the complete blocks JSON shape.
43
-
44
- 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.
45
-
46
- ## Singles CLI commands
47
-
48
- Use Singles for one-off content such as a homepage, site settings, or an About story. The type name identifies the content, so these commands do not take an entry ID.
49
-
50
- ```bash
51
- fimo singles get <TypeName> [--locale es] [--populate FIELDS]
52
- fimo singles update <TypeName> [--locale es] (--body '<json>' | --file <path> | --stdin)
53
- ```
54
-
55
- The update payload uses the regular `{ "data": { ... } }` content body. Pass exactly one input source:
56
-
57
- ```bash
58
- fimo singles update Story --body '{"data":{"title":"Our story"}}'
59
- fimo singles update Story --file story-body.json
60
- cat story-body.json | fimo singles update Story --stdin
61
- ```
62
-
63
- The first update creates the Single's content; later updates change it. Use `--locale` for localized variants.
64
-
65
- ## Entries CLI commands
66
-
67
- Use singular commands for one entry. Bulk create and per-entry bulk update also accept JSON files or stdin.
68
-
69
- ```bash
70
- fimo entries create <TypeName> --body '<json>'
71
- fimo entries create <TypeName> --locale es --document-id <documentId> --body '<json>'
72
- fimo entries list <TypeName> [--limit N] [--cursor CURSOR] [--all-pages] [--search Q] [--where JSON] [--sort F] [--fields FIELDS] [--populate FIELDS]
73
- fimo entries list <TypeName> --locale es
74
- fimo entries get <TypeName> <id> [--locale es] [--populate FIELDS]
75
- fimo entries update <TypeName> <id> [--locale es] --body '<json>'
76
- fimo entries delete <TypeName> <id> [--locale es]
77
- fimo entries query (--sql '<select>' | --file <path> | --stdin)
78
- fimo entries bulk-create <TypeName> (--body '<json-array>' | --file <path> | --stdin)
79
- fimo entries bulk-update <TypeName> (--ids <id1>,<id2> | --where '<json>') --body '<json>'
80
- fimo entries bulk-update <TypeName> (--file <path> | --stdin)
81
- fimo entries bulk-delete <TypeName> (--ids <id1>,<id2> | --where '<json>') [--locale es]
82
- ```
83
-
84
- `create` and `update` require `--body` with a `data` envelope. The content type is positional. For JSON files, use `bulk-create` or `bulk-update` with their documented array formats.
85
-
86
- ```bash
87
- fimo entries create BlogPost --body '{"data":{"slug":"hello","title":"Hello"}}'
88
- fimo entries update BlogPost <id> --body '{"data":{"title":"Updated"}}'
89
- fimo entries list BlogPost --where '{"slug":"hello"}'
90
- ```
91
-
92
- For `get`, `update`, and `delete`, use the UUID returned as `id` by create/list. To find an entry by slug, filter with `list --where` as above, then use its `id`.
93
-
94
- Run `fimo 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.
95
-
96
- `entries list` accepts the same read query surface as generated hooks:
97
-
98
- ```bash
99
- fimo entries list BlogPost --where '{"featured":true}' --sort -publishedAt
100
- fimo entries list BlogPost --where '{"rank":{"$gte":3}}' --sort rank
101
- fimo entries list BlogPost --where '{"__fimo":{"contentType":{"$eq":"BlogPost"}}}'
102
- fimo entries list BlogPost --search "launch"
103
- fimo entries list BlogPost --limit 10 --cursor <next-cursor> --sort title
104
- fimo entries list BlogPost --fields slug,title,excerpt,coverImage --sort -publishedAt --limit 12
105
- fimo entries list BlogPost --fields slug,title,author --populate author
106
- ```
107
-
108
- Use the canonical read query flags: `--search`, `--sort`, `--where`, `--limit`, `--cursor`, `--all-pages`, `--fields`, and `--populate`. `--offset` remains a compatibility alias for existing scripts.
109
- `--where` is a JSON object keyed by schema field name. Simple values mean equality and stay typed inside the JSON (`{"featured":true}`, `{"category":"react"}`, `{"rank":{"$gte":3}}`); operator objects support `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$contains`, `$startsWith`, and `$null`, subject to the field type. Public Fimo-owned metadata lives under `__fimo`; currently `__fimo.contentType` is filterable.
110
-
111
- Reference filters take the target `id` string (`{"author":"750e..."}`). On a to-many field, `$eq` and `$contains` mean membership, `$in` means any listed target is present, `$ne` and `$nin` mean none are present, and `$null: true` means empty or missing. Reference fields cannot be sorted; use `--sort field` / `--sort -field` on scalar fields.
112
- `--fields` is a comma-separated projection for list payloads. The API always keeps `id`, `entryId`, `documentId`, and `locale`; pass only the other fields your view needs, such as `slug,title,excerpt,coverImage`.
113
-
114
- `--populate` is a comma-separated list of top-level fields to embed, on `entries list`, `entries get`, and `singles get`. It accepts reference fields, media fields, and blocks fields that contain media; naming a blocks field populates every media value inside it. Nested paths such as `sections.image` are not supported, and other field types return 400. Run `fimo schemas get <TypeName> --json` to inspect field names and types. Without it, reference fields return `{ "id": "..." }` and media fields return the stored `{ "source", "id", "url", "alt" }`; with `--populate author,cover`, `author` returns the target entry for the requested locale and `cover` adds the asset's current `name`, `mime`, `width`, and `height`. Populate never selects which target fields come back. A populated target missing in the requested locale resolves to null unless you pass `localeFallbacks=true`, which falls back to the best available locale variant, marked by its `locale` field. Limits: 200 references per to-many write, 500 distinct populated documents per field per request (400 past either).
115
-
116
- 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. Fixed and polymorphic references also work inside blocks with these same write shapes (`id`, `documentId`, or `slug` selectors), but nested fields cannot be populated or filtered.
117
-
118
- 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 `fimo skills get fimo-code --ref content/clients`. Writes use `BlogPostInput`.
119
-
120
- ### Read-only SQL
121
-
122
- Use `entries query` when SQL is clearer than list filters, especially for grouping and aggregation. It requires content view access, accepts one `SELECT` statement, can only read the `entries` table, and supports common aggregation, JSON, text, date, and window functions. Queries time out after five seconds and return at most 1,000 rows.
123
-
124
- **Never use SQL for content writes.** SQL writes are rejected because they would bypass schema validation, locale and reference handling, content-change events, and current or future webhooks. Use `entries create`, `entries update`, `entries delete`, or their bulk variants so every mutation follows the content domain path.
125
-
126
- ```bash
127
- fimo entries query --sql "SELECT content_type, count(*) AS total FROM entries GROUP BY content_type"
128
- fimo entries query --sql "SELECT document_id AS id, data->>'title' AS title FROM entries WHERE content_type = 'BlogPost' LIMIT 20"
129
- fimo entries query --file query.sql
130
- cat query.sql | fimo entries query --stdin
131
- ```
132
-
133
- 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.
134
-
135
- 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.
136
-
137
- For example, find English blog posts that do not yet have a Spanish variant:
138
-
139
- ```sql
140
- SELECT source.document_id AS id, source.data
141
- FROM entries source
142
- WHERE source.content_type = 'BlogPost'
143
- AND source.locale = 'en'
144
- AND NOT EXISTS (
145
- SELECT 1
146
- FROM entries target
147
- WHERE target.content_type = source.content_type
148
- AND target.document_id = source.document_id
149
- AND target.locale = 'es'
150
- )
151
- ```
152
-
153
- Find Spanish variants whose English source was edited later:
154
-
155
- ```sql
156
- SELECT
157
- target.document_id AS id,
158
- target.content_type,
159
- target.slug,
160
- source.updated_at AS source_updated_at,
161
- target.updated_at AS target_updated_at
162
- FROM entries source
163
- JOIN entries target
164
- ON target.content_type = source.content_type
165
- AND target.document_id = source.document_id
166
- WHERE source.locale = 'en'
167
- AND target.locale = 'es'
168
- AND source.updated_at > target.updated_at
169
- ORDER BY source.updated_at DESC
170
- ```
171
-
172
- 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`.
173
-
174
- ### Bulk mutations
175
-
176
- `bulk-create` takes an array of regular create bodies. Inline JSON, a file, and stdin all carry the same array shape:
177
-
178
- ```bash
179
- fimo entries bulk-create BlogPost --body '[{"data":{"title":"First"}},{"data":{"title":"Second"},"locale":"es"}]'
180
- fimo entries bulk-create BlogPost --file posts.json
181
- cat posts.json | fimo entries bulk-create BlogPost --stdin
182
- ```
183
-
184
- `bulk-update` applies the regular update body to explicit IDs or the normal `--where` filter:
185
-
186
- ```bash
187
- fimo entries bulk-update BlogPost --ids <id1>,<id2> --body '{"data":{"status":"published"}}'
188
- fimo entries bulk-update BlogPost --where '{"status":"draft"}' --body '{"data":{"status":"published"}}'
189
- ```
190
-
191
- For different changes per entry, `--file` and `--stdin` accept an array of `{ "id", "body" }` records:
192
-
193
- ```json
194
- [
195
- { "id": "<id1>", "body": { "data": { "status": "published" } } },
196
- { "id": "<id2>", "body": { "data": { "featured": true } } }
197
- ]
198
- ```
199
-
200
- ```bash
201
- fimo entries bulk-update BlogPost --file updates.json
202
- cat updates.json | fimo entries bulk-update BlogPost --stdin
203
- fimo entries bulk-delete BlogPost --ids <id1>,<id2>
204
- fimo entries bulk-delete BlogPost --where '{"archived":true}'
205
- ```
206
-
207
- 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.
208
-
209
- For reference schema JSON and entry value shape, run `fimo skills get fimo-code --ref content/schema`. The short version:
210
-
211
- ```json
212
- {
213
- "fields": {
214
- "author": { "type": "reference", "target": "Author" },
215
- "contributors": { "type": "reference", "target": "Author", "many": true }
216
- }
217
- }
218
- ```
219
-
220
- Entry bodies use reference objects with target `id` values:
20
+ ## Write entries and Singles
221
21
 
222
22
  ```bash
223
- fimo entries create BlogPost --body '{"data":{"slug":"hello","title":"Hello","author":{"id":"750e8400-e29b-41d4-a716-446655440000"},"contributors":[]}}'
23
+ fimo entries create <Type> --body '{"data":{"slug":"hello","title":"Hello"}}'
24
+ fimo entries list <Type> --where '{"slug":"hello"}' # find an entry by slug; use its "id"
25
+ fimo entries get <Type> <id> [--locale es] [--populate author,cover]
26
+ fimo entries update <Type> <id> [--locale es] --body '{"data":{"title":"Updated"}}'
27
+ fimo entries delete <Type> <id> [--locale es]
28
+ fimo entries query --sql "SELECT ... FROM entries WHERE content_type = '<Type>'" # read-only: --ref content/sql
29
+ fimo singles get <Type> [--locale es]
30
+ fimo singles update <Type> [--locale es] (--body '<json>' | --file <path> | --stdin)
224
31
  ```
225
32
 
226
- `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.
227
-
228
- ## Localized and shared content
229
-
230
- Schemas are localized by default. Omit `--locale` to use the project default. Pass it explicitly when reading, updating, or deleting a non-default variant: public identity is stable `id` plus `locale`.
231
-
232
- 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.
233
-
234
- 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.
235
-
236
- ### Shared fields inside a localized type
237
-
238
- 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.
239
-
240
- ```json
241
- {
242
- "uid": "Product",
243
- "name": "Products",
244
- "fields": {
245
- "title": { "type": "string" },
246
- "description": { "type": "richtext" },
247
- "sku": { "type": "string", "i18n": false, "unique": true },
248
- "price": { "type": "number", "i18n": false },
249
- "photo": { "type": "media", "i18n": false },
250
- "brand": { "type": "reference", "target": "Brand", "i18n": false }
251
- }
252
- }
253
- ```
254
-
255
- Writing a shared field through any locale updates every locale of that document:
256
-
257
- ```bash
258
- fimo entries update Product <id> --locale es --body '{"data":{"title":"Silla","price":120}}'
259
- ```
260
-
261
- 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.
262
-
263
- Rules:
264
-
265
- - `i18n` belongs on top-level scalar and reference fields only. Fields inside `blocks` follow the locale of the entry containing them and are rejected.
266
- - On a non-localized type the flag is inert — there is one row already.
267
- - `"i18n": true` is the default and never needs writing.
268
-
269
- 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.
270
-
271
- 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.
272
-
273
- ## "Add a blog" recipe
33
+ - `--body` is always a `{"data":{...}}` envelope, also for `singles update`. Put `slug` inside `data`.
34
+ - Before you write a body, load fimo-code `content/richtext`. Rich text is Tiptap JSON (`{"type":"doc","content":[...]}`), a reference is `{"id":"<id>"}`, and media has its own shape.
35
+ - `get`, `update`, and `delete` take the `id` (a UUID) that `create` and `list` return. Never pass a slug as the id.
36
+ - `update` and `singles update` change only the top-level fields in `data`; each field you send replaces its old value. The first `singles update` for a locale creates the Single, so it needs every required field.
37
+ - The project default locale applies when you omit `--locale`.
274
38
 
275
- 1. Run `fimo skills get fimo-code --ref content/schema` for the JSON shape and field types.
276
- 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.
277
- 3. Run `fimo schemas push BlogPost`.
278
- 4. Generate cover images: `fimo image generate --prompt "..." --aspect-ratio 16:9` (see `media.md`).
279
- 5. Seed entries: `fimo entries create BlogPost --body '{"data": {"slug": "first-post", "title": "...", "coverImage": {...}}}'`.
280
- 6. Run `fimo skills get fimo-code --ref ui` and load the detected framework reference for rendering primitives.
281
- 7. Run `fimo skills get fimo-code --ref labels` and load the detected framework reference for labels.
282
- 8. Load the detected framework reference, then build the page with its generated server or client surface.
39
+ **Never write content with SQL.** SQL is read-only. Write with the commands above or their bulk forms.
283
40
 
284
- ## Non-interactive use
41
+ ## Load the page for the task
285
42
 
286
- All `fimo schemas *`, `fimo singles *`, and `fimo entries *` commands run non-interactively without extra flags (they don't prompt). Just pass the arguments documented above.
43
+ - Filter, sort, search, select fields, populate references or media, reference values → `--ref content/entries`
44
+ - Count, group, or compare entries across types or locales with read-only SQL → `--ref content/sql`
45
+ - Create, update, or delete many entries in one command, or from a JSON file → `--ref content/bulk`
46
+ - Add a translation (locale variant), shared `"i18n": false` fields, non-localized types → `--ref content/localized`
47
+ - Rename a field, add a required field, change a type, or delete a schema → `--ref content/schemas`