fimo 0.3.1 → 0.3.2-experimental.1783354419249

package/README.md

@@ -17,28 +17,22 @@
 
 ## Usage
 
-Install the CLI:
+Run the CLI with `npx` — no global install, always the latest:
 
 ```bash
-npm i -g fimo
-```
-
-Log in and scaffold a new project:
-
-```bash
-fimo login
-fimo create my-site
+npx fimo@latest login
+npx fimo@latest init my-site
 cd my-site
 ```
 
-`fimo create` sets up the project, pushes the first commit, and wires it to your Fimo account. Open it in your coding agent and start building.
+Every command runs the same way: **`npx fimo@latest <command>`**. `fimo init` sets up the project, pushes the first commit, and wires it to your Fimo account. Open it in your coding agent and start building.
 
 ## AI coding tools
 
-Fimo ships skills and rules for your AI coding tools (Claude Code, Cursor, Codex, Gemini, and more) so the agent knows how to work in a Fimo project. `fimo create` installs them for you — add or refresh them any time:
+Fimo ships skills and rules for your AI coding tools (Claude Code, Cursor, Codex, Gemini, and more) so the agent knows how to work in a Fimo project. `fimo init` installs them for you — add or refresh them any time (`--mode=copy` is required under npx):
 
 ```bash
-fimo skills install
+npx fimo@latest skills install --mode=copy
 ```
 
 ## Local development

package/assets/agents-starter/AGENTS.md

@@ -31,10 +31,22 @@ fimo skills install                   # interactive: pick agents to add
 
 If you later edit this `AGENTS.md` and want the per-agent variants (`CLAUDE.md`, `.cursor/rules/fimo.mdc`, `.windsurfrules`, `GEMINI.md`) regenerated from it, delete the stale variant file and run `fimo rules sync`. Sync is purely additive — it never overwrites existing files, so project-specific edits are preserved unless you remove the file first.
 
+## Development loop
+
+Work with the developer locally, not through deploys:
+
+1. Start the app with the project's package-manager `dev` script — `pnpm dev`, `npm run dev`, `yarn dev`, or `bun dev` (match the lockfile). Run it in the background; it serves the site on localhost with live reload.
+2. Ask the developer what they want to build or change.
+3. Make the edits — the running dev server shows them instantly. You do not need to deploy to see local changes.
+4. Iterate until they are happy with it locally.
+5. When a unit of work looks done, **offer** to deploy: `fimo deploy` for a hosted preview / shareable link, or `fimo deploy --publish` to go live. Run it only after they confirm (or when they ask). Never deploy on your own.
+
+The local dev server is local (localhost). The Fimo dashboard preview and the shareable preview URL come from `fimo deploy` — so if the developer wants to see it in the dashboard or share a link, that needs a deploy.
+
 ## Critical project rules
 
-- **Deploy at meaningful milestones, not after every edit.** `fimo deploy` commits everything, pushes to `main`, and round-trips the sandbox — it's a finishing step, not a save step. For initial site generation, run it once at the end when the site is complete. For follow-up work, batch related edits and deploy when the user-visible unit of work is done.
-- **Run `fimo deploy --publish` only when the user signals "ship it"** — first-time site completion or an explicit "publish" / "go live" request. Plain `fimo deploy` (preview) is the right default; `--publish` is the visible, externally-facing step.
+- **Deploy is on-demand — not a save step and not a mandatory final step.** `fimo deploy` commits everything, pushes to the current env's branch, and round-trips the sandbox. Iterate locally with the dev server; deploy only when the developer wants a hosted preview, a shareable link, or to go live — and only after they confirm. Batch related edits into one deploy; never deploy after every change.
+- **Run `fimo deploy --publish` only when the developer signals "ship it"** — an explicit "publish" / "go live" request. Plain `fimo deploy` (preview) is the default; `--publish` is the visible, externally-facing step.
 - Do not add a second deploy tool (Vercel, Netlify, etc.).
 - **Never edit `.fimo.settings.json`.** It is the link between this folder and the remote project — it is written once by `fimo create`.
 - The scaffolded homepage is disposable starter content. On the first real generation, replace its copy, layout, and visual style instead of extending the Fimo-branded design. Keep only the technical shell and required legal pages unless the user explicitly asks to preserve the starter.

package/assets/skills/fimo/SKILL.md

@@ -14,7 +14,7 @@ You are writing code in a Fimo project — a content + media + forms + analytics
 
 This skill is version-locked to this project's installed `fimo` package — the shapes here match what your code can actually use.
 
-For CLI commands and workflows (creating a project, pushing schemas/forms, deploying, managing labels, etc.), the **`fimo-cli`** skill is the source of truth. If `fimo-cli` isn't loaded for your AI tool, run `fimo skills install` to register it.
+For CLI commands and workflows (creating a project, pushing schemas/forms, deploying, managing labels, etc.), the **`fimo-cli`** skill is the source of truth. Run every CLI command as `npx fimo <command>` when the project declares a `fimo` dependency (it pins the version matching the project's backend); otherwise use `npx fimo@latest`. If `fimo-cli` isn't loaded for your AI tool, register it with `npx fimo skills install --mode=copy`.
 
 ## Critical: NEVER hardcode user-facing things
 

package/assets/skills/fimo/references/content.md

@@ -12,7 +12,6 @@ This file covers the **package surface**: the JSON shape you write, the generate
   "name": "Blog Posts",
   "fields": {
     "title": { "type": "string" },
-    "slug": { "type": "string" },
     "body": { "type": "richtext" },
     "publishDate": { "type": "string" },
     "featured": { "type": "boolean" },
@@ -24,11 +23,24 @@ This file covers the **package surface**: the JSON shape you write, the generate
 
 **Required**: `uid` (PascalCase, matches filename), `name`, `fields`.
 
+### Reserved field names — do NOT declare these in `fields`
+
+Every entry already carries this metadata automatically. Declaring any of them as a
+schema field is rejected by `fimo schemas push` with a 400 (e.g. `fields.slug: "slug" is
+reserved entry metadata and cannot be used as a content field.`):
+
+`id`, `documentId`, `slug`, `locale`, `createdAt`, `updatedAt`, `__fimo`.
+
+In particular **do not add a `slug` field** — every entry gets a `slug` for free. You still
+pass `slug` inside `data` when *creating an entry* (see "Entry body shape" below); it just
+must not appear in the schema's `fields`. If you need an additional URL-ish string, name it
+something else (e.g. `handle`, `permalink`).
+
 ## Field types
 
 | Type       | `data` JSON shape                                                       | Use for                           |
 | ---------- | ----------------------------------------------------------------------- | --------------------------------- |
-| `string`   | `"..."`                                                                 | Titles, slugs, short text         |
+| `string`   | `"..."`                                                                 | Titles, short text                |
 | `richtext` | Tiptap JSONContent (see below)                                          | Blog body, descriptions, articles |
 | `number`   | `42`                                                                    | Counts, quantities                |
 | `boolean`  | `true` / `false`                                                        | Flags                             |

package/assets/skills/fimo/references/setup-plain-vite.md

@@ -17,7 +17,7 @@ so this layout is what those projects look like now.
 ## Prerequisites
 
 - Node 20+
-- A Fimo project created via `fimo create`.
+- A Fimo project created via `fimo init`.
 
 ## Install
 
@@ -195,9 +195,14 @@ framework-mode project that `reactRouter()` plugin is added by your own
 }
 ```
 
-## Verify
+## Verify and iterate
 
-Run `pnpm dev`. The dashboard's preview iframe should load the running app.
+Run the app with the project's package-manager `dev` script (`pnpm dev` /
+`npm run dev` / `yarn dev` / `bun dev` — match the lockfile). It serves the site
+on localhost with live reload — this is your iteration loop: edit, see the change,
+repeat with the developer. `fimo deploy` is on-demand (hosted preview / shareable
+link / go live), run only on the developer's signal; the dashboard's preview iframe
+shows the **deployed** app, not the localhost dev server.
 
 ## Known limitations vs. React Router
 

package/assets/skills/fimo/references/setup-react-router.md

@@ -1,13 +1,13 @@
 # Setup Fimo on React Router 7
 
 This recipe describes the canonical Fimo + React Router framework-mode setup.
-It mirrors what `fimo create` scaffolds today; you can also apply it to an
+It mirrors what `fimo init` scaffolds today; you can also apply it to an
 existing RR project.
 
 ## Prerequisites
 
 - Node 20+
-- A Fimo project created via `fimo create` (gives you `projectId`,
+- A Fimo project created via `fimo init` (gives you `projectId`,
   `organizationId`, and an `apiUrl`).
 
 ## Install
@@ -206,7 +206,7 @@ export default function HomePage() {
 ```
 
 Replace the `__PROJECT_ID__` / `__ORG_ID__` / `__API_URL__` sentinels with the
-values from `fimo create`'s output (or `fimo projects info`).
+values from `fimo init`'s output (or `fimo projects info`).
 
 ## File: `tsconfig.json`
 
@@ -239,10 +239,17 @@ values from `fimo create`'s output (or `fimo projects info`).
 (Optional — only if using Tailwind. Tailwind is not required for Fimo to
 function; it just ships with the canonical template.)
 
-## Verify
+## Verify and iterate
 
-Run `pnpm dev`. The dashboard's preview iframe should load the running app.
-Run `fimo deploy` to push the project state.
+Run the app with the project's package-manager `dev` script (`pnpm dev` /
+`npm run dev` / `yarn dev` / `bun dev` — match the lockfile). It serves the site
+on localhost with live reload — this is your iteration loop: edit, see the change,
+repeat with the developer.
+
+`fimo deploy` is on-demand, not part of this loop: run it only when the developer
+wants a hosted preview, a shareable link, or to go live — and only on their signal.
+The dashboard's preview iframe shows the **deployed** app, so it only reflects
+changes after a `fimo deploy` (the local dev server is localhost-only).
 
 ## What you don't add
 

package/assets/skills/fimo/references/ui.md

@@ -60,7 +60,7 @@ The template uses **Vite + React 19 + TypeScript + Tailwind v4 + shadcn/ui + rea
 
 ### Starter replacement
 
-- `src/pages/Index.tsx` is disposable scaffold so a fresh `fimo create` project renders immediately.
+- `src/pages/Index.tsx` is disposable scaffold so a fresh `fimo init` project renders immediately.
 - **On the first real website generation, replace that starter page's copy, layout, and visual system entirely** instead of decorating the existing Fimo-branded design.
 - Reuse only the app shell, route contracts, and legal pages unless the user explicitly wants the starter aesthetic.
 

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

@@ -17,6 +17,12 @@ This skill describes **what the CLI does and the workflows it drives**. For the
 
 Use `fimo <command> --help` for full flag details on any command.
 
+## Running the CLI: always `npx fimo@latest`
+
+Run every command as **`npx fimo@latest <command>`**. It always fetches the latest CLI — no install, nothing to keep up to date, and it can't fall behind and get blocked. Do **not** install `fimo` globally.
+
+The examples in this skill and its references write `fimo <command>` for brevity — mentally prefix them with `npx fimo@latest`. (One exception, because npx has no stable package path to symlink into: install skills with `npx fimo@latest skills install --mode=copy`.)
+
 ## Output for agents: `--json` is the stable contract
 
 Every command accepts a global `--json` flag (or `FIMO_OUTPUT=json` env) and emits exactly one structured envelope on stdout:
@@ -32,7 +38,7 @@ For shell composition use plain pretty mode (`cd $(fimo …)`); for structured p
 
 ## Critical: `.fimo.settings.json` is the project link
 
-A Fimo project is identified by `.fimo.settings.json` at its root, written once by `fimo create`. This file connects the local directory to the remote Fimo project. **Never edit it manually.** Most CLI commands look at this file in the cwd to know which project they operate on.
+A Fimo project is identified by `.fimo.settings.json` at its root, written once by `fimo init`. This file connects the local directory to the remote Fimo project. **Never edit it manually.** Most CLI commands look at this file in the cwd to know which project they operate on.
 
 ## Critical: commands target the env of the current git branch
 
@@ -41,25 +47,28 @@ A project can have multiple **envs** — each is a git branch _plus_ its own DB,
 ## Quick Start
 
 ```bash
-npm i -g fimo                              # install the CLI globally
-fimo login                                 # authenticate via browser
-fimo skills install                        # install Fimo skills for your AI tools
-fimo create my-site --org <id>             # scaffold (writes .fimo.settings.json + AGENTS.md + project skill). Use the org **id** from `fimo orgs list`, NOT the slug.
-fimo clone                                 # interactively choose an existing project to clone locally
-cd my-site                                 # the `fimo` project skill auto-loads from here
-fimo credits                               # inspect the owning org's AI credit balance (read-only)
-fimo validate                              # run all checks + codegen; fails on missing DB labels
-fimo deploy                                # push to preview (runs validate internally)
-fimo deploy --publish                      # publish live (only when user says "ship it")
+npx fimo@latest login                          # authenticate via browser
+npx fimo@latest skills install --mode=copy     # install Fimo skills for your AI tools (copy mode: required under npx)
+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 --project-id <id> my-site # link an EXISTING project instead of creating one
+npx fimo@latest clone                          # interactively choose an existing project to clone locally
+cd my-site                                     # the `fimo` project skill auto-loads from here
+pnpm dev                                       # run the app locally (use the project's PM: pnpm/npm run/yarn/bun) — your iteration loop
+npx fimo@latest credits                        # inspect the owning org's AI credit balance (read-only)
+npx fimo@latest validate                       # run all checks + codegen; fails on missing DB labels
+npx fimo@latest deploy                         # ON-DEMAND: hosted preview / shareable link (runs validate internally)
+npx fimo@latest deploy --publish               # ON-DEMAND: publish live (only when the developer says "ship it")
 ```
 
+The working loop is local: run the app with the project's package-manager `dev` script (`pnpm dev` / `npm run dev` / `yarn dev` / `bun dev` — match the lockfile), ask the developer what they want, edit, and iterate against the live localhost server. `fimo deploy` is **not** a required final step — reach for it only when the developer wants a hosted preview, a shareable link, or to go live, and only on their signal (see `references/deploy.md`).
+
 `fimo validate` is the single entrypoint for "prove this project is ready" — it covers schema/form codegen, route metadata checks, lint, and missing label checks for `i18n.defaultLocale` from `fimo-config.json` (fallback: `en`). Use `fimo labels set` / `set-many` to create or update label values in the DB. The underlying phases are also available individually under the hidden `fimo scripts` namespace for advanced/debug use.
 
 ## Decision Tree
 
 Load the matching reference when the user's request fires its trigger. Recipes that involve writing code also need the `fimo` skill's package references — they're called out where relevant.
 
-- "Create a new Fimo project / scaffold a site / start a new website" → `references/create.md`
+- "Create a new Fimo project / scaffold a site / start a new website / link an existing project locally" → `references/init.md`
 - "Add a content type / blog / products / pages / CMS" → `references/content.md` (workflow) **+ load `fimo/references/content.md` for the JSON shape and React hooks**
 - "Add a contact / signup / feedback / newsletter form" → `references/forms.md` (workflow) **+ load `fimo/references/forms.md` for the JSON spec and generated client**
 - "View form submissions / who filled out the contact form / inspect what users sent / how many signups" → `references/forms.md` § Reading submissions
@@ -94,10 +103,12 @@ Load the matching reference when the user's request fires its trigger. Recipes t
 
 These fire at specific moments in the project lifecycle. **Surface them proactively** rather than waiting for the user to ask:
 
-- **Right after `fimo create`** → `cd` into the new directory, then `Read` the project's `AGENTS.md` (or `CLAUDE.md` for Claude Code) **and** `.claude/skills/fimo/SKILL.md` (or `.cursor/skills/fimo/SKILL.md` etc. for other agents) to load the project context before generating any code. The new files came into existence mid-session and may not be auto-loaded by the harness. See `references/create.md` § Load the project context.
-- **Right after `fimo create`** → suggest `fimo rename "<Display Name>"` to set a human-readable name (the default post-create name is an auto-generated slug). Infer the name from what the user is building (e.g. "Acme Coffee" for a café, "Jane Doe Portfolio" for a personal site). See `references/create.md`.
-- **Right after `fimo create` (or at session start in an existing project), if you plan to deploy at some point** → run `fimo deploy -m "chore: init" &` in the background. Pays the one-time ~15-30s provision + dep install cost up front so your final deploy lands warm in ~4-10s. **You still need to `fimo deploy` at the end** with the generated code so the user has a preview to look at. See `references/deploy.md` § Warm the sandbox early in a session.
-- **Iterative code-only deploys** → consider `fimo deploy --no-restart` to skip the sandbox dev-server restart on HMR-safe edits. See `references/deploy.md` § Skipping the dev-server restart for when it's safe.
+- **Right after `fimo init`** → `cd` into the new directory, then `Read` the project's `AGENTS.md` (or `CLAUDE.md` for Claude Code) **and** `.claude/skills/fimo/SKILL.md` (or `.cursor/skills/fimo/SKILL.md` etc. for other agents) to load the project context before generating any code. The new files came into existence mid-session and may not be auto-loaded by the harness. See `references/init.md` § Load the project context.
+- **Right after `fimo init`** → suggest `fimo rename "<Display Name>"` to set a human-readable name (the default post-init name is an auto-generated slug). Infer the name from what the user is building (e.g. "Acme Coffee" for a café, "Jane Doe Portfolio" for a personal site). See `references/init.md`.
+- **Right after `fimo init`** → start the app locally with the project's package-manager `dev` script (`pnpm dev` / `npm run dev` / `yarn dev` / `bun dev`) in the background, then ask the developer what they want to build. This localhost server with live reload is your iteration loop — edit, show, repeat. No deploy is needed to see local changes.
+- **When a user-visible unit of work looks done** → **offer** to deploy (`fimo deploy` for a hosted preview / shareable link, `fimo deploy --publish` to go live) and run it only after the developer confirms — or immediately if they ask. Never deploy on your own. See `references/deploy.md`.
+- **Optional, if you already know a deploy is coming** → warm the sandbox early with `fimo deploy -m "chore: init" &` in the background so the one-time ~15-30s provision + dep install happens while you work and the real deploy lands warm (~4-10s). This is a perf optimization, not a requirement. See `references/deploy.md` § Warm the sandbox early in a session.
+- **Iterative code-only deploys** → once you are deploying, `fimo deploy --no-restart` skips the sandbox dev-server restart on HMR-safe edits. See `references/deploy.md` § Skipping the dev-server restart for when it's safe.
 - **You need the current preview URL but haven't changed code** (opening it, screenshotting it, handing it to another tool, the previous URL expired) → `fimo preview url`, never a no-op `fimo deploy`. See `references/preview.md`.
 - **When the user wants to try something risky / explore a redesign without touching the live site** → suggest a feature env: `fimo checkout -b <name>` gives an isolated branch + DB + preview. Deploy previews there, then `fimo merge` it back and `fimo publish`. See `references/branches.md`.
 - **After the first successful `fimo deploy`** → suggest `fimo invite` if the project involves multiple people. Typical roles: `edit` for developers/content editors, `view` or `comment` for clients/stakeholders, `full` for project leads. See `references/invite.md`.
@@ -106,10 +117,11 @@ These fire at specific moments in the project lifecycle. **Surface them proactiv
 ## Anti-Patterns
 
 - **Editing `.fimo.settings.json`** — read-only; it's the link between local and remote project. Treat as a generated file.
-- **Running `fimo deploy` after every change** — it's a milestone command (commits + pushes + sandbox round-trip), not a save step. Batch related work and deploy at logical breakpoints. See `references/deploy.md`.
+- **Treating `fimo deploy` as the working loop or a required final step** — the loop is local (`pnpm dev` etc.). Deploy commits + pushes + round-trips the sandbox; it's for hosted previews / going live, on-demand. Iterate locally and deploy at logical breakpoints. See `references/deploy.md`.
+- **Deploying without the developer asking or confirming** — offer, then wait for their yes. Don't auto-deploy after finishing an edit.
 - **Running `fimo deploy` just to get a fresh preview URL** — that's a commit + push + sandbox sync for what should be a sub-second read. Use `fimo preview url` instead. See `references/preview.md`.
 - **Using `fimo deploy --publish` casually** — `--publish` makes the site live to the public. Plain `fimo deploy` (preview) is the default. Use `--publish` only when the user says "ship it" / "go live" / "publish".
-- **Bare `fimo create` in a non-interactive shell** — will hang. Always pass `--org`, `--no-install`, and `--agents` explicitly when scripted.
+- **Bare `fimo init` in a non-interactive shell** — will hang. Always pass `[dir]`, `--no-install` (or `--install`), `--no-skills` (or `--skills`), and `--org`/`--agents` as needed explicitly when scripted.
 - **Hardcoding content / strings / images in code** — that's what schemas, `t()`, and the media library are for. See the `fimo` skill's anti-patterns.
 - **Adding another deploy tool (Vercel, Netlify, Cloudflare Pages)** — Fimo handles deploys; don't bolt another platform on.
 - **Committing secrets** — hidden values use `fimo secrets`; public browser-safe values use `fimo vars`. Local env files are ignored and must not become deploy inputs.

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

@@ -1,5 +1,7 @@
 # Account, authentication, and organizations
 
+> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
+
 The `fimo` CLI authenticates against the Fimo platform via a browser-based flow. Credentials are stored **per backend** at `~/.config/fimo/credentials/<host>-<hash>.json` (so a localhost dev backend and production don't clobber each other) and used by every CLI command that talks to the Fimo API.
 
 ## Sign in
@@ -17,7 +19,7 @@ fimo logout       # revoke the current session and clear local credentials
 
 ## Organizations
 
-A Fimo account belongs to one or more organizations. Every project lives inside an organization. The "active organization" is the default for `fimo create` and other org-scoped commands.
+A Fimo account belongs to one or more organizations. Every project lives inside an organization. The "active organization" is the default for `fimo init` and other org-scoped commands.
 
 ```bash
 fimo orgs list                       # list orgs you belong to
@@ -45,5 +47,5 @@ fimo referral stats       # show your referral stats
 
 ## Notes for AI tools / scripted use
 
-- `--org` (with explicit id or slug) is required in non-TTY shells for `fimo create` only when you have no active org and belong to multiple orgs; it's always required for `fimo orgs switch` in non-TTY. If an active org is stored, or you belong to exactly one org, `fimo create` resolves the org without `--org`.
+- `--org` (with explicit id or slug) is required in non-TTY shells for `fimo init` (create-new) only when you have no active org and belong to multiple orgs; it's always required for `fimo orgs switch` in non-TTY. If an active org is stored, or you belong to exactly one org, `fimo init` resolves the org without `--org`.
 - Never hardcode tokens in command flags. The per-backend credentials files written by `fimo login` (`~/.config/fimo/credentials/`) are the canonical store.

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

@@ -1,5 +1,7 @@
 # AI agent setup
 
+> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
+
 Fimo wires up to AI coding tools in three layers:
 
 1. **Global skills** — `fimo-cli`, `fimo-studio`, and `fimo-migration` skills installed once per user, machine-wide. They describe the CLI workflows, the Fimo Studio web app, and URL/source-backed migrations, and load in any compatible AI tool.
@@ -11,24 +13,20 @@ Two CLI namespaces manage all three:
 - `fimo skills install / sync / uninstall` — skill artifacts (layers 1 + 3)
 - `fimo rules sync` — rule files (layer 2)
 
-## Install the CLI
+## Set up skills (no install needed)
 
-Prefer a global CLI install for setup:
+Run the CLI via `npx fimo@latest` — do not install `fimo` globally. To set up the Fimo skills for your AI tools, use **copy mode** (npx runs from an ephemeral cache with no stable package path to symlink into):
 
 ```bash
-npm install -g fimo
+npx fimo@latest skills install --mode=copy
 ```
 
-When the install is interactive, Fimo asks whether to install skills for your AI coding tools and then runs the same `fimo skills install` picker. Non-interactive installs print the manual command instead.
-
-`npx fimo@latest <command>` is useful for one-off commands. For skill setup, a global install is better because the default symlink mode points skills at a stable package path. If you use `npx` for skills, copy the files instead:
+This opens the agent picker and installs everything that applies (see below). Then connect your account when you are ready:
 
 ```bash
-npx fimo@latest skills install --mode=copy
+npx fimo@latest login
 ```
 
-After installation, run `fimo login` when you are ready to connect a Fimo account.
-
 ## `fimo skills` — install + sync + uninstall
 
 ```bash
@@ -36,7 +34,7 @@ fimo skills install                            # interactive: pick agents, insta
 fimo skills install --agents=claude-code,cursor   # explicit list
 fimo skills install -a claude-code -a cursor      # repeatable form
 fimo skills install --agents=claude-code --yes    # skip the install preview prompt (headless / scripts)
-fimo skills install --mode=copy                # opt out of symlinks (default is symlink)
+fimo skills install --mode=copy                # copy files instead of symlinking (required under npx)
 fimo skills sync                               # refresh installed skills (global + project, where applicable)
 fimo skills uninstall                          # remove the global skills
 ```
@@ -59,8 +57,8 @@ The command prints exactly which files were written, so the context-aware behavi
 
 You rarely have to invoke it by hand:
 
-- **Global skills auto-refresh** after a CLI version change via a marker at `~/.config/fimo/last-version`.
-- **The project skill auto-refreshes during Fimo-controlled installs** when the `fimo` package version bumps — the package's postinstall hook re-syncs the skill from `node_modules/fimo/assets/skills/fimo/` (which is version-locked to the installed package). For pnpm, `fimo create --install`, sandbox `fimopm install`, and E2E helper installs pass a scoped allow-all-builds flag so the hook can run without persisting build-script approvals in the template. npm / yarn run lifecycle scripts by default and need no extra config.
+- **Global skills auto-refresh** whenever a newer CLI runs — any `npx fimo@latest …` command detects a version change (marker at `~/.config/fimo/last-version`) and re-copies the latest skills.
+- **The project skill auto-refreshes during Fimo-controlled installs** when the `fimo` package version bumps — the package's postinstall hook re-syncs the skill from `node_modules/fimo/assets/skills/fimo/` (which is version-locked to the installed package). For pnpm, `fimo init --install`, sandbox `fimopm install`, and E2E helper installs pass a scoped allow-all-builds flag so the hook can run without persisting build-script approvals in the template. npm / yarn run lifecycle scripts by default and need no extra config.
 
 Invoke `fimo skills sync` explicitly when iterating on skill content locally, when you bumped the package via something other than a fresh install, or any time you want to force a refresh.
 
@@ -68,7 +66,7 @@ Invoke `fimo skills sync` explicitly when iterating on skill content locally, wh
 
 ## `fimo rules sync` — rule files only
 
-`fimo create` writes `AGENTS.md` (the universal-spec file) and per-agent variants for the AI tools you selected. Variants and their generators:
+`fimo init` writes `AGENTS.md` (the universal-spec file) and per-agent variants for the AI tools you selected. Variants and their generators:
 
 | Agent                             | File(s) generated                     |
 | --------------------------------- | ------------------------------------- |
@@ -101,8 +99,8 @@ Every command that takes agents accepts the same selection inputs:
 - No flag → interactive multi-select. The picker has two sections:
   - **Universal** — agents that read `AGENTS.md` natively (codex, opencode, aider, …). Always covered, not toggleable.
   - **Additional** — agents that need a per-agent rule file or skills dir. The 6 popular ones (`claude-code`, `cursor`, `codex`, `opencode`, `windsurf`, `gemini-cli`) appear at the top of an 8-item scrollable viewport; the full list of 50+ supported agents is below the fold. Each row shows the install path next to the name (e.g. `Claude Code (.claude/skills)`). Agents already present on the machine are pre-checked.
-- `--agents=none` (only `fimo create`) — skip per-agent variants entirely; write only `AGENTS.md`.
-- `--mode=symlink|copy` (only `fimo skills install` and `fimo create`) — pick the install method for the per-agent skills layer. Defaults to symlink so the canonical `.agents/skills/<name>/` is the single source of truth; pass `--mode=copy` to materialize the skill in each per-agent dir.
+- `--agents=none` (only `fimo init`) — skip per-agent variants entirely; write only `AGENTS.md`.
+- `--mode=symlink|copy` (only `fimo skills install` and `fimo init`) — pick the install method for the per-agent skills layer. Defaults to symlink so the canonical `.agents/skills/<name>/` is the single source of truth; pass `--mode=copy` to materialize the skill in each per-agent dir.
 
 In headless contexts (CI, AI-tool-spawned commands), pass the flag explicitly. Env-var detection (only Claude Code's `CLAUDECODE` / `CLAUDE_CODE_ENTRYPOINT`) silently targets `claude-code` if the flag is omitted; every other agent must be named explicitly with `--agents` in a headless shell, or the command exits with "No agents detected and no --agents flag passed."
 
@@ -117,4 +115,4 @@ Every installed `SKILL.md` (global or project) is stamped with `fimoVersion: <cl
 - "The agent doesn't know about my project's latest fimo conventions" → `fimo skills sync`
 - "I edited `AGENTS.md` and want variants regenerated" → delete the stale variant + `fimo rules sync`
 - "I'm done with Fimo on this machine" → `fimo skills uninstall`
-- For a fresh project, `fimo create` wires up everything for the AI tools you select at scaffold time.
+- For a fresh project, `fimo init` wires up everything for the AI tools you select at scaffold time.

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

@@ -1,5 +1,7 @@
 # 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>/agents/<name>/` (a `config.yaml`, a `GOAL.md`, optional `capabilities.yaml`, etc.).
 
 ## Mental model

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

@@ -1,5 +1,7 @@
 # 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,5 +1,7 @@
 # Assets workflow (media library)
 
+> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
+
 > For how to plug returned media into UI components (`FimoMedia` shape, `<Image>` integration), see **`fimo/references/assets.md`** and **`fimo/references/ui.md`**.
 > For **generating** new images / videos with AI, see **`references/media.md`** — the `fimo generate <model>` surface is documented there.
 

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

@@ -1,5 +1,7 @@
 # Envs & branches (git-shaped workflow)
 
+> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
+
 > **Beta:** Branch environments are still in beta. The CLI surface is available for early workflows, but not every command or cross-surface merge path is guaranteed to work reliably yet.
 
 A Fimo **env** is a multi-surface clone of the project: a git branch **plus** its own Neon DB branch, sandbox, preview URL, and R2 asset prefix. The CLI mirrors `git` command shapes so the workflow transfers directly — same verbs, multi-surface semantics.

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

@@ -1,5 +1,7 @@
 # Content workflow (schemas + entries)
 
+> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
+
 > For the JSON shape, field types, Tiptap node spec, slug rules, and generated React Query hooks — these are package surface (version-locked to the project's `fimo`). See **`fimo/references/content.md`**.
 
 This file covers the **CLI workflow** for content. Use it when the user wants to add a content type (blog, products, pages) or create/manage entries.
@@ -67,7 +69,7 @@ When creating a localized variant of an existing entry, pass the source entry's
 ## "Add a blog" recipe
 
 1. Load `fimo/references/content.md` for the JSON shape and field types.
-2. Write `src/schemas/BlogPost.json` with fields `title`, `slug`, `body` (richtext), `coverImage` (media), etc.
+2. Write `src/schemas/BlogPost.json` with fields `title`, `body` (richtext), `coverImage` (media), etc. Do NOT declare a `slug` field — `slug` (and `id`, `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 generate pruna/p-image --prompt "..."` (per-model flags come from `fimo models show <model>`; see `media.md`).
 5. Seed entries: `fimo entries create BlogPost --body '{"data": {"slug": "first-post", "title": "...", "coverImage": {...}}}'`.

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

@@ -1,5 +1,7 @@
 # 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.settings.json` unless `--project <project-id>` is provided.
 
 ```bash

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

@@ -1,6 +1,10 @@
 # Deploy pipeline
 
-**Deploy at meaningful milestones, not after every edit.** `fimo deploy` commits everything, pushes to the current env's branch, and round-trips that env's sandbox (install + restart) — it's a finishing step, not a save step. Batch related edits and deploy when a user-visible unit of work is done. For initial site generation, that's two deploys: one early in the background to warm the sandbox (see "Warm the sandbox early in a session" below), and one at the end with all the generated code to land the user's preview.
+> **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.
+
+> **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`.
 
 `fimo deploy` is **env-aware**: it targets the env of the current git branch (the same one `fimo status` reports on) and prints a one-line banner saying which. New projects are on `main`. It refuses to deploy to read-only `release/*` envs, and `--publish` only runs from `main`. The full multi-env workflow is in `references/branches.md`.
 
@@ -22,11 +26,13 @@ fimo deploy -m "<commit message>" --publish  # also publish a new live version
 
 Public project variables set with `fimo vars set` are injected into preview/build/deploy environments. Project secrets are not injected into app builds; agents request secrets separately through their own config. See `references/project-vars-and-secrets.md`.
 
-## Warm the sandbox early in a session
+## 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.
 
 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).
 
-**To hide that one-time cost, kick off an early deploy in the background while you keep working** — typically right after `fimo create` finishes, or at the start of a fresh session in an existing project. The provisioning happens during your scaffolding / generation work, so by the time the user wants to see something, the sandbox is already warm and the next deploy is fast.
+**To hide that one-time cost, kick off an early deploy in the background while you keep working.** The provisioning happens during your generation work, so by the time the developer wants a hosted preview, the sandbox is already warm and the deploy is fast.
 
 ```bash
 fimo deploy -m "chore: init" &        # background; keep generating code while it runs
@@ -92,7 +98,7 @@ fimo deploy
 ## Other facts
 
 - Source of truth is this git repo.
-- **Never** edit `.fimo.settings.json`; it is written once by `fimo create`.
+- **Never** edit `.fimo.settings.json`; it is written once by `fimo init`.
 - Each env deploys to its own branch + preview sandbox; `--publish` and `fimo publish` run from `main` only. See `references/branches.md`.
 
 ## After the first successful deploy

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

@@ -1,5 +1,7 @@
 # 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.

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

@@ -1,5 +1,7 @@
 # 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,5 +1,7 @@
 # Forms workflow
 
+> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
+
 > For the JSON spec, generated Zod schema, submit helper signature, and React usage patterns — these are package surface (version-locked to the project's `fimo`). See **`fimo/references/forms.md`**.
 
 This file covers the **CLI workflow** for forms. Use it when the user wants to add a contact form, signup, feedback form, etc.