fimo 2.10.0 → 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/README.md +9 -0
- package/assets/skills/fimo-cli/SKILL.md +57 -140
- package/assets/skills/fimo-cli/references/account.md +2 -0
- package/assets/skills/fimo-cli/references/agent-setup.md +1 -1
- package/assets/skills/fimo-cli/references/assets.md +2 -0
- package/assets/skills/fimo-cli/references/branches.md +10 -2
- 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 -262
- package/assets/skills/fimo-cli/references/deploy.md +1 -26
- package/assets/skills/fimo-cli/references/forms.md +1 -1
- package/assets/skills/fimo-cli/references/init.md +19 -19
- package/assets/skills/fimo-cli/references/locales.md +2 -2
- package/assets/skills/fimo-code/references/content/richtext.md +2 -2
- package/assets/skills/fimo-studio/SKILL.md +8 -10
- package/assets/skills/fimo-studio/references/ai-chat.md +2 -2
- package/assets/skills/fimo-studio/references/billing-and-credits.md +12 -1
- package/assets/skills/fimo-studio/references/project-creation.md +4 -4
- package/dist/cli/bundle.json +1 -1
- package/dist/cli/index.js +124 -113
- package/package.json +8 -8
- package/release.json +2 -2
- 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,276 +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
|
-
`--body` is a **required** option on `create` and `update`. 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.
|
|
85
|
-
|
|
86
|
-
`entries list` accepts the same read query surface as generated hooks:
|
|
87
|
-
|
|
88
|
-
```bash
|
|
89
|
-
fimo entries list BlogPost --where '{"featured":true}' --sort -publishedAt
|
|
90
|
-
fimo entries list BlogPost --where '{"rank":{"$gte":3}}' --sort rank
|
|
91
|
-
fimo entries list BlogPost --where '{"__fimo":{"contentType":{"$eq":"BlogPost"}}}'
|
|
92
|
-
fimo entries list BlogPost --search "launch"
|
|
93
|
-
fimo entries list BlogPost --limit 10 --cursor <next-cursor> --sort title
|
|
94
|
-
fimo entries list BlogPost --fields slug,title,excerpt,coverImage --sort -publishedAt --limit 12
|
|
95
|
-
fimo entries list BlogPost --fields slug,title,author --populate author
|
|
96
|
-
```
|
|
97
|
-
|
|
98
|
-
Use the canonical read query flags: `--search`, `--sort`, `--where`, `--limit`, `--cursor`, `--all-pages`, `--fields`, and `--populate`. `--offset` remains a compatibility alias for existing scripts.
|
|
99
|
-
`--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.
|
|
100
|
-
|
|
101
|
-
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.
|
|
102
|
-
`--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`.
|
|
103
|
-
|
|
104
|
-
`--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).
|
|
105
|
-
|
|
106
|
-
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.
|
|
107
|
-
|
|
108
|
-
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`.
|
|
109
|
-
|
|
110
|
-
### Read-only SQL
|
|
111
|
-
|
|
112
|
-
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.
|
|
113
|
-
|
|
114
|
-
**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.
|
|
20
|
+
## Write entries and Singles
|
|
115
21
|
|
|
116
22
|
```bash
|
|
117
|
-
fimo entries
|
|
118
|
-
fimo entries
|
|
119
|
-
fimo entries
|
|
120
|
-
|
|
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)
|
|
121
31
|
```
|
|
122
32
|
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
```sql
|
|
130
|
-
SELECT source.document_id AS id, source.data
|
|
131
|
-
FROM entries source
|
|
132
|
-
WHERE source.content_type = 'BlogPost'
|
|
133
|
-
AND source.locale = 'en'
|
|
134
|
-
AND NOT EXISTS (
|
|
135
|
-
SELECT 1
|
|
136
|
-
FROM entries target
|
|
137
|
-
WHERE target.content_type = source.content_type
|
|
138
|
-
AND target.document_id = source.document_id
|
|
139
|
-
AND target.locale = 'es'
|
|
140
|
-
)
|
|
141
|
-
```
|
|
142
|
-
|
|
143
|
-
Find Spanish variants whose English source was edited later:
|
|
144
|
-
|
|
145
|
-
```sql
|
|
146
|
-
SELECT
|
|
147
|
-
target.document_id AS id,
|
|
148
|
-
target.content_type,
|
|
149
|
-
target.slug,
|
|
150
|
-
source.updated_at AS source_updated_at,
|
|
151
|
-
target.updated_at AS target_updated_at
|
|
152
|
-
FROM entries source
|
|
153
|
-
JOIN entries target
|
|
154
|
-
ON target.content_type = source.content_type
|
|
155
|
-
AND target.document_id = source.document_id
|
|
156
|
-
WHERE source.locale = 'en'
|
|
157
|
-
AND target.locale = 'es'
|
|
158
|
-
AND source.updated_at > target.updated_at
|
|
159
|
-
ORDER BY source.updated_at DESC
|
|
160
|
-
```
|
|
161
|
-
|
|
162
|
-
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`.
|
|
163
|
-
|
|
164
|
-
### Bulk mutations
|
|
165
|
-
|
|
166
|
-
`bulk-create` takes an array of regular create bodies. Inline JSON, a file, and stdin all carry the same array shape:
|
|
167
|
-
|
|
168
|
-
```bash
|
|
169
|
-
fimo entries bulk-create BlogPost --body '[{"data":{"title":"First"}},{"data":{"title":"Second"},"locale":"es"}]'
|
|
170
|
-
fimo entries bulk-create BlogPost --file posts.json
|
|
171
|
-
cat posts.json | fimo entries bulk-create BlogPost --stdin
|
|
172
|
-
```
|
|
173
|
-
|
|
174
|
-
`bulk-update` applies the regular update body to explicit IDs or the normal `--where` filter:
|
|
175
|
-
|
|
176
|
-
```bash
|
|
177
|
-
fimo entries bulk-update BlogPost --ids <id1>,<id2> --body '{"data":{"status":"published"}}'
|
|
178
|
-
fimo entries bulk-update BlogPost --where '{"status":"draft"}' --body '{"data":{"status":"published"}}'
|
|
179
|
-
```
|
|
180
|
-
|
|
181
|
-
For different changes per entry, `--file` and `--stdin` accept an array of `{ "id", "body" }` records:
|
|
182
|
-
|
|
183
|
-
```json
|
|
184
|
-
[
|
|
185
|
-
{ "id": "<id1>", "body": { "data": { "status": "published" } } },
|
|
186
|
-
{ "id": "<id2>", "body": { "data": { "featured": true } } }
|
|
187
|
-
]
|
|
188
|
-
```
|
|
189
|
-
|
|
190
|
-
```bash
|
|
191
|
-
fimo entries bulk-update BlogPost --file updates.json
|
|
192
|
-
cat updates.json | fimo entries bulk-update BlogPost --stdin
|
|
193
|
-
fimo entries bulk-delete BlogPost --ids <id1>,<id2>
|
|
194
|
-
fimo entries bulk-delete BlogPost --where '{"archived":true}'
|
|
195
|
-
```
|
|
196
|
-
|
|
197
|
-
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.
|
|
198
|
-
|
|
199
|
-
For reference schema JSON and entry value shape, run `fimo skills get fimo-code --ref content/schema`. The short version:
|
|
200
|
-
|
|
201
|
-
```json
|
|
202
|
-
{
|
|
203
|
-
"fields": {
|
|
204
|
-
"author": { "type": "reference", "target": "Author" },
|
|
205
|
-
"contributors": { "type": "reference", "target": "Author", "many": true }
|
|
206
|
-
}
|
|
207
|
-
}
|
|
208
|
-
```
|
|
209
|
-
|
|
210
|
-
Entry bodies use reference objects with target `id` values:
|
|
211
|
-
|
|
212
|
-
```bash
|
|
213
|
-
fimo entries create BlogPost --body '{"data":{"slug":"hello","title":"Hello","author":{"id":"750e8400-e29b-41d4-a716-446655440000"},"contributors":[]}}'
|
|
214
|
-
```
|
|
215
|
-
|
|
216
|
-
`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.
|
|
217
|
-
|
|
218
|
-
## Localized and shared content
|
|
219
|
-
|
|
220
|
-
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`.
|
|
221
|
-
|
|
222
|
-
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.
|
|
223
|
-
|
|
224
|
-
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.
|
|
225
|
-
|
|
226
|
-
### Shared fields inside a localized type
|
|
227
|
-
|
|
228
|
-
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.
|
|
229
|
-
|
|
230
|
-
```json
|
|
231
|
-
{
|
|
232
|
-
"uid": "Product",
|
|
233
|
-
"name": "Products",
|
|
234
|
-
"fields": {
|
|
235
|
-
"title": { "type": "string" },
|
|
236
|
-
"description": { "type": "richtext" },
|
|
237
|
-
"sku": { "type": "string", "i18n": false, "unique": true },
|
|
238
|
-
"price": { "type": "number", "i18n": false },
|
|
239
|
-
"photo": { "type": "media", "i18n": false },
|
|
240
|
-
"brand": { "type": "reference", "target": "Brand", "i18n": false }
|
|
241
|
-
}
|
|
242
|
-
}
|
|
243
|
-
```
|
|
244
|
-
|
|
245
|
-
Writing a shared field through any locale updates every locale of that document:
|
|
246
|
-
|
|
247
|
-
```bash
|
|
248
|
-
fimo entries update Product <id> --locale es --body '{"data":{"title":"Silla","price":120}}'
|
|
249
|
-
```
|
|
250
|
-
|
|
251
|
-
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.
|
|
252
|
-
|
|
253
|
-
Rules:
|
|
254
|
-
|
|
255
|
-
- `i18n` belongs on top-level scalar and reference fields only. Fields inside `blocks` follow the locale of the entry containing them and are rejected.
|
|
256
|
-
- On a non-localized type the flag is inert — there is one row already.
|
|
257
|
-
- `"i18n": true` is the default and never needs writing.
|
|
258
|
-
|
|
259
|
-
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.
|
|
260
|
-
|
|
261
|
-
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.
|
|
262
|
-
|
|
263
|
-
## "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`.
|
|
264
38
|
|
|
265
|
-
|
|
266
|
-
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.
|
|
267
|
-
3. Run `fimo schemas push BlogPost`.
|
|
268
|
-
4. Generate cover images: `fimo image generate --prompt "..." --aspect-ratio 16:9` (see `media.md`).
|
|
269
|
-
5. Seed entries: `fimo entries create BlogPost --body '{"data": {"slug": "first-post", "title": "...", "coverImage": {...}}}'`.
|
|
270
|
-
6. Run `fimo skills get fimo-code --ref ui` and load the detected framework reference for rendering primitives.
|
|
271
|
-
7. Run `fimo skills get fimo-code --ref labels` and load the detected framework reference for labels.
|
|
272
|
-
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.
|
|
273
40
|
|
|
274
|
-
##
|
|
41
|
+
## Load the page for the task
|
|
275
42
|
|
|
276
|
-
|
|
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`
|
|
@@ -15,7 +15,6 @@ Before deploying, Fimo fast-forwards a clean checkout that is behind and stops o
|
|
|
15
15
|
```bash
|
|
16
16
|
fimo deploy # preview only (default; reversible)
|
|
17
17
|
fimo deploy -m "<commit message>" # commit pending + push + sandbox sync
|
|
18
|
-
fimo deploy --no-restart # skip dev-server restart (HMR-safe changes only)
|
|
19
18
|
fimo deploy -m "<commit message>" --publish # also publish a new live version
|
|
20
19
|
```
|
|
21
20
|
|
|
@@ -23,7 +22,6 @@ fimo deploy -m "<commit message>" --publish # also publish a new live version
|
|
|
23
22
|
- **`fimo deploy --publish`** — same as above, then triggers a live publish and prints the live URL. Runs from the configured Production source Branch only. **Only use `--publish` when the user signals "ship it"** — first-time site completion, or an explicit "publish" / "go live" request. Otherwise stick to plain `fimo deploy`. (For a _versioned_ prod release, use `fimo publish` instead — see below.)
|
|
24
23
|
- **`-m`** is the commit message used when there are uncommitted local changes; required in non-interactive shells. Omit if the working tree is already clean.
|
|
25
24
|
- **`--description "<why>"`** — the commit body for those changes: why they were made. Teammates and agents that later edit the same files read it, for example when a merge conflicts. Pass it with `-m` when the reason is not obvious from the diff.
|
|
26
|
-
- **`--no-restart`** — tells the sandbox to skip the dev-server restart and let Vite HMR pick up the change. Shaves ~3s per deploy. A deploy that carries changed variables restarts anyway. See "Skipping the dev-server restart" below for when it's safe.
|
|
27
25
|
|
|
28
26
|
## Reading deploy destinations
|
|
29
27
|
|
|
@@ -89,7 +87,7 @@ Redirects, response headers, and URL shape belong in
|
|
|
89
87
|
|
|
90
88
|
This is a **performance optimization, only worth doing when you already know a deploy is coming** (the developer asked to publish, or you're confident they'll want a hosted preview soon). If you're just iterating locally, skip it — don't deploy pre-emptively. New-project onboarding never needs it: its automatic first preview deploy is the warm-up.
|
|
91
89
|
|
|
92
|
-
The first deploy of a project's life pays a one-time cost: the sandbox has to provision (create the VM, install the user's deps if they differ from the template's baked ones, start the dev server) — about 15-30s. Every deploy after that lands on a warm sandbox (~10s
|
|
90
|
+
The first deploy of a project's life pays a one-time cost: the sandbox has to provision (create the VM, install the user's deps if they differ from the template's baked ones, start the dev server) — about 15-30s. Every deploy after that lands on a warm sandbox (~4-10s).
|
|
93
91
|
|
|
94
92
|
**To hide that one-time cost, kick off an early deploy in the background while you keep working.** The provisioning happens during your generation work, so by the time the developer wants a hosted preview, the sandbox is already warm and the deploy is fast.
|
|
95
93
|
|
|
@@ -99,29 +97,6 @@ fimo deploy -m "chore: init" & # background; keep generating code while i
|
|
|
99
97
|
|
|
100
98
|
There's nothing special about this — it's the same `fimo deploy` you'd run later. The `-m` is the commit message for any files `validate` writes via codegen; pick a sensible conventional-commit string (e.g. `chore: init`, `chore: scaffold`). The point is purely the timing: pay the provisioning tax up front instead of when the user is waiting on a result. **This is also the only path that installs your project's deps on the sandbox** — if you skip it, the first interactive deploy will pay both costs.
|
|
101
99
|
|
|
102
|
-
## Skipping the dev-server restart
|
|
103
|
-
|
|
104
|
-
`fimo deploy --no-restart` tells the API not to restart the sandbox's dev server after pulling new code. Vite's HMR picks up the change instead, which is what it's designed for — 3+ seconds saved per deploy.
|
|
105
|
-
|
|
106
|
-
**Use `--no-restart` when you only touched HMR-safe files:**
|
|
107
|
-
|
|
108
|
-
- Anything under `src/**` (components, pages, hooks, styles)
|
|
109
|
-
- Fixed-path static files under `public/`, such as favicons or `robots.txt` (images and videos belong in the media library, not the repository; see the `fimo-code` skill's non-negotiable boundaries)
|
|
110
|
-
- Content / entries / translations / form definitions (JSON the Fimo runtime hot-loads)
|
|
111
|
-
|
|
112
|
-
**Do NOT use `--no-restart` when you touched any of these — they require a fresh dev server:**
|
|
113
|
-
|
|
114
|
-
- `vite.config.*` (Vite plugin or config changes)
|
|
115
|
-
- `react-router.config.*` (router config)
|
|
116
|
-
- `tsconfig.json` (TypeScript compiler)
|
|
117
|
-
- `.env` (env vars are read at process start)
|
|
118
|
-
- `package.json` or any lockfile (dep changes)
|
|
119
|
-
- Anything under `.fimo/` (Fimo's own pre-build / runtime config)
|
|
120
|
-
|
|
121
|
-
**When in doubt, omit the flag.** The default (restart) is the safe choice — a wasted restart costs 3 seconds; a missing one costs the user serving stale code until they notice and re-deploy.
|
|
122
|
-
|
|
123
|
-
**One case is handled for you:** if the deploy changes the project's route set (a page added, removed, or moved), the API tells the preview to reload regardless of this flag. A router builds its route table once per document, so the new page would otherwise exist but be unreachable — missing from the Studio route selector and 404-ing from the site's own links. This costs a page load, not a restart.
|
|
124
|
-
|
|
125
100
|
## Publishing: `fimo deploy --publish` vs `fimo publish`
|
|
126
101
|
|
|
127
102
|
Use `fimo deploy --publish` to push and publish local changes. Use `fimo publish` to publish the revision already on the Fimo remote without pushing. Both target the configured Production source Branch.
|
|
@@ -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
|
|
|
@@ -10,30 +10,30 @@ fimo init [dir] [options]
|
|
|
10
10
|
|
|
11
11
|
`fimo init` runs the full onboarding in one shot:
|
|
12
12
|
|
|
13
|
-
1. **Signs in automatically** — if there's no session it opens the browser loopback login. In `--json` / non-TTY with no session it fails with `NOT_AUTHENTICATED
|
|
13
|
+
1. **Signs in automatically** — if there's no session it opens the browser loopback login. In `--json` / non-TTY with no session it fails with `NOT_AUTHENTICATED`: run `fimo login` in a terminal first, or create the site without an account with `fimo new <dir>` (see `account.md`).
|
|
14
14
|
2. **Resolves the project** — with `--project-id <id>` it sets up the named Fimo site: a project with no code yet is scaffolded as a fresh site, while an existing repository is cloned. Without it, `init` creates a NEW project. An interactive TTY shows a "Create new / Link existing" picker; non-interactive shells default to create-new. New sites use the Next.js App Router by default; `--framework react-router`, `--framework vite`, `--framework astro`, and `--framework sveltekit` select the other minimal framework-native shells.
|
|
15
15
|
3. **Installs dependencies** — prompts for the package manager, or honor `--package-manager <pm>` / `--no-install`.
|
|
16
16
|
4. **Optionally sets up Fimo skills** — confirm prompt, or `--skills` / `--no-skills`.
|
|
17
17
|
|
|
18
18
|
Generated pnpm projects pin `pnpm@10.26.0` and carry project-owned `pnpm-workspace.yaml#strictDepBuilds: true` and `#allowBuilds` settings. Generated Bun projects trust the same required packages through `package.json#trustedDependencies`. Keep the selected package manager's policy committed. When adding a dependency with an install script, review it before extending that policy; never replace it with a blanket allow-all install.
|
|
19
19
|
|
|
20
|
-
| Flag | Required | Purpose
|
|
21
|
-
| ---------------------------- | ----------------------------- |
|
|
22
|
-
| `[dir]` positional | yes in non-TTY for create-new | Target directory (e.g. `my-site`)
|
|
23
|
-
| `--project-id <id>` | no | Set up the named Fimo site: scaffold and push a fresh site when it has no code yet, otherwise clone it.
|
|
24
|
-
| `--org <id>` | no | Target organization **id** when creating (use the `ID` column from `fimo orgs list`, NOT the slug). Picker shown interactively if omitted and TTY.
|
|
25
|
-
| `--branch <name>` | no | Branch to check out when linking an existing project (defaults to `main`).
|
|
26
|
-
| `--env <name>` | no | Rejected as a Branch selector; use `--branch <name>`.
|
|
27
|
-
| `--framework <framework>` | no | New-project scaffold: `nextjs` (App Router, default), `react-router`, `vite` (React SPA), `astro`, or `sveltekit`. Existing repositories are preserved.
|
|
28
|
-
| `--package-manager <pm>` | no | `npm` \| `pnpm` \| `yarn` \| `bun`.
|
|
29
|
-
| `--install` / `--no-install` |
|
|
30
|
-
| `--skills` / `--no-skills` |
|
|
31
|
-
| `--agents <list>` | no | Comma-separated agent IDs (e.g. `claude-code,cursor`). Pass `none` to skip installing the global skill.
|
|
32
|
-
| `-a, --agent <id>` | alternative | Repeatable form: `-a claude-code -a cursor`.
|
|
33
|
-
| `--template-root <path>` | no | Override the bundled template (development only).
|
|
34
|
-
| `-y, --yes` | no | Run non-interactively using defaults (no prompts).
|
|
35
|
-
|
|
36
|
-
In a non-TTY shell the create-new path requires `[dir]`,
|
|
20
|
+
| Flag | Required | Purpose |
|
|
21
|
+
| ---------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
22
|
+
| `[dir]` positional | yes in non-TTY for create-new | Target directory (e.g. `my-site`) |
|
|
23
|
+
| `--project-id <id>` | no | Set up the named Fimo site: scaffold and push a fresh site when it has no code yet, otherwise clone it. |
|
|
24
|
+
| `--org <id>` | no | Target organization **id** when creating (use the `ID` column from `fimo orgs list`, NOT the slug). Picker shown interactively if omitted and TTY. |
|
|
25
|
+
| `--branch <name>` | no | Branch to check out when linking an existing project (defaults to `main`). |
|
|
26
|
+
| `--env <name>` | no | Rejected as a Branch selector; use `--branch <name>`. |
|
|
27
|
+
| `--framework <framework>` | no | New-project scaffold: `nextjs` (App Router, default), `react-router`, `vite` (React SPA), `astro`, or `sveltekit`. Existing repositories are preserved. |
|
|
28
|
+
| `--package-manager <pm>` | no | `npm` \| `pnpm` \| `yarn` \| `bun`. |
|
|
29
|
+
| `--install` / `--no-install` | no | Install deps after checkout (or skip it). |
|
|
30
|
+
| `--skills` / `--no-skills` | no | Install the global Fimo skill (or skip it). |
|
|
31
|
+
| `--agents <list>` | no | Comma-separated agent IDs (e.g. `claude-code,cursor`). Pass `none` to skip installing the global skill. Non-interactive runs without it use `none`, unless `--skills` is passed. |
|
|
32
|
+
| `-a, --agent <id>` | alternative | Repeatable form: `-a claude-code -a cursor`. |
|
|
33
|
+
| `--template-root <path>` | no | Override the bundled template (development only). |
|
|
34
|
+
| `-y, --yes` | no | Run non-interactively using defaults (no prompts). |
|
|
35
|
+
|
|
36
|
+
In a non-TTY shell (or with `-y` / `--json`) the create-new path requires `[dir]`, and `--org` if you have no active org and belong to multiple orgs. Everything else takes a default: dependencies install with the detected package manager unless you pass `--no-install`, and no skill is installed unless you pass `--skills`.
|
|
37
37
|
|
|
38
38
|
### Non-interactive setup
|
|
39
39
|
|
|
@@ -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`.
|
|
@@ -33,7 +33,7 @@ generated client hydration helper where required.
|
|
|
33
33
|
|
|
34
34
|
## Entry payload
|
|
35
35
|
|
|
36
|
-
|
|
36
|
+
`entries create` and `entries update` take `--body` with every field, including the collection slug, under `data`:
|
|
37
37
|
|
|
38
38
|
```json
|
|
39
39
|
{
|
|
@@ -46,7 +46,7 @@ CLI entry writes put every value, including the collection slug, under `data`:
|
|
|
46
46
|
}
|
|
47
47
|
```
|
|
48
48
|
|
|
49
|
-
|
|
49
|
+
Keep `slug` inside `data`; `entries create` rejects unsupported top-level keys.
|
|
50
50
|
|
|
51
51
|
Slugs should be lowercase, hyphenated, stable, meaningful, and unique per content type. Fimo slugifies the supplied candidate. If omitted, Fimo generates one, which is unsuitable for content with durable public URLs.
|
|
52
52
|
|
|
@@ -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
|
|
@@ -12,7 +12,7 @@ The plan decides the agents (FIMO-2856): Free has the SEO and GEO default agents
|
|
|
12
12
|
|
|
13
13
|
An agent is a chat with a job: a name, a one-line summary for people, and instructions that Fimo reads at the start of every reply in that chat and every run of its routines (FIMO-3079). Live agents are shared like any chat, with an **Agent** tag after the name. The **+** above the chat list is a menu: **New chat** (blank), **New agent** (opens the new agent's chat at once: the agent asks what it should do with three one-click answers, then drafts its name, summary, instructions and routines on one card; **Create agent** sends the person's agreement and the agent goes live, the team sees it and its routines start; until then only its creator sees it, as **New agent** with **Setting up…**, its routines do not run, and its chat changes nothing on the site (it reads the site, its data and the web; no CLI, files, work sessions or publish), and it goes live only after the person saw its latest draft; a routine time the person did not name keeps its hour and Fimo picks the minute; below Pro, **Create agent** opens the plans), and under **Agents** Fimo's default agents (**SEO**, **GEO**, **Content**, **Quality**, **Compliance**); a new site starts with SEO and GEO listed, their routines active from the start; Content, Quality and Compliance, and every default on an older site, are created the first time someone selects them, routines active, the same chat every time after. In an agent, the header shows the name alone and the message box reads **Message <name>**. A default agent's empty state greets in its own words and offers its own starter requests; its description stays in its settings. A starter is sent as shown, by anyone who can send messages. Asked to, an agent changes its own instructions with its `agent` tool; the chat shows **Updated instructions** with **View change** (before and after). The agent's settings page has **Summary** and **Instructions** fields, shared with everyone (empty means none), and an **Instruction history** where **Restore previous** puts back the text a change replaced. In text, an agent links another as `[Name](agent://id)`, shown as a chip that opens it. The filter icon's **Kind** option shows only chats or only agents; search finds an agent by its name.
|
|
14
14
|
|
|
15
|
-
The **SEO** default runs six routines backed by Studio's built-in `fimo-seo` skill, which checks the site as a browser renders it and fixes at the source: **Technical SEO** (status, redirects, canonicals, sitemap, robots.txt, language, main heading,
|
|
15
|
+
The **SEO** default runs six routines backed by Studio's built-in `fimo-seo` skill, which checks the site as a browser renders it and fixes at the source: **Technical SEO** (status, redirects, canonicals, sitemap, robots.txt, language, main heading, changes since its last run: pages moved without a redirect, and, with Search Console, old addresses Google still shows that the site no longer serves), **Broken links**, **Meta tags** (titles, descriptions, Open Graph, the site's title ending, length in characters and pixels), **Image SEO** (alt text, file names, images over 200 KB: one in the media library or the site's own files is rendered through Fimo's resizing on its own, a file of the site uploaded first), **Hreflang** (only on a site in more than one language) and **Internal linking** (orphan and deep pages, articles with no link up to a hub or product page or more than eight links). Each default routine wakes on the changes on main that can matter to it, before a publish (CMS edits, code changes, images, languages, forms; the first publish and a new domain for Technical SEO and Cookie consent): a small model reads each change first, so a quiet site runs nothing, and the run checks what changed (the whole site on its first run). A schedule covers what no single change shows: every Monday, Technical SEO, Meta tags and Internal linking read every page of main's hosted preview (pages out of the sitemap, shared titles and title shape, orphan and deep pages); what changes without anyone touching the site also keeps one: Broken links checks outbound links on the 1st of every month, Content refresh runs on the 2nd, Content lifecycle every three months, Privacy and legal pages once a year. A page it changed is left alone for 8 weeks, the time Google takes to show the effect. A fix with one right answer from the page's own words is made without a message (a link only once the new target is checked to be the same content in the same language; a link on words the text already uses to name another page; a 301 from a page's old address once the same page is live at a new one); a change to what visitors read, which page wins a search, whether a page exists, a redirect with more than one possible target, a price or a legal page is asked as a decision; page removals and the robots policy are never changed on its own. A change a person asks for in a chat is made. What a check could not tell (a timeout, a 5xx, a page past the crawl limit) is never acted on: the run retries once, then says the check was incomplete.
|
|
16
16
|
|
|
17
17
|
The **GEO** default runs three routines backed by Studio's built-in `fimo-geo` skill, which shares `fimo-seo`'s crawl and its rule for what a run may change alone: **AI readiness** (llms.txt, the text each page serves before JavaScript, landmarks and heading levels) and **Structured data** (valid JSON-LD; Organization and WebSite, Article, BreadcrumbList; Product and FAQ where they fit) and **AI citation optimization** (a direct answer under each content page's H1, question headings on long pages). On its own it writes a missing llms.txt and keeps its links in step, adds Organization, WebSite, Article and BreadcrumbList from fields the site already has (never an invented logo, address, author or rating), and fixes landmarks and heading levels without changing words; an opening answer, new headings, FAQ or Product data, and how pages are rendered are asked as decisions; who robots.txt lets crawl, AI crawlers included, prices and claims are never changed, nor reported: asked whether an assistant can read the site, it checks and names the crawlers robots.txt keeps out. Where AI assistants cite the site needs a visibility source; until one is connected there is no routine for it.
|
|
18
18
|
|
|
@@ -37,7 +37,7 @@ A routine is saved instructions an agent runs in a thread of its own, by hand, o
|
|
|
37
37
|
|
|
38
38
|
The AI can place choices, cards, tables, images, and contextual actions directly in its reply. Optional suggestions do not interrupt the conversation.
|
|
39
39
|
|
|
40
|
-
When the AI needs an answer before it can continue, it
|
|
40
|
+
When the AI needs an answer before it can continue, it opens a form in the conversation, under the message that asks, and waits for your response. The form goes one step at a time with **Previous**, **Next**, and **Submit**, and a step with choices has an optional note field under them. If you send a message that does not answer it, the question folds to one line with an orange **?** where it was asked. Select it to open it there and answer it at any time; the answer is sent as a new message at the end of the chat. An answered question shows a gray check next to its title. When a routine asks again before anyone answered, its earlier question stays unanswered, folded where it was asked. Select **Minimize** to fold the form to one line without losing your answers, then select that line to reopen it. **Submit** sends only the completed form and leaves anything typed in the message box unsent. Sending from the message box includes any selections already made in the form with your message; with no selections, it is an ordinary reply and the question stays open.
|
|
41
41
|
|
|
42
42
|
## Attaching Context
|
|
43
43
|
|
|
@@ -61,10 +61,21 @@ From there:
|
|
|
61
61
|
3. Pick a plan and complete checkout.
|
|
62
62
|
4. Your new monthly credit pool is available right away.
|
|
63
63
|
|
|
64
|
+
## Activating a team organization
|
|
65
|
+
|
|
66
|
+
Only your personal organization starts on Free. A new team organization opens nothing until someone completes a Starter or Pro checkout: every page of it lands on **Choose a plan for {organization}**, and its sites, integrations, members, domains and settings stay unavailable until then.
|
|
67
|
+
|
|
68
|
+
- An owner or admin picks **Continue with Starter** or **Continue with Pro** and completes checkout. Other members see that an owner or admin must activate it.
|
|
69
|
+
- Leaving checkout without paying keeps the organization inactive. Use the organization switcher at the top of the page to go back to another organization.
|
|
70
|
+
- An owner who no longer wants the organization can delete it from the same page.
|
|
71
|
+
- A team organization that has paid once stays usable if it later moves to Free.
|
|
72
|
+
|
|
64
73
|
## Extra usage budget
|
|
65
74
|
|
|
66
|
-
Open **Billing & usage**, then **Details** beside public bandwidth. Billing admins on Starter or Pro can edit one **Monthly budget**
|
|
75
|
+
Open **Billing & usage**, then **Details** beside public bandwidth. Billing admins on Starter or Pro can edit one **Monthly budget** that covers public bandwidth, routine agent-hours, and database compute beyond each site's own allowance. The page shows each one's cost and **Spent this period**. This budget does not cover AI credit purchases or auto-refill.
|
|
67
76
|
|
|
77
|
+
- Database compute: each site includes 100 compute-unit hours a month (400 on Pro). From 1 November 2026, compute beyond that is billed from the budget at $0.08 per compute-unit hour on Starter and $0.05 on Pro. Free sites stop at their allowance.
|
|
78
|
+
- When a site stops at its database limit, the owner finds **Manage extra usage** in the site's **Database limit** details, which opens this page.
|
|
68
79
|
- At the budget, additional paid usage stops; remaining included allowances stay usable.
|
|
69
80
|
- Disabling extra usage preserves charges already incurred. The budget cannot be lowered below existing extra-usage charges.
|
|
70
81
|
|