fimo 0.14.0 → 0.15.0-staging.1

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

@@ -17,6 +17,8 @@ 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)
 
+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.

package/assets/skills/fimo-cli/SKILL.md

@@ -52,7 +52,6 @@ A project can have multiple **envs** — each is a git branch _plus_ its own DB,
 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

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

@@ -25,18 +25,18 @@ fimo --env <name> <command>     # peek at another env for one command (does not
 
 ## Commands
 
-| Command                 | git analogue        | What it does                                                                                                                              |
-| ----------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `fimo branch`           | `git branch`        | List envs (current marked `*`). `-v` adds preview URLs + deleted envs.                                                                    |
-| `fimo branch <name>`    | `git branch <name>` | Create an env off the current one. `--from <env>` forks from a different parent. Provisions DB + sandbox + preview + R2 prefix.           |
-| `fimo branch -d <name>` | `git branch -d`     | Delete an env — tears down its sandbox, Neon branch, and R2 prefix. Refuses `main` and `prod`.                                            |
-| `fimo checkout <name>`  | `git checkout`      | Switch to an env (checks out the matching git branch too). `-b` creates + switches; `--from <env>` sets the parent (with `-b`).           |
-| `fimo switch <name>`    | `git switch`        | Switch to an existing env. Takes only `<name>` (no `-b`/`--from`) — use `fimo checkout -b` to create + switch.                            |
-| `fimo pull`             | `git pull`          | Sync the current env's data plane (DB/assets) down from its parent. `--from <env>` syncs from an explicit ancestor.                       |
-| `fimo diff [from] [to]` | `git diff`          | Two-env diff across all surfaces. Defaults `from` = current env, `to` = `main`. `--surface <name>` limits to one; `--json`; `--no-color`. |
-| `fimo status`           | `git status`        | Multi-surface status for the current env vs its parent. See below.                                                                        |
-| `fimo merge <from>`     | `git merge`         | Merge another env into the current one (multi-surface, atomic, interactive conflict resolver). See below.                                 |
-| `fimo publish`          | —                   | Tag `main@HEAD` as `release/<version>` and trigger the prod swap. See "Publishing" below.                                                 |
+| Command                 | git analogue        | What it does                                                                                                                                                                     |
+| ----------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `fimo branch`           | `git branch`        | List envs (current marked `*`). `-v` adds preview URLs + deleted envs.                                                                                                           |
+| `fimo branch <name>`    | `git branch <name>` | Create an env off the current one. `--from <env>` forks from a different parent. Provisions DB + sandbox + preview + R2 prefix.                                                  |
+| `fimo branch -d <name>` | `git branch -d`     | Delete an env — tears down its sandbox, Neon branch, and R2 prefix. Refuses `main` and `prod`.                                                                                   |
+| `fimo checkout <name>`  | `git checkout`      | Switch to an env (checks out the matching git branch; the app derives its env from that branch at startup). `-b` creates + switches; `--from <env>` sets the parent (with `-b`). |
+| `fimo switch <name>`    | `git switch`        | Switch to an existing env. Takes only `<name>` (no `-b`/`--from`) — use `fimo checkout -b` to create + switch.                                                                   |
+| `fimo pull`             | `git pull`          | Sync the current env's data plane (DB/assets) down from its parent. `--from <env>` syncs from an explicit ancestor.                                                              |
+| `fimo diff [from] [to]` | `git diff`          | Two-env diff across all surfaces. Defaults `from` = current env, `to` = `main`. `--surface <name>` limits to one; `--json`; `--no-color`.                                        |
+| `fimo status`           | `git status`        | Multi-surface status for the current env vs its parent. See below.                                                                                                               |
+| `fimo merge <from>`     | `git merge`         | Merge another env into the current one (multi-surface, atomic, interactive conflict resolver). See below.                                                                        |
+| `fimo publish`          | —                   | Tag `main@HEAD` as `release/<version>` and trigger the prod swap. See "Publishing" below.                                                                                        |
 
 All of these accept the global `--env` override. `diff`, `status`, `merge`, and `publish` additionally accept `-C, --cwd <dir>` to point at a project directory.
 
@@ -105,7 +105,8 @@ Use `fimo publish` for versioned prod releases; use `fimo deploy --publish` for
 
 ## Anti-patterns
 
-- **Using `git checkout -b` instead of `fimo checkout -b`** — raw git creates the branch but **not** the env's DB / sandbox / preview. Always use `fimo` for branch operations so resources are provisioned atomically. (Running `fimo branch <name>` after the fact provisions them.)
+- **Using `git checkout -b` instead of `fimo checkout -b`** — raw git creates the branch but **not** the env's DB / sandbox / preview. Always use `fimo` for branch operations so resources are provisioned atomically. (Running `fimo branch <name>` after the fact provisions them.) The running app itself follows the git branch either way.
+- **Hardcoding the tenant API URL** — the app derives it from the git branch and `.fimo/project.json`. Set `VITE_API_URL` / `NEXT_PUBLIC_FIMO_API_URL` yourself only as a deliberate override (e.g. a local API); it then wins over derivation on every branch.
 - **Trying to push to or delete `prod` / `release/*`** — these are read-only/protected. Publish to update prod; never push.
 - **`fimo merge` straight onto `main` as a habit** — it's gated for a reason. Merge on a branch, then publish.
 - **Confusing `fimo switch` (env) with `fimo orgs switch` (org).**

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

@@ -54,9 +54,10 @@ framework default. Production uses `.fimo/config.json#runtime.framework` and
 the same bounded build/install overrides. Existing applications keep their
 router and hosting behavior: do not replace the router or derive
 deployment rewrites from `.fimo/config.json#routes`. When setup changes are
-needed, load the `fimo-code` skill's `references/frameworks/hosting.md` recipe;
-it covers the React Router `fimoPreset()` connector and the explicit catch-all
-used only by plain Vite `BrowserRouter` SPAs.
+needed, load the `fimo-code` skill's framework reference:
+`references/frameworks/hosting.md` covers the React Router `fimoPreset()`
+connector and the explicit catch-all used only by plain Vite `BrowserRouter`
+SPAs; Astro's `fimo()` integration lives in `references/frameworks/astro.md`.
 
 ## Warm the sandbox early in a session (optional)
 

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

@@ -77,5 +77,5 @@ The scoped view still emits the project-level metadata header (name, framework,
 ## Notes for AI tools
 
 - The JSON shape is stable; parse it rather than scraping the human output when you need a specific field.
-- The `framework` field uses Fimo's shared Vercel filesystem detector, which considers package dependencies, configuration files, and framework-specific file layout. For unusual or deliberately mixed projects it may be `null`; inspect `package.json` and the application tree before choosing a framework reference.
+- `framework` is normally auto-detected. If it is `null`, inspect the project before choosing framework-specific guidance.
 - The command runs in any directory that contains `.fimo/project.json` or one of its ancestors. If you're not in a Fimo project, `describe` will run against whatever directory you point it at (it doesn't require Fimo credentials).

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

@@ -13,7 +13,7 @@ fimo init [dir] [options]
 `fimo init` runs the full onboarding in one shot:
 
 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).
-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` selects the minimal Next.js App Router scaffold. An optional `--starter fimo-site@1` adds a React-Router content starter only to a newly created project.
+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.
 3. **Installs dependencies** — prompts for the package manager, or honor `--package-manager <pm>` / `--no-install`.
 4. **Optionally sets up Fimo skills** — confirm prompt, or `--skills` / `--no-skills`.
 
@@ -23,7 +23,7 @@ fimo init [dir] [options]
 | `--project-id <id>`          | no                            | Link an EXISTING project instead of creating one (clones it).                                                                                                  |
 | `--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.             |
 | `--env <name>`               | no                            | Env to check out when linking an existing project (defaults to `main`).                                                                                        |
-| `--framework <framework>`    | no                            | New-project scaffold: `react-router` (default) or `nextjs` (App Router). Existing repositories are preserved.                                                  |
+| `--framework <framework>`    | no                            | New-project scaffold: `react-router` (default), `nextjs` (App Router), or `sveltekit`. Existing repositories are preserved.                                  |
 | `--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`. |
 | `--package-manager <pm>`     | no                            | `npm` \| `pnpm` \| `yarn` \| `bun`.                                                                                                                            |
 | `--install` / `--no-install` | yes in non-TTY                | Install deps after checkout (or skip it).                                                                                                                      |
@@ -63,15 +63,16 @@ writing anything. If dependencies were skipped, install them and run
 
 ### Choose the application framework
 
-Omit `--framework` for the existing React Router scaffold, or select the
-minimal Next.js App Router shell explicitly:
+Omit `--framework` for the existing React Router scaffold, or select a
+minimal framework-native shell explicitly:
 
 ```bash
 npx fimo@latest init my-next-site --framework nextjs --org <organizationId>
+npx fimo@latest init my-svelte-site --framework sveltekit --org <organizationId>
 ```
 
-The Next scaffold includes `src/app`, `FimoProvider`, the hosted-preview config,
-and `.fimo/config.json#runtime.framework`. It intentionally contains no schema,
+Both shells include their framework adapter, hosted-preview connector, and
+`.fimo/config.json#runtime.framework`. They intentionally contain no schema,
 labels, or designed website. After init, load the project rules and `fimo-code`
 to build the requested site. The current `fimo-site@1` content starter supports
 React Router only.
@@ -86,11 +87,11 @@ Pass `--project-id <id>` to link an EXISTING project instead of creating one. Th
 
 `fimo init` (create-new path) scaffolds:
 
-- The selected project shell: React Router by default, or Next.js App Router with `--framework nextjs`
+- The selected project shell: React Router by default, Next.js App Router with `--framework nextjs`, or SvelteKit with `--framework sveltekit`
 - `.fimo/project.json` — links this directory to the remote project (read-only after creation)
 - `.fimo/config.json` — project, route, locale, SEO, and agent policy
 - `.fimo/agents/` — versioned agent bundles
-- `.env` — tenant content API URLs for Vite and Next runtimes
+- `.env` — framework-specific tenant content API URLs for local development
 - `AGENTS.md` + `CLAUDE.md` — project rules (from the template) read by AGENTS.md-compatible tools and Claude Code. Both point the agent at `fimo skills get` to load the real skills on demand.
 - A git repository with `fimo` as the remote, and — after dependencies install — an initial commit (including the lockfile) plus an initial push
 
@@ -106,7 +107,7 @@ Nothing is written into per-agent skill dirs: the rich skills are fetched on dem
 
 Codex, OpenCode, Aider, and similar AGENTS.md-native tools work directly off AGENTS.md.
 
-`.env` is only the bootstrap app env so local `pnpm dev` works immediately. User-managed public variables are stored with `fimo vars add` and synced into a managed `.env.local` block; hidden values use `fimo secrets add`. See `references/project-vars-and-secrets.md`.
+`.env` is only the bootstrap app env so local `pnpm dev` works immediately. Fimo writes the tenant API aliases used by its supported frameworks; users should not discover or set those URLs manually. User-managed public variables are stored with `fimo vars add` and synced into a managed `.env.local` block; hidden values use `fimo secrets add`. See `references/project-vars-and-secrets.md`.
 
 ## Right after scaffolding
 
@@ -137,7 +138,7 @@ After `fimo init` completes, the project root has `AGENTS.md` (universal) and `C
 2. `Read` the project rules file: `AGENTS.md` (or `CLAUDE.md` if you're Claude Code).
 3. Run `npx fimo@latest describe --json` and read the detected framework, schemas, locales, and tree.
 4. Load the code skill on demand: `npx fimo@latest skills get fimo-code`.
-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.
+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.
 
 Do not batch-load every reference. Progressive disclosure keeps unrelated framework and product guidance out of the coding context.
 
@@ -155,4 +156,3 @@ The first installs the global bootstrap skill for the new agent; the second gene
 ## Multi-org accounts
 
 If you belong to a single organization, `fimo init` defaults to it. If you belong to multiple and don't pass `--org`, the CLI shows an interactive picker. For `fimo init`, pass the org **id** (from the `ID` column of `fimo orgs list`) — not the slug. Use `fimo orgs switch --org <id-or-slug>` to set a default for future `fimo init` invocations. See `references/account.md`.
-</content>