fimo 0.15.0-staging.1 → 0.15.0-staging.3

package/README.md

@@ -28,6 +28,7 @@ Run the CLI with `npx` — no global install, always the latest:
 ```bash
 npx fimo@latest login
 npx fimo@latest init my-site                 # default React Router scaffold
+# or: npx fimo@latest init my-astro-site --framework astro
 # or: npx fimo@latest init my-next-site --framework nextjs
 # or: npx fimo@latest init my-svelte-site --framework sveltekit
 cd my-site

package/assets/content-templates/forms/framework.eta

@@ -0,0 +1,90 @@
+<%
+const quote = (value) => JSON.stringify(value);
+const localName = (key, index) => `field_${index}_${key.replace(/[^a-zA-Z0-9_$]/g, '_')}`;
+
+function zodForField(field) {
+  if (field.type === 'hidden') {
+    return 'z.string().optional()';
+  }
+
+  if (field.type === 'file') {
+    let schema = `z.custom<File>((value) => typeof File !== "undefined" && value instanceof File, ${quote('Expected a file')})`;
+    if (!field.required) schema += '.optional()';
+    return schema;
+  }
+
+  if (field.type === 'checkbox') {
+    let schema = `z.boolean({ message: ${quote('Must be true or false')} })`;
+    if (field.required) schema += `.refine((value) => value, ${quote(`${field.label} is required`)})`;
+    return schema;
+  }
+
+  if (field.type === 'number') {
+    let schema = 'z.coerce.number()';
+    if (field.validation?.min !== undefined) schema += `.min(${field.validation.min})`;
+    if (field.validation?.max !== undefined) schema += `.max(${field.validation.max})`;
+    if (!field.required) schema += '.optional()';
+    return schema;
+  }
+
+  if (field.type === 'select' && field.options?.length) {
+    let schema = `z.enum(${JSON.stringify(field.options)} as [string, ...string[]])`;
+    if (!field.required) schema += '.optional()';
+    return schema;
+  }
+
+  let schema = 'z.string()';
+  if (field.required) schema += `.min(1, ${quote(`${field.label} is required`)})`;
+  if (field.type === 'email') schema += `.email(${quote('Invalid email address')})`;
+  if (field.type === 'url') schema += `.url(${quote('Invalid URL')})`;
+  if (field.validation?.minLength !== undefined) schema += `.min(${field.validation.minLength})`;
+  if (field.validation?.maxLength !== undefined) schema += `.max(${field.validation.maxLength})`;
+  if (field.validation?.pattern) schema += `.regex(new RegExp(${quote(field.validation.pattern)}))`;
+  if (!field.required) schema += '.optional()';
+  return schema;
+}
+-%>
+<% if (form.clientDirective) { %><%= form.clientDirective %>
+<% } %>// AUTO-GENERATED by `fimo` from src/forms/<%= form.name %>.json - DO NOT EDIT.
+
+import { z } from "zod";
+import { formClient as defaultFormClient } from "<%= form.runtimeImport %>";
+import type { FormClient } from "fimo/forms";
+
+export const FORM_ID = <%= quote(form.id ?? 'undefined') %>;
+
+export const <%= form.pascal %>Schema = z.object({
+<% Object.entries(form.fields).forEach(([key, field]) => { -%>
+  <%= JSON.stringify(key) %>: <%= zodForField(field) %>,
+<% }); -%>
+});
+
+export type <%= form.pascal %>Data = z.infer<typeof <%= form.pascal %>Schema>;
+
+/** Convert a browser form submission into the typed shape expected by Fimo. */
+export function parse<%= form.pascal %>FormData(formData: FormData): <%= form.pascal %>Data {
+  const data: Record<string, unknown> = {};
+<% Object.entries(form.fields).forEach(([key, field], index) => { -%>
+<% if (field.type === 'checkbox') { -%>
+  data[<%= JSON.stringify(key) %>] = ['on', 'true', '1'].includes(formData.get(<%= JSON.stringify(key) %>) as string);
+<% } else if (field.type === 'number') { -%>
+  const <%= localName(key, index) %> = formData.get(<%= JSON.stringify(key) %>);
+  if (<%= localName(key, index) %> !== null && <%= localName(key, index) %> !== '') {
+    data[<%= JSON.stringify(key) %>] = Number(<%= localName(key, index) %>);
+  }
+<% } else { -%>
+  const <%= localName(key, index) %> = formData.get(<%= JSON.stringify(key) %>);
+  if (<%= localName(key, index) %> !== null) {
+    data[<%= JSON.stringify(key) %>] = <%= localName(key, index) %>;
+  }
+<% } -%>
+<% }); -%>
+  return <%= form.pascal %>Schema.parse(data);
+}
+
+export function submit<%= form.pascal %>(
+  data: <%= form.pascal %>Data,
+  client: FormClient = defaultFormClient
+) {
+  return client.submit(FORM_ID, data);
+}

package/assets/content-templates/forms/react.eta

@@ -10,24 +10,24 @@
  */
 
 const hasFileFields = Object.values(form.fields).some(f => f.type === 'file');
+const quote = (value) => JSON.stringify(value);
+const localName = (key, index) => `field_${index}_${key.replace(/[^a-zA-Z0-9_$]/g, '_')}`;
 
-function zodForField(key, field) {
-  const lines = [];
-
+function zodForField(field) {
   if (field.type === 'hidden') {
     return 'z.string().optional()';
   }
 
   if (field.type === 'file') {
-    let s = 'z.instanceof(File)';
-    if (!field.required) s = 'z.instanceof(File).optional()';
+    let s = `z.custom<File>((value) => typeof File !== "undefined" && value instanceof File, ${quote('Expected a file')})`;
+    if (!field.required) s += '.optional()';
     return s;
   }
 
   if (field.type === 'checkbox') {
-    let s = 'z.boolean()';
+    let s = `z.boolean({ message: ${quote('Must be true or false')} })`;
     if (field.required) {
-      s += `.refine(v => v, "${field.label} is required")`;
+      s += `.refine(v => v, ${quote(`${field.label} is required`)})`;
     }
     return s;
   }
@@ -41,8 +41,7 @@ function zodForField(key, field) {
   }
 
   if (field.type === 'select' && field.options?.length) {
-    const opts = field.options.map(o => `"${o}"`).join(', ');
-    let s = `z.enum([${opts}])`;
+    let s = `z.enum(${JSON.stringify(field.options)} as [string, ...string[]])`;
     if (!field.required) s += '.optional()';
     return s;
   }
@@ -51,7 +50,7 @@ function zodForField(key, field) {
   let s = 'z.string()';
 
   if (field.required) {
-    s += `.min(1, "${field.label} is required")`;
+    s += `.min(1, ${quote(`${field.label} is required`)})`;
   }
 
   if (field.type === 'email') {
@@ -62,7 +61,7 @@ function zodForField(key, field) {
 
   if (field.validation?.minLength) s += `.min(${field.validation.minLength})`;
   if (field.validation?.maxLength) s += `.max(${field.validation.maxLength})`;
-  if (field.validation?.pattern) s += `.regex(new RegExp("${field.validation.pattern}"))`;
+  if (field.validation?.pattern) s += `.regex(new RegExp(${quote(field.validation.pattern)}))`;
 
   if (!field.required) s += '.optional()';
 
@@ -79,16 +78,33 @@ const fileFieldKeys = Object.entries(form.fields)
 
 import { z } from "zod";
 
-export const FORM_ID = "<%= form.id %>";
+export const FORM_ID = <%= quote(form.id ?? 'undefined') %>;
 
 export const <%= form.pascal %>Schema = z.object({
 <% Object.entries(form.fields).forEach(([key, field]) => { -%>
-  <%= key %>: <%= zodForField(key, field) %>,
+  <%= JSON.stringify(key) %>: <%= zodForField(field) %>,
 <% }); -%>
 });
 
 export type <%= form.pascal %>Data = z.infer<typeof <%= form.pascal %>Schema>;
 
+/** Convert a browser form submission into the typed shape expected by Fimo. */
+export function parse<%= form.pascal %>FormData(formData: FormData): <%= form.pascal %>Data {
+  const data: Record<string, unknown> = {};
+<% Object.entries(form.fields).forEach(([key, field], index) => { -%>
+<% if (field.type === 'checkbox') { -%>
+  data[<%= JSON.stringify(key) %>] = ['on', 'true', '1'].includes(formData.get(<%= JSON.stringify(key) %>) as string);
+<% } else if (field.type === 'number') { -%>
+  const <%= localName(key, index) %> = formData.get(<%= JSON.stringify(key) %>);
+  if (<%= localName(key, index) %> !== null && <%= localName(key, index) %> !== '') data[<%= JSON.stringify(key) %>] = Number(<%= localName(key, index) %>);
+<% } else { -%>
+  const <%= localName(key, index) %> = formData.get(<%= JSON.stringify(key) %>);
+  if (<%= localName(key, index) %> !== null) data[<%= JSON.stringify(key) %>] = <%= localName(key, index) %>;
+<% } -%>
+<% }); -%>
+  return <%= form.pascal %>Schema.parse(data);
+}
+
 // @ts-ignore - meta.env is a vite feature
 const base = import.meta.env.VITE_API_URL;
 <% if (hasFileFields) { %>
@@ -135,8 +151,13 @@ async function uploadFile(file: File): Promise<string> {
 <% } %>
 export async function submit<%= form.pascal %>(data: <%= form.pascal %>Data): Promise<{
   success: boolean;
+  status: number;
   errors?: Record<string, string>;
 }> {
+  if (!FORM_ID || FORM_ID === "undefined") {
+    throw new Error(`Form "${FORM_ID || "unknown"}" has not been pushed. Run fimo forms push first.`);
+  }
+
 <% if (hasFileFields) { -%>
   const payload: Record<string, unknown> = { ...data };
 
@@ -144,9 +165,9 @@ export async function submit<%= form.pascal %>(data: <%= form.pascal %>Data): Pr
   await Promise.all([
 <% fileFieldKeys.forEach((key) => { -%>
     (async () => {
-      const file = data.<%= key %>;
-      if (file instanceof File) {
-        payload.<%= key %> = await uploadFile(file);
+      const file = data[<%= JSON.stringify(key) %>];
+      if (typeof File !== "undefined" && file instanceof File) {
+        payload[<%= JSON.stringify(key) %>] = await uploadFile(file);
       }
     })(),
 <% }); -%>
@@ -160,7 +181,7 @@ export async function submit<%= form.pascal %>(data: <%= form.pascal %>Data): Pr
       body: JSON.stringify(payload),
     });
   } catch {
-    return { success: false };
+    return { success: false, status: 0 };
   }
 <% } else { -%>
   let res: Response;
@@ -171,18 +192,18 @@ export async function submit<%= form.pascal %>(data: <%= form.pascal %>Data): Pr
       body: JSON.stringify(data),
     });
   } catch {
-    return { success: false };
+    return { success: false, status: 0 };
   }
 <% } -%>
 
   if (res.ok) {
-    return { success: true };
+    return { success: true, status: res.status };
   }
 
   if (res.status === 422) {
     const json = await res.json();
-    return { success: false, errors: json.errors };
+    return { success: false, status: res.status, errors: json.errors };
   }
 
-  return { success: false };
+  return { success: false, status: res.status };
 }

package/assets/skills/fimo/SKILL.md

@@ -12,27 +12,34 @@ description: >-
 Fimo ships its skills through its CLI. `fimo-code` resolves from the project's installed `fimo` package;
 workflow skills resolve from the CLI you run. This file is only a pointer — fetch the real skill when needed.
 
+If the initiating prompt supplies an exact Fimo CLI invocation prefix, preserve it for every Fimo command in
+that flow. Replace `<fimo-cli>` below with that prefix; otherwise use `npx fimo@latest`. The detailed selector
+rule and shorthand for the fetched workflow docs live in `fimo-cli`.
+
 When you are about to do Fimo work:
 
-1. List what's available: `npx fimo@latest skills list`
-2. Load the relevant skill: `npx fimo@latest skills get <name>` (add `--ref <doc>` for a reference doc)
+1. List what's available: `<fimo-cli> skills list`
+2. Load the relevant skill: `<fimo-cli> skills get <name>` (add `--ref <doc>` for a reference doc)
 
 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.
 
 Reference paths mentioned in streamed skill output, such as `references/media.md`, are identifiers,
 not files in the project. Load them through the CLI, for example
-`npx fimo@latest skills get fimo-cli --ref media`. Do not use a filesystem read tool for them.
+`<fimo-cli> skills get fimo-cli --ref media`. Do not use a filesystem read tool for them.
 
 Pick by task:
 
 - Writing code — schemas/forms, generated clients, labels, framework adapters, rendering primitives → `fimo-code`
-- CLI commands and workflows — push, deploy, sync, labels, domains, analytics → `fimo-cli`
+- Project creation, local setup, cloning, and CLI workflows — init, push, deploy, sync, labels, domains, analytics → `fimo-cli`
 - Fimo agents — create, configure, validate, deploy, run, or inspect them → `fimo-cli` (`references/agents.md`)
 - AI agent setup — connect Claude Code, Codex, Cursor, or another agent → `fimo-cli` (`references/agent-setup.md`)
 - Project MCP setup — configure `fimo mcp` for a local agent → `fimo-cli` (`references/mcp.md`)
 - The Fimo Studio dashboard / web app UI → `fimo-studio`
 - Migrating an existing site into Fimo → `fimo-migration`
 
+For project setup, load `fimo-cli` first. Its `references/init.md` decision tree distinguishes a new or empty
+project, an existing Fimo project, and an external migration; load `fimo-migration` for the last path.
+
 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.
 
 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

@@ -11,17 +11,17 @@ description: >-
 
 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.
 
-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`.
+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.
 
 Use `fimo <command> --help` for full flag details on any command.
 
 > **Webhooks are beta.** Verify a destination with `fimo webhooks test <id> --wait` and inspect its delivery history before depending on it in production.
 
-## Running the CLI: always `npx fimo@latest`
+## Running the CLI
 
-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.
+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.
 
-The examples in this skill and its references write `fimo <command>` for brevity — mentally prefix them with `npx fimo@latest`.
+The examples in this skill and its references use `fimo <command>` as shorthand. Execute them with the selected invocation above.
 
 ## Output for agents: `--json` is the stable contract
 
@@ -49,22 +49,22 @@ A project can have multiple **envs** — each is a git branch _plus_ its own DB,
 ## Quick Start
 
 ```bash
-npx fimo@latest login                          # authenticate via browser
-npx fimo@latest skills install                 # install the global Fimo skill for your AI tools
-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.
-npx fimo@latest init my-site --starter fimo-site@1 --org <id> --yes --no-skills  # opt-in content-led starter for a new project
-npx fimo@latest init --project-id <id> my-site # link an EXISTING project instead of creating one
-npx fimo@latest clone                          # interactively choose an existing project to clone locally
-cd my-site                                     # then load skills on demand: npx fimo@latest skills get fimo-code
+fimo login                                     # authenticate via browser
+fimo skills install                            # install the global Fimo skill for your AI tools
+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.
+fimo init my-site --starter fimo-site@1 --org <id> --yes --no-skills  # opt-in content-led starter for a new project
+fimo init --project-id <id> my-site            # set up a project by ID: scaffold a newly created project or clone existing code
+fimo clone                                     # interactively choose an existing project to clone locally
+cd my-site                                     # then load skills on demand: fimo skills get fimo-code
 pnpm dev                                       # run the app locally (use the project's PM: pnpm/npm run/yarn/bun) — your iteration loop
-npx fimo@latest credits                        # inspect the owning org's AI credit balance (read-only)
-npx fimo@latest history list                   # inspect this environment's restore points
-npx fimo@latest validate                       # run all checks + codegen; fails on missing DB labels
-npx fimo@latest deploy                         # ON-DEMAND: hosted preview / shareable link (runs validate internally)
-npx fimo@latest deploy --publish               # ON-DEMAND: publish live (only when the developer says "ship it")
+fimo credits                                   # inspect the owning org's AI credit balance (read-only)
+fimo history list                              # inspect this environment's restore points
+fimo validate                                  # run all checks + codegen; fails on missing DB labels
+fimo deploy                                    # ON-DEMAND: hosted preview / shareable link (runs validate internally)
+fimo deploy --publish                          # ON-DEMAND: publish live (only when the developer says "ship it")
 ```
 
-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`).
+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`).
 
 `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.
 
@@ -73,13 +73,13 @@ The working loop is local: run the app with the project's package-manager `dev`
 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.
 
 - "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`
-- "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**
-- "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**
+- "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**
+- "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**
 - "View form submissions / who filled out the contact form / inspect what users sent / how many signups" → `references/forms.md` § Reading submissions
-- "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**
-- "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**
-- "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**
-- "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**
+- "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**
+- "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**
+- "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**
+- "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**
 - "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`
 - "Deploy / publish / go live / push my changes" → `references/deploy.md`
 - "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
 These fire at specific moments in the project lifecycle. **Surface them proactively** rather than waiting for the user to ask:
 
 - **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.
+- **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.
 - **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`.
-- **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.
-- **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`.
-- **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.
+- **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.
+- **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`.
+- **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.
 - **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.
 - **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`.
 - **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
 
 - **Editing `.fimo/project.json`** — read-only; it's the link between local and remote project. Treat as a generated file.
 - **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`.
-- **Deploying without the developer asking or confirming** — offer, then wait for their yes. Don't auto-deploy after finishing an edit.
+- **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.
 - **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`.
 - **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".
 - **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

@@ -1,7 +1,5 @@
 # Account, authentication, and organizations
 
-> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
-
 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.
 
 ## Sign in

package/assets/skills/fimo-cli/references/agent-setup.md

@@ -1,7 +1,5 @@
 # AI agent setup
 
-> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
-
 Fimo connects agents in two layers:
 
 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:
 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:
 
 ```bash
-npx fimo@latest skills list            # what's available
-npx fimo@latest skills get fimo-code   # writing code: schemas, generated clients, labels, framework adapters
-npx fimo@latest skills get fimo-cli    # CLI + workflows (this skill)
-npx fimo@latest skills get fimo-cli --ref deploy   # a reference doc
+fimo skills list                           # what's available
+fimo skills get fimo-code                  # writing code: schemas, generated clients, labels, framework adapters
+fimo skills get fimo-cli                   # CLI + workflows (this skill)
+fimo skills get fimo-cli --ref deploy      # a reference doc
 ```
 
 Two CLI namespaces manage the two layers:
@@ -23,11 +21,11 @@ Two CLI namespaces manage the two layers:
 
 ## Set up the global skill (no install needed)
 
-Run the CLI via `npx fimo@latest` — do not install `fimo` globally.
+Do not install `fimo` globally; use the selected CLI invocation from the main `fimo-cli` skill.
 
 ```bash
-npx fimo@latest skills install         # opens the agent picker, installs the global fimo bootstrap
-npx fimo@latest login                  # connect your account when ready
+fimo skills install                    # opens the agent picker, installs the global fimo bootstrap
+fimo login                             # connect your account when ready
 ```
 
 ## `fimo skills` — install + sync + uninstall

package/assets/skills/fimo-cli/references/agents.md

@@ -1,7 +1,5 @@
 # Agents workflow (`fimo agents *`)
 
-> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
-
 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>/`.
 
 ## Mental model

package/assets/skills/fimo-cli/references/analytics.md

@@ -1,7 +1,5 @@
 # Analytics workflow
 
-> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
-
 Pageview aggregates for the **published** site are stored in Fimo's analytics pipeline. Preview traffic is not recorded.
 
 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

@@ -1,8 +1,6 @@
 # Assets workflow (media library)
 
-> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
-
-> 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.
+> 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.
 > For **generating** new images / videos with AI, see **`references/media.md`** for the task commands and recipes.
 
 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>
 
 1. Upload with `fimo assets upload` or generate with a task command such as `fimo image generate`.
 2. Keep the returned `url` (for direct use) or `id` (to attach to a `media` content-type field).
-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.
+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

@@ -1,7 +1,5 @@
 # Envs & branches (git-shaped workflow)
 
-> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
-
 > **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.
 
 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

@@ -1,8 +1,6 @@
 # Content workflow (schemas + Singles + entries)
 
-> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
-
-> 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.
+> 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.
 
 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.
 
@@ -15,7 +13,7 @@ Never remove `isSingleton: true` merely because `fimo entries create` rejects th
 
 ## Flow
 
-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.
+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.
 2. Run `fimo schemas push {Uid}`. It registers the schema and generates the framework-specific public modules. It does not run whole-project validation.
 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.
 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
 
 All commands accept `-C, --cwd <dir>` to point at a different project directory.
 
-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.
+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.
 
 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.
 
@@ -83,7 +81,7 @@ fimo entries bulk-update <TypeName> (--file <path> | --stdin)
 fimo entries bulk-delete <TypeName> (--ids <id1>,<id2> | --where '<json>') [--locale es]
 ```
 
-`--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.
+`--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.
 
 `entries list` accepts the same read query surface as generated hooks:
 
@@ -107,7 +105,7 @@ Reference filters take the target `id` string (`{"author":"750e..."}`). On a to-
 
 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.
 
-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`.
+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`.
 
 ### Read-only SQL
 
@@ -198,7 +196,7 @@ fimo entries bulk-delete BlogPost --where '{"archived":true}'
 
 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.
 
-For reference schema JSON and entry value shape, run `npx fimo@latest skills get fimo-code --ref content/schema`. The short version:
+For reference schema JSON and entry value shape, run `fimo skills get fimo-code --ref content/schema`. The short version:
 
 ```json
 {
@@ -264,13 +262,13 @@ Use `"isSingleton": true` for a Single with exactly one set of content. Generate
 
 ## "Add a blog" recipe
 
-1. Run `npx fimo@latest skills get fimo-code --ref content/schema` for the JSON shape and field types.
+1. Run `fimo skills get fimo-code --ref content/schema` for the JSON shape and field types.
 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.
 3. Run `fimo schemas push BlogPost`.
 4. Generate cover images: `fimo image generate --prompt "..." --aspect-ratio 16:9` (see `media.md`).
 5. Seed entries: `fimo entries create BlogPost --body '{"data": {"slug": "first-post", "title": "...", "coverImage": {...}}}'`.
-6. Run `npx fimo@latest skills get fimo-code --ref ui` and load the detected framework reference for rendering primitives.
-7. Run `npx fimo@latest skills get fimo-code --ref labels` and load the detected framework reference for labels.
+6. Run `fimo skills get fimo-code --ref ui` and load the detected framework reference for rendering primitives.
+7. Run `fimo skills get fimo-code --ref labels` and load the detected framework reference for labels.
 8. Load the detected framework reference, then build the page with its generated server or client surface.
 
 ## Non-interactive use

package/assets/skills/fimo-cli/references/credits.md

@@ -1,7 +1,5 @@
 # Credits
 
-> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
-
 `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.
 
 ```bash

package/assets/skills/fimo-cli/references/deploy.md

@@ -1,8 +1,6 @@
 # Deploy pipeline
 
-> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
-
-**`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.
+**`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.
 
 > **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`.
 
@@ -61,7 +59,7 @@ SPAs; Astro's `fimo()` integration lives in `references/frameworks/astro.md`.
 
 ## Warm the sandbox early in a session (optional)
 
-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.
+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.
 
 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).
 

package/assets/skills/fimo-cli/references/describe.md

@@ -1,7 +1,5 @@
 # Describe — read-only snapshot of the current project
 
-> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
-
 `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.
 
 It is **read-only**. Never writes, never hits the network. Safe to run any time.