fimo 2.10.1-staging.2 → 2.10.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/assets/skills/fimo-cli/SKILL.md +2 -2
  2. package/assets/skills/fimo-cli/SKILL.studio.md +42 -0
  3. package/assets/skills/fimo-cli/references/branches.md +43 -106
  4. package/assets/skills/fimo-cli/references/content/bulk.md +3 -12
  5. package/assets/skills/fimo-cli/references/content/localized.md +1 -1
  6. package/assets/skills/fimo-cli/references/content/sql.md +3 -10
  7. package/assets/skills/fimo-cli/references/deploy.md +35 -126
  8. package/assets/skills/fimo-cli/references/domains.md +38 -131
  9. package/assets/skills/fimo-cli/references/init.md +36 -170
  10. package/assets/skills/fimo-cli/references/projects.md +1 -1
  11. package/assets/skills/fimo-code/references/design.md +42 -126
  12. package/assets/skills/fimo-migration/SKILL.md +114 -408
  13. package/assets/skills/fimo-migration/references/content-delivery.md +67 -0
  14. package/assets/skills/fimo-migration/references/frameworks/nextjs.md +1 -1
  15. package/assets/skills/fimo-migration/references/qa/browser.md +41 -0
  16. package/assets/skills/fimo-migration/references/qa/guardrails.md +95 -0
  17. package/assets/skills/fimo-migration/references/qa/results.md +78 -0
  18. package/assets/skills/fimo-migration/references/qa.md +102 -383
  19. package/assets/skills/fimo-migration/references/questions-and-improvements.md +77 -168
  20. package/assets/skills/fimo-migration/references/setup.md +90 -0
  21. package/assets/skills/fimo-migration/references/workers/validator.md +2 -2
  22. package/assets/skills/fimo-migration/references/workers.md +1 -1
  23. package/assets/skills/fimo-migration/references/workflow.md +117 -171
  24. package/assets/skills/fimo-studio/SKILL.md +4 -1
  25. package/assets/skills/fimo-studio/references/ai-chat/agents.md +46 -0
  26. package/assets/skills/fimo-studio/references/ai-chat/default-agents.md +57 -0
  27. package/assets/skills/fimo-studio/references/ai-chat/routines.md +53 -0
  28. package/assets/skills/fimo-studio/references/ai-chat.md +39 -76
  29. package/assets/skills/fimo-studio/references/custom-domains.md +2 -2
  30. package/assets/skills/fimo-studio/references/publish-and-deploy.md +1 -1
  31. package/dist/cli/bundle.json +2 -2
  32. package/dist/cli/index.js +32 -11
  33. package/package.json +8 -8
  34. package/release.json +2 -2
  35. package/templates/astro/package.json +3 -3
  36. package/templates/nextjs/package.json +4 -4
  37. package/templates/react-router/package.json +5 -5
  38. package/templates/sveltekit/package.json +3 -3
  39. package/templates/vite/package.json +5 -5
@@ -1,154 +1,61 @@
1
1
  # Domains
2
2
 
3
- `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:
3
+ `fimo domains` manages every site address. There are three kinds. Find out which one the user wants before you run a command:
4
4
 
5
- | Resource | What it is | Plan | Per project | Source of truth |
6
- | --------------------- | -------------------------------------------------------------------- | ---------------------- | ----------- | -------------------------- |
7
- | **Default URL** | The `<slug>.fimo.site` subdomain Fimo provisions automatically | Free | Exactly one | `projects.subdomain` |
8
- | **Custom domain** | A hostname the user owns (e.g. `blog.example.com`), attached via DNS | Premium | Many | `project_domains` table |
9
- | **Registered domain** | A new domain bought _through_ Fimo via the registrar reseller | Premium + feature flag | Many | `registered_domains` table |
5
+ | User says | Kind | Commands | Plan |
6
+ | ------------------------------------------ | ----------------------------------------- | ----------------------------------- | ------------------------------------------------------------- |
7
+ | "Keep the free address, but make it nicer" | default URL `<slug>.fimo.site` (one each) | `rename-default`, `suggest-default` | every plan, no DNS |
8
+ | "I own example.com" | custom domain, attached through DNS | `add`, `refresh`, `remove` | Starter or higher |
9
+ | "I want to buy a domain" | registered domain, bought through Fimo | `search`, `pricing`, `buy`, `owned` | purchase must be enabled; `buy` and `owned` need an org admin |
10
10
 
11
- > **A renamed URL or custom domain only resolves once the site is published** (`fimo deploy --publish`); before that it returns "Project Not Found".
11
+ If the user is not sure, start with `fimo domains suggest-default`: it is free and takes one step. `fimo domains list --json` shows the default URL and every custom domain. Run `fimo domains <command> --help` for flags.
12
12
 
13
- ## Commands
13
+ **A new default URL or custom domain shows "Project Not Found" until the site is published** (`fimo deploy --publish`, only when the user says to go live).
14
+
15
+ ## Default URL
14
16
 
15
17
  ```bash
16
- # Default URL (free, every project)
17
- fimo domains list # default URL + custom domains in one view
18
- fimo domains rename-default <slug> # rename the default URL slug
19
- fimo domains suggest-default # propose & claim a default URL
20
- fimo domains suggest-default --base "Acme Blog" # use a custom base instead of project display name
21
- fimo domains suggest-default --pick 0 # non-interactive: claim the first suggestion
22
-
23
- # Custom domain (Premium, user owns the hostname)
24
- fimo domains add <hostname> # attach a custom domain
25
- fimo domains add <hostname> --redirect-www # also configure an apex → www redirect
26
- fimo domains add <hostname> --wait # block until SSL is active (5 min default)
27
- fimo domains add <hostname> --wait 10m # poll for a custom duration (Ns / Nm)
28
- fimo domains refresh <hostname> # re-check DNS / SSL (polls by default)
29
- fimo domains refresh <hostname> --no-wait # one snapshot, no polling
30
- fimo domains remove <hostname> # detach a custom domain
31
-
32
- # Registered domain (Premium, buy a new domain through Fimo)
33
- fimo domains search <keyword> # find available domains to buy
34
- fimo domains search <keyword> --tld com,io # restrict TLDs
35
- fimo domains search <keyword> --max-price 20 # purchase-price ceiling in dollars
36
- fimo domains search <keyword> --limit 10 # truncate to first N results (default 20)
37
- fimo domains pricing <domain> # one-shot price check
38
- fimo domains buy <domain> # create checkout invoice (interactive confirm)
39
- fimo domains buy <domain> --years 1 --yes # non-interactive (for agents)
40
- fimo domains buy <domain> --open --wait # auto-open checkout in browser + poll until paid
41
- fimo domains buy <domain> --wait 10m # poll for a custom duration (Ns / Nm)
42
- fimo domains owned # list domains registered through Fimo
43
- fimo domains owned --status owned,pending_payment
44
- fimo domains owned --limit 10 # truncate to first N results
18
+ fimo domains rename-default <slug> --json # slug only: acme-coffee, not acme-coffee.fimo.site
19
+ fimo domains suggest-default --base "<brand>" --json # candidates; --json claims nothing
20
+ fimo domains suggest-default --base "<brand>" --pick <slug-or-index> --json # claim one
45
21
  ```
46
22
 
47
- Global flags: `--project <id>` / `-C, --cwd <dir>` for project resolution, `--org <id>` on org-scoped commands (`buy`, `owned`), `--json` on read/output commands.
48
-
49
- ## Choosing the right resource
50
-
51
- When a user says "I want to change my website's URL," ask which case fits:
52
-
53
- - **"It's fine as-is, just nicer"** → `rename-default` or `suggest-default`. Free, instant, no DNS.
54
- - **"I own example.com already"** → `add example.com`. Starter or higher. They configure CNAME at their registrar.
55
- - **"I want to buy a domain"** → `search` → `pricing` → `buy`. The registered-domains feature flag and an eligible plan must be on (the flag is not enabled in every environment).
56
-
57
- If they aren't sure, run `fimo domains suggest-default` first — it's free, takes one step, and a good fallback if they don't want to commit to a domain purchase.
58
-
59
- ## Offer a cleaner default URL before first publish
60
-
61
- After the automatic first-preview deploy on a newly created project, offer a cleaner free `*.fimo.site` URL before the first public publish when there is no custom domain and the current default slug still looks generated or was never explicitly chosen. Choosing it now lets the first public launch use the clean URL. Skip the offer if the user already chose the default slug, attached a custom domain, or declined.
62
-
63
- The default URL is free and needs no DNS. A custom domain needs Starter or higher, as above. A default slug can be reserved before publication, but it returns "Project Not Found" until the site is published. Renaming changes the address that will become public, so never silently claim a suggestion:
64
-
65
- 1. Run `fimo domains suggest-default --base "<brand>" --json` to get candidates.
66
- 2. Show the candidates and ask the user to choose one explicitly.
67
- 3. After confirmation, run `fimo domains rename-default <slug>` or `fimo domains suggest-default --pick <slug>`.
68
-
69
- Choosing the slug does not publish the site. The first successful `fimo deploy --publish` makes the renamed URL resolve.
70
-
71
- ## Pricing & how money moves
72
-
73
- The CLI never charges directly. Two distinct money paths:
74
-
75
- 1. **Starter or higher** — gates custom-domain operations. Starter or Pro is chosen in the Fimo web app (Hyperline-hosted checkout). When a Free user runs a gated command they get a 403 with the billing URL; surface it as-is to the user.
76
- 2. **Domain registration** — `fimo domains buy` creates a Hyperline invoice with `payment_method_strategy: 'external'` and returns a `checkoutUrl`. The user opens that URL in a browser to pay. **No money moves until they pay the invoice.** That's why `--yes` on `buy` is safe: it queues an invoice; the human still has to consent at checkout.
77
-
78
- Domain prices come from name.com via the registrar reseller. They vary by TLD and can change. Pricing is in USD (cents in the API, formatted as dollars in CLI output).
23
+ A slug uses lowercase letters, numbers, and hyphens (at most 63). To change the address, use `rename-default`; never `add` a `*.fimo.site` hostname.
79
24
 
80
- ## Buy flow — what agents should do
25
+ ### Cleaner default URL before the first publish
81
26
 
82
- The CLI is permissive (any caller with Premium + org-admin can run `buy --yes`), but agents should be deliberate. The skill workflow:
27
+ After the first preview of a new site, offer a cleaner free URL when the current slug looks generated or the user never chose it, and the site has no custom domain. Skip it when the user already chose a slug, attached a domain, or said no.
83
28
 
84
- 1. **Run `fimo domains search <keyword> --json`** (or `pricing` for a specific domain). Never call `buy` blind.
85
- 2. **Show the user the candidates with prices.** Format: `"example.com — $14.00 first year, $14.00/yr renewal"`.
86
- 3. **Get explicit user acknowledgment** before running `buy`. Phrasing like:
29
+ 1. Run `fimo domains suggest-default --base "<brand>" --json`.
30
+ 2. Show the candidates and ask the user to choose one. **Never claim a slug the user did not choose.**
31
+ 3. Run `fimo domains rename-default <slug>` (or `--pick <slug>`).
87
32
 
88
- > "Want me to register `example.com` for $14.00 (1 year)? You'll complete payment in your browser. Auto-renew is on by default — say so if you want it off."
33
+ Choosing the slug does not publish the site. The URL resolves after the first successful publish.
89
34
 
90
- 4. **Run `fimo domains buy <domain> [--years N] [--no-auto-renew] --yes`** once they confirm.
91
- 5. **Surface the `checkoutUrl` prominently.** The agent's message should make it obvious the user must click the link to actually pay. Example:
92
-
93
- > "Invoice created. Open this to pay — no charge until you do:
94
- > https://checkout.hyperline.co/abc123"
95
-
96
- 6. **Mention `--no-auto-renew`** in step 3 if appropriate. It's a recurring yearly charge otherwise.
97
- 7. Optionally **`--wait`** on the buy call so the agent can confirm registration completed (poll up to 5 min). For longer waits, ask the user to re-run `fimo domains owned` later.
98
-
99
- ## Custom domain (`add`) — the DNS dance
35
+ ## Custom domain the user owns
100
36
 
101
37
  ```bash
102
- fimo domains add blog.example.com
103
- ```
104
-
105
- Add `--redirect-www` to also configure an apex → www redirect for the hostname.
106
-
107
- Fimo prints DNS records the user copies to their registrar (Cloudflare, Namecheap, GoDaddy, etc.):
108
-
38
+ fimo domains add <hostname> [--redirect-www] [--wait [10m]] --json # --redirect-www: the apex redirects to www; bare --wait = 5 min (Ns or Nm)
39
+ fimo domains refresh <hostname> # check DNS and SSL again; it polls by default
40
+ fimo domains remove <hostname> --yes
109
41
  ```
110
- DNS records to add at your registrar:
111
-
112
- TYPE NAME VALUE
113
- CNAME blog customers.fimo.site
114
- TXT _fimo verify=abc123…
115
- ```
116
-
117
- Run `fimo domains refresh blog.example.com` after configuring DNS to re-check. `refresh` polls by default; `--no-wait` for a snapshot.
118
-
119
- Propagation: typically 15–30 minutes, up to 48 hours rarely.
120
-
121
- ## Common errors
122
-
123
- - **"Project Not Found" on a new URL or custom domain.** The route exists but the site was never published — run `fimo deploy --publish`.
124
- - **"Custom domains require Starter or higher."** — choose a plan at `/app/billing`, then retry. Free users can still run `list`, `rename-default`, `suggest-default`, `search`, and `pricing`.
125
- - **"Domain purchase is not enabled on this account."** — the registered-domains feature flag is off on this API instance. Contact support.
126
- - **"This URL is not available."** — slug or hostname collides with another project or is reserved.
127
- - **"That's a Fimo-owned domain."** — user tried `add <something>.fimo.site`. Use `rename-default` instead.
128
- - **"Invalid URL."** — slug violates RFC 1123 (lowercase letters, numbers, hyphens; max 63 chars).
129
- - **"`<domain>` is not available for registration."** — the requested registered domain is taken or otherwise unbuyable. Suggest `search` to find alternatives.
130
- - **"`<domain>` is a premium domain and isn't supported through the CLI."** — name.com flags some domains as premium with elevated prices; the CLI deliberately rejects these to avoid surprise charges. Direct the user to a different name.
131
- - **"You don't have permission to buy domains for this organization. Org admins only."** — org admin role required for `buy` and `owned`.
132
- - **"Couldn't sync the URL."** — transient Cloudflare KV write failure. Retry.
133
-
134
- ## When to use `--wait`
135
42
 
136
- `--wait` takes an optional duration on `add`, `refresh`, and `buy` (e.g. `--wait 10m`, `--wait 300` — `Ns` or `Nm`). Passed bare, it defaults to a 5-minute poll.
43
+ - `add` returns the DNS records (usually a CNAME and a TXT) that the user sets at their registrar; with `--json` they are in the domain record. Give them to the user exactly.
44
+ - After the user sets DNS, run `refresh` once; it polls until SSL is active or the wait ends (`--no-wait` prints one status). Read the returned status: the end of a wait does not prove the domain works. Do not run `refresh` in a loop. DNS can take from minutes to 48 hours.
45
+ - In an interactive setup, omit `--wait` on `add` so the user gets the records at once. In CI, `--wait` polls until the domain is verified or the wait ends.
46
+ - A Free plan gets a `PAYWALL` 403 with the billing URL: give that URL to the user.
47
+ - `remove` and `buy` ask for confirmation: pass `--yes` in a run without prompts, after the user agreed.
137
48
 
138
- - **CI / scripted setup**: `fimo domains add ... --wait` blocks until verification, so the next pipeline step can assume the domain works.
139
- - **Interactive user setup**: omit `--wait` on `add` so they get the DNS table immediately and can paste it into their registrar.
140
- - **`refresh`**: defaults to wait because if a user is explicitly refreshing they want the new state. Pass `--no-wait` to opt out.
141
- - **`buy`**: opt-in via `--wait`. The poll covers "payment landed" + "name.com registration completed."
49
+ ## Buy a domain (paid)
142
50
 
143
- ## Web app equivalent
51
+ `buy` creates an invoice and returns a `checkoutUrl`. No money moves until the user pays in the browser. Registration is usually not refundable, and auto-renew is on by default (a yearly charge).
144
52
 
145
- For users on the dashboard, the same workflow lives at **Settings → Domains** (custom domain) and **Organization → Domains** (buy/owned). See `fimo-studio/references/custom-domains.md` and the [public docs](https://fimo.ai/docs/publish/custom-domains).
53
+ 1. Run `fimo domains search <keyword> [--tld com,io] --json`, or `fimo domains pricing <domain> --json`. **Never run `buy` before you check the price.**
54
+ 2. Show the candidates with prices, for example `acme.com — $14.00 first year, $14.00/yr renewal`.
55
+ 3. Get the user's explicit approval for the domain, the years, and auto-renew (`--no-auto-renew` to turn it off).
56
+ 4. Run `fimo domains buy <domain> [--years <n>] [--no-auto-renew] --yes --json` (`--wait` polls until payment and registration finish, fail, or the wait ends).
57
+ 5. **Show the `checkoutUrl` clearly**, and say that the user must open it to pay. Later status: `fimo domains owned`.
146
58
 
147
- ## Anti-patterns
59
+ The CLI refuses names that the registrar prices as premium: suggest another name.
148
60
 
149
- - **Calling `fimo domains buy` blind.** Always run `search` or `pricing` first and confirm the price with the user.
150
- - **Forgetting that registered-domain purchases are typically non-refundable.** ICANN rules; once registered, you generally own it for the term.
151
- - **Trying to `add` a `*.fimo.site` hostname** — that's the default URL. Use `rename-default` to change the slug. The CLI catches this.
152
- - **Running `refresh` in a manual loop** — it polls by default; let it run. Manual loops waste API calls and may trigger 429s.
153
- - **Forgetting `--yes` in scripts** — `remove` and `buy` confirm by default; pass `--yes` or they hang in a non-TTY.
154
- - **Surfacing the `buy` checkout URL too quietly.** The user must visit the URL to pay; if the agent buries it in a long message they may miss the next step.
61
+ Studio equivalent: Settings → Domains (custom domain), Organization → Domains (buy, owned); see the `fimo-studio` skill's `custom-domains`.
@@ -1,190 +1,56 @@
1
- # `fimo init`
1
+ # Create or set up a site: `fimo init`
2
2
 
3
- One-stop project setup: sign in, create a new Fimo site (or link an existing one), install dependencies, and optionally set up Fimo skills for your AI tools.
4
-
5
- ## Command
6
-
7
- ```bash
8
- fimo init [dir] [options]
9
- ```
10
-
11
- `fimo init` runs the full onboarding in one shot:
12
-
13
- 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` in a terminal first, or create the site without an account with `fimo new <dir>` (see `account.md`).
14
- 2. **Resolves the project** — with `--project-id <id>` it sets up the named Fimo site: 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 sites use the Next.js App Router by default; `--framework react-router`, `--framework vite`, `--framework astro`, and `--framework sveltekit` select the other minimal framework-native shells.
15
- 3. **Installs dependencies** — prompts for the package manager, or honor `--package-manager <pm>` / `--no-install`.
16
- 4. **Optionally sets up Fimo skills** — confirm prompt, or `--skills` / `--no-skills`.
17
-
18
- Generated pnpm projects pin `pnpm@10.26.0` and carry project-owned `pnpm-workspace.yaml#strictDepBuilds: true` and `#allowBuilds` settings. Generated Bun projects trust the same required packages through `package.json#trustedDependencies`. Keep the selected package manager's policy committed. When adding a dependency with an install script, review it before extending that policy; never replace it with a blanket allow-all install.
19
-
20
- | Flag | Required | Purpose |
21
- | ---------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
22
- | `[dir]` positional | yes in non-TTY for create-new | Target directory (e.g. `my-site`) |
23
- | `--project-id <id>` | no | Set up the named Fimo site: scaffold and push a fresh site when it has no code yet, otherwise clone it. |
24
- | `--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. |
25
- | `--branch <name>` | no | Branch to check out when linking an existing project (defaults to `main`). |
26
- | `--env <name>` | no | Rejected as a Branch selector; use `--branch <name>`. |
27
- | `--framework <framework>` | no | New-project scaffold: `nextjs` (App Router, default), `react-router`, `vite` (React SPA), `astro`, or `sveltekit`. Existing repositories are preserved. |
28
- | `--package-manager <pm>` | no | `npm` \| `pnpm` \| `yarn` \| `bun`. |
29
- | `--install` / `--no-install` | no | Install deps after checkout (or skip it). |
30
- | `--skills` / `--no-skills` | no | Install the global Fimo skill (or skip it). |
31
- | `--agents <list>` | no | Comma-separated agent IDs (e.g. `claude-code,cursor`). Pass `none` to skip installing the global skill. Non-interactive runs without it use `none`, unless `--skills` is passed. |
32
- | `-a, --agent <id>` | alternative | Repeatable form: `-a claude-code -a cursor`. |
33
- | `--template-root <path>` | no | Override the bundled template (development only). |
34
- | `-y, --yes` | no | Run non-interactively using defaults (no prompts). |
35
-
36
- In a non-TTY shell (or with `-y` / `--json`) the create-new path requires `[dir]`, and `--org` if you have no active org and belong to multiple orgs. Everything else takes a default: dependencies install with the detected package manager unless you pass `--no-install`, and no skill is installed unless you pass `--skills`.
37
-
38
- ### Non-interactive setup
39
-
40
- Use explicit flags when a script or agent owns the flow. `--json` gives the
41
- caller one stable result envelope; `--yes` is useful when running in a TTY but
42
- is not required in a pipe or CI shell. The default scaffold is the Next.js App
43
- Router template. Select the canonical React Router template explicitly with
44
- `--framework react-router`.
45
-
46
- ```bash
47
- fimo --json init my-site \
48
- --org <organizationId> \
49
- --no-install \
50
- --no-skills \
51
- --agents=none \
52
- --yes
53
- ```
54
-
55
- If dependencies were skipped, install them and run `fimo validate` before
56
- starting the app so generated clients are present.
57
-
58
- > **Zero-install:** the selected `fimo init` invocation needs no global install. `fimo projects create` is also an alias of `fimo init` (create-new path).
59
-
60
- ### Choose the application framework
61
-
62
- Omit `--framework` for the default Next.js App Router shell, or select a
63
- different framework explicitly:
64
-
65
- ```bash
66
- fimo init my-react-site --framework react-router --org <organizationId>
67
- fimo init my-vite-site --framework vite --org <organizationId>
68
- fimo init my-astro-site --framework astro --org <organizationId>
69
- fimo init my-next-site --framework nextjs --org <organizationId>
70
- fimo init my-svelte-site --framework sveltekit --org <organizationId>
71
- ```
72
-
73
- Each shell includes its framework adapter, hosted-preview connector, and
74
- `.fimo/config.json#runtime.framework`, plus an application-owned optional locale
75
- boundary that keeps the default locale unprefixed. The Astro shell also includes a minimal
76
- content-backed example with static, on-demand, and dynamic routes; the other shells intentionally
77
- contain no schema, labels, or designed website.
78
-
79
- The React Router shell is the canonical Fimo React template for framework mode;
80
- select it with `--framework react-router` when a project should use React Router
81
- instead of the default Next.js App Router shell.
82
-
83
- Set the primary locale from the request: when several are explicitly named, use the first as default;
84
- if none is requested, keep `en` and tell the user. After init, load `references/locales.md` and use its
85
- typed lifecycle commands to configure the locale set and default. Then update the framework-native locale
86
- boundary, matcher, and HTML language default. Do not keep `en` solely because the shell starts there.
87
- Do not add `/en`, a language picker, global path-prefix configuration, or localized schemas unless the
88
- site needs them.
89
- After init, load the project rules and `fimo-code` to build the requested site.
90
- If you replace a shell's code with a site that uses another framework or none,
91
- fix `runtime.framework` in the same change
92
- (`fimo-code` → `references/frameworks/hosting.md`).
93
-
94
- 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.
95
-
96
- ## Setting up a project by ID
97
-
98
- Pass `--project-id <id>` to set up a known Fimo site. 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 `--branch <name>` to check out a specific Branch (defaults to `main`). Without `--project-id`, `fimo init` creates a new site.
99
-
100
- ## Linking an existing local application
101
-
102
- Use `fimo link <projectId>` to adopt the application in the current folder without replacing its code or comparing its Git history. Running it again with the same project id repairs missing Fimo metadata, dependencies, or the `fimo` remote. If the folder is linked to a different project, the command stops before changing the remote or local files. Pass `--relink` only when the project replacement is intentional:
3
+ `fimo init` signs in, creates or sets up a site, installs dependencies, and can install the global Fimo skill. Run `fimo init --help` for every flag.
103
4
 
104
5
  ```bash
105
- fimo link <projectId> --relink
6
+ fimo --json init <dir> --org <organizationId> [--framework nextjs|react-router|vite|astro|sveltekit] [--package-manager pnpm|npm|yarn|bun] [--no-install] [--skills --agents <id>,<id>]
7
+ fimo --json init <dir> --project-id <id> [--branch <name>] # set up a site that already exists in Fimo
8
+ fimo link <projectId> [--relink] # link the app in this folder, in place
106
9
  ```
107
10
 
108
- Linking keeps every word typed in the code, where Fimo Studio shows "Nothing to edit". When people will edit the site,
109
- load `fimo-migration` and follow its source-backed, same-framework path: its content pass moves that
110
- text to labels and the CMS, and its `editable-text` guardrail proves it.
111
-
112
- ## What gets written (create-new path)
113
-
114
- `fimo init` (create-new path) scaffolds:
115
-
116
- - The selected project shell: Next.js App Router by default, React Router with `--framework react-router`, a native React SPA with `--framework vite`, Astro with `--framework astro`, or SvelteKit with `--framework sveltekit`
117
- - `.fimo/project.json` — links this directory to the remote site (read-only after creation)
118
- - `.fimo/config.json` — project, optional Studio Pages route metadata, locale, and SEO
119
- - `AGENTS.md` + `CLAUDE.md` — project rules (from the template) read by AGENTS.md-compatible tools and Claude Code. Both point the agent at `fimo skills get` to load the real skills on demand.
120
- - A git repository with `fimo` as the remote, and — after dependencies install — an initial commit (including the lockfile) plus an initial push
121
-
122
- Nothing is written into per-agent skill dirs: the rich skills are fetched on demand via `fimo skills get <name>`, never copied into the project. `fimo init` separately installs the small global `fimo` bootstrap skill for the agents you select (machine-wide, not in the project) unless you pass `--no-skills`. For other agents' rule-file variants (`.cursor/rules/fimo.mdc`, `.windsurfrules`, `GEMINI.md`), run `fimo rules sync`. See `references/agent-setup.md`.
123
-
124
- Codex, OpenCode, Aider, and similar AGENTS.md-native tools work directly off AGENTS.md.
125
-
126
- Supported framework runtimes derive the Fimo connection from
127
- `.fimo/project.json` and the active git branch, so local development needs no
128
- Fimo env file. User-managed public variables are stored with `fimo vars add`
129
- and synced into a managed `.env.local` block; hidden values use
130
- `fimo secrets add`. See `references/project-vars-and-secrets.md`.
131
-
132
- ## Right after scaffolding
133
-
134
- 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`.
135
-
136
- ```bash
137
- cd my-site
138
- fimo rename "Acme Coffee"
139
- ```
11
+ ## Pick the path
140
12
 
141
- **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.
13
+ - **New site:** `fimo init <dir>`. Without a TTY, or with `--json` or `-y`, it needs `<dir>`. It also needs `--org <id>` when you are in more than one organization and none is active. Use the `ID` column of `fimo orgs list`, not the slug.
14
+ - **Site from Studio, or another existing site:** add `--project-id <id>`. A site with no code yet (for example one just created in Studio) gets a new scaffold and the first push. A site with code is cloned into `<dir>`. `--branch` selects the Branch to check out (default: the site's default Branch).
15
+ - **App that already exists in this folder:** `fimo link <projectId>` keeps the code and the Git history. Run it again to repair missing Fimo files, dependencies, or the `fimo` remote. If the folder is linked to another site, the command stops. Add `--relink` only when the user wants to replace that link. The linked app keeps its text in code, so Studio shows "Nothing to edit". When people will edit the site, load the `fimo-migration` skill and follow its source-backed, same-framework path: it moves the text to labels and the CMS, and its `editable-text` guardrail proves it.
16
+ - **No account, or no browser:** `fimo new <dir> --yes --json` (`--ref account`). With `--json` and no session, `init` fails with `NOT_AUTHENTICATED`.
142
17
 
143
- ```bash
144
- pnpm dev & # or npm run dev / yarn dev / bun dev — the project's package manager
145
- ```
18
+ ## Defaults
146
19
 
147
- Outside the first-preview path below, when a unit of work looks done, **offer** to deploy (`fimo deploy` for a hosted project preview, `fimo deploy --publish` to go live) and run it only after the developer confirms.
20
+ - **Framework:** the Next.js App Router shell. `--framework` selects another shell for a new scaffold only; existing code stays as it is. The React Router shell is the canonical Fimo React template. Each shell has its framework adapter, the hosted-preview connector, `.fimo/config.json#runtime.framework`, and a locale boundary that keeps the default locale unprefixed. Only the Astro shell has example content; the others have no schema, labels, or design.
21
+ - **Dependencies:** install with the detected package manager unless you pass `--no-install`. After `--no-install`, install them and run `fimo validate` before you start the app.
22
+ - **Global skill:** a run without prompts installs it only with `--skills`; `--agents` alone installs nothing. Name the tool you run in: `--skills --agents=claude-code` (or `cursor`, `codex`, another id from `fimo skills install --help`; `-a <id>` repeats). A later teammate on another tool: `--ref agent-setup`.
23
+ - **Package-manager policy:** generated pnpm projects pin `pnpm@10.26.0` and commit `strictDepBuilds: true` and `allowBuilds` in `pnpm-workspace.yaml`; Bun projects use `trustedDependencies`. Keep this policy committed. Never replace it with an allow-all setting (`--ref deploy` for a blocked build script).
148
24
 
149
- ## Load the project context
25
+ ## What init writes
150
26
 
151
- After `fimo init` completes, the project root has `AGENTS.md` (universal) and `CLAUDE.md` (for Claude Code) from the template.
27
+ - `.fimo/project.json` links the folder to the site. Never edit it.
28
+ - `.fimo/config.json` holds project settings, locales, SEO, and optional Studio page routes.
29
+ - `AGENTS.md` and `CLAUDE.md` hold the project rules. They tell agents to load skills with `fimo skills get`; skills are not copied into the project. Other tools' rule files: `fimo rules sync`.
30
+ - A Git repository with `fimo` as the remote, a first commit (with the lockfile when dependencies were installed), and a first push.
31
+ - No Fimo env file: the framework runtime reads the connection from `.fimo/project.json` and the Git branch. Variables and secrets: `--ref project-vars-and-secrets`.
152
32
 
153
- **These files came into existence mid-session, so they may not be auto-loaded by the harness.** Explicitly:
33
+ ## Right after init
154
34
 
155
- 1. `cd <project-dir>` — switch into the new site.
156
- 2. `Read` the project rules file: `AGENTS.md` (or `CLAUDE.md` if you're Claude Code).
157
- 3. Run `fimo describe --json` with the current invocation prefix and read the detected framework, schemas, locales, and tree.
158
- 4. Load the code skill on demand with the same prefix: `fimo skills get fimo-code`.
159
- 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.
35
+ Do these steps in this order:
160
36
 
161
- Do not batch-load every reference. Progressive disclosure keeps unrelated framework and product guidance out of the coding context.
37
+ 1. `cd <dir>`. Read `AGENTS.md` (or `CLAUDE.md`): the harness may not load files that appeared during the session.
38
+ 2. Run `fimo describe --json`. Load `fimo skills get fimo-code` and only the reference for the detected framework, for example fimo-code `frameworks/next`, `frameworks/astro`, or `frameworks/sveltekit`. For Next.js, load the App Router, Pages Router, or locale reference only when the project needs it. Do not load every reference.
39
+ 3. **Locales:** take the default locale from the request: when several are explicitly named, use the first as default. When none is named, keep `en` and tell the user. Then load `references/locales.md` and use its lifecycle commands (`fimo locales add es`, then `fimo locales set-default es`); never edit `i18n` in the config file. Update the framework's locale boundary, matcher, and HTML `lang` default. Do not add `/en`, a language picker, global path-prefix configuration, or localized schemas unless the site needs them.
40
+ 4. Set a display name from what the user builds: `fimo rename "Acme Coffee"`. The default name is the directory name. Rename after the locale commands: it changes `.fimo/config.json` (also the SEO `siteName`), and locale commands refuse a config with uncommitted changes. The next deploy sends the name to Fimo.
41
+ 5. Start the dev server in the background with the project's package manager (`pnpm dev &`). Local edits show with live reload; they do not need a deploy.
42
+ 6. If you replace the shell with another framework, or with no framework, fix `runtime.framework` in the same change (fimo-code `frameworks/hosting`).
162
43
 
163
- ### Create the first hosted preview (create-new path)
44
+ ## First hosted preview
164
45
 
165
- Whenever `fimo init` created or scaffolded a new site — 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:
46
+ When `init` created or scaffolded a new site, including a Studio project with no code, end the setup with exactly one preview deploy. Skip it only when the user said not to deploy.
166
47
 
167
48
  ```bash
168
49
  fimo deploy -m "chore: first preview" --json
169
50
  ```
170
51
 
171
- `-m` is required because you run non-interactively; the deploy validates, commits pending changes, pushes, and syncs the preview sandbox. Return `data.studio_url` from the envelope. Run `fimo preview url --json` only when the hosted site URL itself is needed. 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.
172
-
173
- This first deploy creates a preview only — never add `--publish`, and treat every later deploy as offer-then-confirm. It also warms the sandbox: do not run a separate warm-up deploy. 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.
174
-
175
- After the preview succeeds, follow `references/domains.md` § Offer a cleaner default URL before first publish. Reserve a slug only after the user chooses it; the URL will not resolve until the site is published.
176
-
177
- ## Adding another AI tool to an existing project later
178
-
179
- If a teammate joins on a different AI tool (e.g. Cursor) after the project was scaffolded for claude-code only:
180
-
181
- ```bash
182
- fimo skills install --agents=cursor # install the global Fimo skill for cursor
183
- fimo rules sync --agents=cursor # generate cursor's rule file (.cursor/rules/fimo.mdc)
184
- ```
185
-
186
- The first installs the global bootstrap skill for the new agent; the second generates its project rule file from `AGENTS.md`. See `references/agent-setup.md`.
187
-
188
- ## Multi-org accounts
189
-
190
- 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`.
52
+ - If the request describes a site, first build a small, meaningful first screen. If not, deploy the scaffold and then ask what to build. Never ask before init.
53
+ - Give the user `data.studio_url`. Run `fimo preview url --json` only when you need the hosted site URL.
54
+ - **Never add `--publish`.** This deploy also warms the sandbox, so do not run another warm-up deploy. Later deploys need the user's request or agreement.
55
+ - A cloned site with code, or a migration, does not get this automatic preview.
56
+ - Then offer a cleaner free URL before the first publish (`--ref domains`, "Cleaner default URL").
@@ -16,7 +16,7 @@ fimo projects rename <name> [projectId] [-C <dir>] # set seo.siteName in the l
16
16
 
17
17
  - **`list`** — projects you can see in the org. Live projects are marked.
18
18
  - **`create`** — identical to `fimo init` (create-new path); see `references/init.md`.
19
- - **`clone`** — clone a remote Fimo site's git repo to your machine and write the local `.fimo/project.json` and 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 site ID and fail fast instead of prompting. By default it clones `main`; pass `--branch <name>` to clone a specific Branch. The removed `--env <name>` spelling is rejected as a Branch selector. The target directory defaults to the project display name/name, or pass `[dir]` explicitly.
19
+ - **`clone`** — clone a remote Fimo site's git repo to your machine and write the local `.fimo/project.json` and 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 site ID and fail fast instead of prompting. By default it clones the site's default Branch; pass `--branch <name>` to clone a specific Branch. The removed `--env <name>` spelling is rejected as a Branch selector. The target directory defaults to the project display name/name, or pass `[dir]` explicitly.
20
20
  - **`delete`** — destructive; prompts unless `-y`. Removes the remote site.
21
21
  - **`publish` / `unpublish`** — toggle the project's public visibility. `publish` flips the configured Production source state live (the same "go live" as `fimo deploy --publish`, minus the git push).
22
22
  - **`rename`** — edits only the linked local project's `seo.siteName`. It does not commit or deploy. It requires a project marker in the cwd, and if you pass a `[projectId]` that doesn't match the linked project it errors and exits 1 (so you can't rename a different project). Later remote config commands may require reconciliation while the local config is dirty. Finish your local edits, then explicitly run `fimo deploy --no-wait` when ready for a quick sync.