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.
@@ -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`
@@ -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". For older submissions or bulk export, point them at the dashboard — there's no batch export endpoint yet.
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. Studio chat can run `locales list`.
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` § Shared fields inside a localized type.
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
- Load ONLY when the user explicitly asks about the Fimo web app /
5
- Fimo Studio / the dashboard UI — never for CLI commands or code work.
6
- Triggers: "in Fimo Studio", "in the dashboard", "in the web app",
7
- "how do I X in the UI", or screenshots of the dashboard. Topics
8
- covered: dashboard content and CMS, publishing from the dashboard,
9
- dashboard SEO/domain settings, site connections, schedules and run history, outbound webhooks,
10
- visual editing, version history UI, dashboard sharing/billing, dashboard chat,
11
- and the command palette. Never describe
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
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "bundled": true,
3
3
  "bundler": "esbuild",
4
- "bundledAt": "2026-10-28T12:48:54.828Z",
4
+ "bundledAt": "2026-10-28T16:35:30.753Z",
5
5
  "cliVersion": "2.10.0",
6
6
  "external": [
7
7
  "oxc-parser",