fimo 0.3.3-staging.24 → 0.3.4-staging.26

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

@@ -0,0 +1,114 @@
+# `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
+
+```bash
+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.
+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).                                                                                      |
+| `--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`).                                                                            |
+| `--package-manager <pm>`     | no                            | `npm` \| `pnpm` \| `yarn` \| `bun`.                                                                                                                |
+| `--install` / `--no-install` | yes in non-TTY                | Install deps after checkout (or skip it).                                                                                                          |
+| `--skills` / `--no-skills`   | yes in non-TTY                | Set up Fimo skills (or skip it).                                                                                                                   |
+| `--agents <list>`            | no                            | Comma-separated agent IDs (e.g. `claude-code,cursor`). Pass `none` to write only universal AGENTS.md.                                              |
+| `-a, --agent <id>`           | alternative                   | Repeatable form: `-a claude-code -a cursor`.                                                                                                       |
+| `--mode <symlink\|copy>`     | no                            | Project skill install method.                                                                                                                      |
+| `--template-root <path>`     | no                            | Override the bundled template (development only).                                                                                                  |
+| `-y, --yes`                  | no                            | Skip the skills install preview confirmation.                                                                                                      |
+
+In a non-TTY shell the create-new path requires `[dir]`, `--install` / `--no-install`, and `--skills` / `--no-skills` (and `--org` if you have no active org and belong to multiple orgs). Without them the command exits with `Cannot prompt in a non-interactive shell.`
+
+> **Zero-install:** run `npx fimo@latest init` — no global install needed. `fimo projects create` is also an alias of `fimo init` (create-new path).
+
+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
+
+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.settings.json` + agent files, 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.
+
+## What gets written (create-new)
+
+`fimo init` (create-new path) scaffolds:
+
+- The project template (Vite + React 19 + TypeScript + Tailwind v4 + shadcn/ui + react-router)
+- `.fimo.settings.json` — links this directory to the remote project (read-only after creation)
+- `.env` — initial env vars (currently just `VITE_API_URL`)
+- `AGENTS.md` — project rules read by all agentskills.io-compatible AI tools (Codex, OpenCode, Aider, etc.)
+- Per-agent variants based on `--agents`:
+  - `claude-code` → `CLAUDE.md` + `.claude/settings.json`
+  - `cursor` → `.cursor/rules/fimo.mdc`
+  - `windsurf` → `.windsurfrules`
+  - `gemini-cli` → `GEMINI.md`
+  - codex / opencode / aider / others → no extra file; AGENTS.md is read natively
+- The project-scope `fimo` skill (npm package surface: schemas, forms, `t()`, `fimo/ui` components) copied into each selected agent's skill dir (`.claude/skills/fimo/`, `.cursor/skills/fimo/`, etc.). Version-locked to the bundled `fimo` package — the installed `SKILL.md` is stamped with `fimoVersion`. Refresh later with `fimo skills sync`. See `references/agent-setup.md`.
+- A git repository with `fimo` as the remote, an initial commit, and an initial push
+
+Codex, OpenCode, Aider, and similar AGENTS.md-native tools work directly off AGENTS.md without a per-agent variant.
+
+`.env` is only the bootstrap app env so local `pnpm dev` works immediately. User-managed public variables are stored with `fimo vars set` and synced into a managed `.env.local` block; hidden values use `fimo secrets set`. See `references/project-vars-and-secrets.md`.
+
+## Right after scaffolding
+
+Set a human-readable display name with `fimo rename "<Name>"`. Infer it from what the user is building (e.g. "Acme Coffee" for a café site, "Jane Doe Portfolio" for a personal site). The default post-`fimo init` name is an auto-generated slug; renaming updates the dashboard label and the SEO `siteName`.
+
+```bash
+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.
+
+```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.
+
+## Load the project context
+
+After `fimo init` completes, the project root has:
+
+- `AGENTS.md` (universal) plus the per-agent variant for the AI tool you're running in (e.g. `CLAUDE.md` for Claude Code, `.cursor/rules/fimo.mdc` for Cursor)
+- `.claude/skills/fimo/SKILL.md` (or the equivalent per-agent path) — the project-scope `fimo` skill, version-locked to the installed `fimo` package
+
+**These files came into existence mid-session, so they may not be auto-loaded by the harness.** Explicitly:
+
+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. `Read` the project skill: `.claude/skills/fimo/SKILL.md` (or `.cursor/skills/fimo/SKILL.md` for Cursor, etc.).
+4. From the project skill's "load these references up front" section, batch-read `references/content.md`, `references/forms.md`, `references/assets.md`, `references/labels.md`, `references/locales.md`, `references/ui.md` before generating any significant code.
+
+Once those are in context, generation respects the project's conventions (schemas, `t()`, `fimo/ui` components, asset handling).
+
+## 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:
+
+```bash
+fimo skills install --agents=cursor       # one command — global skill + project skill + rule file
+```
+
+Run from inside the project. The command detects the project context and wires up everything for the new agent in a single shot. See `references/agent-setup.md`.
+
+## 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,5 +1,7 @@
 # Firecrawl Integration
 
+> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
+
 Use Firecrawl when an agent needs to inspect public websites: 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,5 +1,7 @@
 # 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,5 +1,7 @@
 # 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,5 +1,7 @@
 # Labels workflow
 
+> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
+
 > For the `t()` helper signature, `useLabels()` hook, key naming rules, and the "wrap every user-facing string" rule, see **`fimo/references/labels.md`**.
 > For locale configuration and route-prefix validation, see **`references/locales.md`**.
 

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

@@ -1,5 +1,7 @@
 # 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 helpers such as `fimoRoutes()` and `FimoLink`, load `fimo/references/locales.md`.
 
 ## Configure Locales

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

@@ -1,5 +1,7 @@
 # Media generation
 
+> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
+
 > For uploading existing files, browsing the library, and opening assets, see
 > `references/assets.md`. This file is **only** about generating new media
 > via AI — the `fimo generate <model>` surface.

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

@@ -1,5 +1,7 @@
 # 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,5 +1,7 @@
 # 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`.
@@ -40,7 +42,7 @@ Secrets are not written to `.env.local`, preview app env files, browser bundles,
 
 ## Local Env Files
 
-`fimo create` writes `.env` for bootstrap app runtime values such as `VITE_API_URL`. This lets `pnpm dev` work without a Fimo wrapper.
+`fimo init` writes `.env` for bootstrap app runtime values such as `VITE_API_URL`. This lets `pnpm dev` work without a Fimo wrapper.
 
 `fimo vars set` and `fimo vars pull` write public project variables to a managed block in `.env.local`.
 

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

@@ -1,12 +1,14 @@
 # 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.settings.json` in the cwd) by default; for `delete`, `publish`, and `unpublish` you can pass an explicit `[projectId]` to target another. (`rename` is local-only — it never targets a different 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>] [--install|--no-install]   # alias of `fimo create`
+fimo projects create [dir] [--org <id>] [--install|--no-install]   # alias of `fimo init` (create-new path)
 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)
@@ -15,7 +17,7 @@ fimo projects rename <name> [projectId] [-C <dir>]   # local-only: set seo.siteN
 ```
 
 - **`list`** — projects you can see in the org. Live projects are marked.
-- **`create`** — identical to `fimo create`; see `references/create.md`.
+- **`create`** — identical to `fimo init` (create-new path); see `references/init.md`.
 - **`clone`** — clone a remote Fimo project's git repo to your machine and write the local `.fimo.settings.json`/agent files. Use `fimo clone <projectId>` when scripting or when the ID is known. In an interactive terminal, bare `fimo clone` opens a project picker for the active org; JSON mode and non-TTY shells require an explicit project ID and fail fast instead of prompting. By default it clones `main`; pass `--env <name>` to clone a specific env. The target directory defaults to the project display name/name, or pass `[dir]` explicitly.
 - **`delete`** — destructive; prompts unless `-y`. Removes the remote project.
 - **`publish` / `unpublish`** — toggle the project's public visibility. `publish` flips the current `main` state live (the same "go live" as `fimo deploy --publish`, minus the git push). This is **not** the versioned release path — for that, see `fimo publish` in `references/branches.md`.
@@ -39,7 +41,7 @@ fimo unpublish [-C <dir>]        # unpublish the current project
 fimo rename "<Site Name>"        # local edit: set seo.siteName in fimo-config.json
 ```
 
-`fimo rename` sets the **site name** (`seo.siteName`) in the local `fimo-config.json` — it is a local edit, not a remote update, so it requires a follow-up commit + `fimo deploy` to take effect. It does **not** change the project's remote display name (the `displayName` shown by `projects list`), which is set once at creation time from the project directory name. See `references/create.md` and `references/deploy.md`.
+`fimo rename` sets the **site name** (`seo.siteName`) in the local `fimo-config.json` — it is a local edit, not a remote update, so it requires a follow-up commit + `fimo deploy` to take effect. It does **not** change the project's remote display name (the `displayName` shown by `projects list`), which is set once at creation time from the project directory name. See `references/init.md` and `references/deploy.md`.
 
 ## Three "publish" verbs — don't confuse them
 

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

@@ -1,5 +1,7 @@
 # Scheduled Commands
 
+> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
+
 `fimo schedules` manages recurring commands for a project env. A schedule is scoped to the env of the current checkout by default, or to `--env <name>` when passed.
 
 ## Commands

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

@@ -17,6 +17,8 @@ exports, source repositories, CMS exports, media folders, or any hybrid of those
 It owns intake, source inventory, URL crawl bootstrapping, ledger normalization,
 imports, and QA so any LLM can run the work without silently dropping content.
 
+> Run every `fimo` command as `npx fimo@latest <command>` — always the latest CLI, no global install.
+
 ## Non-Negotiables
 
 - No source data may disappear silently. Every route, CMS export, entry, media

package/assets/skills/fimo-migration/references/manifest.md

@@ -76,7 +76,6 @@ than first-party CSV/XML/JSON exports.
   "importedCount": 0,
   "fields": {
     "title": { "type": "string", "source": "Name" },
-    "slug": { "type": "string", "source": "Slug" },
     "body": { "type": "richtext", "source": "Post Body" },
     "coverImage": { "type": "media", "source": "Main Image" },
     "publishedAt": { "type": "datetime", "source": "Published On" }
@@ -85,6 +84,11 @@ than first-party CSV/XML/JSON exports.
 }
 ```
 
+> **Do not put reserved names in `fields`.** `id`, `documentId`, `slug`, `locale`,
+> `createdAt`, `updatedAt`, and `__fimo` are built-in entry metadata — declaring them as
+> schema fields makes `fimo schemas push` fail with a 400. Map a source "Slug" column onto
+> the entry's built-in `slug` (inside `data`) at import time, not onto a schema field.
+
 ## Entry Batch Item
 
 ```json

package/dist/build/vite/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/build/vite/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAU,YAAY,EAAE,MAAM,MAAM,CAAC;AAyEjD,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;;;;;;;;OAUG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAGD,wBAAgB,IAAI,CAAC,IAAI,GAAE,eAAoB,GAAG,YAAY,EAAE,CAsB/D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/build/vite/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAU,YAAY,EAAE,MAAM,MAAM,CAAC;AAmFjD,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;;;;;;;;OAUG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAGD,wBAAgB,IAAI,CAAC,IAAI,GAAE,eAAoB,GAAG,YAAY,EAAE,CAsB/D"}

package/dist/build/vite/index.js

@@ -34,16 +34,26 @@ function bundleFimoIntoSsrPlugin() {
         config: () => ({
             ssr: { noExternal: ['fimo'] },
             optimizeDeps: {
-                include: ['fimo/ui'],
-                esbuildOptions: {
+                // Pre-include fimo's scanner-invisible dependency surface. The
+                // scanner can't traverse the fimo package (virtual: imports), so deps
+                // reached only THROUGH fimo (its react-router adapter subpath, its
+                // internal react-query usage) get discovered mid-first-load — vite
+                // re-optimizes and 504s the in-flight generation's chunks ("Outdated
+                // Optimize Dep") and the app never mounts (blank preview; caught by
+                // content/query e2e). Deps the template's own source imports (react,
+                // react-router) are scanner-visible and need no listing.
+                include: ['fimo/ui', 'fimo/react-router', '@tanstack/react-query'],
+                rolldownOptions: {
                     plugins: [
                         {
                             name: 'fimo-externalize-virtuals',
-                            setup(build) {
-                                build.onResolve({ filter: /^virtual:/ }, (args) => ({
-                                    path: args.path,
-                                    external: true,
-                                }));
+                            resolveId(id) {
+                                if (id.startsWith('virtual:')) {
+                                    return {
+                                        id,
+                                        external: true,
+                                    };
+                                }
                             },
                         },
                     ],

package/dist/cli/bundle.json

@@ -1,7 +1,7 @@
 {
   "bundled": true,
   "bundler": "esbuild",
-  "bundledAt": "2026-07-06T18:53:21.864Z",
+  "bundledAt": "2026-07-07T09:17:55.884Z",
   "cliVersion": "0.3.3",
   "external": [
     "oxc-parser",