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

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.
+3. Validation/build generates `src/forms/{name}.ts` (Zod schema, `parseXFormData`, and `submitX` helper). Next.js also gets `{name}.client.ts`; other adapters keep one module. 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,18 +43,18 @@ 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.
 
 ## When to run sync manually
 
-The `fimo/vite` plugin regenerates `src/forms/*.ts` after form JSON changes during development. Before a production build, regenerate explicitly with:
+The `fimo/vite` plugin regenerates legacy Vite `src/forms/*.ts` after form JSON changes during development. Framework-aware generation runs during validation. Before a production build, regenerate explicitly with:
 
 ```bash
 fimo validate                  # runs all phases: codegen, lint, route validation, label checks

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` 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.
+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 astro`, `--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), `nextjs` (App Router), or `sveltekit`. Existing repositories are preserved.                                  |
+| `--framework <framework>`    | no                            | New-project scaffold: `react-router` (default), `astro`, `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,7 +57,7 @@ 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
 
@@ -67,27 +65,29 @@ 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>
+fimo init my-astro-site --framework astro --org <organizationId>
+fimo init my-next-site --framework nextjs --org <organizationId>
+fimo init my-svelte-site --framework sveltekit --org <organizationId>
 ```
 
-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.
+Each shell includes its framework adapter, hosted-preview connector, and
+`.fimo/config.json#runtime.framework`. The Astro shell also includes a minimal
+content-backed example with static, on-demand, and dynamic routes plus an English default locale;
+the other shells 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, Next.js App Router with `--framework nextjs`, or SvelteKit with `--framework sveltekit`
+- The selected project shell: React Router by default, Astro with `--framework astro`, 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
@@ -118,15 +118,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
 
@@ -136,12 +134,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. For SvelteKit, start with `npx fimo@latest skills get fimo-code --ref frameworks/sveltekit`. For Astro, `--ref frameworks/astro` is the single framework reference.
+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:

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,8 +1,6 @@
 # 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.
@@ -61,9 +59,9 @@ Prefer `fimo validate` — this primitive is for narrow debugging/test use.
 
 ## Workflow
 
-1. Declare literal label keys using the API documented for the detected framework. Run `npx fimo@latest skills get fimo-code --ref labels` before writing them.
+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; Astro projects run `npx fimo@latest skills get fimo-code --ref frameworks/astro` and pass the page-resolved locale into server reads and `getLabels`.
+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.

package/assets/skills/fimo-cli/references/project-vars-and-secrets.md

@@ -1,7 +1,5 @@
 # Project Variables And Secrets
 
-> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
-
 Use project variables for values that are safe to expose to the browser. Use project secrets for hidden values such as API keys, tokens, webhooks, and service credentials.
 
 There is no private-variable mode. If leaking the value would be a problem, use `fimo secrets`.

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

@@ -1,14 +1,12 @@
 # Managing projects
 
-> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
-
 Commands for listing projects across an org, cloning a remote project locally, and managing the lifecycle of a single project (delete, publish, unpublish, rename). Most lifecycle commands operate on the **current project** (read from `.fimo/project.json`, or the legacy `.fimo.settings.json`, in the cwd) by default; for `delete`, `publish`, and `unpublish` you can pass an explicit `[projectId]` to target another. (`rename` only edits the linked local project; see below.)
 
 ## The `fimo projects` namespace
 
 ```bash
 fimo projects list [--org <id>]                 # list projects in an org (defaults to active org)
-fimo projects create [dir] [--org <id>] [--framework react-router|nextjs] [--install|--no-install]
+fimo projects create [dir] [--org <id>] [--framework react-router|astro|nextjs|sveltekit] [--install|--no-install]
 fimo projects clone [projectId] [dir] [--env <name>] # clone an existing project locally
 fimo projects delete [projectId] [-C <dir>] [-y] # delete (defaults to current project)
 fimo projects publish [projectId] [-C <dir>]     # make the project live (publish from main)
@@ -29,7 +27,7 @@ fimo projects rename <name> [projectId] [-C <dir>]   # set seo.siteName in the l
 fimo clone [projectId] [dir] [--env <name>] # same as `fimo projects clone`
 ```
 
-Use the top-level shortcut for the common "get this project onto my machine" workflow. After clone succeeds, `cd` into the printed directory, `Read` the project's `AGENTS.md`, and load the code skill with `npx fimo@latest skills get fimo-code` before generating code.
+Use the top-level shortcut for the common "get this project onto my machine" workflow. After clone succeeds, `cd` into the printed directory, `Read` the project's `AGENTS.md`, and load the code skill with `fimo skills get fimo-code` before generating code.
 
 ## Top-level shortcuts (current project)
 

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

@@ -1,7 +1,5 @@
 # Scheduled Commands
 
-> **Run via `npx fimo@latest <command>`** - always the latest CLI, no install needed.
-
 `fimo schedules` manages recurring commands for one project environment. It uses the current checkout environment by default, or the environment passed with `--env <name>`.
 
 The command starts in that environment's sandbox. Commands can still target another environment explicitly, for example with `fimo schemas list --env preview`.

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

@@ -1,7 +1,5 @@
 # Reporting a problem to Fimo
 
-> **Run via `npx fimo@latest <command>`** - always the latest CLI, no install needed.
-
 `fimo support report` sends a project-scoped problem to Fimo support. It automatically includes the project, current environment, and CLI version so support can start investigating without asking the user to repeat that context.
 
 ## When to prepare it

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

@@ -1,7 +1,5 @@
 # Outbound webhooks
 
-> **Run via `npx fimo@latest <command>`** so the event catalog and delivery commands match the platform.
-
 > **Beta:** Test each destination and inspect its delivery history before depending on it in production.
 
 Use `fimo webhooks` to send project events to external HTTPS endpoints. The CLI and Studio edit the same project-wide configurations and delivery history. The CLI has no provider presets: inspect the destination's API documentation, then pass its URL, headers, and JSON body explicitly.

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

@@ -2,7 +2,7 @@
 
 > For the CLI workflow (`fimo forms push`, "Add a contact form" recipe), see **`fimo-cli/references/forms.md`**.
 
-This file covers the **package surface**: the JSON spec you write, the generated Zod schema + `submitX` helper you import, the React patterns. Version-locked to the project's `fimo` package.
+This file covers the **package surface**: the JSON spec, generated Zod schema, `parseXFormData`, and `submitX` helper. Version-locked to the project's `fimo` package. The application owns form markup, actions, routing, locale, and UX.
 
 ## Form JSON spec
 
@@ -43,7 +43,7 @@ This file covers the **package surface**: the JSON spec you write, the generated
 
 ## Generated TS client
 
-After pre-build (or `fimo deploy`), `src/forms/{name}.ts` exists with:
+After `fimo forms push` and the next validation/build, `src/forms/{name}.ts` exists with:
 
 ```ts
 export const FORM_ID = '<uuid>';
@@ -51,20 +51,28 @@ export const ContactUsSchema = z.object({
   /* fields */
 });
 export type ContactUsData = z.infer<typeof ContactUsSchema>;
-export async function submitContactUs(data): Promise<{ success: boolean; errors?: Record<string, string> }>;
+export function parseContactUsFormData(formData: FormData): ContactUsData;
+export function submitContactUs(
+  data: ContactUsData,
+  client?
+): Promise<{
+  success: boolean;
+  status: number;
+  errors?: Record<string, string>;
+}>;
 ```
 
-Re-exported by `src/forms/index.ts`.
+The schema, parser, submitter, and form id are re-exported by `src/forms/index.ts`.
 
-The `submitX` helper handles fetch + file uploads (presigned URLs) automatically. Never hand-roll fetch or validation.
+The `submitX` helper uses the framework adapter's shared Fimo transport and handles presigned file uploads automatically. Never hand-roll the Fimo API fetch or validation.
 
-## React code pattern
+## Common code pattern
 
-Always import from `@/forms/{name}` — never hand-roll fetch, never hand-roll validation.
+Always import the generated module. Keep the native form and pending/error state in the framework's normal pattern:
 
 ```tsx
 import { useState } from 'react';
-import { ContactUsSchema, submitContactUs } from '@/forms/contact-us';
+import { ContactUsSchema, parseContactUsFormData, submitContactUs } from '@/forms/contact-us';
 import type { ContactUsData } from '@/forms/contact-us';
 
 export function ContactForm() {
@@ -76,8 +84,7 @@ export function ContactForm() {
     setErrors({});
     setLoading(true);
 
-    const raw = Object.fromEntries(new FormData(e.currentTarget));
-    const parsed = ContactUsSchema.safeParse(raw);
+    const parsed = ContactUsSchema.safeParse(parseContactUsFormData(new FormData(e.currentTarget)));
     if (!parsed.success) {
       const fieldErrors: Record<string, string> = {};
       for (const issue of parsed.error.issues) fieldErrors[issue.path[0] as string] = issue.message;
@@ -97,6 +104,13 @@ export function ContactForm() {
 
 **File fields**: pass the raw `File` from `<input type="file">` to `submitX` — it handles the presigned upload automatically. **Never base64-encode.**
 
+## Framework bindings
+
+- **Vite/React:** `submitX(data)` keeps using the existing `fimo/ui` runtime and preserves the current generated API.
+- **Next.js:** server modules import `@/forms/name`; client components import `@/forms/name.client`. Both expose the same `submitX(data)` shape.
+- **Astro:** import the generated server module and call `submitX(data)` in an Astro action or endpoint. Astro keeps the HTML form and redirect.
+- **SvelteKit:** use `createFimoFormClient({ event })` in a server action and pass it as the second argument: `submitX(data, client)`.
+
 ## Labels and copy
 
 Wrap every visible string in `t('key')` and create the DB value with `fimo labels set` — see `references/labels.md`. This includes form labels, placeholders, button text, success/error messages.

package/assets/skills/fimo-code/references/frameworks/astro.md

@@ -75,6 +75,15 @@ const [settings, stories, labels] = await Promise.all([
 
 The native surface is `Text`, `RichText`, `Image`, `StaticImage`, `Video`, `Date`, `Boolean`, and `Json` (component table: `references/ui.md`). Pass tracked values whole so Studio can resolve their source; use `String(value)` only for attributes and URLs.
 
+## Forms
+
+Generated forms use the native Astro server adapter. Keep the form element,
+action, redirect, and error UI in Astro; call `submitX(data)` from an Astro
+action or endpoint. Use `parseXFormData(new FormData(request))` to normalize
+browser values before submitting. Do not import the server form module into a
+client island; add a project endpoint if the form is intentionally browser-
+submitted.
+
 ## Static and on-demand rendering
 
 Keep the application's per-route rendering choice:

package/assets/skills/fimo-code/references/frameworks/next.md

@@ -82,6 +82,31 @@ Never write the registry by hand and never create alternate `*.schema.json` file
 
 ## Server and client boundaries
 
+Forms follow the same boundary. Server actions and route handlers import the
+generated server form module; a Client Component imports its generated
+`.client.ts` module. Both expose `submitX(data)` and use the shared Fimo form
+transport; do not call the tenant API directly.
+
+```tsx
+'use client';
+
+import { parseContactUsFormData, submitContactUs } from '@/forms/contact-us.client';
+
+export function ContactForm() {
+  return (
+    <form
+      action={async (formData) => {
+        await submitContactUs(parseContactUsFormData(formData));
+      }}
+    >
+      <input name="email" type="email" required />
+      <textarea name="message" required />
+      <button type="submit">Send</button>
+    </form>
+  );
+}
+```
+
 Server Components, route handlers, `getStaticProps`, and `getServerSideProps` import from `fimo/next` and generated server modules:
 
 ```ts

package/assets/skills/fimo-code/references/frameworks/sveltekit.md

@@ -59,17 +59,28 @@ export async function load(event) {
 }
 ```
 
-Resolve the locale with the application's existing policy, then fetch labels in
-the root server layout and publish the snapshot to descendants:
+Pass `createFimo` the locale the application resolved. Omit it and Fimo sends
+`.fimo/config.json#i18n.defaultLocale`, or no locale at all when none is
+configured, so the API answers with the project default. Never hardcode a locale
+to satisfy the signature.
+
+`getLabels` follows the same rule: pass the locale the application resolved, or
+omit it and the API answers with the project default, whose locale the returned
+snapshot reports. Fetch labels in the root server layout and publish the
+snapshot to descendants. Fimo resolves its injected content API URL internally;
+do not import a Fimo environment variable or hardcode a tenant URL:
 
 ```ts
 // src/routes/+layout.server.ts
-import { env } from '$env/dynamic/public';
 import { getLabels } from 'fimo/sveltekit';
 
 export async function load(event) {
-  const locale = 'en'; // replace with the application's resolved locale
-  return { labels: await getLabels({ apiUrl: env.PUBLIC_FIMO_API_URL, event, locale }) };
+  // If the app resolves a locale from its URL or session, pass it:
+  // const locale = resolveLocale(event.url); // your app's resolver
+  // return { labels: await getLabels({ event, locale }) };
+
+  // Otherwise, omit it and use the Fimo project default.
+  return { labels: await getLabels({ event }) };
 }
 ```
 
@@ -94,6 +105,23 @@ component that renders them. Use `Text`, `RichText`, `Image`, `Video`, `Date`,
 formats plain numeric values for display; numeric fields currently have no
 source metadata, so it is not a Studio-editable primitive.
 
+## Forms
+
+Use a `+page.server` action so SvelteKit owns the request and redirect. Pass its
+event to `createFimoFormClient` and use the generated parser/helper:
+
+```ts
+import { createFimoFormClient } from 'fimo/sveltekit';
+import { parseContactUsFormData, submitContactUs } from '$lib/forms/contact-us';
+
+export const actions = {
+  default: async (event) => {
+    const data = parseContactUsFormData(await event.request.formData());
+    return submitContactUs(data, createFimoFormClient({ event }));
+  },
+};
+```
+
 ## Live preview
 
 `FimoProvider` owns the Studio browser bridge. On mount it reads

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

@@ -41,7 +41,7 @@ The label contract is shared; acquisition differs by runtime:
 - Next server: `getLabels({ locale? })` from `fimo/next`.
 - Next client: `useLabels()` from `fimo/next/client`, under `FimoProvider`.
 - React Router/Vite client: `Label` and `useLabels()` from `fimo/ui`, under the existing framework integration.
-- SvelteKit: resolve the locale in the root server load and return `getLabels({ apiUrl, event, locale })`. Wrap the root layout with `FimoProvider` from `fimo/sveltekit/components`; the snapshot supplies its locale. Descendants use `Label` from that entrypoint or `useLabels().t()` from `fimo/sveltekit`. Pass the same resolved locale to `createFimo({ content, event, locale })` in content loads.
+- SvelteKit: pass the application's resolved locale to `getLabels({ apiUrl, event, locale })`, or omit it to let the API choose the project default. Wrap the root layout with `FimoProvider` from `fimo/sveltekit/components`; the snapshot supplies its locale. Descendants use `Label` from that entrypoint or `useLabels().t()` from `fimo/sveltekit`. Apply the same explicit-or-omitted rule to `createFimo({ content, event, locale? })` in content loads.
 - Astro server page: `getLabels({ locale? })` from `fimo/astro`; no provider.
 
 Load the matching framework reference before choosing a provider or server reader.