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.
Files changed (30) hide show
  1. package/README.md +9 -0
  2. package/assets/skills/fimo-cli/SKILL.md +57 -140
  3. package/assets/skills/fimo-cli/references/account.md +2 -0
  4. package/assets/skills/fimo-cli/references/agent-setup.md +1 -1
  5. package/assets/skills/fimo-cli/references/assets.md +2 -0
  6. package/assets/skills/fimo-cli/references/branches.md +10 -2
  7. package/assets/skills/fimo-cli/references/content/bulk.md +57 -0
  8. package/assets/skills/fimo-cli/references/content/entries.md +54 -0
  9. package/assets/skills/fimo-cli/references/content/localized.md +56 -0
  10. package/assets/skills/fimo-cli/references/content/schemas.md +29 -0
  11. package/assets/skills/fimo-cli/references/content/sql.md +64 -0
  12. package/assets/skills/fimo-cli/references/content.md +33 -262
  13. package/assets/skills/fimo-cli/references/deploy.md +1 -26
  14. package/assets/skills/fimo-cli/references/forms.md +1 -1
  15. package/assets/skills/fimo-cli/references/init.md +19 -19
  16. package/assets/skills/fimo-cli/references/locales.md +2 -2
  17. package/assets/skills/fimo-code/references/content/richtext.md +2 -2
  18. package/assets/skills/fimo-studio/SKILL.md +8 -10
  19. package/assets/skills/fimo-studio/references/ai-chat.md +2 -2
  20. package/assets/skills/fimo-studio/references/billing-and-credits.md +12 -1
  21. package/assets/skills/fimo-studio/references/project-creation.md +4 -4
  22. package/dist/cli/bundle.json +1 -1
  23. package/dist/cli/index.js +124 -113
  24. package/package.json +8 -8
  25. package/release.json +2 -2
  26. package/templates/astro/package.json +3 -3
  27. package/templates/nextjs/package.json +4 -4
  28. package/templates/react-router/package.json +5 -5
  29. package/templates/sveltekit/package.json +3 -3
  30. package/templates/vite/package.json +5 -5
package/README.md CHANGED
@@ -37,6 +37,15 @@ cd my-site
37
37
 
38
38
  Every command runs the same way: **`npx fimo@latest <command>`**. `fimo init` sets up the site, pushes the first commit, and wires it to your Fimo account. Open it in your coding agent and start building.
39
39
 
40
+ ## No account yet?
41
+
42
+ `fimo new` creates a site without signing in; a person claims it within 72 hours through the printed claim link. It is the path for sandboxes, CI, and headless coding agents, where `fimo login` cannot open a browser:
43
+
44
+ ```bash
45
+ npx fimo@latest new my-site # creates the site and prints the claim link
46
+ npx fimo@latest new --instructions # the setup guide for coding agents (the text of https://fimo.new)
47
+ ```
48
+
40
49
  ## AI coding tools
41
50
 
42
51
  Fimo ships skills and rules for your AI coding tools (Claude Code, Cursor, Codex, Gemini, and more) so the agent knows how to work in a Fimo site. `fimo init` installs them for you — add or refresh them any time (`--mode=copy` is required under npx):
@@ -9,151 +9,68 @@ description: >-
9
9
 
10
10
  # Fimo CLI
11
11
 
12
- The `fimo` CLI is the workflow surface for Fimo. Fimo connects content, media, forms, analytics, editing, and hosting to web applications. The CLI handles site creation, content / forms / media / labels / locale workflows, deploys, collaboration, account management, AI credit inspection, and AI agent setup.
12
+ This skill covers CLI workflows. For code (schema JSON, generated clients, primitives, framework adapters), load `fimo skills get fimo-code`. For the flags of one command, run `fimo <command> --help`.
13
13
 
14
- This skill describes **what the CLI does and the workflows it drives**. For the package surface used IN code (component props, generated hooks, JSON shapes, code-side rules), load the `fimo-code` skill on demand with `fimo skills get fimo-code`, using the invocation prefix below.
14
+ ## Every task
15
15
 
16
- Use `fimo <command> --help` for full flag details on any command.
17
-
18
- > Verify a destination with `fimo webhooks test <id> --wait` and inspect its delivery history before depending on it in production.
19
-
20
- ## Shared site knowledge
21
-
22
- Before site planning, recommendations, design, copy, content, or code work, read the site's
23
- knowledge: `fimo knowledge get --project <id> --json` (omit `--project` in a linked checkout).
24
- Use the selected CLI invocation. Load `fimo skills get fimo-cli --ref knowledge` for refresh,
25
- empty-state, and explicit-write rules. This prerequisite also applies when entering this skill directly.
26
-
27
- ## Running the CLI
28
-
29
- Use **`npx fimo@latest`** by default. If the initiating prompt supplies another Fimo CLI selector, such as `npx fimo@staging` or `npx fimo@0.14.0`, preserve that selector for every Fimo command in the same flow. Do **not** install `fimo` globally.
30
-
31
- The examples in this skill and its references use `fimo <command>` as shorthand. Execute them with the selected invocation above.
32
-
33
- ## Output for agents: `--json` is the stable contract
34
-
35
- Every command accepts a global `--json` flag (or `FIMO_OUTPUT=json` env) and emits exactly one structured envelope on stdout:
16
+ - **Invocation:** run `npx fimo@latest`, unless the prompt gives another selector, such as `npx fimo@staging` or `npx fimo@0.14.0`. Then use that selector for every Fimo command in the flow. Do not install `fimo` globally. This skill writes `fimo` for the selected invocation.
17
+ - **Site knowledge:** before planning, recommendations, design, copy, content, or code work, read `fimo knowledge get --json` (add `--project <id>` outside a linked checkout). Rules: `--ref knowledge`.
18
+ - **Project link:** `.fimo/project.json` links the folder to the site. Never edit it.
19
+ - **Branch:** site commands act on the Fimo Branch that matches the current git branch, and print its name. `--branch <name>` changes the Branch for one command. Analytics reads use `prod` by default. Switch Branches with `fimo checkout <name>` (`--ref branches`).
20
+ - **Output:** pass `--json` and read `data`. Branch on `error.code`, not on the message, and follow `hint`. JSON mode never prompts, so give each answer as a flag (`--yes`, `--org <id>`, `-m <message>`).
36
21
 
37
22
  ```json
38
23
  { "status": "ok", "command": "<name>", "schema_version": 1, "data": { ... }, "hint"?: "...", "warnings"?: [...] }
39
24
  { "status": "error", "command": "<name>", "schema_version": 1, "error": { "code": "UPPER_SNAKE_CASE", "message": "...", "hint"?: "..." } }
40
25
  ```
41
26
 
42
- Branch on `error.code`, never on `error.message`. The envelope shape is versioned — `schema_version: 1` is stable; any breaking change bumps the version. Per-command `data` shapes are documented in `apps/cli/CLAUDE.md` (consumers of this skill don't normally need to read it, but it's the source of truth).
43
-
44
- For shell composition use plain pretty mode (`cd $(fimo …)`); for structured parsing use `--json`. JSON mode disables interactive prompts — commands that need a confirmation fail fast unless every required arg is on the command line (`--yes`, `--org`, etc.). Locale lifecycle commands use `CONFIRMATION_REQUIRED` and require `--yes`; other older commands may use `NON_INTERACTIVE_REFUSAL`.
45
-
46
- Pretty output may hide URLs behind clickable labels. Agents should use `--json` and read `data`.
47
-
48
- ## Critical: `.fimo/project.json` is the project link
49
-
50
- A Fimo site is identified by `.fimo/project.json`, written by `fimo init`. This file connects the local directory to the remote Fimo site. **Never edit it manually.** Most CLI commands find it by walking up from the cwd.
51
-
52
- ## Critical: commands target the Branch matching the current git branch
53
-
54
- A project can have multiple **Branches** — each is a git branch _plus_ its own DB, sandbox, preview, and assets. Site-scoped commands (`deploy`, `status`, `entries`, `diff`, …) operate on the Branch matching the **current git branch**, and print a one-line banner saying which one. Analytics reads are the exception: they default to canonical `prod`, independent of the checkout; see `references/analytics.md`. Annotation writes keep the current or explicit Branch. New sites start on `main`. Override for a single command with the canonical `--branch <name>` flag; the removed `--env <name>` spelling is rejected. Never edit the link file to switch. The full git-shaped workflow (`branch` / `checkout` / `switch` / `pull` / `diff` / `merge` / `status` / `publish`) lives in `references/branches.md`.
55
-
56
- ## Quick Start
57
-
58
- ```bash
59
- fimo login # authenticate via browser
60
- fimo skills install # install the global Fimo skill for your AI tools
61
- fimo init my-site --org <id> # one-stop setup: sign in, create/link a project, install deps + skills. Use the org **id** from `fimo orgs list`, NOT the slug.
62
- fimo init my-react-site --framework react-router --org <id> --yes --no-skills # canonical React Router template
63
- fimo init --project-id <id> my-site # set up a project by ID: scaffold a newly created project or clone existing code
64
- fimo new my-site --yes --json # create a site without an account; a person claims it within 72 hours. Run `fimo new --instructions` for the full guide
65
- fimo claim --json # inside a `fimo new` site: the claim link and claim state
66
- fimo clone # interactively choose an existing project to clone locally
67
- cd my-site # then load skills on demand: fimo skills get fimo-code
68
- pnpm dev # run the app locally (use the project's PM: pnpm/npm run/yarn/bun) — your iteration loop
69
- fimo credits # inspect the owning org's AI credit balance (read-only)
70
- fimo history list # inspect this Branch's restore points
71
- fimo validate # run all checks + codegen; fails on missing DB labels
72
- fimo deploy # ON-DEMAND: hosted project preview (runs validate internally)
73
- fimo deploy --publish # ON-DEMAND: publish live (only when the developer says "ship it")
74
- ```
75
-
76
- New sites use the Next.js App Router template by default. Fimo's canonical React Router template is selected explicitly with `--framework react-router`; use `--framework vite` for a React SPA.
77
-
78
- The working 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), ask the developer what they want, edit, and iterate against the live localhost server. Outside the first-time onboarding rule below, `fimo deploy` is **not** a required final step — reach for it only when the developer wants a hosted project preview or to go live, and only on their signal (see `references/deploy.md`).
79
-
80
- `fimo validate` is the single entrypoint for "prove this project is ready" — it covers schema/form codegen, route metadata checks, lint, and missing label checks for `i18n.defaultLocale` from `.fimo/config.json` (fallback: `en`). Use `fimo labels set` / `set-many` to create or update label values in the DB. The underlying phases are also available individually under the hidden `fimo scripts` namespace for advanced/debug use.
81
-
82
- Keep `fimo validate --json` at the front of the project's `build` script, which is where the bundled templates put it. The hosted build runs that script, so validation runs on the exact code being published and a rejected build reports the failing rule instead of a generic build error. Removing it is the developer's call, but do not drop it while editing `package.json` for other reasons.
83
-
84
- **`fimo validate` does not type check.** Run the project's own `typecheck` or `check` script after changing code.
85
-
86
- ## Decision Tree
87
-
88
- Load the matching reference when the user's request fires its trigger. Recipes that involve writing code also need the `fimo-code` skill's package references — they're called out where relevant.
89
-
90
- - "Create a new Fimo site / scaffold a site / start a new website / link an existing project locally" → `references/init.md`
91
- - "Add a content type / blog / products / content schemas / CMS" → `references/content.md` (workflow) **+ run `fimo skills get fimo-code --ref content/schema` and load the detected framework reference**
92
- - "Declare Pages routes / configure Pages sources or route params / control what Studio shows for a route" → `references/pages.md`
93
- - "Add a contact / signup / feedback / newsletter form" → `references/forms.md` (workflow) **+ run `fimo skills get fimo-code --ref forms` for the JSON spec and generated client**
94
- - "View form submissions / who filled out the contact form / inspect what users sent / how many signups" → `references/forms.md` § Reading submissions
95
- - "Upload, inspect, replace, safely remove, or permanently destroy an image / hero / cover / existing media file" → `references/assets.md` **+ run `fimo skills get fimo-code --ref assets` for the `FimoMedia` shape and rendering**
96
- - "Generate AI image / video / draft preview / image edit / cover from a prompt" → `references/media.md` (task commands, quality, recipes, and verification) **+ run `fimo skills get fimo-code --ref assets` for the `FimoMedia` shape if you'll plug the result into UI**
97
- - "Add labels / update static copy / fix missing `t()` values" → `references/labels.md` (workflow) **+ run `fimo skills get fimo-code --ref labels` and load the detected framework reference**
98
- - "Enable locales / configure default locale / integrate an existing locale system" → `references/locales.md` **+ run `fimo skills get fimo-code --ref locales` and load the detected framework locale reference**
99
- - "What's in this project / show the project structure / describe the project / what schemas does it have / how many routes / project tree / show me what's here" → `references/describe.md`
100
- - "Deploy / publish / go live / push my changes" → `references/deploy.md`
101
- - "Add a redirect / security headers / CSP / HSTS / clean URLs / trailing slash" → `references/hosting.md`
102
- - "Get the preview URL / open the preview / what's the URL for this Branch / refresh the preview link / I just want to see the site / the preview URL stopped working" → `references/preview.md`
103
- - "Check the site in a browser / SEO check / broken links / missing titles, descriptions or alt text / `fimo site check` / is my site accessible / a11y or WCAG check / measure LCP or Web Vitals / why is the page slow / inspect network requests or console errors / Lighthouse score" → `references/site-checks.md`
104
- - "Schedule a command / cron / nightly publish / recurring checks / `fimo schedules`" → `references/schedules.md`
105
- - "Set env vars / configure API keys / add project secrets / local `.env.local` / `fimo vars` / `fimo secrets`" → `references/project-vars-and-secrets.md`
106
- - "React to form submissions / publish changes / analytics reports / media activity / send events to Resend, Slack, GitHub, Zapier, or an HTTP endpoint / configure or debug outbound webhooks" → `references/webhooks.md`
107
- - "Use a connected app / Google Search Console / clicks, impressions, rankings, keywords from Google / Google Analytics / GA4 users, sessions, traffic sources, key events / enable provider tools / integrations / add, inspect, search, or run an MCP server / `fimo integrations` or `fimo mcp`" → `references/integrations.md`
108
- - "Firecrawl / scrape a public website / competitor research / agent web research" → `references/integrations.md` **+ load `references/integrations/firecrawl.md`**
109
- - "Check credits / credit balance / can I keep using AI / billing credits / running low / how many credits are left" → `references/credits.md`
110
- - "List history / create a restore point / recover content and code / restore a previous version / snapshot usage or retention" → `references/history.md`
111
- - "Create a Branch / feature Branch / switch Branches / merge Branches / diff two Branches / Branch status / what changed on this Branch / sync from parent / cut a release / tag a version / go to prod" → `references/branches.md`
112
- - "List my projects / clone an existing project locally / check out a project / delete this project / unpublish / rename the project / manage projects across the org" → `references/projects.md`
113
- - "Migrate an existing Webflow / Framer / Squarespace / Wix / Carrd site from only a published URL" → load the `fimo-migration` skill, set the target up with `fimo migrate init <dir>`, and read the published site yourself with a browser — the CLI does not crawl it
114
- - "Put my existing site or app on Fimo / link or deploy the app in this folder / host the site I built" → load the `fimo-migration` skill and follow its source-backed, same-framework path: `fimo link` keeps every word typed in the code, which Studio cannot edit, until the migration's content pass moves it to labels and the CMS
115
- - "Migrate from an exported project, source repository, Webflow code export plus CMS CSVs, Framer CMS CSVs, Squarespace XML/CSV, Wix CSVs, Carrd/static export, or downloaded site files" → load the `fimo-migration` skill and use the source repo/export as the migration source of truth
116
- - "How do AI agents read my site / markdown for agents" → `references/deploy.md`
117
- - "Modify the URL of the website / change my project's address / connect a custom domain (e.g. blog.example.com) / rename the Fimo-provided `*.fimo.site` subdomain / buy a new domain through Fimo / set up a domain" → `references/domains.md`
118
- - "Invite a collaborator / add Marc / share with client" → `references/invite.md`
119
- - "Login / log out / who am I / switch organization" → `references/account.md` — note: switching **org** is `fimo orgs switch`; bare `fimo switch` changes the active **Fimo Branch** (see `references/branches.md`)
120
- - "Install Fimo for my agent / fimo skills install / set up Claude Code, Codex, or Cursor for Fimo" → `references/agent-setup.md`
121
- - "Refresh / update installed Fimo skills / fimo skills sync / agent missing the latest Fimo conventions" → `references/agent-setup.md`
122
- - "Update / upgrade the project's fimo packages / move to a new Fimo release / `fimo update`" → `references/update.md`. Never edit `fimo` or `fimo-*` versions directly in `package.json`; `fimo update` keeps package pins and codemods aligned.
123
- - "Report a Fimo problem or blocking feature request / contact Fimo support / a Fimo API or command keeps failing / a documented argument is rejected / a supported operation needs an undocumented workaround / a Fimo API is abnormally slow / a confirmed missing capability blocks completion or forces a fragile or heavily manual workaround" → `references/support.md`
124
- - "Regenerate rule files / I edited AGENTS.md / fimo rules sync" → `references/agent-setup.md`
125
- - "Show analytics / visitor stats / traffic / pageviews / how is my site performing / top pages / where do visitors come from" → `references/analytics.md` (7-day preview free for all; longer ranges require paid)
126
- - "Mark a date on the analytics chart / annotate the chart with a deploy / add a launch note" → `references/analytics.md` § Annotations
127
-
128
- ## Lifecycle nudges
129
-
130
- These fire at specific moments in the project lifecycle. **Surface them proactively** rather than waiting for the user to ask:
131
-
132
- - **Right after `fimo init`** → `cd` into the new directory, read the project's `AGENTS.md` (or `CLAUDE.md` for Claude Code), run `fimo describe --json`, then load `fimo-code` and only the task/framework references it routes to. The rules file came into existence mid-session and may not be auto-loaded by the harness. See `references/init.md` § Load the project context.
133
- - **When `fimo init` created or scaffolded a new site (create-new path, including a Studio-supplied `--project-id`)** → after init and context loading succeed, run the single first-preview deploy and return the preview and dashboard links — see `references/init.md` § Create the first hosted preview. That deploy is also the sandbox warm-up; never run a separate warm-up deploy. Skip it only if the user explicitly said not to deploy. Linking a project with existing code and migrations keep their own approval rules.
134
- - **Right after `fimo init`** → suggest `fimo rename "<Display Name>"` to set a human-readable name (the default post-init name is an auto-generated slug). Infer the name from what the user is building (e.g. "Acme Coffee" for a café, "Jane Doe Portfolio" for a personal site). See `references/init.md`.
135
- - **Right after `fimo init`** → start the app locally with the project's package-manager `dev` script (`pnpm dev` / `npm run dev` / `yarn dev` / `bun dev`) in the background. This localhost server with live reload is your iteration loop — edit, show, repeat. No deploy is needed to see local changes. If the initiating request did not say what to build, ask the developer — after the first preview on the create-new path, never as a blocker before initializing.
136
- - **When a user-visible unit of work looks done outside first-time onboarding** → **offer** to deploy (`fimo deploy` for a hosted project preview, `fimo deploy --publish` to go live) and run it only after the developer confirms — or immediately if they ask. Never deploy ordinary edits on your own. See `references/deploy.md`.
137
- - **Optional, outside new-project onboarding (its first preview already warms the sandbox), if you already know a deploy is coming** → warm the sandbox early with `fimo deploy -m "chore: init" &` in the background so the one-time ~15-30s provision + dep install happens while you work and the real deploy lands warm (~4-10s). This is a perf optimization, not a requirement. See `references/deploy.md` § Warm the sandbox early in a session.
138
- - **Iterative code-only deploys** → once you are deploying, `fimo deploy --no-restart` skips the sandbox dev-server restart on HMR-safe edits. See `references/deploy.md` § Skipping the dev-server restart for when it's safe.
139
- - **You need the current preview URL but haven't changed code** (opening it, screenshotting it, handing it to another tool, the previous URL expired) → `fimo preview url`, never a no-op `fimo deploy`. See `references/preview.md`.
140
- - **When the user wants to try something risky / explore a redesign without touching the live site** → suggest a feature Branch: `fimo checkout -b <name>` gives an isolated Branch + DB + preview. Deploy previews there, then `fimo merge` it back and `fimo publish`. See `references/branches.md`.
141
- - **After completing or safely preserving the user's main work, when a confirmed Fimo platform failure still materially blocks the task after one safe recovery attempt, or a confirmed missing capability blocks completion or forces a fragile or heavily manual workaround** → use the built-in `supportReport` tool. Do not wait for the user to ask and do not stop after only describing the gap. See `references/support.md`.
142
- - **After the first successful `fimo deploy`** → suggest `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`.
143
- - **After the automatic first-preview deploy on the create-new path, before the project has been published** → if there is no custom domain and the free default `*.fimo.site` slug still looks generated or was never explicitly chosen, offer to find a cleaner free subdomain. It needs no DNS. Never claim one without explicit user confirmation: suggest candidates, let the user choose, then rename it. Choosing the slug does not publish the site; the URL starts resolving only after the first successful `fimo deploy --publish`. Skip this nudge if the user already chose the default slug, attached a custom domain, or declined. See `references/domains.md` § Offer a cleaner default URL before first publish.
144
- - **When the user wants to modify the URL of their website** → walk through `references/domains.md`. The CLI surface covers renaming the Fimo-provided subdomain (`fimo domains rename-default`, free), attaching a domain they already own (`fimo domains add`, Premium), and buying a new domain through Fimo (`fimo domains buy`, Premium).
145
-
146
- ## Anti-Patterns
147
-
148
- - **Editing `.fimo/project.json`** — read-only; it's the link between local and remote site. Treat as a generated file.
149
- - **Treating `fimo deploy` as the working loop or a required final step** — the loop is local (`pnpm dev` etc.). Deploy commits + pushes + round-trips the sandbox; it's for hosted previews / going live, on-demand. Iterate locally and deploy at logical breakpoints. See `references/deploy.md`.
150
- - **Deploying without the developer asking or confirming** — new-project onboarding authorizes exactly one automatic first preview deploy (unless the user said not to deploy); every other deploy is offer-then-confirm. Don't auto-deploy after finishing an ordinary edit.
151
- - **Running `fimo deploy` just to get the current preview URL** — that's a commit + push + sandbox sync when only destination resolution is needed. Use `fimo preview url` instead. See `references/preview.md`.
152
- - **Using `fimo deploy --publish` casually** — `--publish` makes the site live to the public. Plain `fimo deploy` (preview) is the default. Use `--publish` only when the user says "ship it" / "go live" / "publish".
153
- - **Bare `fimo init` in a non-interactive shell** — will hang. Always pass `[dir]`, `--no-install` (or `--install`), `--no-skills` (or `--skills`), and `--org`/`--agents` as needed explicitly when scripted.
154
- - **Hardcoding content / strings / images in code, or committing image and video files** — that's what schemas, `t()`, and the media library are for. See the `fimo-code` skill's non-negotiable boundaries.
155
- - **Adding another deploy tool**. Fimo handles deploys; don't bolt another platform on.
156
- - **Committing secrets or storing API keys as public variables** — server-side keys use `fimo vars add --private`; Fimo-only credentials use `fimo secrets`; public browser-safe values use `fimo vars`. Local env files are ignored and must not become deploy inputs.
157
- - **Hardcoding tokens in flags** — use the credentials written by `fimo login` (one file per backend at `~/.config/fimo/credentials/<host>-<hash>.json`).
158
- - **Treating the daily allowance as extra credits** — the allowance section appears only for legacy Premium organizations, and `fimo credits` already includes its spendable credits in "Available now"; it is accounting context, not an amount to add.
159
- - **Trying to refill credits from the CLI** — `fimo credits` is read-only. Buying/refilling credits belongs in the billing UI for now.
27
+ ## Work loop
28
+
29
+ - Work locally: run the project's `dev` script in the background (`pnpm dev`, `npm run dev`, `yarn dev`, or `bun dev`, from the lockfile). Live reload shows each change. You do not need a deploy to see it.
30
+ - `fimo validate` runs all checks and codegen, and fails when default-locale labels are missing. It does not type check: also run the project's `typecheck` or `check` script. Keep `fimo validate --json` first in the `build` script.
31
+ - Keep editor content, copy, and media in schemas, labels, and the media library, not in code (`fimo-code`).
32
+ - Fimo hosts and deploys the site. Do not add another hosting or deploy tool.
33
+
34
+ ## Safety
35
+
36
+ - **Deploy:** `fimo deploy -m "<message>"` makes a hosted preview. Deploy only when the developer asks or agrees. When a unit of work looks done, offer a deploy. The only automatic deploy is the first preview after `fimo init` creates a site (`--ref init`).
37
+ - **Publish:** add `--publish` only when the user says to publish, ship, or go live. It makes the site public.
38
+ - **Preview URL:** when you need the current preview URL and the code did not change, run `fimo preview url`. Never deploy only to get a URL.
39
+ - **Secrets:** put server-side keys in `fimo vars add <NAME> --private`, and Fimo-only credentials in `fimo secrets`. Never commit secrets, put them in public variables, or pass tokens in flags. `fimo login` stores the session.
40
+ - **Packages:** change `fimo` and `fimo-*` versions only with `fimo update <version>`, never in `package.json`.
41
+ - **Blockers:** first finish or save the main work. Then, if a confirmed Fimo platform failure still blocks the task after one safe recovery step, or a missing capability blocks it or forces a fragile workaround, use the `supportReport` tool. Do not wait for the user to ask (`--ref support`).
42
+
43
+ ## Find the reference
44
+
45
+ Load a reference with `fimo skills get fimo-cli --ref <name>`. "+ fimo-code `<ref>`" means: also load that `fimo-code` reference and the reference for the detected framework.
46
+
47
+ - Create a site, link a project, `fimo init`, and the steps right after init → `init`
48
+ - No account or no browser: `fimo new <dir> --yes --json` (a person claims the site in 72 hours; `fimo claim --json` shows the link; `fimo new --instructions` prints the guide) → `account`
49
+ - Sign in, who am I, switch organization (`fimo orgs switch`; `fimo switch` changes the Branch) → `account`
50
+ - List, clone, rename, delete, or unpublish projects → `projects`
51
+ - Project snapshot: framework, schemas, routes, locales, tree (`fimo describe --json`) → `describe`
52
+ - Content types, Singles, entries, a blog, the CMS → `content` + fimo-code `content/schema`
53
+ - Page routes, params, and sources that Studio shows → `pages`
54
+ - Forms and form submissions → `forms` + fimo-code `forms`
55
+ - Upload, replace, or remove media files → `assets` + fimo-code `assets`
56
+ - Generate or edit an image or video with AI → `media` (+ fimo-code `assets` to show it in the UI)
57
+ - Labels, static copy, missing `t()` values → `labels` + fimo-code `labels`
58
+ - Locales and the default locale → `locales` + fimo-code `locales`
59
+ - Deploy, publish, failed deploys, markdown pages for AI agents → `deploy`
60
+ - Preview URL → `preview`
61
+ - Redirects, security headers, clean URLs, trailing slash → `hosting`
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`
64
+ - Restore points and recovery → `history`
65
+ - Environment variables and secrets → `project-vars-and-secrets`
66
+ - Send form submissions, publishes, or other events to Slack, Resend, GitHub, Zapier, or a URL → `webhooks`
67
+ - Connected apps, Search Console, Google Analytics, MCP servers → `integrations`; Firecrawl web research → also `integrations/firecrawl`
68
+ - Visitors, page views, top pages, chart annotations → `analytics`
69
+ - Site URL: rename the free `*.fimo.site` slug (`fimo domains rename-default <slug>`), add a domain the user owns, buy a domain → `domains`
70
+ - Invite people. After the first deploy, suggest it when other people work on the site → `invite`
71
+ - AI credit balance (read-only) → `credits`
72
+ - Scheduled commands → `schedules`
73
+ - Set up an AI agent, install or sync Fimo skills, `fimo rules sync` → `agent-setup`
74
+ - Update Fimo packages → `update`
75
+ - Report a Fimo problem → `support`
76
+ - Move an existing site or app onto Fimo (published URL, source code, export, CSV files, `fimo link`) → load the `fimo-migration` skill
@@ -10,6 +10,8 @@ fimo login # opens your browser; the CLI captures the token automatically
10
10
 
11
11
  `fimo login` starts a local loopback server, opens your browser to authorize, and the browser redirects the token back to the CLI — **there's nothing to copy or paste**. After login, the CLI saves the session token and auto-selects an active organization (your session's current org, otherwise the first one) — it never prompts. If you belong to more than one org, change the active one later with `fimo orgs switch` (see below).
12
12
 
13
+ `fimo login` needs a browser on this machine, not a terminal: a coding agent can run it and the user finishes sign-in in the browser that opens. Where no browser can open (a sandbox, CI), it stops at once with `LOGIN_REQUIRES_BROWSER`; create the site without an account instead with `fimo new <dir> --yes --json` (`fimo new --instructions` prints the guide).
14
+
13
15
  ```bash
14
16
  fimo whoami # show the currently signed-in user + active organization
15
17
  fimo logout # revoke the current session and clear local credentials
@@ -84,7 +84,7 @@ Every command that takes agents accepts the same selection inputs:
84
84
  - **Additional** — agents that get the global bootstrap skill installed. The popular ones (`claude-code`, `cursor`, `codex`, `opencode`, `windsurf`, `gemini-cli`, `hermes`) appear at the top of the picker; the full list of supported agents remains available below them. Agents already set up on the machine are pre-checked.
85
85
  - `--agents=none` (only `fimo init`) — skip the global skill entirely.
86
86
 
87
- In headless contexts (CI, agent-spawned commands), pass the flag explicitly. Env-var detection (only Claude Code's `CLAUDECODE` / `CLAUDE_CODE_ENTRYPOINT`) silently targets `claude-code` if the flag is omitted; every other agent must be named explicitly with `--agents` in a headless shell, or the command exits with "No agents detected and no --agents flag passed."
87
+ In headless contexts (CI, agent-spawned commands), pass the flag explicitly. Env-var detection (only Claude Code's `CLAUDECODE` / `CLAUDE_CODE_ENTRYPOINT`) silently targets `claude-code` if the flag is omitted; every other agent must be named explicitly with `--agents` in a headless shell, or the command exits with "No agents detected and no --agents flag passed." `fimo new` takes no agent flags and installs no skill. A non-interactive `fimo init` without `--skills` installs no skill and needs no agent; with `--skills` and no agent found, it still sets up the site and skips the skill install with a warning.
88
88
 
89
89
  ## Always current, never stale
90
90
 
@@ -15,6 +15,8 @@ fimo assets upload ./hero.jpg --name "Hero Image" --parent-id "<folder-uuid>"
15
15
  fimo assets upload ./screenshot.png --folder-path ".agents/<session-id>/screenshots"
16
16
  ```
17
17
 
18
+ Upload options are `--name`, `--parent-id`, and `--folder-path`. Set alt text in the content media field's `alt` value or the rendering component; upload does not accept `--alt`.
19
+
18
20
  Response (JSON) — the full asset object, wrapped in a `data` envelope:
19
21
 
20
22
  ```json
@@ -32,7 +32,7 @@ fimo --branch <name> <command> # peek at another Branch for one command (does n
32
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
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
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` | Sync the current Branch's data plane (DB/assets) down from its parent. `--from <branch>` syncs from an explicit ancestor. |
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
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
37
  | `fimo status` | `git status` | Multi-surface status for the current Branch vs its parent. See below. |
38
38
  | `fimo merge <from>` | `git merge` | Merge another Branch into the current one (multi-surface, atomic, interactive conflict resolver). See below. |
@@ -95,7 +95,15 @@ fimo merge feat/seo --allow-direct-merge # override the "don't merge straight
95
95
 
96
96
  ## `fimo pull`
97
97
 
98
- Syncs the current Branch's data plane from its parent (or `--from <ancestor>`). Conflicts currently resolve **parent-wins** automatically (a future release adds per-row picks). Use it to refresh a stale feature Branch with the latest `main` content/schema state.
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).
99
107
 
100
108
  ## Publishing — `fimo publish` vs `fimo deploy --publish`
101
109
 
@@ -0,0 +1,57 @@
1
+ # Bulk entry writes
2
+
3
+ Load this page to create, update, or delete many entries in one command, or to write entries from a JSON file. Bulk writes use the same validation, locale, reference, and content-change paths as single writes.
4
+
5
+ ```bash
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)
9
+ fimo entries bulk-delete <Type> (--ids <id1>,<id2> | --where '<json>') [--locale <code>]
10
+ ```
11
+
12
+ ## Create
13
+
14
+ `bulk-create` takes an array of normal create bodies. `--body`, `--file`, and `--stdin` all take the same array:
15
+
16
+ ```bash
17
+ fimo entries bulk-create BlogPost --body '[{"data":{"title":"First"}},{"data":{"title":"Second"},"locale":"es"}]'
18
+ fimo entries bulk-create BlogPost --file posts.json
19
+ ```
20
+
21
+ ## Same change for many entries
22
+
23
+ `--body` is a normal update body. Select the entries with `--ids`, or with a `--where` filter (the `entries list` filter, `--ref content/entries`):
24
+
25
+ ```bash
26
+ fimo entries bulk-update BlogPost --ids <id1>,<id2> --body '{"data":{"status":"published"}}'
27
+ fimo entries bulk-update BlogPost --where '{"status":"draft"}' --body '{"data":{"status":"published"}}'
28
+ ```
29
+
30
+ ## A different change for each entry
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
+ ```
40
+
41
+ ```bash
42
+ fimo entries bulk-update BlogPost --file updates.json
43
+ cat updates.json | fimo entries bulk-update BlogPost --stdin
44
+ ```
45
+
46
+ ## Delete
47
+
48
+ ```bash
49
+ fimo entries bulk-delete BlogPost --ids <id1>,<id2>
50
+ fimo entries bulk-delete BlogPost --where '{"archived":true}'
51
+ ```
52
+
53
+ ## Results and limits
54
+
55
+ - One request writes at most 1,000 entries.
56
+ - 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
+ - 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.
@@ -0,0 +1,54 @@
1
+ # Read and filter entries
2
+
3
+ Load this page to filter, sort, search, select fields, or populate references and media. Write commands are in `--ref content`.
4
+
5
+ ```bash
6
+ fimo entries list <Type> [--where <json>] [--sort [-]<field>] [--search <q>] [--fields <a,b>] [--populate <a,b>]
7
+ [--locale <code>] [--limit <n>=20] [--cursor <cursor>] [--all-pages]
8
+ fimo entries get <Type> <id> [--locale <code>] [--populate <a,b>]
9
+ fimo singles get <Type> [--locale <code>] [--populate <a,b>]
10
+ ```
11
+
12
+ ```bash
13
+ fimo entries list BlogPost --where '{"featured":true}' --sort -publishedAt
14
+ fimo entries list BlogPost --where '{"rank":{"$gte":3}}' --sort rank
15
+ fimo entries list BlogPost --where '{"__fimo":{"contentType":{"$eq":"BlogPost"}}}'
16
+ fimo entries list BlogPost --search "launch"
17
+ fimo entries list BlogPost --limit 10 --cursor <next-cursor> --sort title
18
+ fimo entries list BlogPost --fields slug,title,excerpt,coverImage --sort -publishedAt --limit 12
19
+ fimo entries list BlogPost --fields slug,title,author --populate author
20
+ ```
21
+
22
+ ## `--where`
23
+
24
+ - A JSON object keyed by schema field name. A plain value means equality and keeps its JSON type: `{"featured":true}`, `{"category":"react"}`.
25
+ - Operators: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$contains`, `$startsWith`, `$null`, as the field type allows.
26
+ - Fimo metadata is under `__fimo`. Only `__fimo.contentType` is filterable.
27
+ - A reference filter takes the target `id`: `{"author":"750e..."}`. On a to-many field, `$eq` and `$contains` mean "contains this target", `$in` means "contains any of these", `$ne` and `$nin` mean "contains none of these", and `$null: true` means empty or missing.
28
+ - You cannot filter polymorphic references yet: the command fails with a clear error.
29
+
30
+ ## `--sort`, `--fields`, `--search`, pages
31
+
32
+ - `--sort field` is ascending and `--sort -field` is descending. You cannot sort on reference fields.
33
+ - `--fields` is a comma-separated list for list payloads. The API always returns `id`, `entryId`, `documentId`, and `locale`; name only the other fields the view needs.
34
+ - Use `--limit`, `--cursor` (the `nextCursor` of the last page), and `--all-pages` for pages. `--offset` still works in old scripts.
35
+
36
+ ## `--populate`
37
+
38
+ - A comma-separated list of top-level reference, media, or blocks fields to embed. A blocks field populates every media value inside it. Nested paths such as `sections.image` and other field types return 400. Run `fimo schemas get <Type> --json` to see field names and types.
39
+ - Without `--populate`, a reference returns `{ "id": "..." }` and media returns the stored `{ "source", "id", "url", "alt" }`. With `--populate author,cover`, `author` returns the target entry in the requested locale, and `cover` also gets the current `name`, `mime`, `width`, and `height` of the asset.
40
+ - Populate does not choose which target fields return.
41
+ - A populated target that does not exist in the requested locale is `null`. Add `localeFallbacks=true` to get the best available locale variant instead; its `locale` field shows which one.
42
+ - Limits: 200 references in one to-many write, and 500 different populated documents per field in one request. Over a limit, the API returns 400.
43
+
44
+ ## Reference values
45
+
46
+ - A fixed reference field has `"target": "Author"`; add `"many": true` for to-many. Write it as `{"id":"<id>"}`, or an array of those. Use `null` or `[]` for empty.
47
+ - A polymorphic reference has `"targets": ["Post", "Product"]` (never both `target` and `targets`). Write it as `{"contentType":"Post","id":"<id>"}`. Populated values are full entries of mixed types, and generated hooks add `$type` to each one.
48
+ - References inside blocks use the same write shapes (`id`, `documentId`, or `slug` selectors), but you cannot populate or filter them.
49
+
50
+ ```bash
51
+ fimo entries create BlogPost --body '{"data":{"slug":"hello","title":"Hello","author":{"id":"750e8400-e29b-41d4-a716-446655440000"},"contributors":[]}}'
52
+ ```
53
+
54
+ In generated app code, the same query uses `populate: ['author', 'contributors'] as const`. Let the generated client infer the result type. If you need a named type, use `BlogPostResult<TFields, TPopulate>` (fimo-code `content/clients`); writes use `BlogPostInput`.
@@ -0,0 +1,56 @@
1
+ # Localized and shared content
2
+
3
+ Load this page to add a locale variant of an entry, or to work with fields or types that are the same in every language.
4
+
5
+ ## Locale variants
6
+
7
+ Schemas are localized by default. Without `--locale`, a command uses the project default locale. To read, update, or delete another variant, pass `--locale`: an entry is its stable `id` plus a `locale`.
8
+
9
+ To add a variant of an existing entry, create it with the source entry's `documentId`:
10
+
11
+ ```bash
12
+ fimo entries list Story --where '{"slug":"spring-notes"}' --fields slug,title # gives "id" and "documentId"
13
+ fimo entries create Story --locale es --document-id <documentId> --body '{"data":{"title":"Notas de primavera"}}'
14
+ ```
15
+
16
+ - 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.
17
+ - Keep a project single-locale unless the user asks for more languages. When the project has more locales, create and update each locale explicitly.
18
+ - To find missing or stale translations, use SQL (`--ref content/sql`).
19
+
20
+ ## Non-localized types
21
+
22
+ For content that is the same in every locale, set `"i18n": { "enabled": false }` at the schema root and create each entry once. Do not pass `--document-id` to make locale variants. Raw API and CLI responses then omit `locale`; generated collection models add the active or default locale, with no per-locale variants. The schema root accepts no other `i18n` options.
23
+
24
+ ## Shared fields in a localized type
25
+
26
+ Mark a field `"i18n": false` when its value is not translated, such as a price, a SKU, a product photo, or a reference to the same target. Without it, editors enter the value once per locale, and the values drift apart.
27
+
28
+ ```json
29
+ {
30
+ "uid": "Product",
31
+ "name": "Products",
32
+ "fields": {
33
+ "title": { "type": "string" },
34
+ "description": { "type": "richtext" },
35
+ "sku": { "type": "string", "i18n": false, "unique": true },
36
+ "price": { "type": "number", "i18n": false },
37
+ "photo": { "type": "media", "i18n": false },
38
+ "brand": { "type": "reference", "target": "Brand", "i18n": false }
39
+ }
40
+ }
41
+ ```
42
+
43
+ A write to a shared field through any locale changes it in every locale of the document:
44
+
45
+ ```bash
46
+ fimo entries update Product <id> --locale es --body '{"data":{"title":"Silla","price":120}}'
47
+ ```
48
+
49
+ This sets the Spanish title, and sets the price to `120` in every language. An update that does not name a shared field does not change it.
50
+
51
+ - Only top-level scalar and reference fields accept `i18n`. Fields inside `blocks` follow the locale of their entry, and the push rejects `i18n` on them.
52
+ - On a non-localized type, the flag has no effect.
53
+ - `"i18n": true` is the default. Do not write it.
54
+ - `localized` is not a valid key anywhere.
55
+
56
+ **Making a field with content shared deletes data** when the languages hold different values. The push keeps the default-locale value of each document and discards the others, with no prompt and no undo. Before you add `"i18n": false` to a field that has content, tell the user what happens. If you are not sure, check whether the languages differ.
@@ -0,0 +1,29 @@
1
+ # Schema commands and changes
2
+
3
+ Load this page to change a schema that already has content, or to list, read, or delete schemas. The schema JSON itself is in fimo-code `content/schema`.
4
+
5
+ ```bash
6
+ fimo schemas push [<Type>] # create or update from src/schemas; no type pushes all
7
+ fimo schemas push <Type> --rename <old.path>=<new.path> # repeat --rename for each moved field
8
+ fimo schemas list
9
+ fimo schemas get <Type> [--json]
10
+ fimo schemas delete <Type>
11
+ ```
12
+
13
+ - The command is `fimo schemas` (plural). There is no `fimo schema`.
14
+ - A push of all schemas sends them as one atomic batch, so types that reference each other, also in a cycle, can go in one push.
15
+ - A push never deletes a schema whose file is missing. Use `fimo schemas delete <Type>`.
16
+ - Blocks allow at most 7 nested levels, 40 variants in one `schema.oneOf`, and 200 items per blocks field (`min` and `max`).
17
+
18
+ ## What a push does to existing content
19
+
20
+ Fimo migrates content on push. A failed push changes nothing.
21
+
22
+ - Adding an optional field and changing labels keep all content.
23
+ - A new required field fills its `default` only where existing values need it. When no default can satisfy the existing content, the push fails.
24
+ - Removing a nested field or a block variant removes only those values.
25
+ - `string` and `text` values convert both ways. Other type changes convert safe values and reject unsafe ones, with no change to the schema or entries.
26
+ - Lowering a blocks `max` trims items from the end. Raising `min` adds items from the blocks `default` templates.
27
+ - Changing a reference target clears its links.
28
+ - When a field moves to a new name, pass `--rename old.path=new.path` so the one-time migration keeps its values. The rename is not stored in the schema JSON.
29
+ - Collection to Single removes the entries of that type and cleans the references to them. Single to collection keeps its entry.
@@ -0,0 +1,64 @@
1
+ # Read-only SQL over entries
2
+
3
+ Use `fimo entries query` when SQL is clearer than list filters, for example to group, count, or compare entries across types and locales.
4
+
5
+ ```bash
6
+ fimo entries query --sql "SELECT content_type, count(*) AS total FROM entries GROUP BY content_type"
7
+ fimo entries query --sql "SELECT document_id AS id, data->>'title' AS title FROM entries WHERE content_type = 'BlogPost' LIMIT 20"
8
+ fimo entries query --file query.sql
9
+ cat query.sql | fimo entries query --stdin
10
+ ```
11
+
12
+ ## Rules
13
+
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
+ - **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
+ - 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
+ ## 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
+ ## Examples
28
+
29
+ English blog posts that have no Spanish variant:
30
+
31
+ ```sql
32
+ SELECT source.document_id AS id, source.data
33
+ FROM entries source
34
+ WHERE source.content_type = 'BlogPost'
35
+ AND source.locale = 'en'
36
+ AND NOT EXISTS (
37
+ SELECT 1
38
+ FROM entries target
39
+ WHERE target.content_type = source.content_type
40
+ AND target.document_id = source.document_id
41
+ AND target.locale = 'es'
42
+ )
43
+ ```
44
+
45
+ Spanish variants whose English source changed later:
46
+
47
+ ```sql
48
+ SELECT
49
+ target.document_id AS id,
50
+ target.content_type,
51
+ target.slug,
52
+ source.updated_at AS source_updated_at,
53
+ target.updated_at AS target_updated_at
54
+ FROM entries source
55
+ JOIN entries target
56
+ ON target.content_type = source.content_type
57
+ AND target.document_id = source.document_id
58
+ WHERE source.locale = 'en'
59
+ AND target.locale = 'es'
60
+ AND source.updated_at > target.updated_at
61
+ ORDER BY source.updated_at DESC
62
+ ```
63
+
64
+ These rows are possibly stale, not proof of a bad translation: the query shows only that the source changed later. Review the content, and use each row's `id` to update the variant.