fimo 0.14.0 → 0.15.0-staging.2

package/README.md

@@ -29,6 +29,7 @@ Run the CLI with `npx` — no global install, always the latest:
 npx fimo@latest login
 npx fimo@latest init my-site                 # default React Router scaffold
 # 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/astro/components/Boolean.astro

@@ -0,0 +1,14 @@
+---
+import { getFimoSource } from 'fimo/astro';
+
+interface Props {
+  value: { valueOf(): boolean } | null | undefined;
+  as?: keyof astroHTML.JSX.IntrinsicElements;
+  [key: string]: unknown;
+}
+
+const { value, as: Component = 'span', ...props } = Astro.props;
+const source = getFimoSource(value);
+---
+
+{value != null && <Component {...props} data-fimo-source={source}>{String(value.valueOf())}</Component>}

package/assets/astro/components/Date.astro

@@ -0,0 +1,23 @@
+---
+import { getFimoSource } from 'fimo/astro';
+
+interface Props {
+  value: globalThis.Date | String | string | number | null | undefined;
+  locale?: string;
+  options?: Intl.DateTimeFormatOptions;
+  [key: string]: unknown;
+}
+
+const { value, locale, options, ...props } = Astro.props;
+const rawValue = value instanceof String ? value.toString() : value;
+const date = rawValue == null ? null : new globalThis.Date(rawValue as string | number | globalThis.Date);
+const validDate = date && !Number.isNaN(date.getTime()) ? date : null;
+const dateTime = validDate?.toISOString().split('T')[0];
+const content = validDate?.toLocaleDateString(
+  locale,
+  options ?? { year: 'numeric', month: 'short', day: 'numeric' }
+);
+const source = getFimoSource(value);
+---
+
+{validDate && <time {...props} datetime={dateTime} data-fimo-source={source}>{content}</time>}

package/assets/astro/components/Image.astro

@@ -0,0 +1,79 @@
+---
+import type { FimoMedia } from 'fimo/astro';
+import { getFimoSource } from 'fimo/astro';
+
+import {
+  mergeAstroImageStyle,
+  resolveImagePresentation,
+  type ImageFit,
+} from 'fimo/astro/internal';
+
+interface Props {
+  value: FimoMedia | null | undefined;
+  alt?: string;
+  quality?: number;
+  fit?: ImageFit;
+  unoptimized?: boolean;
+  overrideSrc?: string;
+  width?: string | number;
+  height?: string | number;
+  sizes?: string;
+  srcset?: string;
+  srcSet?: string;
+  hostSuffixes?: readonly string[];
+  style?: string | Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+const {
+  value,
+  alt,
+  quality,
+  fit,
+  unoptimized,
+  overrideSrc,
+  width,
+  height,
+  sizes,
+  srcset,
+  srcSet,
+  hostSuffixes,
+  style,
+  ...props
+} = Astro.props;
+const image = value
+  ? resolveImagePresentation({
+      src: value.url,
+      alt: alt ?? value.alt,
+      mediaWidth: value.width,
+      mediaHeight: value.height,
+      quality,
+      fit,
+      unoptimized,
+      overrideSrc,
+      width,
+      height,
+      sizes,
+      srcSet: srcset ?? srcSet,
+      hostSuffixes,
+    })
+  : null;
+const imageStyle = image ? mergeAstroImageStyle(style, image.objectFit) : style;
+const source = getFimoSource(value);
+---
+
+{
+  image && (
+    <img
+      {...props}
+      src={image.src}
+      alt={image.alt}
+      width={image.width}
+      height={image.height}
+      sizes={image.sizes}
+      srcset={image.srcSet}
+      style={imageStyle}
+      data-fimo-source={source}
+    />
+  )
+}

package/assets/astro/components/Json.astro

@@ -0,0 +1,14 @@
+---
+import { getFimoSource } from 'fimo/astro';
+
+interface Props {
+  value: unknown;
+  as?: keyof astroHTML.JSX.IntrinsicElements;
+  [key: string]: unknown;
+}
+
+const { value, as: Component = 'span', ...props } = Astro.props;
+const source = getFimoSource(value);
+---
+
+{value != null && <Component {...props} data-fimo-source={source}>{JSON.stringify(value)}</Component>}

package/assets/astro/components/RichText.astro

@@ -0,0 +1,17 @@
+---
+import type { FimoRichText } from 'fimo/astro';
+import { getFimoSource } from 'fimo/astro';
+
+import { renderRichTextHtml } from 'fimo/astro/internal';
+
+interface Props {
+  value: FimoRichText | null | undefined;
+  [key: string]: unknown;
+}
+
+const { value, ...props } = Astro.props;
+const source = getFimoSource(value);
+const html = renderRichTextHtml(value?.content);
+---
+
+{value && <div {...props} data-fimo-source={source} data-fimo-richtext="" set:html={html} />}

package/assets/astro/components/StaticImage.astro

@@ -0,0 +1,66 @@
+---
+import {
+  mergeAstroImageStyle,
+  resolveImagePresentation,
+  type ImageFit,
+} from 'fimo/astro/internal';
+
+interface Props {
+  src: string;
+  alt: string;
+  quality?: number;
+  fit?: ImageFit;
+  unoptimized?: boolean;
+  overrideSrc?: string;
+  width?: string | number;
+  height?: string | number;
+  sizes?: string;
+  srcset?: string;
+  srcSet?: string;
+  hostSuffixes?: readonly string[];
+  style?: string | Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+const {
+  src,
+  alt,
+  quality,
+  fit,
+  unoptimized,
+  overrideSrc,
+  width,
+  height,
+  sizes,
+  srcset,
+  srcSet,
+  hostSuffixes,
+  style,
+  ...props
+} = Astro.props;
+const image = resolveImagePresentation({
+  src,
+  alt,
+  quality,
+  fit,
+  unoptimized,
+  overrideSrc,
+  width,
+  height,
+  sizes,
+  srcSet: srcset ?? srcSet,
+  hostSuffixes,
+});
+const imageStyle = mergeAstroImageStyle(style, image.objectFit);
+---
+
+<img
+  {...props}
+  src={image.src}
+  alt={image.alt}
+  width={image.width}
+  height={image.height}
+  sizes={image.sizes}
+  srcset={image.srcSet}
+  style={imageStyle}
+/>

package/assets/astro/components/Text.astro

@@ -0,0 +1,23 @@
+---
+import { getFimoParts, getFimoSource } from 'fimo/astro';
+
+interface Props {
+  value: unknown;
+  as?: keyof astroHTML.JSX.IntrinsicElements;
+  [key: string]: unknown;
+}
+
+const { value, as: Component = 'span', ...props } = Astro.props;
+const parts = getFimoParts(value);
+const source = getFimoSource(value);
+---
+
+<Component {...props} data-fimo-source={source}>
+  {
+    parts && parts.length > 1
+      ? parts.map((part) =>
+          part.source ? <span data-fimo-source={part.source}>{part.text}</span> : part.text
+        )
+      : String(value ?? '')
+  }
+</Component>

package/assets/astro/components/Video.astro

@@ -0,0 +1,47 @@
+---
+import type { FimoMedia } from 'fimo/astro';
+import { getFimoSource } from 'fimo/astro';
+
+interface Props {
+  value: FimoMedia | null | undefined;
+  overrideSrc?: string;
+  autoplay?: boolean;
+  autoPlay?: boolean;
+  loop?: boolean;
+  muted?: boolean;
+  playsinline?: boolean;
+  playsInline?: boolean;
+  [key: string]: unknown;
+}
+
+const {
+  value,
+  overrideSrc,
+  autoplay,
+  autoPlay,
+  loop = true,
+  muted = true,
+  playsinline,
+  playsInline,
+  ...props
+} = Astro.props;
+const source = getFimoSource(value);
+const shouldAutoplay = autoplay ?? autoPlay ?? true;
+const shouldPlayInline = playsinline ?? playsInline ?? true;
+---
+
+{
+  value && (
+    <video
+      {...props}
+      src={overrideSrc ?? value.url}
+      width={value.width}
+      height={value.height}
+      autoplay={shouldAutoplay}
+      loop={loop}
+      muted={muted}
+      playsinline={shouldPlayInline}
+      data-fimo-source={source}
+    />
+  )
+}

package/assets/astro/components/index.d.ts

@@ -0,0 +1,8 @@
+export { default as Boolean } from './Boolean.astro';
+export { default as Date } from './Date.astro';
+export { default as Image } from './Image.astro';
+export { default as Json } from './Json.astro';
+export { default as RichText } from './RichText.astro';
+export { default as StaticImage } from './StaticImage.astro';
+export { default as Text } from './Text.astro';
+export { default as Video } from './Video.astro';

package/assets/astro/components/index.js

@@ -0,0 +1,8 @@
+export { default as Boolean } from './Boolean.astro';
+export { default as Date } from './Date.astro';
+export { default as Image } from './Image.astro';
+export { default as Json } from './Json.astro';
+export { default as RichText } from './RichText.astro';
+export { default as StaticImage } from './StaticImage.astro';
+export { default as Text } from './Text.astro';
+export { default as Video } from './Video.astro';

package/assets/content-templates/shared/server.eta

@@ -0,0 +1,56 @@
+// AUTO-GENERATED by `fimo` from src/schemas/<%= model.uid %>.json - DO NOT EDIT.
+// Runtime implementation lives in the project-local <%= runtimeImport %> package export.
+<% if (model.isSingleton) { -%>
+import { createSingletonClient } from "<%= runtimeImport %>";
+import type { ContentSchema, SingletonContentClient } from "<%= runtimeImport %>";
+<% } else { -%>
+import { createContentClient } from "<%= runtimeImport %>";
+import type { CollectionContentClient, ContentSchema } from "<%= runtimeImport %>";
+<% } -%>
+
+import schema from "./<%= model.uid %>.json";
+<%
+if (model.referenceImports && model.referenceImports.length > 0) {
+  model.referenceImports.forEach((referenceImport) => {
+-%>
+import * as <%= referenceImport.pascal %> from "./<%= referenceImport.pascal %>";
+<%
+  });
+}
+if (model.isSingleton) {
+-%>
+import type { <%= model.pascal %>, <%= model.pascal %>Input } from "./<%= model.pascal %>.types";
+<% } else { -%>
+import type { <%= model.pascal %>, <%= model.pascal %>Fields, <%= model.pascal %>Input, <%= model.pascal %>Populate, <%= model.pascal %>Query } from "./<%= model.pascal %>.types";
+<% } -%>
+
+export type { <%= model.pascal %>, <%= model.pascal %>Fields, <%= model.pascal %>FimoMeta, <%= model.pascal %>Input, <%= model.pascal %>Populate, <%= model.pascal %>Query, <%= model.pascal %>References, <%= model.pascal %>Result, <%= model.pascal %>Sort, <%= model.pascal %>Where } from "./<%= model.pascal %>.types";
+<% if (!model.isSingleton) { -%>
+export type { CollectionPage, CollectionPageInfo } from "<%= runtimeImport %>";
+<% } -%>
+
+<% if (model.isSingleton) { -%>
+const client: SingletonContentClient<<%= model.pascal %>, <%= model.pascal %>Input> = createSingletonClient<
+  <%= model.pascal %>,
+  <%= model.pascal %>Input
+>({
+  schema: schema as unknown as ContentSchema,
+<% } else { -%>
+const client: CollectionContentClient<<%= model.pascal %>, <%= model.pascal %>Input> = createContentClient<
+  <%= model.pascal %>,
+  <%= model.pascal %>Input
+>({
+  schema: schema as unknown as ContentSchema,
+<% } -%>
+<% if (model.referenceImports && model.referenceImports.length > 0) { -%>
+  references: { <%= model.referenceImports.map((referenceImport) => referenceImport.pascal).join(", ") %> },
+<% } -%>
+});
+
+<% if (model.isSingleton) { -%>
+export const { get, update, wrapWithSource, meta } = client;
+<% } else { -%>
+export const { wrapWithSource, meta, getById, getBySlug, getByField, list, get, create, update, remove } = client;
+<% } -%>
+
+export default client;

package/assets/content-templates/sveltekit/content.eta

@@ -0,0 +1,86 @@
+// AUTO-GENERATED by `fimo` from src/schemas/<%= model.uid %>.json - DO NOT EDIT.
+// This isomorphic module is safe in SvelteKit server and universal load functions.
+import { env } from "$env/dynamic/public";
+<% if (model.isSingleton) { -%>
+import { createSingletonClient, serializeContent } from "<%= runtimeImport %>";
+import type { ContentSchema, SerializedContent, SingletonContentClient } from "<%= runtimeImport %>";
+<% } else { -%>
+import { createContentClient, serializeContent } from "<%= runtimeImport %>";
+import type { CollectionContentClient, ContentSchema, SerializedContent } from "<%= runtimeImport %>";
+<% } -%>
+
+import schema from "./<%= model.uid %>.json";
+import fimoConfig from "../../.fimo/config.json";
+<%
+if (model.referenceImports && model.referenceImports.length > 0) {
+  model.referenceImports.forEach((referenceImport) => {
+-%>
+import * as <%= referenceImport.pascal %> from "./<%= referenceImport.pascal %>";
+<%
+  });
+}
+if (model.isSingleton) {
+-%>
+import type { <%= model.pascal %>, <%= model.pascal %>Input } from "./<%= model.pascal %>.types";
+<% } else { -%>
+import type { <%= model.pascal %>, <%= model.pascal %>Fields, <%= model.pascal %>Input, <%= model.pascal %>Populate, <%= model.pascal %>Query } from "./<%= model.pascal %>.types";
+<% } -%>
+
+export type { <%= model.pascal %>, <%= model.pascal %>Fields, <%= model.pascal %>FimoMeta, <%= model.pascal %>Input, <%= model.pascal %>Populate, <%= model.pascal %>Query, <%= model.pascal %>References, <%= model.pascal %>Result, <%= model.pascal %>Sort, <%= model.pascal %>Where } from "./<%= model.pascal %>.types";
+<% if (!model.isSingleton) { -%>
+export type { CollectionPage, CollectionPageInfo } from "<%= runtimeImport %>";
+<% } -%>
+
+<% if (model.isSingleton) { -%>
+const client: SingletonContentClient<<%= model.pascal %>, <%= model.pascal %>Input> = createSingletonClient<
+  <%= model.pascal %>,
+  <%= model.pascal %>Input
+>({
+  schema: schema as unknown as ContentSchema,
+  apiUrl: env.PUBLIC_FIMO_API_URL,
+  defaultLocale: (fimoConfig as { i18n?: { defaultLocale?: string } }).i18n?.defaultLocale,
+<% } else { -%>
+const client: CollectionContentClient<<%= model.pascal %>, <%= model.pascal %>Input> = createContentClient<
+  <%= model.pascal %>,
+  <%= model.pascal %>Input
+>({
+  schema: schema as unknown as ContentSchema,
+  apiUrl: env.PUBLIC_FIMO_API_URL,
+  defaultLocale: (fimoConfig as { i18n?: { defaultLocale?: string } }).i18n?.defaultLocale,
+<% } -%>
+<% if (model.referenceImports && model.referenceImports.length > 0) { -%>
+  references: { <%= model.referenceImports.map((referenceImport) => referenceImport.pascal).join(", ") %> },
+<% } -%>
+});
+
+type <%= model.pascal %>Source = Pick<<%= model.pascal %>, "id" | "__fimo">;
+declare const SERIALIZED_CONTENT: unique symbol;
+
+/** Plain data for passing <%= model.pascal %> content through a SvelteKit load boundary. */
+export type Serialized<%= model.pascal %><
+  TValue extends <%= model.pascal %>Source | readonly <%= model.pascal %>Source[] = <%= model.pascal %>,
+> = SerializedContent<TValue> & { readonly [SERIALIZED_CONTENT]: TValue };
+
+export function serialize<TValue extends <%= model.pascal %>Source | readonly <%= model.pascal %>Source[]>(
+  value: TValue
+): Serialized<%= model.pascal %><TValue> {
+  return serializeContent(value) as Serialized<%= model.pascal %><TValue>;
+}
+
+<% if (model.isSingleton) { -%>
+export const { get, update, wrapWithSource, meta } = client;
+<% } else { -%>
+export const { wrapWithSource, meta, getById, getBySlug, getByField, list, get, create, update, remove } = client;
+<% } -%>
+
+/** Restore Fimo source tracking after content crosses a SvelteKit load boundary. */
+export function hydrate<TValue extends <%= model.pascal %>Source | readonly <%= model.pascal %>Source[]>(
+  value: Serialized<%= model.pascal %><TValue>
+): TValue {
+  if (Array.isArray(value)) {
+    return value.map((entry) => wrapWithSource(entry)) as unknown as TValue;
+  }
+  return wrapWithSource(value as unknown as Record<string, unknown>) as unknown as TValue;
+}
+
+export default client;

package/assets/skills/fimo/SKILL.md

@@ -12,25 +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,23 +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-next-site --framework nextjs --org <id>  # opt-in Next.js App Router scaffold
-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.
 
@@ -74,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`
@@ -113,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`.
@@ -128,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