fimo 0.14.0 → 0.15.0-staging.2

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.
@@ -25,18 +23,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 +103,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/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`.
 
@@ -54,13 +52,14 @@ 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)
 
-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.
@@ -77,5 +75,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/domains.md

@@ -1,7 +1,5 @@
 # Domains
 
-> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
-
 `fimo domains` is the surface for everything URL-related on a project. Three resources live here, and they're easy to confuse — keep them straight:
 
 | Resource              | What it is                                                           | Plan                   | Per project | Source of truth            |

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

@@ -1,19 +1,17 @@
 # Forms workflow
 
-> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
-
-> Package contract: run `npx fimo@latest skills get fimo-code --ref forms` for the JSON spec, generated Zod schema, submit helper, and application usage.
+> Package contract: run `fimo skills get fimo-code --ref forms` for the JSON spec, generated Zod schema, submit helper, and application usage.
 
 This file covers the **CLI workflow** for forms. Use it when the user wants to add a contact form, signup, feedback form, etc.
 
 ## Flow
 
-1. Write `src/forms/{name}.json` — kebab-case filename (e.g. `contact-us.json`). For the JSON spec and field types, run `npx fimo@latest skills get fimo-code --ref forms`.
+1. Write `src/forms/{name}.json` — kebab-case filename (e.g. `contact-us.json`). For the JSON spec and field types, run `fimo skills get fimo-code --ref forms`.
 2. Register with `fimo forms push {name}` — creates the form, obtains its `id`, patches it back into the JSON file.
 3. Pre-build generates `src/forms/{name}.ts` (Zod schema + `submitX` helper). Use the same `fimo-code` reference for the generated API.
 4. Write the application form using the generated `@/forms/{name}` module and the existing framework conventions.
 
-Steps 1, 3, and 4 reference the `fimo-code` skill (`npx fimo@latest skills get fimo-code`). Step 2 is the CLI command.
+Steps 1, 3, and 4 reference the `fimo-code` skill (`fimo skills get fimo-code`). Step 2 is the CLI command.
 
 ## CLI commands
 
@@ -45,11 +43,11 @@ Use this when the user asks "who filled out the contact form?", "how many signup
 
 ## "Add a contact form" recipe
 
-1. Run `npx fimo@latest skills get fimo-code --ref forms` for the JSON spec.
+1. Run `fimo skills get fimo-code --ref forms` for the JSON spec.
 2. Write `src/forms/contact-us.json` with the required fields.
 3. Run `fimo forms push contact-us` — the `id` is patched back into the JSON automatically.
 4. Use the same `fimo-code` forms reference for the generated `submitContactUs` + `ContactUsSchema` API.
-5. Run `npx fimo@latest skills get fimo-code --ref labels` and load the detected framework reference for form labels.
+5. Run `fimo skills get fimo-code --ref labels` and load the detected framework reference for form labels.
 6. Write the application form using the generated `@/forms/contact-us` module.
 
 **Register BEFORE writing app code that depends on the form** — otherwise the generated `.ts` doesn't exist and the runtime fetch 404s.

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

@@ -1,7 +1,5 @@
 # Project History
 
-> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
-
 History is scoped to the selected project environment. A restore point records the environment's CMS content and the matching Git commit so code and content can be recovered together.
 
 Fimo also creates restore points automatically after a successful deploy, on the destination of a completed environment merge, and after direct content editing has been quiet for 30 seconds. Rapid Studio auto-saves are grouped into one content point.

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

@@ -1,7 +1,5 @@
 # `fimo init`
 
-> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
-
 One-stop project setup: sign in, create a new Fimo project (or link an existing one), install dependencies, and optionally set up Fimo skills for your AI tools.
 
 ## Command
@@ -13,17 +11,17 @@ 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 sets up the named Fimo project: a project with no code yet is scaffolded as a fresh site, while an existing repository is cloned. Without it, `init` creates a NEW project. An interactive TTY shows a "Create new / Link existing" picker; non-interactive shells default to create-new. New projects use React Router by default; `--framework nextjs` and `--framework sveltekit` select minimal framework-native shells. An optional `--starter fimo-site@1` adds a content-led starter only to a newly created project without `--project-id`.
 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`.
 
 | Flag                         | Required                      | Purpose                                                                                                                                                        |
 | ---------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `[dir]` positional           | yes in non-TTY for create-new | Target directory (e.g. `my-site`)                                                                                                                              |
-| `--project-id <id>`          | no                            | Link an EXISTING project instead of creating one (clones it).                                                                                                  |
+| `--project-id <id>`          | no                            | Set up the named Fimo project: scaffold and push a fresh site when it has no code yet, otherwise clone it.                                                     |
 | `--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).                                                                                                                      |
@@ -42,7 +40,7 @@ caller one stable result envelope; `--yes` is useful when running in a TTY but
 is not required in a pipe or CI shell. The starter is never selected by default.
 
 ```bash
-npx fimo@latest --json init my-site \
+fimo --json init my-site \
   --starter fimo-site@1 \
   --org <organizationId> \
   --no-install \
@@ -59,38 +57,39 @@ singleton, `contact` form, and labels in `main`, writes the form id into
 writing anything. If dependencies were skipped, install them and run
 `fimo validate` before starting the app so generated clients are present.
 
-> **Zero-install:** run `npx fimo@latest init` — no global install needed. `fimo projects create` is also an alias of `fimo init` (create-new path).
+> **Zero-install:** the selected `fimo init` invocation needs no global install. `fimo projects create` is also an alias of `fimo init` (create-new path).
 
 ### 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>
+fimo init my-next-site --framework nextjs --org <organizationId>
+fimo 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.
 
 For `--agents`, pass the AI tool you're running in: `--agents=claude-code` for Claude Code, `--agents=cursor` for Cursor, `--agents=codex` for Codex, etc. When the flag is omitted, env-var detection of the invoking harness (e.g. `CLAUDECODE` / `CLAUDE_CODE_ENTRYPOINT` → claude-code) auto-targets that agent; other agents must be selected explicitly via `--agents`/`-a` or the interactive picker.
 
-## Linking an existing project
+## Setting up a project by ID
 
-Pass `--project-id <id>` to link an EXISTING project instead of creating one. This clones the project's git repo into `[dir]` and writes the local `.fimo/project.json`, the same as `fimo clone` (init's `--project-id` path reuses it). Use `--env <name>` to check out a specific env (defaults to `main`). Without `--project-id`, `fimo init` creates a new project.
+Pass `--project-id <id>` to set up a known Fimo project. If the project has no code yet — for example, one just created in Fimo Studio — `init` scaffolds a fresh site into it and pushes the initial commit: the same create-new path, linked to the existing ID. If the project already has code, `init` clones it into `[dir]`, like `fimo clone`. Use `--env <name>` to check out a specific env (defaults to `main`). Without `--project-id`, `fimo init` creates a new project.
 
-## What gets written (create-new)
+## What gets written (create-new path)
 
 `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 +105,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
 
@@ -117,15 +116,13 @@ cd my-site
 fimo rename "Acme Coffee"
 ```
 
-**Then start the local dev loop and ask the developer what they want to build.** Run the app with the project's package-manager `dev` script — `pnpm dev`, `npm run dev`, `yarn dev`, or `bun dev` (match the lockfile) — in the background; it serves the site on localhost with live reload. Edit, show, iterate. You do not need to deploy to see local changes.
+**Then start the local dev loop.** Run the app with the project's package-manager `dev` script — `pnpm dev`, `npm run dev`, `yarn dev`, or `bun dev` (match the lockfile) — in the background; it serves the site on localhost with live reload. Edit, show, iterate. You do not need to deploy to see local changes. If the initiating request did not say what to build, ask the developer — after the first preview below, never as a blocker before initializing.
 
 ```bash
 pnpm dev &            # or npm run dev / yarn dev / bun dev — the project's package manager
 ```
 
-When a unit of work looks done, **offer** to deploy (`fimo deploy` for a hosted preview / shareable link, `fimo deploy --publish` to go live) and run it only after the developer confirms.
-
-**Optional — warm the sandbox early:** only if you already know a deploy is coming, kick off a background `fimo deploy -m "chore: init" &` so the one-time ~15-30s sandbox provision + dep install happens while you work. This is a perf optimization, not a required step — skip it while you're just iterating locally. See `references/deploy.md` § Warm the sandbox early in a session.
+Outside the first-preview path below, when a unit of work looks done, **offer** to deploy (`fimo deploy` for a hosted preview / shareable link, `fimo deploy --publish` to go live) and run it only after the developer confirms.
 
 ## Load the project context
 
@@ -135,12 +132,24 @@ After `fimo init` completes, the project root has `AGENTS.md` (universal) and `C
 
 1. `cd <project-dir>` — switch into the new project.
 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.
+3. Run `fimo describe --json` with the current invocation prefix and read the detected framework, schemas, locales, and tree.
+4. Load the code skill on demand with the same prefix: `fimo 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 `fimo skills get fimo-code --ref frameworks/next`, then load App Router, Pages Router, or locales only when the project shape requires it. For SvelteKit, start with `fimo skills get fimo-code --ref frameworks/sveltekit`. For Astro, `fimo skills get fimo-code --ref frameworks/astro` is the single framework reference.
 
 Do not batch-load every reference. Progressive disclosure keeps unrelated framework and product guidance out of the coding context.
 
+### Create the first hosted preview (create-new path)
+
+Whenever `fimo init` created or scaffolded a new project — including a Studio-supplied `--project-id`, since Studio creates the project before any code exists — finish onboarding with exactly one plain preview deploy after init and context loading succeed, unless the user explicitly said not to deploy:
+
+```bash
+fimo deploy -m "chore: first preview" --json
+```
+
+`-m` is required because you run non-interactively; the deploy validates, commits pending changes, pushes, and syncs the hosted preview. It is also the sandbox warm-up — never run a separate warm-up deploy on this path. Read `data.preview_url` and `data.dashboard_url` from the envelope and return both links. If the initiating request described a concrete site, build a minimal meaningful first screen before this single deploy; otherwise deploy the scaffolded site as-is and then ask what to build.
+
+This first deploy creates a preview only — never add `--publish`, and treat every later deploy as offer-then-confirm. The rule does not apply when `init` cloned a project with existing code or when the work is a migration; those paths keep their normal deployment approval rules.
+
 ## Adding another AI tool to an existing project later
 
 If a teammate joins on a different AI tool (e.g. Cursor) after the project was scaffolded for claude-code only:
@@ -155,4 +164,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>

package/assets/skills/fimo-cli/references/integrations/firecrawl.md

@@ -1,7 +1,5 @@
 # Firecrawl Integration
 
-> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
-
 Use Firecrawl when an agent needs to research or inspect public websites: direct web answers, landing-page research, competitor structure analysis, migration prep, link extraction, and factual page snapshots. Do not use Firecrawl for private URLs, logged-in websites, or content the user has not asked you to fetch.
 
 Current execution support is `search`, `scrape`, `map`, `crawl`, and `monitor.*`.

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

@@ -1,7 +1,5 @@
 # Integrations
 
-> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
-
 Use integrations to enable external services for a Fimo project. API keys are stored by Fimo and never printed back to the CLI. Teammates and agents receive access to the integration, not the underlying token.
 
 ## Inspect

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

@@ -1,7 +1,5 @@
 # Invite users
 
-> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
-
 Invite collaborators to your Fimo organization or project. After deploying a website for the first time, suggest inviting team members so they can contribute.
 
 ## When to suggest inviting users

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

@@ -1,15 +1,13 @@
 # Labels workflow
 
-> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
-
-> Package contract: run `npx fimo@latest skills get fimo-code --ref labels` for the `t()` contract and key rules, then load the detected framework reference for its label readers.
+> Package contract: run `fimo skills get fimo-code --ref labels` for the `t()` contract and key rules, then load the detected framework reference for its label readers.
 > For locale configuration and route-prefix validation, see **`references/locales.md`**.
 
 This file covers the **CLI workflow** for labels: static UI copy such as nav items, buttons, headings, placeholders, alt text, and SEO strings.
 
 ## What validate does
 
-`fimo validate` scans `src/**/*.{ts,tsx,js,jsx}` for literal `t('key')` calls, including server readers such as `labels.t('key')` (skipping `src/ui` and `node_modules`), and verifies every key has a value in the tenant DB for the default locale.
+`fimo validate` scans `src/**/*.{ts,tsx,js,jsx,svelte}` for literal `t('key')` calls and framework-supported `<Label value="key">` elements (skipping `src/ui` and `node_modules`), then verifies every key has a value in the tenant DB for the default locale.
 
 The database is the source of truth for visible label values. Code declares keys; it does not create visible copy.
 
@@ -55,15 +53,15 @@ Prefer `fimo validate` — this primitive is for narrow debugging/test use.
 
 ## When to run validate
 
-- After adding or changing any `t()` keys in code, run `fimo validate`.
+- After adding or changing any `t()` or `<Label>` keys in code, run `fimo validate`.
 - If validate reports `labels/missing`, add values with `fimo labels set` or `fimo labels set-many`, then run validate again.
 - After renaming/removing keys, clean old DB labels intentionally with `fimo labels delete` when they are no longer used.
 
 ## Workflow
 
-1. Write code with literal `t('key')` calls. Run `npx fimo@latest skills get fimo-code --ref labels` and load the detected framework reference.
+1. Declare literal label keys using the API documented for the detected framework. Run `fimo skills get fimo-code --ref labels` before writing them.
 2. Run `fimo validate`.
 3. Add missing values with `fimo labels set` or `fimo labels set-many`.
 4. Editors can now change copy in the Fimo admin without code changes.
 
-For helper signatures and code patterns, run `npx fimo@latest skills get fimo-code --ref labels` before writing code that uses `t()`.
+For helper signatures and code patterns, run `fimo skills get fimo-code --ref labels` before writing code that uses `t()`.

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

@@ -1,8 +1,6 @@
 # Locales Workflow
 
-> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
-
-This file covers CLI-side locale configuration and validation. For code integration, run `npx fimo@latest skills get fimo-code --ref locales` plus the detected framework's locale reference.
+This file covers CLI-side locale configuration and validation. For code integration, run `fimo skills get fimo-code --ref locales` plus the detected framework's locale reference.
 
 ## Configure Locales
 
@@ -88,7 +86,7 @@ For every framework, the application owns its URL scheme and passes the resolved
 
 Inspect the existing locale provider, route table, switcher, redirects, and public URLs before editing configuration. Preserve working URL behavior during the migration.
 
-Preserve the existing locale provider, router, switcher, redirects, and public URLs. Use framework helpers only when they fit that architecture. Next.js projects run `npx fimo@latest skills get fimo-code --ref frameworks/next/locales`; React Router projects load the React Router setup reference.
+Preserve the existing locale provider, router, switcher, redirects, and public URLs. Use framework helpers only when they fit that architecture. Next.js projects run `fimo skills get fimo-code --ref frameworks/next/locales`; React Router projects load the React Router setup reference; Astro projects run `fimo skills get fimo-code --ref frameworks/astro` and pass the page-resolved locale into server reads and `getLabels`.
 
 ## Labels And Content
 

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

@@ -1,7 +1,5 @@
 # Project MCP
 
-> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
-
 The **Project MCP** lets an AI coding client use Fimo's project workflows through the Model Context Protocol. It is
 the same Fimo tool surface exposed in two ways:
 
@@ -17,13 +15,13 @@ The local and remote Project MCP modes share the same catalog. The public Docs M
 Authenticate the CLI first:
 
 ```bash
-npx fimo@latest login
+fimo login
 ```
 
 Then configure the MCP client to launch:
 
 ```text
-npx fimo@latest mcp
+fimo mcp
 ```
 
 For clients that accept a JSON command configuration, the equivalent entry is:

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

@@ -1,7 +1,5 @@
 # AI media tasks
 
-> **Run via `npx fimo@latest <command>`** so the task catalog and CLI stay aligned.
-
 Use task commands for AI media. The command describes the outcome; Fimo chooses and can change the underlying generation route without changing agent instructions.
 
 ```bash

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

@@ -1,7 +1,5 @@
 # Preview URL (without deploying)
 
-> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
-
 **Use `fimo preview url` whenever you need the current preview link — to open it, screenshot it, hand it to another tool, or verify a change you've already deployed. Never trigger a `fimo deploy` just to refresh a URL.**
 
 `fimo deploy` is a milestone command: it commits, pushes, syncs the sandbox, and only then prints the preview URL. `fimo preview url` skips all of that. It calls the API directly, gets a fresh 15-min token, and prints the URL. No commit, no push, no restart. Sub-second on a warm sandbox.