fimo 2.10.1-staging.1 → 2.10.1-staging.2
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.
- package/assets/skills/fimo-cli/SKILL.md +57 -139
- package/assets/skills/fimo-cli/references/content/bulk.md +57 -0
- package/assets/skills/fimo-cli/references/content/entries.md +54 -0
- package/assets/skills/fimo-cli/references/content/localized.md +56 -0
- package/assets/skills/fimo-cli/references/content/schemas.md +29 -0
- package/assets/skills/fimo-cli/references/content/sql.md +64 -0
- package/assets/skills/fimo-cli/references/content.md +33 -272
- package/assets/skills/fimo-cli/references/forms.md +1 -1
- package/assets/skills/fimo-cli/references/init.md +1 -1
- package/assets/skills/fimo-cli/references/locales.md +2 -2
- package/assets/skills/fimo-studio/SKILL.md +8 -10
- package/dist/cli/bundle.json +1 -1
- package/dist/cli/index.js +6 -6
- package/package.json +8 -8
- package/templates/astro/package.json +3 -3
- package/templates/nextjs/package.json +4 -4
- package/templates/react-router/package.json +5 -5
- package/templates/sveltekit/package.json +3 -3
- package/templates/vite/package.json +5 -5
|
@@ -1,286 +1,47 @@
|
|
|
1
|
-
# Content
|
|
1
|
+
# Content: schemas, Singles, and entries
|
|
2
2
|
|
|
3
|
-
|
|
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
|
-
|
|
5
|
+
## Choose the write path
|
|
6
6
|
|
|
7
|
-
|
|
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
|
-
|
|
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
|
-
|
|
12
|
+
## Add a content type (for example, a blog)
|
|
13
13
|
|
|
14
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
`
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
41
|
+
## Load the page for the task
|
|
285
42
|
|
|
286
|
-
|
|
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`
|
|
@@ -43,7 +43,7 @@ The list response includes `nextCursor` when another page exists. `--offset` rem
|
|
|
43
43
|
- `delete` removes one submission permanently and prints the deleted record. There is no undo, no bulk delete, and no confirmation prompt — confirm with the user before running it. An unknown or already-deleted id fails with `Submission not found`.
|
|
44
44
|
- There's no CLI command to create a submission. Submissions are created by the form intake endpoint when a user submits the published site's form.
|
|
45
45
|
|
|
46
|
-
Use this when the user asks "who filled out the contact form?", "how many signups did we get this week?", or "show me the latest submission".
|
|
46
|
+
Use this when the user asks "who filled out the contact form?", "how many signups did we get this week?", or "show me the latest submission". To show someone where submissions are in Studio, or for older submissions and bulk export, read the `fimo-studio` skill's `cms` reference before you name a screen — there's no batch export endpoint yet.
|
|
47
47
|
|
|
48
48
|
## "Add a contact form" recipe
|
|
49
49
|
|
|
@@ -170,7 +170,7 @@ fimo deploy -m "chore: first preview" --json
|
|
|
170
170
|
|
|
171
171
|
`-m` is required because you run non-interactively; the deploy validates, commits pending changes, pushes, and syncs the preview sandbox. Return `data.studio_url` from the envelope. Run `fimo preview url --json` only when the hosted site URL itself is needed. If the initiating request described a concrete site, build a minimal meaningful first screen before this single deploy; otherwise deploy the scaffolded site as-is and then ask what to build.
|
|
172
172
|
|
|
173
|
-
This first deploy creates a preview only — never add `--publish`, and treat every later deploy as offer-then-confirm. The rule does not apply when `init` cloned a project with existing code or when the work is a migration; those paths keep their normal deployment approval rules.
|
|
173
|
+
This first deploy creates a preview only — never add `--publish`, and treat every later deploy as offer-then-confirm. It also warms the sandbox: do not run a separate warm-up deploy. The rule does not apply when `init` cloned a project with existing code or when the work is a migration; those paths keep their normal deployment approval rules.
|
|
174
174
|
|
|
175
175
|
After the preview succeeds, follow `references/domains.md` § Offer a cleaner default URL before first publish. Reserve a slug only after the user chooses it; the URL will not resolve until the site is published.
|
|
176
176
|
|
|
@@ -13,7 +13,7 @@ fimo locales set-default es --yes --json
|
|
|
13
13
|
fimo locales remove es --yes --json
|
|
14
14
|
```
|
|
15
15
|
|
|
16
|
-
In a linked project, change the locale set or default only through these commands or Studio Settings. Never edit `i18n.defaultLocale` or `i18n.locales` directly.
|
|
16
|
+
In a linked project, change the locale set or default only through these commands or Studio Settings. Never edit `i18n.defaultLocale` or `i18n.locales` directly. Fimo chat in Studio and Slack can run `locales list` and `locales add`; removing a locale or changing the default stays with a site manager.
|
|
17
17
|
|
|
18
18
|
These commands update the selected Branch through the locale lifecycle API. The API commits `.fimo/config.json` to the Fimo Branch, then the CLI synchronizes the **whole local branch** to that commit. They refuse a dirty config, a local-ahead branch, or a diverged branch before applying the remote change. `--yes` bypasses only the explanatory prompt.
|
|
19
19
|
|
|
@@ -123,4 +123,4 @@ Labels and content are separate translated surfaces:
|
|
|
123
123
|
|
|
124
124
|
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.
|
|
125
125
|
|
|
126
|
-
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
|
|
126
|
+
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 `references/content/localized.md`.
|
|
@@ -1,16 +1,14 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: fimo-studio
|
|
3
3
|
description: >-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
UI locations, buttons, or panels from memory — always read the relevant
|
|
13
|
-
reference file first.
|
|
4
|
+
How to find and do things in the Fimo web app (Studio, the dashboard):
|
|
5
|
+
content and the CMS, form submissions, media, publishing and preview, SEO
|
|
6
|
+
and domain settings, site connections, analytics, integrations, variables
|
|
7
|
+
and secrets, schedules and run history, outbound webhooks, visual editing,
|
|
8
|
+
version history, sharing and billing, chat, and the command palette. Load
|
|
9
|
+
it when someone asks where something is or how to do it in Fimo, even when
|
|
10
|
+
they do not say "Studio", and read the matching reference before you name a
|
|
11
|
+
screen, button, or setting.
|
|
14
12
|
---
|
|
15
13
|
|
|
16
14
|
# Fimo Studio
|