fimo 2.10.1-staging.2 → 2.10.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/assets/skills/fimo-cli/SKILL.md +2 -2
  2. package/assets/skills/fimo-cli/SKILL.studio.md +42 -0
  3. package/assets/skills/fimo-cli/references/branches.md +43 -106
  4. package/assets/skills/fimo-cli/references/content/bulk.md +3 -12
  5. package/assets/skills/fimo-cli/references/content/localized.md +1 -1
  6. package/assets/skills/fimo-cli/references/content/sql.md +3 -10
  7. package/assets/skills/fimo-cli/references/deploy.md +35 -126
  8. package/assets/skills/fimo-cli/references/domains.md +38 -131
  9. package/assets/skills/fimo-cli/references/init.md +36 -170
  10. package/assets/skills/fimo-cli/references/projects.md +1 -1
  11. package/assets/skills/fimo-code/references/design.md +42 -126
  12. package/assets/skills/fimo-migration/SKILL.md +114 -408
  13. package/assets/skills/fimo-migration/references/content-delivery.md +67 -0
  14. package/assets/skills/fimo-migration/references/frameworks/nextjs.md +1 -1
  15. package/assets/skills/fimo-migration/references/qa/browser.md +41 -0
  16. package/assets/skills/fimo-migration/references/qa/guardrails.md +95 -0
  17. package/assets/skills/fimo-migration/references/qa/results.md +78 -0
  18. package/assets/skills/fimo-migration/references/qa.md +102 -383
  19. package/assets/skills/fimo-migration/references/questions-and-improvements.md +77 -168
  20. package/assets/skills/fimo-migration/references/setup.md +90 -0
  21. package/assets/skills/fimo-migration/references/workers/validator.md +2 -2
  22. package/assets/skills/fimo-migration/references/workers.md +1 -1
  23. package/assets/skills/fimo-migration/references/workflow.md +117 -171
  24. package/assets/skills/fimo-studio/SKILL.md +4 -1
  25. package/assets/skills/fimo-studio/references/ai-chat/agents.md +46 -0
  26. package/assets/skills/fimo-studio/references/ai-chat/default-agents.md +57 -0
  27. package/assets/skills/fimo-studio/references/ai-chat/routines.md +53 -0
  28. package/assets/skills/fimo-studio/references/ai-chat.md +39 -76
  29. package/assets/skills/fimo-studio/references/custom-domains.md +2 -2
  30. package/assets/skills/fimo-studio/references/publish-and-deploy.md +1 -1
  31. package/dist/cli/bundle.json +2 -2
  32. package/dist/cli/index.js +32 -11
  33. package/package.json +8 -8
  34. package/release.json +2 -2
  35. package/templates/astro/package.json +3 -3
  36. package/templates/nextjs/package.json +4 -4
  37. package/templates/react-router/package.json +5 -5
  38. package/templates/sveltekit/package.json +3 -3
  39. package/templates/vite/package.json +5 -5
@@ -56,11 +56,11 @@ Load a reference with `fimo skills get fimo-cli --ref <name>`. "+ fimo-code `<re
56
56
  - Generate or edit an image or video with AI → `media` (+ fimo-code `assets` to show it in the UI)
57
57
  - Labels, static copy, missing `t()` values → `labels` + fimo-code `labels`
58
58
  - Locales and the default locale → `locales` + fimo-code `locales`
59
- - Deploy, publish, failed deploys, markdown pages for AI agents → `deploy`
59
+ - Deploy, publish, a failed deploy or publication, blocked build scripts, markdown pages for AI agents → `deploy`
60
60
  - Preview URL → `preview`
61
61
  - Redirects, security headers, clean URLs, trailing slash → `hosting`
62
62
  - Broken links, SEO, alt text, accessibility, Web Vitals, console errors in a browser → `site-checks`
63
- - Branches: create, switch, diff, merge, status, release. Suggest a Branch for a risky change (`fimo checkout -b <name>`) → `branches`
63
+ - Branches: create, switch, status, diff, merge into `main`, pull. Suggest a Branch for a risky change (`fimo checkout -b <name>`) → `branches`
64
64
  - Restore points and recovery → `history`
65
65
  - Environment variables and secrets → `project-vars-and-secrets`
66
66
  - Send form submissions, publishes, or other events to Slack, Resend, GitHub, Zapier, or a URL → `webhooks`
@@ -0,0 +1,42 @@
1
+ ---
2
+ name: fimo-cli
3
+ description: >-
4
+ Operate a Fimo site through the `fimo` tool: content, Singles, schemas,
5
+ forms and their submissions, media and AI images, labels and locales, pages,
6
+ analytics, domains, webhooks, schedules, site checks and history. Read the
7
+ matching reference before the first command in a domain.
8
+ ---
9
+
10
+ # Fimo CLI
11
+
12
+ The `fimo` tool runs each command for you, on this project's Fimo version and on the version of the site you are working on, and returns the CLI's JSON. Fimo serves the preview, so there is nothing to install, start or deploy. Code in the project (schema JSON, generated clients, primitives, framework adapters) is the `fimo-code` skill. For one command's flags, run it with `--help`.
13
+
14
+ ## Every task
15
+
16
+ - **Site knowledge:** before planning, recommendations, design, copy, content, or code work, read `knowledge get`. Rules: reference `knowledge`.
17
+ - **Output:** read `data`. Branch on `error.code`, not on the message, and follow `hint`. Commands never prompt, so give each answer as a flag (`--yes`).
18
+ - **Content lives in Fimo:** editor content, copy and media go in schemas, labels and the media library, not in code, so people can change them in Studio without you (`fimo-code`).
19
+
20
+ ## Find the reference
21
+
22
+ Load a reference with `skillLoad` (`fimo-cli`, reference `<name>`). "+ fimo-code `<ref>`" means: also load that `fimo-code` reference and the reference for the project's framework.
23
+
24
+ - Project snapshot: framework, schemas, routes, locales, tree (`describe`) → `describe`
25
+ - Content types, Singles, entries, a blog, the CMS → `content` + fimo-code `content/schema`
26
+ - Page routes, params, and the sources Studio shows for a page → `pages`
27
+ - Forms and form submissions → `forms` + fimo-code `forms`
28
+ - Upload, replace, or remove media files → `assets` + fimo-code `assets`
29
+ - Generate or edit an image or video with AI → `media` (+ fimo-code `assets` to show it on the site)
30
+ - Labels, static copy, missing `t()` values → `labels` + fimo-code `labels`
31
+ - Locales → `locales` + fimo-code `locales`
32
+ - Preview URL → `preview`; a preview that fails to build, and its logs → `deploy`
33
+ - Redirects, security headers, clean URLs, trailing slash → `hosting`
34
+ - Broken links, SEO, alt text, accessibility, Web Vitals, console errors in a browser → `site-checks`
35
+ - Restore points → `history`
36
+ - Send form submissions, publishes, or other events to Slack, Resend, GitHub, Zapier, or a URL → `webhooks`
37
+ - Firecrawl web research and Fal media → `integrations/firecrawl`, `integrations`
38
+ - Visitors, page views, top pages, chart annotations → `analytics`
39
+ - Site URL: the free `*.fimo.site` slug, a domain the person owns, buying a domain → `domains`
40
+ - Scheduled commands → `schedules`
41
+ - Report a Fimo problem → `support`
42
+ - Move an existing site or app onto Fimo → load the `fimo-migration` skill
@@ -1,126 +1,63 @@
1
- # Branches (git-shaped workflow)
1
+ # Branches
2
2
 
3
- > **Beta:** Branches are still in beta. The CLI surface is available for early workflows, but not every command or cross-surface merge path is guaranteed to work reliably yet.
3
+ Branches are in beta: some commands and cross-surface merges can still fail.
4
4
 
5
- A Fimo **Branch** is a multi-surface clone of the project: a git branch **plus** its own Neon DB branch, sandbox, preview URL, and R2 asset prefix. The CLI mirrors `git` command shapes so the workflow transfers directly — same verbs, multi-surface semantics. In Project Settings, an **Environment** is a grouping policy such as Production or Preview; it is not this Branch-backed clone.
5
+ A Fimo **Branch** is a Git branch plus its own database, preview sandbox, preview URL, and asset prefix. The commands copy `git` verbs. An **Environment** in Project Settings (Production, Preview) is a policy that groups Branches; it is not a Branch.
6
6
 
7
- New standalone projects start with one Branch: `main`. Linking an unversioned folder, cloning, and scaffolding read the project's default Branch from Fimo when they set up Git. You create more for feature work, deploy previews per Branch, then merge back and publish.
7
+ ## Which Branch a command uses
8
8
 
9
- ## The Branch model — how every command picks its target
10
-
11
- **This is the single most important concept: site-scoped commands target the Branch matching the _current git branch_.** When you're on git branch `feat/seo`, `fimo deploy`, `fimo status`, `fimo entries list`, etc. all operate on the `feat/seo` Branch's DB / sandbox / preview. The CLI prints a one-line stderr banner telling you which Branch it resolved.
12
-
13
- ```bash
14
- fimo --branch <name> <command> # peek at another Branch for one command (does not switch)
15
- ```
16
-
17
- - **`--branch <name>`** is the canonical global override. `fimo --branch main status` inspects `main` while you stay checked out on your feature Branch.
18
- - **`--env <name>`** is not a Branch selector. It is rejected; use `--branch <name>`.
19
- - Git-changing commands use the current branch; cross-branch status only reports the mismatch.
20
- - If Git cannot name a Branch, the CLI stops instead of guessing. Check out a Branch or pass `--branch <name>`. Sandboxes receive their Branch through `FIMO_ENV`.
21
- - If the git branch maps to no Fimo Branch, the CLI errors with a hint (`fimo branch` to list, `fimo branch <name>` to create) rather than guessing.
22
- - The project's default Branch cannot be deleted. Existing standalone projects use **`main`**.
23
- - **`release/*`** Branches are **read-only** — they're tags produced by `fimo publish`, not branches you push to. `fimo deploy` refuses them.
24
- - **`prod`** is protected: it cannot be created, forked from, checked out, or deleted. It's updated by publishing, never by pushing.
9
+ - A site command uses the Fimo Branch that matches the current Git branch, and prints its name.
10
+ - `fimo --branch <name> <command>` reads or writes another Branch for one command, without a switch. `--env` is not accepted. `deploy` and `pull` change Git, so they need the matching checkout: run `fimo checkout <name>` first.
11
+ - If Git names no branch (detached HEAD) and you pass no `--branch`, or the Git branch has no Fimo Branch, the CLI stops with a hint. It does not guess.
12
+ - **Protected:** the default Branch (`main`) cannot be deleted. A checkout of a `release/*` tag is read-only. `prod` cannot be created, forked, checked out, or deleted; only a publish changes it.
25
13
 
26
14
  ## Commands
27
15
 
28
- | Command | git analogue | What it does |
29
- | ----------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
30
- | `fimo branch` | `git branch` | List Branches (current marked `*`). `-v` includes deleted Branches. |
31
- | `fimo branch <name>` | `git branch <name>` | Create a Branch off the current one. `--from <branch>` forks from a different parent. Provisions DB + sandbox + preview + R2 prefix. |
32
- | `fimo branch -d <name>` | `git branch -d` | Delete a Branch — tears down its sandbox, Neon branch, and R2 prefix. Refuses `main` and `prod`. |
33
- | `fimo checkout <name>` | `git checkout` | Switch to a Branch (checks out the matching git branch; the app derives its Branch from that branch at startup). `-b` creates + switches; `--from <branch>` sets the parent. |
34
- | `fimo switch <name>` | `git switch` | Switch to an existing Branch. Takes only `<name>` (no `-b`/`--from`) — use `fimo checkout -b` to create + switch. |
35
- | `fimo pull` | `git pull` | Fast-forward the local checkout to the Branch's latest code on Fimo. Never changes the Branch on the server. |
36
- | `fimo diff [from] [to]` | `git diff` | Two-Branch diff across all surfaces. Defaults `from` = current Branch, `to` = `main`. `--surface <name>` limits to one; `--json`; `--no-color`. |
37
- | `fimo status` | `git status` | Multi-surface status for the current Branch vs its parent. See below. |
38
- | `fimo merge <from>` | `git merge` | Merge another Branch into the current one (multi-surface, atomic, interactive conflict resolver). See below. |
39
- | `fimo publish` | — | Publish the revision already on the Fimo remote (no push) with a stable Fimo publication ID. See "Publishing" below. |
40
-
41
- All of these accept the global `--branch` override. `diff`, `status`, `merge`, and `publish` additionally accept `-C, --cwd <dir>` to point at a project directory.
42
-
43
- > **`fimo switch` changes the active Fimo Branch, not the org.** A Fimo Branch keeps its code, database, sandbox, content, and preview together. To change your active organization, use `fimo orgs switch` — see `references/account.md`.
44
-
45
- ## The 6 surfaces
46
-
47
- `status`, `diff`, and `merge` all reason over the same per-Branch surfaces, in this order:
48
-
49
- `code` · `schemas` · `content` · `translations` · `assets` · `forms`
50
-
51
- `--surface <name>` on `diff` and the per-surface flags on `status` (`--code`, `--content`, `--i18n`, `--agents`, `--assets`, `--forms`) filter to one of them.
52
-
53
- ## Typical PR-style flow
54
-
55
- ```bash
56
- fimo checkout -b feat/seo # branch off main: git branch + Branch provisioned
57
- # …generate / edit code, schemas, content, translations…
58
- fimo deploy -m "feat: seo pass" # deploy a preview of the feat/seo Branch
59
- fimo preview url # canonical URL to open / screenshot the feat/seo preview
60
- fimo status # see what changed vs main, surface by surface
61
- fimo checkout main # back to main
62
- fimo merge feat/seo # merge the Branch back into main (resolve conflicts)
63
- fimo publish --label "Homepage launch" --notes "Initial production publish"
64
- fimo branch -d feat/seo # tear down the feature Branch
65
- ```
66
-
67
- ## `fimo status`
68
-
69
- The showcase command — a unified, color-coded report of what's changed on the current Branch, grouped by surface, with per-surface counts.
70
-
71
16
  ```bash
72
- fimo status # full report, current Branch vs parent (or main)
73
- fimo status --short # one line per surface
74
- fimo status --vs main # compare against an explicit Branch
75
- fimo status --content # only the content surface (combine flags freely)
76
- fimo status --json # machine-readable
17
+ fimo branch [-v] [--all] # list (-v: deleted too; --all: agent task/* Branches too)
18
+ fimo checkout -b <name> [--from <branch>] # create a Branch from the current one (or --from) and switch to it
19
+ fimo checkout <name> # switch; `fimo switch <name>` is the same (no -b)
20
+ fimo branch <name> [--from <branch>] # create without a switch
21
+ fimo branch -d <name> # delete: removes its sandbox, database, and assets
22
+ fimo status [--vs <branch>] [--short] [--code|--content|--i18n|--assets|--forms] --json
23
+ fimo diff [from] [to] [--surface <name>] --json # from = current Branch, to = its parent (else main)
24
+ fimo merge <from> [-y] [--resume] [--allow-direct-merge] --json
25
+ fimo pull # fast-forward this checkout to the Branch on Fimo
77
26
  ```
78
27
 
79
- - The **code** surface is computed from your local git workspace (`git status --porcelain`), so uncommitted edits show up immediately.
80
- - Each surface has a soft timeout — a slow surface renders as timed-out rather than blocking the whole report.
28
+ - **Create Branches with `fimo`, not `git checkout -b`.** Raw Git makes no database, sandbox, or preview. If that happened, run `fimo branch <name> --from <parent>` to add them.
29
+ - `fimo switch` changes the Branch. `fimo orgs switch` changes the organization.
30
+ - `status`, `diff`, and `merge` compare six surfaces: `code`, `schemas`, `content`, `translations`, `assets`, `forms`. `status` also shows uncommitted local edits. A slow surface shows as timed out: treat it as unknown, not unchanged.
31
+ - Code reads its Fimo connection from the Git branch and `.fimo/project.json`. Do not hardcode the tenant API URL; an explicit host variable overrides that on every Branch.
32
+ - Deleting a Branch removes its data. Delete only a Branch that the user no longer needs.
81
33
 
82
- ## `fimo merge`
34
+ ## Typical flow
83
35
 
84
36
  ```bash
85
- fimo merge feat/seo # merge feat/seo into the current Branch
86
- fimo merge feat/seo -y # non-interactive: keep the target's value on every conflict
87
- fimo merge feat/seo --resume # continue a stopped merge, or follow one still applying
88
- fimo merge feat/seo --allow-direct-merge # override the "don't merge straight onto main" gate
37
+ fimo checkout -b feat/seo --from main # isolated Branch from main
38
+ fimo deploy -m "feat: seo pass" # hosted preview of feat/seo
39
+ fimo preview url # its preview URL
40
+ fimo status # what changed, surface by surface
41
+ fimo checkout main
42
+ fimo merge feat/seo --allow-direct-merge # only when the user asked to merge into main
43
+ fimo deploy --publish # only when the user says to go live (--ref deploy)
44
+ fimo branch -d feat/seo
89
45
  ```
90
46
 
91
- - Merging directly onto `main` is gated — the CLI refuses unless you pass `--allow-direct-merge`. Prefer merging on a branch and publishing.
92
- - On conflicts nothing is applied. In a terminal you get a resolver per row: **parent** (keep the target's value), **child** (take the source's value), **pick** (edit in `$EDITOR`), or **abort**. `-y` keeps the target's value for everything.
93
- - `--json` never prompts. Unresolved conflicts exit non-zero with `MERGE_CONFLICTS`; `error.details` carries `merge_id`, `from`, `to`, and `conflicts`. Re-run with `--resume --yes` to keep the target's values, or resolve interactively.
94
- - After resolutions are accepted the CLI waits for the merge: success is `status: "ok"` with the completed merge's `mergeId` and `summary` but no `applied` list (per-surface counts are only reported when a merge applies cleanly without conflicts); `MERGE_FAILED` and `MERGE_CANCELLED` are terminal; `MERGE_IN_PROGRESS` means it is still applying — run `--resume` to keep following it. `--resume` never resubmits a merge that is already applying.
95
-
96
- ## `fimo pull`
97
-
98
- Brings the current Branch's latest code from Fimo into the local checkout, like `git pull --ff-only fimo <branch>`. Run it before editing locally when the Branch may have changed elsewhere (Studio, an agent, a teammate's deploy). It only reads from Fimo: it never changes the Branch on the server. To bring `main` into a feature Branch, use `fimo merge main`.
99
-
100
- It never rebases, merges, or stashes local work. It stops instead:
101
-
102
- - `ENV_BRANCH_BEHIND_DIRTY` — the checkout is behind and has uncommitted changes. Commit or stash them, then run `fimo pull` again.
103
- - `ENV_BRANCH_DIVERGED` — local commits and remote commits both exist. Run `git pull --rebase fimo <branch>`, fix any conflicts, then `fimo deploy`.
104
- - `ENV_BRANCH_MISMATCH` — the git checkout is on another branch, or a detached HEAD. Run `fimo checkout <branch>`.
105
-
106
- `--json` returns `details.commits_pulled` and `details.head` (the checkout's commit afterwards).
107
-
108
- ## Publishing — `fimo publish` vs `fimo deploy --publish`
47
+ ## Merge
109
48
 
110
- Two different "go live" mechanisms — don't confuse them:
49
+ - **`fimo merge` into `main` stops with `PROTECTED_FLOW`** unless you add `--allow-direct-merge`. Add it only when the user asked to merge into `main`. Merges between other Branches need no flag.
50
+ - A merge with conflicts applies nothing. A terminal shows a resolver per conflict: keep the target (current Branch) value, take the source value, edit the value, or stop. `-y` keeps the target value for every conflict.
51
+ - `--json` never prompts. Conflicts exit with `MERGE_CONFLICTS`; `error.details` has `merge_id`, `from`, `to`, and `conflicts`. To keep the target values, run `fimo merge <from> --resume --yes`.
52
+ - After the answers are accepted, the CLI waits for the merge. Success is `status: "ok"` with the `mergeId`; per-surface counts (`applied`) appear only for a merge with no conflicts, so their absence is not a reason to retry. `MERGE_FAILED` and `MERGE_CANCELLED` are final. `MERGE_IN_PROGRESS` means it still applies: run `--resume` to follow it. `--resume` on a merge that still applies only follows it; it does not send it again.
53
+ - To bring `main` into a feature Branch, run `fimo merge main` on the feature Branch.
111
54
 
112
- - **`fimo publish [--label <text>] [--notes <md>]`** — publishes the revision already on the Fimo remote without pushing. Fimo assigns the immutable publication ID; labels and notes are optional annotations. `--skip-validate` is an operator override.
113
- - **`fimo deploy --publish`** — pushes the current Production source Branch and flips the project live. See `references/deploy.md`.
55
+ ## Pull
114
56
 
115
- Choose `fimo deploy --publish` when local changes need to go live; choose `fimo publish` when the remote revision is the intended release. Both only run from the configured Production source Branch. Existing projects use `main`.
57
+ `fimo pull` gets the Branch's latest code from Fimo, like `git pull --ff-only fimo <branch>`. Run it before you edit when Studio, an agent, or a teammate may have changed the Branch. It never changes the Branch on Fimo, and it never rebases, merges, or stashes:
116
58
 
117
- ## Anti-patterns
59
+ - `ENV_BRANCH_BEHIND_DIRTY`: commit or stash the local changes, then pull again.
60
+ - `ENV_BRANCH_DIVERGED`: run `git pull --rebase fimo <branch>`, fix conflicts, then `fimo deploy`. Never force-push.
61
+ - `ENV_BRANCH_MISMATCH`: Git is on another branch or a detached HEAD. Run `fimo checkout <branch>`.
118
62
 
119
- - **Using `git checkout -b` instead of `fimo checkout -b`** — raw git creates the branch but **not** the Branch's DB / sandbox / preview. Always use `fimo` for Branch operations so resources are provisioned atomically. (Running `fimo branch <name>` after the fact provisions them.) The running app itself follows the git branch either way.
120
- - **Hardcoding the tenant API URL** — the framework runtime derives it from the
121
- git branch and `.fimo/project.json`. Use an explicit host variable only as a
122
- deliberate override, such as a local API; it then wins over derivation on
123
- every branch.
124
- - **Trying to push to or delete `prod` / `release/*`** — these are read-only/protected. Publish to update prod; never push.
125
- - **`fimo merge` straight onto `main` as a habit** — it's gated for a reason. Merge on a branch, then publish.
126
- - **Confusing `fimo switch` (Branch) with `fimo orgs switch` (org).**
63
+ `--json` returns `details.commits_pulled` and `details.head`.
@@ -4,8 +4,8 @@ Load this page to create, update, or delete many entries in one command, or to w
4
4
 
5
5
  ```bash
6
6
  fimo entries bulk-create <Type> (--body '<json-array>' | --file <path> | --stdin) [--upsert-by <field>]
7
- fimo entries bulk-update <Type> (--ids <id1>,<id2> | --where '<json>') --body '<json>'
8
- fimo entries bulk-update <Type> (--file <path> | --stdin)
7
+ fimo entries bulk-update <Type> (--ids <id1>,<id2> | --where '<json>') --body '<json>' [--locale <code>]
8
+ fimo entries bulk-update <Type> (--file <path> | --stdin) [--locale <code>] # file shape: bulk-update --help
9
9
  fimo entries bulk-delete <Type> (--ids <id1>,<id2> | --where '<json>') [--locale <code>]
10
10
  ```
11
11
 
@@ -29,18 +29,10 @@ fimo entries bulk-update BlogPost --where '{"status":"draft"}' --body '{"data":{
29
29
 
30
30
  ## A different change for each entry
31
31
 
32
- `--file` and `--stdin` take an array of `{ "id", "body" }` records. Do not add `--body`:
33
-
34
- ```json
35
- [
36
- { "id": "<id1>", "body": { "data": { "status": "published" } } },
37
- { "id": "<id2>", "body": { "data": { "featured": true } } }
38
- ]
39
- ```
32
+ Write the per-entry array that `fimo entries bulk-update --help` shows to a file, then run it without `--body`:
40
33
 
41
34
  ```bash
42
35
  fimo entries bulk-update BlogPost --file updates.json
43
- cat updates.json | fimo entries bulk-update BlogPost --stdin
44
36
  ```
45
37
 
46
38
  ## Delete
@@ -52,6 +44,5 @@ fimo entries bulk-delete BlogPost --where '{"archived":true}'
52
44
 
53
45
  ## Results and limits
54
46
 
55
- - One request writes at most 1,000 entries.
56
47
  - Requested IDs that do not exist do not stop the valid writes: the CLI prints a warning, and `--json` lists the IDs in `warnings` and in `data.meta.missing`.
57
48
  - Each `bulk-create` or `bulk-update` request saves all of its entries or none. `bulk-create` sends 100 entries per request (`--chunk-size`, at most 1,000). When a later request fails, the earlier ones stay saved: retry with `--upsert-by <field>` so that saved entries are updated, not created again.
@@ -13,7 +13,7 @@ fimo entries list Story --where '{"slug":"spring-notes"}' --fields slug,title
13
13
  fimo entries create Story --locale es --document-id <documentId> --body '{"data":{"title":"Notas de primavera"}}'
14
14
  ```
15
15
 
16
- - The API validates the variant like a new entry: send every required field, shared ones too. A shared (`"i18n": false`) value applies to every locale, so send its current value.
16
+ - When the create names a missing shared (`"i18n": false`) field, send its current value: a shared value applies to every locale.
17
17
  - Keep a project single-locale unless the user asks for more languages. When the project has more locales, create and update each locale explicitly.
18
18
  - To find missing or stale translations, use SQL (`--ref content/sql`).
19
19
 
@@ -9,21 +9,14 @@ fimo entries query --file query.sql
9
9
  cat query.sql | fimo entries query --stdin
10
10
  ```
11
11
 
12
+ `fimo entries query --help` lists the columns and limits. Rows that feed another command select `document_id AS id`.
13
+
12
14
  ## Rules
13
15
 
14
- - One `SELECT` statement that reads only the `entries` table. Common aggregate, JSON, text, date, and window functions work. It needs content view access.
15
- - A query stops after five seconds and returns at most 1,000 rows.
16
+ - Common aggregate, JSON, text, date, and window functions work. A query needs content view access.
16
17
  - **Never use SQL for content writes.** The API rejects them, because a SQL write skips schema validation, locale and reference handling, content-change events, and webhooks. Use `entries create`, `entries update`, `entries delete`, or their bulk variants (`--ref content/bulk`).
17
18
  - If a safe read needs a SQL function that is not available, tell the user which function is missing, and use the `supportReport` tool when that gap blocks the task. Do not work around it with a write.
18
19
 
19
- ## Columns
20
-
21
- - `id`, `document_id`, `content_type`, `locale`, `slug`, `data`, `created_at`, `updated_at`. Fimo can add internal columns: select the columns you need, not `SELECT *`.
22
- - Schema fields are in the JSONB `data` column, for example `data->>'title'`.
23
- - `document_id` is the stable id that `fimo entries`, content tools, references, and the API use. `id` is the internal id of one locale variant.
24
- - A localized entry has one row per locale, and all rows share one `document_id`. A non-localized entry has `locale` null.
25
- - When results feed another Fimo command, select `document_id AS id`, and use `locale` to choose a variant.
26
-
27
20
  ## Examples
28
21
 
29
22
  English blog posts that have no Spanish variant:
@@ -1,142 +1,51 @@
1
- # Deploy pipeline
1
+ # Deploy and publish
2
2
 
3
- **`fimo deploy` is on-demand, not the working loop and not a required final step.** The loop is local: run the app with the project's package-manager `dev` script (`pnpm dev` / `npm run dev` / `yarn dev` / `bun dev` — match the lockfile), iterate with the developer, and let live reload show changes. Reach for `fimo deploy` only when the developer wants a **hosted preview**, a **project-member preview link**, or to **go live** — and only on their signal. New-project onboarding counts as the signal for its single automatic first preview deploy (see `references/init.md` § Create the first hosted preview). It commits everything, pushes to the current Branch, and round-trips that Branch's sandbox (install + restart); it's a milestone command, not a save step. Batch related edits into one deploy; never deploy after every change.
4
-
5
- > **Local vs hosted.** The local dev server is localhost only. The Fimo **dashboard preview** and the authenticated **project-member preview URL** are served by the deployed sandbox — so if the developer wants to see the site in the dashboard or send another project member a link, that requires a `fimo deploy`.
6
-
7
- `fimo deploy` uses the current Branch. New sites start on `main`; `release/*` is read-only, and `--publish` only runs from the project's configured Production source Branch. See `references/branches.md` for the multi-Branch workflow.
8
-
9
- Before deploying, Fimo fast-forwards a clean checkout that is behind and stops on dirty-behind or diverged branches. This syncs the whole branch, including config commits from Studio or locale commands.
10
-
11
- > **Just need the current preview URL?** That's `fimo preview url` — no commit or push. It waits if the hosted generation is still building. See `references/preview.md`.
12
-
13
- ## Commands
14
-
15
- ```bash
16
- fimo deploy # preview only (default; reversible)
17
- fimo deploy -m "<commit message>" # commit pending + push + sandbox sync
18
- fimo deploy -m "<commit message>" --publish # also publish a new live version
19
- ```
20
-
21
- - **`fimo deploy`** — commits pending changes, pushes to the current Branch, syncs that Branch's preview sandbox, and links to Fimo Studio.
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.)
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.
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.
25
-
26
- ## Reading deploy destinations
27
-
28
- Interactive output uses named links. Agents and scripts should request JSON:
29
-
30
- ```bash
31
- fimo deploy -m "<commit message>" --json
32
- fimo deploy -m "<commit message>" --publish --json
33
- ```
34
-
35
- Read these fields from `data`:
36
-
37
- | Field | Destination |
38
- | --------------- | ---------------------------------------------------------- |
39
- | `studio_url` | Stable Fimo Studio project and Branch page. |
40
- | `dashboard_url` | Deprecated compatibility alias for `studio_url`. |
41
- | `app_url` | Public live site, returned after a successful `--publish`. |
42
-
43
- When reporting the result, give the user `studio_url`. If a person or tool needs the hosted site itself, run `fimo preview url` after deploy.
44
-
45
- Public variables are injected into preview, build, and deploy runtimes. Private variables (`fimo vars add --private`) reach the site's server code at runtime in previews and production, never an env file or the browser bundle. Secrets are not injected into the site; agents request them separately through their own config. See `references/project-vars-and-secrets.md`.
46
-
47
- ## Diagnose a failed publication
48
-
49
- Use the publication ID returned by the failed command: run `fimo publish inspect <id> --json` for its durable status, then `fimo publish logs <id> --json` for a bounded build-log tail. Use `fimo publish list --cursor <cursor>` to continue through older attempts or `--all-pages` to fetch the complete retained history. `--before` remains a compatibility alias. Logs come from the hosting provider and may be unavailable after its deployment is reclaimed.
50
-
51
- ## Diagnose a failed preview deploy
52
-
53
- A failed `fimo deploy --json` names the cause in `error.details.failure_code` and the phase in `error.details.phase`: `pull` (Git synchronization into the sandbox), `install` (dependency install), `restart` (dev-server start), or `readiness` (the final preview check); `acquire` and `sync-env` are the sandbox and environment steps before them. When the failed process produced output, the same error carries `error.details.exit_code` and a bounded, redacted `error.details.log_tail` (newest line last). Read that tail first: it is the failed process's own output, and a replacement sandbox that failed is discarded, so `fimo logs` shows the preview that is still serving rather than the attempt that failed. The top-level codes remain compatible:
54
-
55
- - `SANDBOX_SYNC_FAILED` — the revision never became ready. Fix what the tail reports (a manifest or lockfile for `install`, the Git state for `pull`), then deploy again. When `error.details.failure_code` is `install_policy_blocked`, follow the typed repair in `error.details.repair`.
56
- - `PREVIEW_NOT_READY` — the revision landed and the preview never proved ready. `error.message` names what the readiness probe last saw: a dev server that died, or the optimized dependency the public preview route was still delivering and what the dev server said about it over loopback. Fix what the tail reports; when there is no tail, act on the message before reading `fimo logs --json`, which shows a dev server that may be healthy.
57
-
58
- `--no-wait` skips only the final readiness check. Pull, install, and dev-server failures are still reported with the same fields.
59
-
60
- When there is no tail, run `fimo logs --json` before retrying. Read the newest install and dev-server events first; when the response is truncated, use its `previousCursor` as `fimo logs --cursor <cursor> --json` to fetch the preceding page, or use `--all-pages` to fetch every retained page. `--before` remains a compatibility alias. Do not recreate or replace the sandbox before collecting logs, because that can discard the failure evidence.
61
-
62
- When Preview reports blocked dependency build scripts, treat that as a project security-policy repair, not a transient sandbox failure. Review every named package before approving it, then use the package manager's narrow project-owned mechanism:
63
-
64
- - **pnpm:** add each approved package to `allowBuilds` in `pnpm-workspace.yaml`.
65
- - **Yarn:** set `dependenciesMeta.<package>.built` in `package.json` for each approved package.
66
- - **Bun:** add approved packages to `trustedDependencies` in `package.json`, or run the exact `bun pm trust <packages>` command Preview reports.
67
- - **npm:** npm has no equivalent per-package approval error. Diagnose the failing lifecycle script itself; do not turn a generic npm script failure into a trust-policy change.
68
-
69
- Run the same plain install locally and commit the policy plus lockfile before retrying Preview. Never bypass the error with `dangerouslyAllowAllBuilds`, `enableScripts`, or another global allow-all switch: Preview and publishing intentionally consume the committed project policy.
70
-
71
- ## Framework hosting
72
-
73
- Fimo preview resolves `runtime.commands` override → package script → detected
74
- framework default. Production uses `.fimo/config.json#runtime.framework` and
75
- the same bounded build/install overrides. Existing applications keep their
76
- router and hosting behavior: do not replace the router or derive
77
- deployment rewrites from `.fimo/config.json#routes`. When setup changes are
78
- needed, load the `fimo-code` skill's framework reference:
79
- `references/frameworks/hosting.md` covers the React Router `fimoPreset()`
80
- connector and the explicit catch-all used only by plain Vite `BrowserRouter`
81
- SPAs; Astro's `fimo()` integration lives in `references/frameworks/astro.md`.
82
-
83
- Redirects, response headers, and URL shape belong in
84
- `.fimo/config.json#hosting` — see `references/hosting.md`.
85
-
86
- ## Warm the sandbox early in a session (optional)
87
-
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.
89
-
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).
91
-
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.
3
+ `fimo deploy` is a milestone command, not the work loop. Work locally with the `dev` script. Deploy when the user wants a hosted preview, a link for a project member, the Studio preview, or to go live. The new-site first preview is the only automatic deploy (`--ref init`).
93
4
 
94
5
  ```bash
95
- fimo deploy -m "chore: init" & # background; keep generating code while it runs
6
+ fimo deploy -m "<commit message>" [--description "<why>"] --json # hosted preview of the current Branch
7
+ fimo deploy -m "<commit message>" --publish --json # preview, then publish: the site goes live
8
+ fimo publish [--label <text>] [--notes <md>] --json # publish the revision already on Fimo, no push
9
+ fimo preview url --json # current hosted preview URL, no deploy
96
10
  ```
97
11
 
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.
99
-
100
- ## Publishing: `fimo deploy --publish` vs `fimo publish`
12
+ ## What a deploy does
101
13
 
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.
14
+ - It commits pending changes (`-m` is the subject, `--description` is the body: why the change was made), pushes to the current Branch, and syncs that Branch's preview sandbox (it installs and restarts when needed). Batch related edits into one deploy.
15
+ - It uses the Branch of the current Git checkout. A checkout of a `release/*` tag is read-only. `--publish` and `fimo publish` run only from the configured production source Branch (default `main`). Other Branches: `--ref branches`.
16
+ - Before it changes files, it fast-forwards a clean checkout that is behind. It stops on a dirty checkout that is behind, or on a diverged one: follow the `hint`. If the push still loses a race, run `git pull --rebase fimo <branch>`, fix conflicts, and deploy again.
17
+ - Read `data.studio_url` and give it to the user (`data.dashboard_url` is an old alias). After `--publish`, `data.app_url` is the public site. For the hosted preview URL, run `fimo preview url`.
18
+ - Public variables reach preview and production. Private variables reach server code and the build, never the `.env` file; do not read them in browser code. Secrets do not reach the site (`--ref project-vars-and-secrets`).
103
19
 
104
- Check the reported source commit and warnings before reporting completion. If local work is excluded or the built commit cannot be confirmed, follow the CLI's hint.
20
+ ## Publish safely
105
21
 
106
- ## Markdown for AI agents
22
+ - **Publish only when the user says to publish, ship, or go live.** Publishing makes the site public.
23
+ - Local changes to go live: `fimo deploy --publish`. The revision already on Fimo is the release: `fimo publish` (it never pushes).
24
+ - Check the reported source commit and warnings before you report success. If local work is not in the build, or the built commit is unknown, follow the hint.
25
+ - A failed publication usually gives its id (`error.details.publication_id`; else find it with `fimo publish list`). Run `fimo publish inspect <id> --json` for the status and cause, then `fimo publish logs <id> --json` for the build log. The hosting provider can delete old logs: then report that, and do not publish again only to get logs. Older attempts: `fimo publish list --cursor <cursor>` or `--all-pages`.
107
26
 
108
- Every Fimo deploy emits an AI-friendly version of the site alongside the HTML. No setup needed.
27
+ ## A failed preview deploy
109
28
 
110
- - **`.md` next to every prerendered page** — e.g. `index.html` → `index.md`. Frontmatter is pulled from `<title>`, `<meta name="description">`, and OG tags. Body is the `<main>` content converted to GitHub-flavored markdown.
111
- - **`/llms.txt` at the site root** — a markdown index of all pages with their title, description, and `.md` URL, following the [llms.txt](https://llmstxt.org) convention. Pages are grouped by top-level path segment (e.g. `/blog/*` → "Blog" section).
29
+ - When known, the error names the step in `error.details.phase` (`acquire`, `pull`, `sync-env`, `install`, `restart`, `readiness`) and the cause in `error.details.failure_code`, with `error.details.exit_code` and `error.details.log_tail` (newest line last) when the process wrote output. **Read the tail first.** A failed replacement sandbox is deleted, so `fimo logs` shows the preview that still serves, not the failed attempt.
30
+ - `SANDBOX_SYNC_FAILED`: the revision never became ready. Fix what the tail reports (manifest or lockfile for `install`, Git state for `pull`), then deploy again.
31
+ - `PREVIEW_NOT_READY`: the revision landed but the preview never proved ready. `error.message` says what the check saw (a dev server that stopped, or a dependency that was still being optimized). Act on it before you read `fimo logs`, which can show a healthy dev server.
32
+ - No tail: run `fimo logs --json` before you retry, newest install and dev-server events first (`--cursor` or `--all-pages` for more). Do not replace the sandbox before you collect logs.
33
+ - `--no-wait` skips only the last readiness check; earlier failures still report.
112
34
 
113
- Three equivalent ways for an agent to fetch markdown:
114
-
115
- ```bash
116
- curl https://your-site/index.md # .md suffix
117
- curl -H 'Accept: text/markdown' https://your-site/ # content negotiation
118
- curl https://your-site/?format=md # query param
119
- ```
35
+ ### Blocked build scripts (`install_policy_blocked`)
120
36
 
121
- This is a hosting capability: Fimo generates the `.md`, content-negotiation, and `?format=md` responses for supported built pages. Application code must not reimplement any of them — in particular, never add a route that fetches the app's own public URL to convert it to Markdown. For a dynamic page, render Markdown from the same server-side data the page itself uses when the framework supports that; otherwise report the capability as unresolved instead of building a self-fetching route.
122
-
123
- ## Recovering from Git drift
124
-
125
- Most stale states are caught before deploy changes or commits files. Follow the emitted hint: clean a dirty checkout, or reconcile a diverged branch. A push can still lose a race if the remote advances after preflight:
126
-
127
- ```bash
128
- git pull --rebase fimo <branch> # <branch> = the Branch you're deploying (e.g. main)
129
- # fix any conflicts
130
- fimo deploy
131
- ```
37
+ This is a project security policy, not a sandbox fault. Follow `error.details.repair`. Review each named package, then approve only those packages with the project's own setting:
132
38
 
133
- ## Other facts
39
+ - **pnpm:** add each package to `allowBuilds` in `pnpm-workspace.yaml`.
40
+ - **Yarn:** set `dependenciesMeta.<package>.built` in `package.json`.
41
+ - **Bun:** add the package to `trustedDependencies` in `package.json`, or run the exact `bun pm trust <packages>` command from the error.
42
+ - **npm:** has no per-package approval. Fix the failed script itself; do not change a trust policy.
134
43
 
135
- - Source of truth is this git repo.
136
- - **Never** edit `.fimo/project.json`; it is generated by `fimo init`.
137
- - Each Branch deploys to its own preview sandbox; `--publish` and `fimo publish` run from the configured Production source Branch only. See `references/branches.md`.
44
+ Run the same install locally, commit the policy and the lockfile, then deploy again. **Never use `dangerouslyAllowAllBuilds`, `enableScripts`, or another allow-all switch.**
138
45
 
139
- ## After the first successful deploy
46
+ ## Hosting facts
140
47
 
141
- - Suggest inviting collaborators with `fimo invite` if the project involves multiple people. Typical roles: `edit` for developers/content editors, `view` or `comment` for clients/stakeholders, `full` for project leads. See `references/invite.md`.
142
- - If the user wants to modify the URL of the deployed website, see `references/domains.md` — that skill covers renaming the Fimo subdomain (`rename-default`, free), attaching a domain they own (`add`, Premium), and buying a new domain through Fimo (`buy`, Premium).
48
+ - Fimo hosts the site. Preview runs `runtime.commands`, else the package script, else the framework default. Production builds from `.fimo/config.json#runtime.framework` with the same build and install overrides. An existing app keeps its router and hosting setup: do not replace the router, and do not derive rewrites from `.fimo/config.json#routes`. Framework setup (React Router `fimoPreset()`, plain Vite SPA catch-all): fimo-code `frameworks/hosting`; Astro: `frameworks/astro`. Redirects, headers, and URL shape: `--ref hosting`.
49
+ - **Markdown for AI agents:** Fimo hosting also serves a Markdown copy of each prerendered page (`/page.md`, `Accept: text/markdown`, or `?format=md`) and an `/llms.txt` index. Fimo makes these; never add a route that does it, and never add a route that fetches the site's own public URL. For a dynamic page, render Markdown from the same server data when the framework supports it; otherwise report the gap.
50
+ - **Warm-up:** the first deploy of a project provisions the sandbox, so it is slower than later deploys. When the user already asked for a hosted preview or a publish later in the session, you can start that deploy early in the background. The new-site first preview is already the warm-up.
51
+ - After the first deploy, change the site URL with `--ref domains`: a free `*.fimo.site` rename, a domain the user owns (Starter or higher), or a new domain bought through Fimo.