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.
- package/assets/skills/fimo-cli/SKILL.md +2 -2
- package/assets/skills/fimo-cli/SKILL.studio.md +42 -0
- package/assets/skills/fimo-cli/references/branches.md +43 -106
- package/assets/skills/fimo-cli/references/content/bulk.md +3 -12
- package/assets/skills/fimo-cli/references/content/localized.md +1 -1
- package/assets/skills/fimo-cli/references/content/sql.md +3 -10
- package/assets/skills/fimo-cli/references/deploy.md +35 -126
- package/assets/skills/fimo-cli/references/domains.md +38 -131
- package/assets/skills/fimo-cli/references/init.md +36 -170
- package/assets/skills/fimo-cli/references/projects.md +1 -1
- package/assets/skills/fimo-code/references/design.md +42 -126
- package/assets/skills/fimo-migration/SKILL.md +114 -408
- package/assets/skills/fimo-migration/references/content-delivery.md +67 -0
- package/assets/skills/fimo-migration/references/frameworks/nextjs.md +1 -1
- package/assets/skills/fimo-migration/references/qa/browser.md +41 -0
- package/assets/skills/fimo-migration/references/qa/guardrails.md +95 -0
- package/assets/skills/fimo-migration/references/qa/results.md +78 -0
- package/assets/skills/fimo-migration/references/qa.md +102 -383
- package/assets/skills/fimo-migration/references/questions-and-improvements.md +77 -168
- package/assets/skills/fimo-migration/references/setup.md +90 -0
- package/assets/skills/fimo-migration/references/workers/validator.md +2 -2
- package/assets/skills/fimo-migration/references/workers.md +1 -1
- package/assets/skills/fimo-migration/references/workflow.md +117 -171
- package/assets/skills/fimo-studio/SKILL.md +4 -1
- package/assets/skills/fimo-studio/references/ai-chat/agents.md +46 -0
- package/assets/skills/fimo-studio/references/ai-chat/default-agents.md +57 -0
- package/assets/skills/fimo-studio/references/ai-chat/routines.md +53 -0
- package/assets/skills/fimo-studio/references/ai-chat.md +39 -76
- package/assets/skills/fimo-studio/references/custom-domains.md +2 -2
- package/assets/skills/fimo-studio/references/publish-and-deploy.md +1 -1
- package/dist/cli/bundle.json +2 -2
- package/dist/cli/index.js +32 -11
- package/package.json +8 -8
- package/release.json +2 -2
- package/templates/astro/package.json +3 -3
- package/templates/nextjs/package.json +4 -4
- package/templates/react-router/package.json +5 -5
- package/templates/sveltekit/package.json +3 -3
- package/templates/vite/package.json +5 -5
|
@@ -1,154 +1,61 @@
|
|
|
1
1
|
# Domains
|
|
2
2
|
|
|
3
|
-
`fimo domains`
|
|
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
|
-
|
|
|
6
|
-
|
|
|
7
|
-
|
|
|
8
|
-
|
|
|
9
|
-
|
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
#
|
|
17
|
-
fimo domains
|
|
18
|
-
fimo domains
|
|
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
|
-
|
|
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
|
-
|
|
25
|
+
### Cleaner default URL before the first publish
|
|
81
26
|
|
|
82
|
-
|
|
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.
|
|
85
|
-
2.
|
|
86
|
-
3.
|
|
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
|
-
|
|
33
|
+
Choosing the slug does not publish the site. The URL resolves after the first successful publish.
|
|
89
34
|
|
|
90
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
59
|
+
The CLI refuses names that the registrar prices as premium: suggest another name.
|
|
148
60
|
|
|
149
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
144
|
-
pnpm dev & # or npm run dev / yarn dev / bun dev — the project's package manager
|
|
145
|
-
```
|
|
18
|
+
## Defaults
|
|
146
19
|
|
|
147
|
-
|
|
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
|
-
##
|
|
25
|
+
## What init writes
|
|
150
26
|
|
|
151
|
-
|
|
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
|
-
|
|
33
|
+
## Right after init
|
|
154
34
|
|
|
155
|
-
|
|
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
|
-
|
|
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
|
-
|
|
44
|
+
## First hosted preview
|
|
164
45
|
|
|
165
|
-
|
|
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
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
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
|
|
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.
|