fimo 0.15.0-staging.1 → 0.15.0-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 (46) hide show
  1. package/assets/skills/fimo/SKILL.md +11 -4
  2. package/assets/skills/fimo-cli/SKILL.md +28 -27
  3. package/assets/skills/fimo-cli/references/account.md +0 -2
  4. package/assets/skills/fimo-cli/references/agent-setup.md +7 -9
  5. package/assets/skills/fimo-cli/references/agents.md +0 -2
  6. package/assets/skills/fimo-cli/references/analytics.md +0 -2
  7. package/assets/skills/fimo-cli/references/assets.md +2 -4
  8. package/assets/skills/fimo-cli/references/branches.md +0 -2
  9. package/assets/skills/fimo-cli/references/content.md +9 -11
  10. package/assets/skills/fimo-cli/references/credits.md +0 -2
  11. package/assets/skills/fimo-cli/references/deploy.md +2 -4
  12. package/assets/skills/fimo-cli/references/describe.md +0 -2
  13. package/assets/skills/fimo-cli/references/domains.md +0 -2
  14. package/assets/skills/fimo-cli/references/forms.md +5 -7
  15. package/assets/skills/fimo-cli/references/history.md +0 -2
  16. package/assets/skills/fimo-cli/references/init.md +27 -19
  17. package/assets/skills/fimo-cli/references/integrations/firecrawl.md +0 -2
  18. package/assets/skills/fimo-cli/references/integrations.md +0 -2
  19. package/assets/skills/fimo-cli/references/invite.md +0 -2
  20. package/assets/skills/fimo-cli/references/labels.md +3 -5
  21. package/assets/skills/fimo-cli/references/locales.md +2 -4
  22. package/assets/skills/fimo-cli/references/mcp.md +2 -4
  23. package/assets/skills/fimo-cli/references/media.md +0 -2
  24. package/assets/skills/fimo-cli/references/preview.md +0 -2
  25. package/assets/skills/fimo-cli/references/project-vars-and-secrets.md +0 -2
  26. package/assets/skills/fimo-cli/references/projects.md +1 -3
  27. package/assets/skills/fimo-cli/references/schedules.md +0 -2
  28. package/assets/skills/fimo-cli/references/support.md +0 -2
  29. package/assets/skills/fimo-cli/references/webhooks.md +0 -2
  30. package/assets/skills/fimo-migration/SKILL.md +99 -146
  31. package/assets/skills/fimo-migration/references/frameworks/nextjs.md +26 -0
  32. package/assets/skills/fimo-migration/references/inventory/coordinator.md +40 -0
  33. package/assets/skills/fimo-migration/references/inventory/locales/next-intl.md +39 -0
  34. package/assets/skills/fimo-migration/references/inventory/locales.md +41 -0
  35. package/assets/skills/fimo-migration/references/workflow.md +3 -2
  36. package/assets/skills/fimo-migration/scripts/inventory/locales/next-intl.mjs +459 -0
  37. package/assets/skills/fimo-studio/SKILL.md +1 -1
  38. package/assets/skills/fimo-studio/references/project-creation.md +10 -18
  39. package/dist/build/astro/config.js +20 -1
  40. package/dist/cli/bundle.json +1 -1
  41. package/dist/cli/index.js +72 -66
  42. package/package.json +2 -1
  43. package/templates/nextjs/AGENTS.md +10 -5
  44. package/templates/react-router/AGENTS.md +4 -3
  45. package/templates/react-router/package.json +1 -1
  46. package/templates/sveltekit/AGENTS.md +24 -4
package/assets/skills/fimo/SKILL.md CHANGED
@@ -12,27 +12,34 @@ description: >-
12
12
  Fimo ships its skills through its CLI. `fimo-code` resolves from the project's installed `fimo` package;
13
13
  workflow skills resolve from the CLI you run. This file is only a pointer — fetch the real skill when needed.
14
14
 
15
+ If the initiating prompt supplies an exact Fimo CLI invocation prefix, preserve it for every Fimo command in
16
+ that flow. Replace `<fimo-cli>` below with that prefix; otherwise use `npx fimo@latest`. The detailed selector
17
+ rule and shorthand for the fetched workflow docs live in `fimo-cli`.
18
+
15
19
  When you are about to do Fimo work:
16
20
 
17
- 1. List what's available: `npx fimo@latest skills list`
18
- 2. Load the relevant skill: `npx fimo@latest skills get <name>` (add `--ref <doc>` for a reference doc)
21
+ 1. List what's available: `<fimo-cli> skills list`
22
+ 2. Load the relevant skill: `<fimo-cli> skills get <name>` (add `--ref <doc>` for a reference doc)
19
23
 
20
24
  Streamed output opens with the fimo version that produced it. An older project runtime is normal, so never "fix" it. Quote that line when reporting bad guidance.
21
25
 
22
26
  Reference paths mentioned in streamed skill output, such as `references/media.md`, are identifiers,
23
27
  not files in the project. Load them through the CLI, for example
24
- `npx fimo@latest skills get fimo-cli --ref media`. Do not use a filesystem read tool for them.
28
+ `<fimo-cli> skills get fimo-cli --ref media`. Do not use a filesystem read tool for them.
25
29
 
26
30
  Pick by task:
27
31
 
28
32
  - Writing code — schemas/forms, generated clients, labels, framework adapters, rendering primitives → `fimo-code`
29
- - CLI commands and workflows — push, deploy, sync, labels, domains, analytics → `fimo-cli`
33
+ - Project creation, local setup, cloning, and CLI workflows — init, push, deploy, sync, labels, domains, analytics → `fimo-cli`
30
34
  - Fimo agents — create, configure, validate, deploy, run, or inspect them → `fimo-cli` (`references/agents.md`)
31
35
  - AI agent setup — connect Claude Code, Codex, Cursor, or another agent → `fimo-cli` (`references/agent-setup.md`)
32
36
  - Project MCP setup — configure `fimo mcp` for a local agent → `fimo-cli` (`references/mcp.md`)
33
37
  - The Fimo Studio dashboard / web app UI → `fimo-studio`
34
38
  - Migrating an existing site into Fimo → `fimo-migration`
35
39
 
40
+ For project setup, load `fimo-cli` first. Its `references/init.md` decision tree distinguishes a new or empty
41
+ project, an existing Fimo project, and an external migration; load `fimo-migration` for the last path.
42
+
36
43
  If a confirmed Fimo platform failure or missing capability materially blocks the task, finish or safely preserve the main work first, then use the built-in `supportReport` tool. Load the `fimo-cli` support instructions for the reporting criteria.
37
44
 
38
45
  If the project has an `AGENTS.md` (or `CLAUDE.md`), read it too — it carries project-specific context.
package/assets/skills/fimo-cli/SKILL.md CHANGED
@@ -11,17 +11,17 @@ description: >-
11
11
 
12
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 project creation, content / forms / media / labels / locale workflows, deploys, collaboration, account management, Fimo agents, AI credit inspection, and AI agent setup.
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 `npx fimo@latest skills get fimo-code`.
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.
15
15
 
16
16
  Use `fimo <command> --help` for full flag details on any command.
17
17
 
18
18
  > **Webhooks are beta.** Verify a destination with `fimo webhooks test <id> --wait` and inspect its delivery history before depending on it in production.
19
19
 
20
- ## Running the CLI: always `npx fimo@latest`
20
+ ## Running the CLI
21
21
 
22
- Run every command as **`npx fimo@latest <command>`**. It always fetches the latest CLI — no install, nothing to keep up to date, and it can't fall behind and get blocked. Do **not** install `fimo` globally.
22
+ 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.
23
23
 
24
- The examples in this skill and its references write `fimo <command>` for brevity — mentally prefix them with `npx fimo@latest`.
24
+ The examples in this skill and its references use `fimo <command>` as shorthand. Execute them with the selected invocation above.
25
25
 
26
26
  ## Output for agents: `--json` is the stable contract
27
27
 
@@ -49,22 +49,22 @@ A project can have multiple **envs** — each is a git branch _plus_ its own DB,
49
49
  ## Quick Start
50
50
 
51
51
  ```bash
52
- npx fimo@latest login # authenticate via browser
53
- npx fimo@latest skills install # install the global Fimo skill for your AI tools
54
- npx fimo@latest 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.
55
- npx fimo@latest init my-site --starter fimo-site@1 --org <id> --yes --no-skills # opt-in content-led starter for a new project
56
- npx fimo@latest init --project-id <id> my-site # link an EXISTING project instead of creating one
57
- npx fimo@latest clone # interactively choose an existing project to clone locally
58
- cd my-site # then load skills on demand: npx fimo@latest skills get fimo-code
52
+ fimo login # authenticate via browser
53
+ fimo skills install # install the global Fimo skill for your AI tools
54
+ 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.
55
+ fimo init my-site --starter fimo-site@1 --org <id> --yes --no-skills # opt-in content-led starter for a new project
56
+ fimo init --project-id <id> my-site # set up a project by ID: scaffold a newly created project or clone existing code
57
+ fimo clone # interactively choose an existing project to clone locally
58
+ cd my-site # then load skills on demand: fimo skills get fimo-code
59
59
  pnpm dev # run the app locally (use the project's PM: pnpm/npm run/yarn/bun) — your iteration loop
60
- npx fimo@latest credits # inspect the owning org's AI credit balance (read-only)
61
- npx fimo@latest history list # inspect this environment's restore points
62
- npx fimo@latest validate # run all checks + codegen; fails on missing DB labels
63
- npx fimo@latest deploy # ON-DEMAND: hosted preview / shareable link (runs validate internally)
64
- npx fimo@latest deploy --publish # ON-DEMAND: publish live (only when the developer says "ship it")
60
+ fimo credits # inspect the owning org's AI credit balance (read-only)
61
+ fimo history list # inspect this environment's restore points
62
+ fimo validate # run all checks + codegen; fails on missing DB labels
63
+ fimo deploy # ON-DEMAND: hosted preview / shareable link (runs validate internally)
64
+ fimo deploy --publish # ON-DEMAND: publish live (only when the developer says "ship it")
65
65
  ```
66
66
 
67
- 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. `fimo deploy` is **not** a required final step — reach for it only when the developer wants a hosted preview, a shareable link, or to go live, and only on their signal (see `references/deploy.md`).
67
+ 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 preview, a shareable link, or to go live, and only on their signal (see `references/deploy.md`).
68
68
 
69
69
  `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.
70
70
 
@@ -73,13 +73,13 @@ The working loop is local: run the app with the project's package-manager `dev`
73
73
  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.
74
74
 
75
75
  - "Create a new Fimo project / scaffold a site / start a new website / add the opt-in content starter / link an existing project locally" → `references/init.md`
76
- - "Add a content type / blog / products / pages / CMS" → `references/content.md` (workflow) **+ run `npx fimo@latest skills get fimo-code --ref content/schema` and load the detected framework reference**
77
- - "Add a contact / signup / feedback / newsletter form" → `references/forms.md` (workflow) **+ run `npx fimo@latest skills get fimo-code --ref forms` for the JSON spec and generated client**
76
+ - "Add a content type / blog / products / pages / CMS" → `references/content.md` (workflow) **+ run `fimo skills get fimo-code --ref content/schema` and load the detected framework reference**
77
+ - "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**
78
78
  - "View form submissions / who filled out the contact form / inspect what users sent / how many signups" → `references/forms.md` § Reading submissions
79
- - "Upload an image / hero / cover / existing media file" → `references/assets.md` (workflow: upload, browse, open, delete) **+ run `npx fimo@latest skills get fimo-code --ref assets` for the `FimoMedia` shape and rendering**
80
- - "Generate AI image / video / draft preview / image edit / cover from a prompt" → `references/media.md` (task commands, quality, recipes, and verification) **+ run `npx fimo@latest skills get fimo-code --ref assets` for the `FimoMedia` shape if you'll plug the result into UI**
81
- - "Add labels / update static copy / fix missing `t()` values" → `references/labels.md` (workflow) **+ run `npx fimo@latest skills get fimo-code --ref labels` and load the detected framework reference**
82
- - "Enable locales / configure default locale / integrate an existing locale system" → `references/locales.md` **+ run `npx fimo@latest skills get fimo-code --ref locales` and load the detected framework locale reference**
79
+ - "Upload an image / hero / cover / existing media file" → `references/assets.md` (workflow: upload, browse, open, delete) **+ run `fimo skills get fimo-code --ref assets` for the `FimoMedia` shape and rendering**
80
+ - "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**
81
+ - "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**
82
+ - "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**
83
83
  - "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`
84
84
  - "Deploy / publish / go live / push my changes" → `references/deploy.md`
85
85
  - "Get the preview URL / open the preview / what's the URL for this env / refresh the preview link / I just want to see the site / the preview URL stopped working" → `references/preview.md`
@@ -112,10 +112,11 @@ Load the matching reference when the user's request fires its trigger. Recipes t
112
112
  These fire at specific moments in the project lifecycle. **Surface them proactively** rather than waiting for the user to ask:
113
113
 
114
114
  - **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.
115
+ - **When `fimo init` created or scaffolded a new project (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.
115
116
  - **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`.
116
- - **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, then ask the developer what they want to build. This localhost server with live reload is your iteration loop — edit, show, repeat. No deploy is needed to see local changes.
117
- - **When a user-visible unit of work looks done** → **offer** to deploy (`fimo deploy` for a hosted preview / shareable link, `fimo deploy --publish` to go live) and run it only after the developer confirms — or immediately if they ask. Never deploy on your own. See `references/deploy.md`.
118
- - **Optional, 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.
117
+ - **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.
118
+ - **When a user-visible unit of work looks done outside first-time onboarding** → **offer** to deploy (`fimo deploy` for a hosted preview / shareable link, `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`.
119
+ - **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.
119
120
  - **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.
120
121
  - **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`.
121
122
  - **When the user wants to try something risky / explore a redesign without touching the live site** → suggest a feature env: `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`.
@@ -127,7 +128,7 @@ These fire at specific moments in the project lifecycle. **Surface them proactiv
127
128
 
128
129
  - **Editing `.fimo/project.json`** — read-only; it's the link between local and remote project. Treat as a generated file.
129
130
  - **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`.
130
- - **Deploying without the developer asking or confirming** — offer, then wait for their yes. Don't auto-deploy after finishing an edit.
131
+ - **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.
131
132
  - **Running `fimo deploy` just to get a fresh preview URL** — that's a commit + push + sandbox sync for what should be a sub-second read. Use `fimo preview url` instead. See `references/preview.md`.
132
133
  - **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".
133
134
  - **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.
package/assets/skills/fimo-cli/references/account.md CHANGED
@@ -1,7 +1,5 @@
1
1
  # Account, authentication, and organizations
2
2
 
3
- > **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
4
-
5
3
  The `fimo` CLI authenticates against the Fimo platform via a browser-based flow. Credentials are stored **per backend** at `~/.config/fimo/credentials/<host>-<hash>.json` (so a localhost dev backend and production don't clobber each other) and used by every CLI command that talks to the Fimo API.
6
4
 
7
5
  ## Sign in
package/assets/skills/fimo-cli/references/agent-setup.md CHANGED
@@ -1,7 +1,5 @@
1
1
  # AI agent setup
2
2
 
3
- > **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
4
-
5
3
  Fimo connects agents in two layers:
6
4
 
7
5
  1. **One global bootstrap skill** — a tiny, generic `fimo` skill installed once per user, machine-wide (symlinked into each agent's global skills directory). It contains no workflow content; it routes the agent to skills fetched through `fimo skills get`.
@@ -10,10 +8,10 @@ Fimo connects agents in two layers:
10
8
  The rich skills (`fimo-code`, `fimo-cli`, `fimo-studio`, `fimo-migration`) are **never installed as files**. They are served on demand and never land in the project. `fimo-code` resolves from the project's installed package; the others resolve from the CLI being run:
11
9
 
12
10
  ```bash
13
- npx fimo@latest skills list # what's available
14
- npx fimo@latest skills get fimo-code # writing code: schemas, generated clients, labels, framework adapters
15
- npx fimo@latest skills get fimo-cli # CLI + workflows (this skill)
16
- npx fimo@latest skills get fimo-cli --ref deploy # a reference doc
11
+ fimo skills list # what's available
12
+ fimo skills get fimo-code # writing code: schemas, generated clients, labels, framework adapters
13
+ fimo skills get fimo-cli # CLI + workflows (this skill)
14
+ fimo skills get fimo-cli --ref deploy # a reference doc
17
15
  ```
18
16
 
19
17
  Two CLI namespaces manage the two layers:
@@ -23,11 +21,11 @@ Two CLI namespaces manage the two layers:
23
21
 
24
22
  ## Set up the global skill (no install needed)
25
23
 
26
- Run the CLI via `npx fimo@latest` — do not install `fimo` globally.
24
+ Do not install `fimo` globally; use the selected CLI invocation from the main `fimo-cli` skill.
27
25
 
28
26
  ```bash
29
- npx fimo@latest skills install # opens the agent picker, installs the global fimo bootstrap
30
- npx fimo@latest login # connect your account when ready
27
+ fimo skills install # opens the agent picker, installs the global fimo bootstrap
28
+ fimo login # connect your account when ready
31
29
  ```
32
30
 
33
31
  ## `fimo skills` — install + sync + uninstall
package/assets/skills/fimo-cli/references/agents.md CHANGED
@@ -1,7 +1,5 @@
1
1
  # Agents workflow (`fimo agents *`)
2
2
 
3
- > **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
4
-
5
3
  The `fimo agents` namespace authors and operates **agent bundles** — multi-file definitions under `<project>/.fimo/agents/<name>/` (a `config.yaml`, a `GOAL.md`, optional `capabilities.yaml`, etc.). Legacy projects keep using root `agents/<name>/`.
6
4
 
7
5
  ## Mental model
package/assets/skills/fimo-cli/references/analytics.md CHANGED
@@ -1,7 +1,5 @@
1
1
  # Analytics workflow
2
2
 
3
- > **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
4
-
5
3
  Pageview aggregates for the **published** site are stored in Fimo's analytics pipeline. Preview traffic is not recorded.
6
4
 
7
5
  Analytics has a **retained preview for every org** — free included. The free default is a 7-day retention window, so short ranges (`today`, `yesterday`, `this_week`, `last_week`, `last_7_days`) work for everyone. **Extended date ranges and longer retention are paid** — `last_30_days`, `last_90_days`, `this_month`, `last_month`, `last_quarter`, `last_year`, and `custom` require the `canUseExtendedDateRanges` privilege, which only paid orgs have. Asking for an extended range as a free user returns a 403 with an upgrade hint.
package/assets/skills/fimo-cli/references/assets.md CHANGED
@@ -1,8 +1,6 @@
1
1
  # Assets workflow (media library)
2
2
 
3
- > **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
4
-
5
- > Package contract: run `npx fimo@latest skills get fimo-code --ref assets` for `FimoMedia`, `--ref ui` for rendering primitives, and load the detected framework reference for framework-specific integration.
3
+ > Package contract: run `fimo skills get fimo-code --ref assets` for `FimoMedia`, `--ref ui` for rendering primitives, and load the detected framework reference for framework-specific integration.
6
4
  > For **generating** new images / videos with AI, see **`references/media.md`** for the task commands and recipes.
7
5
 
8
6
  This file covers the **CLI workflow** for media that already exists: uploading files, browsing the library, opening an asset to inspect it, moving / deleting items.
@@ -129,4 +127,4 @@ fimo assets delete <asset-id>
129
127
 
130
128
  1. Upload with `fimo assets upload` or generate with a task command such as `fimo image generate`.
131
129
  2. Keep the returned `url` (for direct use) or `id` (to attach to a `media` content-type field).
132
- 3. To use in application code, run `npx fimo@latest skills get fimo-code --ref ui` and load the detected framework reference: schema media → `<Image>` / `<Video>`, deliberate non-schema URLs → `<StaticImage>`. Never use raw `<img src={asset.url}>` for tracked media.
130
+ 3. To use in application code, run `fimo skills get fimo-code --ref ui` and load the detected framework reference: schema media → `<Image>` / `<Video>`, deliberate non-schema URLs → `<StaticImage>`. Never use raw `<img src={asset.url}>` for tracked media.
package/assets/skills/fimo-cli/references/branches.md CHANGED
@@ -1,7 +1,5 @@
1
1
  # Envs &amp; branches (git-shaped workflow)
2
2
 
3
- > **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
4
-
5
3
  > **Beta:** Branch environments 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.
6
4
 
7
5
  A Fimo **env** 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.
package/assets/skills/fimo-cli/references/content.md CHANGED
@@ -1,8 +1,6 @@
1
1
  # Content workflow (schemas + Singles + entries)
2
2
 
3
- > **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
4
-
5
- > Package contract: load the version-locked `fimo-code` skill with `npx fimo@latest skills get fimo-code`, then fetch its nested content and detected-framework references for schema JSON, entry values, generated clients, and imports.
3
+ > Package contract: load the version-locked `fimo-code` skill with `fimo skills get fimo-code`, then fetch its nested content and detected-framework references for schema JSON, entry values, generated clients, and imports.
6
4
 
7
5
  This file covers the **CLI workflow** for content. Use it when the user wants to add a content type (blog, products, pages) or manage Singles and entries.
8
6
 
@@ -15,7 +13,7 @@ Never remove `isSingleton: true` merely because `fimo entries create` rejects th
15
13
 
16
14
  ## Flow
17
15
 
18
- 1. Write `src/schemas/{Uid}.json` — PascalCase filename (e.g. `BlogPost.json`). Run `npx fimo@latest skills get fimo-code --ref content/schema` for the JSON contract.
16
+ 1. Write `src/schemas/{Uid}.json` — PascalCase filename (e.g. `BlogPost.json`). Run `fimo skills get fimo-code --ref content/schema` for the JSON contract.
19
17
  2. Run `fimo schemas push {Uid}`. It registers the schema and generates the framework-specific public modules. It does not run whole-project validation.
20
18
  3. App code imports generated public modules, never `.types.ts` directly. Load the detected framework reference before choosing server modules, client modules, hooks, or a registry.
21
19
  4. Seed collections via `fimo entries create`, or update one-off content via `fimo singles update`. Generate cover images first with `fimo image generate` if needed (see `media.md` / `assets.md`).
@@ -41,7 +39,7 @@ The command is `fimo schemas` (plural). There is no singular `fimo schema` alias
41
39
 
42
40
  All commands accept `-C, --cwd <dir>` to point at a different project directory.
43
41
 
44
- Blocks schemas support at most 7 nested `blocks` levels, 40 variants in one `schema.oneOf`, and `min` or `max` values up to 200 items per blocks field. Run `npx fimo@latest skills get fimo-code --ref content/schema` for the complete blocks JSON shape.
42
+ Blocks schemas support at most 7 nested `blocks` levels, 40 variants in one `schema.oneOf`, and `min` or `max` values up to 200 items per blocks field. Run `fimo skills get fimo-code --ref content/schema` for the complete blocks JSON shape.
45
43
 
46
44
  Schema transitions are automatic. Adding optional fields and changing labels preserve content. A new required field backfills its `default` only where existing values need it; the push fails safely when no default can satisfy existing content. Removing a nested field or block variant removes only those values. `string` and `text` preserve values in both directions. Other primitive changes convert safe values and reject unsafe ones without changing the schema or entries. Lowering block `max` trims from the end; raising `min` fills from the blocks `default` templates. A reference target change clears its connections. Use repeatable `--rename old.path=new.path` arguments when a field moved by name so the one-time migration preserves its values; the operation is not stored in schema JSON. Collection-to-Single removes that type's entries and cleans inbound references; Single-to-collection preserves its entry.
47
45
 
@@ -83,7 +81,7 @@ fimo entries bulk-update <TypeName> (--file <path> | --stdin)
83
81
  fimo entries bulk-delete <TypeName> (--ids <id1>,<id2> | --where '<json>') [--locale es]
84
82
  ```
85
83
 
86
- `--body` is a **required** option on `create` and `update`. Run `npx fimo@latest skills get fimo-code --ref content/richtext` before constructing an entry payload: slug belongs inside `data`, media has a specific shape, and richtext must be Tiptap JSONContent.
84
+ `--body` is a **required** option on `create` and `update`. Run `fimo skills get fimo-code --ref content/richtext` before constructing an entry payload: slug belongs inside `data`, media has a specific shape, and richtext must be Tiptap JSONContent.
87
85
 
88
86
  `entries list` accepts the same read query surface as generated hooks:
89
87
 
@@ -107,7 +105,7 @@ Reference filters take the target `id` string (`{"author":"750e..."}`). On a to-
107
105
 
108
106
  Polymorphic references declare `targets: ["Post", "Product"]` instead of `target` (never both) and their values carry both parts: `{ "contentType": "Post", "id": "..." }`. Populate returns mixed full entries, and generated hooks expose `$type` on each populated value to branch on. `--where` on polymorphic fields is not supported yet and fails with a clear error.
109
107
 
110
- In generated application code, the equivalent is `populate: ['author', 'contributors'] as const` in query params. Let the generated client infer the result when possible; if a named TypeScript shape is needed, use `BlogPostResult<TFields, TPopulate>` as documented by `npx fimo@latest skills get fimo-code --ref content/clients`. Writes use `BlogPostInput`.
108
+ In generated application code, the equivalent is `populate: ['author', 'contributors'] as const` in query params. Let the generated client infer the result when possible; if a named TypeScript shape is needed, use `BlogPostResult<TFields, TPopulate>` as documented by `fimo skills get fimo-code --ref content/clients`. Writes use `BlogPostInput`.
111
109
 
112
110
  ### Read-only SQL
113
111
 
@@ -198,7 +196,7 @@ fimo entries bulk-delete BlogPost --where '{"archived":true}'
198
196
 
199
197
  Each bulk request handles at most 1,000 entries. Missing requested IDs do not fail valid work: the CLI prints a warning, and `--json` includes both a top-level `warnings` array and the exact IDs in `data.meta.missing`. Bulk writes use the same validation, locale, reference, and content-change paths as singular entry writes. They apply entries one at a time. Recoverable create and update errors report how many earlier entries were already changed.
200
198
 
201
- For reference schema JSON and entry value shape, run `npx fimo@latest skills get fimo-code --ref content/schema`. The short version:
199
+ For reference schema JSON and entry value shape, run `fimo skills get fimo-code --ref content/schema`. The short version:
202
200
 
203
201
  ```json
204
202
  {
@@ -264,13 +262,13 @@ Use `"isSingleton": true` for a Single with exactly one set of content. Generate
264
262
 
265
263
  ## "Add a blog" recipe
266
264
 
267
- 1. Run `npx fimo@latest skills get fimo-code --ref content/schema` for the JSON shape and field types.
265
+ 1. Run `fimo skills get fimo-code --ref content/schema` for the JSON shape and field types.
268
266
  2. Write `src/schemas/BlogPost.json` with fields `title`, `body` (richtext), `coverImage` (media), etc. Do NOT declare a `slug` field — `slug` (and `id`, `entryId`, `documentId`, `locale`, `createdAt`, `updatedAt`, `__fimo`) is reserved entry metadata and will be rejected; every entry gets a `slug` for free.
269
267
  3. Run `fimo schemas push BlogPost`.
270
268
  4. Generate cover images: `fimo image generate --prompt "..." --aspect-ratio 16:9` (see `media.md`).
271
269
  5. Seed entries: `fimo entries create BlogPost --body '{"data": {"slug": "first-post", "title": "...", "coverImage": {...}}}'`.
272
- 6. Run `npx fimo@latest skills get fimo-code --ref ui` and load the detected framework reference for rendering primitives.
273
- 7. Run `npx fimo@latest skills get fimo-code --ref labels` and load the detected framework reference for labels.
270
+ 6. Run `fimo skills get fimo-code --ref ui` and load the detected framework reference for rendering primitives.
271
+ 7. Run `fimo skills get fimo-code --ref labels` and load the detected framework reference for labels.
274
272
  8. Load the detected framework reference, then build the page with its generated server or client surface.
275
273
 
276
274
  ## Non-interactive use
package/assets/skills/fimo-cli/references/credits.md CHANGED
@@ -1,7 +1,5 @@
1
1
  # Credits
2
2
 
3
- > **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
4
-
5
3
  `fimo credits` is a read-only command for checking the AI credit balance of the organization that owns a Fimo project. It resolves the project from `.fimo/project.json` unless `--project <project-id>` is provided.
6
4
 
7
5
  ```bash
package/assets/skills/fimo-cli/references/deploy.md CHANGED
@@ -1,8 +1,6 @@
1
1
  # Deploy pipeline
2
2
 
3
- > **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
4
-
5
- **`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 **shareable link**, or to **go live** — and only on their signal. It commits everything, pushes to the current env's branch, and round-trips that env's sandbox (install + restart); it's a milestone command, not a save step. Batch related edits into one deploy; never deploy after every change.
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 **shareable 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 env's branch, and round-trips that env's sandbox (install + restart); it's a milestone command, not a save step. Batch related edits into one deploy; never deploy after every change.
6
4
 
7
5
  > **Local vs hosted.** The local dev server is localhost only. The Fimo **dashboard preview** and the **shareable preview URL** are served by the deployed sandbox — so if the developer wants to see the site in the dashboard or send someone a link, that requires a `fimo deploy`.
8
6
 
@@ -61,7 +59,7 @@ SPAs; Astro's `fimo()` integration lives in `references/frameworks/astro.md`.
61
59
 
62
60
  ## Warm the sandbox early in a session (optional)
63
61
 
64
- 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.
62
+ 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.
65
63
 
66
64
  The first deploy of a project's life pays a one-time cost: the sandbox has to provision (create the VM, install the user's deps if they differ from the template's baked ones, start the dev server) — about 15-30s. Every deploy after that lands on a warm sandbox (~10s, or ~4s when you also use `--no-restart` and the lockfile hasn't changed).
67
65
 
package/assets/skills/fimo-cli/references/describe.md CHANGED
@@ -1,7 +1,5 @@
1
1
  # Describe — read-only snapshot of the current project
2
2
 
3
- > **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
4
-
5
3
  `fimo describe` prints a structured snapshot of the Fimo project in the current working directory: project name + config version, detected framework, fimo package version, package manager, route / schema / locale counts, and a file tree.
6
4
 
7
5
  It is **read-only**. Never writes, never hits the network. Safe to run any time.
package/assets/skills/fimo-cli/references/domains.md CHANGED
@@ -1,7 +1,5 @@
1
1
  # Domains
2
2
 
3
- > **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
4
-
5
3
  `fimo domains` is the surface for everything URL-related on a project. Three resources live here, and they're easy to confuse — keep them straight:
6
4
 
7
5
  | Resource | What it is | Plan | Per project | Source of truth |
package/assets/skills/fimo-cli/references/forms.md CHANGED
@@ -1,19 +1,17 @@
1
1
  # Forms workflow
2
2
 
3
- > **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
4
-
5
- > Package contract: run `npx fimo@latest skills get fimo-code --ref forms` for the JSON spec, generated Zod schema, submit helper, and application usage.
3
+ > Package contract: run `fimo skills get fimo-code --ref forms` for the JSON spec, generated Zod schema, submit helper, and application usage.
6
4
 
7
5
  This file covers the **CLI workflow** for forms. Use it when the user wants to add a contact form, signup, feedback form, etc.
8
6
 
9
7
  ## Flow
10
8
 
11
- 1. Write `src/forms/{name}.json` — kebab-case filename (e.g. `contact-us.json`). For the JSON spec and field types, run `npx fimo@latest skills get fimo-code --ref forms`.
9
+ 1. Write `src/forms/{name}.json` — kebab-case filename (e.g. `contact-us.json`). For the JSON spec and field types, run `fimo skills get fimo-code --ref forms`.
12
10
  2. Register with `fimo forms push {name}` — creates the form, obtains its `id`, patches it back into the JSON file.
13
11
  3. Pre-build generates `src/forms/{name}.ts` (Zod schema + `submitX` helper). Use the same `fimo-code` reference for the generated API.
14
12
  4. Write the application form using the generated `@/forms/{name}` module and the existing framework conventions.
15
13
 
16
- Steps 1, 3, and 4 reference the `fimo-code` skill (`npx fimo@latest skills get fimo-code`). Step 2 is the CLI command.
14
+ Steps 1, 3, and 4 reference the `fimo-code` skill (`fimo skills get fimo-code`). Step 2 is the CLI command.
17
15
 
18
16
  ## CLI commands
19
17
 
@@ -45,11 +43,11 @@ Use this when the user asks "who filled out the contact form?", "how many signup
45
43
 
46
44
  ## "Add a contact form" recipe
47
45
 
48
- 1. Run `npx fimo@latest skills get fimo-code --ref forms` for the JSON spec.
46
+ 1. Run `fimo skills get fimo-code --ref forms` for the JSON spec.
49
47
  2. Write `src/forms/contact-us.json` with the required fields.
50
48
  3. Run `fimo forms push contact-us` — the `id` is patched back into the JSON automatically.
51
49
  4. Use the same `fimo-code` forms reference for the generated `submitContactUs` + `ContactUsSchema` API.
52
- 5. Run `npx fimo@latest skills get fimo-code --ref labels` and load the detected framework reference for form labels.
50
+ 5. Run `fimo skills get fimo-code --ref labels` and load the detected framework reference for form labels.
53
51
  6. Write the application form using the generated `@/forms/contact-us` module.
54
52
 
55
53
  **Register BEFORE writing app code that depends on the form** — otherwise the generated `.ts` doesn't exist and the runtime fetch 404s.
package/assets/skills/fimo-cli/references/history.md CHANGED
@@ -1,7 +1,5 @@
1
1
  # Project History
2
2
 
3
- > **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
4
-
5
3
  History is scoped to the selected project environment. A restore point records the environment's CMS content and the matching Git commit so code and content can be recovered together.
6
4
 
7
5
  Fimo also creates restore points automatically after a successful deploy, on the destination of a completed environment merge, and after direct content editing has been quiet for 30 seconds. Rapid Studio auto-saves are grouped into one content point.
package/assets/skills/fimo-cli/references/init.md CHANGED
@@ -1,7 +1,5 @@
1
1
  # `fimo init`
2
2
 
3
- > **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
4
-
5
3
  One-stop project setup: sign in, create a new Fimo project (or link an existing one), install dependencies, and optionally set up Fimo skills for your AI tools.
6
4
 
7
5
  ## Command
@@ -13,17 +11,17 @@ fimo init [dir] [options]
13
11
  `fimo init` runs the full onboarding in one shot:
14
12
 
15
13
  1. **Signs in automatically** — if there's no session it opens the browser loopback login. In `--json` / non-TTY with no session it fails with `NOT_AUTHENTICATED` (run `fimo login` first).
16
- 2. **Resolves the project** — with `--project-id <id>` it links an EXISTING project (clones it); without it, it creates a NEW project. An interactive TTY shows a "Create new / Link existing" picker; non-interactive shells default to create-new. New projects use React Router by default; `--framework nextjs` and `--framework sveltekit` select minimal framework-native shells. An optional `--starter fimo-site@1` adds a React-Router content starter only to a newly created project.
14
+ 2. **Resolves the project** — with `--project-id <id>` it sets up the named Fimo project: a project with no code yet is scaffolded as a fresh site, while an existing repository is cloned. Without it, `init` creates a NEW project. An interactive TTY shows a "Create new / Link existing" picker; non-interactive shells default to create-new. New projects use React Router by default; `--framework nextjs` and `--framework sveltekit` select minimal framework-native shells. An optional `--starter fimo-site@1` adds a content-led starter only to a newly created project without `--project-id`.
17
15
  3. **Installs dependencies** — prompts for the package manager, or honor `--package-manager <pm>` / `--no-install`.
18
16
  4. **Optionally sets up Fimo skills** — confirm prompt, or `--skills` / `--no-skills`.
19
17
 
20
18
  | Flag | Required | Purpose |
21
19
  | ---------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
22
20
  | `[dir]` positional | yes in non-TTY for create-new | Target directory (e.g. `my-site`) |
23
- | `--project-id <id>` | no | Link an EXISTING project instead of creating one (clones it). |
21
+ | `--project-id <id>` | no | Set up the named Fimo project: scaffold and push a fresh site when it has no code yet, otherwise clone it. |
24
22
  | `--org <id>` | no | Target organization **id** when creating (use the `ID` column from `fimo orgs list`, NOT the slug). Picker shown interactively if omitted and TTY. |
25
23
  | `--env <name>` | no | Env to check out when linking an existing project (defaults to `main`). |
26
- | `--framework <framework>` | no | New-project scaffold: `react-router` (default), `nextjs` (App Router), or `sveltekit`. Existing repositories are preserved. |
24
+ | `--framework <framework>` | no | New-project scaffold: `react-router` (default), `nextjs` (App Router), or `sveltekit`. Existing repositories are preserved. |
27
25
  | `--starter <id>` | no | Opt-in project starter for create-new (currently `fimo-site@1`). It seeds CMS content, labels, a contact form, and manual-only agents. Rejects `--project-id`. |
28
26
  | `--package-manager <pm>` | no | `npm` \| `pnpm` \| `yarn` \| `bun`. |
29
27
  | `--install` / `--no-install` | yes in non-TTY | Install deps after checkout (or skip it). |
@@ -42,7 +40,7 @@ caller one stable result envelope; `--yes` is useful when running in a TTY but
42
40
  is not required in a pipe or CI shell. The starter is never selected by default.
43
41
 
44
42
  ```bash
45
- npx fimo@latest --json init my-site \
43
+ fimo --json init my-site \
46
44
  --starter fimo-site@1 \
47
45
  --org <organizationId> \
48
46
  --no-install \
@@ -59,7 +57,7 @@ singleton, `contact` form, and labels in `main`, writes the form id into
59
57
  writing anything. If dependencies were skipped, install them and run
60
58
  `fimo validate` before starting the app so generated clients are present.
61
59
 
62
- > **Zero-install:** run `npx fimo@latest init` — no global install needed. `fimo projects create` is also an alias of `fimo init` (create-new path).
60
+ > **Zero-install:** the selected `fimo init` invocation needs no global install. `fimo projects create` is also an alias of `fimo init` (create-new path).
63
61
 
64
62
  ### Choose the application framework
65
63
 
@@ -67,8 +65,8 @@ Omit `--framework` for the existing React Router scaffold, or select a
67
65
  minimal framework-native shell explicitly:
68
66
 
69
67
  ```bash
70
- npx fimo@latest init my-next-site --framework nextjs --org <organizationId>
71
- npx fimo@latest init my-svelte-site --framework sveltekit --org <organizationId>
68
+ fimo init my-next-site --framework nextjs --org <organizationId>
69
+ fimo init my-svelte-site --framework sveltekit --org <organizationId>
72
70
  ```
73
71
 
74
72
  Both shells include their framework adapter, hosted-preview connector, and
@@ -79,11 +77,11 @@ React Router only.
79
77
 
80
78
  For `--agents`, pass the AI tool you're running in: `--agents=claude-code` for Claude Code, `--agents=cursor` for Cursor, `--agents=codex` for Codex, etc. When the flag is omitted, env-var detection of the invoking harness (e.g. `CLAUDECODE` / `CLAUDE_CODE_ENTRYPOINT` → claude-code) auto-targets that agent; other agents must be selected explicitly via `--agents`/`-a` or the interactive picker.
81
79
 
82
- ## Linking an existing project
80
+ ## Setting up a project by ID
83
81
 
84
- Pass `--project-id <id>` to link an EXISTING project instead of creating one. This clones the project's git repo into `[dir]` and writes the local `.fimo/project.json`, the same as `fimo clone` (init's `--project-id` path reuses it). Use `--env <name>` to check out a specific env (defaults to `main`). Without `--project-id`, `fimo init` creates a new project.
82
+ Pass `--project-id <id>` to set up a known Fimo project. If the project has no code yet — for example, one just created in Fimo Studio — `init` scaffolds a fresh site into it and pushes the initial commit: the same create-new path, linked to the existing ID. If the project already has code, `init` clones it into `[dir]`, like `fimo clone`. Use `--env <name>` to check out a specific env (defaults to `main`). Without `--project-id`, `fimo init` creates a new project.
85
83
 
86
- ## What gets written (create-new)
84
+ ## What gets written (create-new path)
87
85
 
88
86
  `fimo init` (create-new path) scaffolds:
89
87
 
@@ -118,15 +116,13 @@ cd my-site
118
116
  fimo rename "Acme Coffee"
119
117
  ```
120
118
 
121
- **Then start the local dev loop and ask the developer what they want to build.** Run the app with the project's package-manager `dev` script — `pnpm dev`, `npm run dev`, `yarn dev`, or `bun dev` (match the lockfile) — in the background; it serves the site on localhost with live reload. Edit, show, iterate. You do not need to deploy to see local changes.
119
+ **Then start the local dev loop.** Run the app with the project's package-manager `dev` script — `pnpm dev`, `npm run dev`, `yarn dev`, or `bun dev` (match the lockfile) — in the background; it serves the site on localhost with live reload. Edit, show, iterate. You do not need to deploy to see local changes. If the initiating request did not say what to build, ask the developer — after the first preview below, never as a blocker before initializing.
122
120
 
123
121
  ```bash
124
122
  pnpm dev & # or npm run dev / yarn dev / bun dev — the project's package manager
125
123
  ```
126
124
 
127
- When a unit of work looks done, **offer** to deploy (`fimo deploy` for a hosted preview / shareable link, `fimo deploy --publish` to go live) and run it only after the developer confirms.
128
-
129
- **Optional — warm the sandbox early:** only if you already know a deploy is coming, kick off a background `fimo deploy -m "chore: init" &` so the one-time ~15-30s sandbox provision + dep install happens while you work. This is a perf optimization, not a required step — skip it while you're just iterating locally. See `references/deploy.md` § Warm the sandbox early in a session.
125
+ Outside the first-preview path below, when a unit of work looks done, **offer** to deploy (`fimo deploy` for a hosted preview / shareable link, `fimo deploy --publish` to go live) and run it only after the developer confirms.
130
126
 
131
127
  ## Load the project context
132
128
 
@@ -136,12 +132,24 @@ After `fimo init` completes, the project root has `AGENTS.md` (universal) and `C
136
132
 
137
133
  1. `cd <project-dir>` — switch into the new project.
138
134
  2. `Read` the project rules file: `AGENTS.md` (or `CLAUDE.md` if you're Claude Code).
139
- 3. Run `npx fimo@latest describe --json` and read the detected framework, schemas, locales, and tree.
140
- 4. Load the code skill on demand: `npx fimo@latest skills get fimo-code`.
141
- 5. Follow its decision tree and load only the task reference plus the detected framework reference. For Next.js, start with `npx fimo@latest skills get fimo-code --ref frameworks/next`, then load App Router, Pages Router, or locales only when the project shape requires it. For SvelteKit, start with `npx fimo@latest skills get fimo-code --ref frameworks/sveltekit`. For Astro, `--ref frameworks/astro` is the single framework reference.
135
+ 3. Run `fimo describe --json` with the current invocation prefix and read the detected framework, schemas, locales, and tree.
136
+ 4. Load the code skill on demand with the same prefix: `fimo skills get fimo-code`.
137
+ 5. Follow its decision tree and load only the task reference plus the detected framework reference. For Next.js, start with `fimo skills get fimo-code --ref frameworks/next`, then load App Router, Pages Router, or locales only when the project shape requires it. For SvelteKit, start with `fimo skills get fimo-code --ref frameworks/sveltekit`. For Astro, `fimo skills get fimo-code --ref frameworks/astro` is the single framework reference.
142
138
 
143
139
  Do not batch-load every reference. Progressive disclosure keeps unrelated framework and product guidance out of the coding context.
144
140
 
141
+ ### Create the first hosted preview (create-new path)
142
+
143
+ Whenever `fimo init` created or scaffolded a new project — including a Studio-supplied `--project-id`, since Studio creates the project before any code exists — finish onboarding with exactly one plain preview deploy after init and context loading succeed, unless the user explicitly said not to deploy:
144
+
145
+ ```bash
146
+ fimo deploy -m "chore: first preview" --json
147
+ ```
148
+
149
+ `-m` is required because you run non-interactively; the deploy validates, commits pending changes, pushes, and syncs the hosted preview. It is also the sandbox warm-up — never run a separate warm-up deploy on this path. Read `data.preview_url` and `data.dashboard_url` from the envelope and return both links. If the initiating request described a concrete site, build a minimal meaningful first screen before this single deploy; otherwise deploy the scaffolded site as-is and then ask what to build.
150
+
151
+ This first deploy creates a preview only — never add `--publish`, and treat every later deploy as offer-then-confirm. The rule does not apply when `init` cloned a project with existing code or when the work is a migration; those paths keep their normal deployment approval rules.
152
+
145
153
  ## Adding another AI tool to an existing project later
146
154
 
147
155
  If a teammate joins on a different AI tool (e.g. Cursor) after the project was scaffolded for claude-code only:
package/assets/skills/fimo-cli/references/integrations/firecrawl.md CHANGED
@@ -1,7 +1,5 @@
1
1
  # Firecrawl Integration
2
2
 
3
- > **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
4
-
5
3
  Use Firecrawl when an agent needs to research or inspect public websites: direct web answers, landing-page research, competitor structure analysis, migration prep, link extraction, and factual page snapshots. Do not use Firecrawl for private URLs, logged-in websites, or content the user has not asked you to fetch.
6
4
 
7
5
  Current execution support is `search`, `scrape`, `map`, `crawl`, and `monitor.*`.
package/assets/skills/fimo-cli/references/integrations.md CHANGED
@@ -1,7 +1,5 @@
1
1
  # Integrations
2
2
 
3
- > **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
4
-
5
3
  Use integrations to enable external services for a Fimo project. API keys are stored by Fimo and never printed back to the CLI. Teammates and agents receive access to the integration, not the underlying token.
6
4
 
7
5
  ## Inspect
package/assets/skills/fimo-cli/references/invite.md CHANGED
@@ -1,7 +1,5 @@
1
1
  # Invite users
2
2
 
3
- > **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
4
-
5
3
  Invite collaborators to your Fimo organization or project. After deploying a website for the first time, suggest inviting team members so they can contribute.
6
4
 
7
5
  ## When to suggest inviting users
package/assets/skills/fimo-cli/references/labels.md CHANGED
@@ -1,8 +1,6 @@
1
1
  # Labels workflow
2
2
 
3
- > **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
4
-
5
- > Package contract: run `npx fimo@latest skills get fimo-code --ref labels` for the `t()` contract and key rules, then load the detected framework reference for its label readers.
3
+ > Package contract: run `fimo skills get fimo-code --ref labels` for the `t()` contract and key rules, then load the detected framework reference for its label readers.
6
4
  > For locale configuration and route-prefix validation, see **`references/locales.md`**.
7
5
 
8
6
  This file covers the **CLI workflow** for labels: static UI copy such as nav items, buttons, headings, placeholders, alt text, and SEO strings.
@@ -61,9 +59,9 @@ Prefer `fimo validate` — this primitive is for narrow debugging/test use.
61
59
 
62
60
  ## Workflow
63
61
 
64
- 1. Declare literal label keys using the API documented for the detected framework. Run `npx fimo@latest skills get fimo-code --ref labels` before writing them.
62
+ 1. Declare literal label keys using the API documented for the detected framework. Run `fimo skills get fimo-code --ref labels` before writing them.
65
63
  2. Run `fimo validate`.
66
64
  3. Add missing values with `fimo labels set` or `fimo labels set-many`.
67
65
  4. Editors can now change copy in the Fimo admin without code changes.
68
66
 
69
- For helper signatures and code patterns, run `npx fimo@latest skills get fimo-code --ref labels` before writing code that uses `t()`.
67
+ For helper signatures and code patterns, run `fimo skills get fimo-code --ref labels` before writing code that uses `t()`.