fimo 2.10.1-staging.1 → 2.10.1-staging.3

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 (43) hide show
  1. package/assets/skills/fimo-cli/SKILL.md +57 -139
  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 +48 -0
  5. package/assets/skills/fimo-cli/references/content/entries.md +54 -0
  6. package/assets/skills/fimo-cli/references/content/localized.md +56 -0
  7. package/assets/skills/fimo-cli/references/content/schemas.md +29 -0
  8. package/assets/skills/fimo-cli/references/content/sql.md +57 -0
  9. package/assets/skills/fimo-cli/references/content.md +33 -272
  10. package/assets/skills/fimo-cli/references/deploy.md +35 -126
  11. package/assets/skills/fimo-cli/references/domains.md +38 -131
  12. package/assets/skills/fimo-cli/references/forms.md +1 -1
  13. package/assets/skills/fimo-cli/references/init.md +36 -170
  14. package/assets/skills/fimo-cli/references/locales.md +2 -2
  15. package/assets/skills/fimo-cli/references/projects.md +1 -1
  16. package/assets/skills/fimo-code/references/design.md +42 -126
  17. package/assets/skills/fimo-migration/SKILL.md +114 -408
  18. package/assets/skills/fimo-migration/references/content-delivery.md +67 -0
  19. package/assets/skills/fimo-migration/references/frameworks/nextjs.md +1 -1
  20. package/assets/skills/fimo-migration/references/qa/browser.md +41 -0
  21. package/assets/skills/fimo-migration/references/qa/guardrails.md +95 -0
  22. package/assets/skills/fimo-migration/references/qa/results.md +78 -0
  23. package/assets/skills/fimo-migration/references/qa.md +102 -383
  24. package/assets/skills/fimo-migration/references/questions-and-improvements.md +77 -168
  25. package/assets/skills/fimo-migration/references/setup.md +90 -0
  26. package/assets/skills/fimo-migration/references/workers/validator.md +2 -2
  27. package/assets/skills/fimo-migration/references/workers.md +1 -1
  28. package/assets/skills/fimo-migration/references/workflow.md +117 -171
  29. package/assets/skills/fimo-studio/SKILL.md +12 -11
  30. package/assets/skills/fimo-studio/references/ai-chat/agents.md +46 -0
  31. package/assets/skills/fimo-studio/references/ai-chat/default-agents.md +57 -0
  32. package/assets/skills/fimo-studio/references/ai-chat/routines.md +53 -0
  33. package/assets/skills/fimo-studio/references/ai-chat.md +39 -76
  34. package/assets/skills/fimo-studio/references/custom-domains.md +2 -2
  35. package/assets/skills/fimo-studio/references/publish-and-deploy.md +1 -1
  36. package/dist/cli/bundle.json +1 -1
  37. package/dist/cli/index.js +38 -17
  38. package/package.json +8 -8
  39. package/templates/astro/package.json +3 -3
  40. package/templates/nextjs/package.json +4 -4
  41. package/templates/react-router/package.json +5 -5
  42. package/templates/sveltekit/package.json +3 -3
  43. package/templates/vite/package.json +5 -5
@@ -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. 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").
@@ -13,7 +13,7 @@ fimo locales set-default es --yes --json
13
13
  fimo locales remove es --yes --json
14
14
  ```
15
15
 
16
- In a linked project, change the locale set or default only through these commands or Studio Settings. Never edit `i18n.defaultLocale` or `i18n.locales` directly. Studio chat can run `locales list`.
16
+ In a linked project, change the locale set or default only through these commands or Studio Settings. Never edit `i18n.defaultLocale` or `i18n.locales` directly. Fimo chat in Studio and Slack can run `locales list` and `locales add`; removing a locale or changing the default stays with a site manager.
17
17
 
18
18
  These commands update the selected Branch through the locale lifecycle API. The API commits `.fimo/config.json` to the Fimo Branch, then the CLI synchronizes the **whole local branch** to that commit. They refuse a dirty config, a local-ahead branch, or a diverged branch before applying the remote change. `--yes` bypasses only the explanatory prompt.
19
19
 
@@ -123,4 +123,4 @@ Labels and content are separate translated surfaces:
123
123
 
124
124
  Omit `--locale` for default-locale writes. Pass `--locale <locale>` for each non-default localized entry you need to create or update. Shared schemas (`i18n.enabled: false`) have one locale-free entry instead.
125
125
 
126
- Inside a localized schema, a single field can still be shared across every language with `"i18n": false` — use it for values that are not translated, such as a price or a SKU, so they are written once instead of per locale. See `content.md` § Shared fields inside a localized type.
126
+ Inside a localized schema, a single field can still be shared across every language with `"i18n": false` — use it for values that are not translated, such as a price or a SKU, so they are written once instead of per locale. See `references/content/localized.md`.
@@ -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.
@@ -1,142 +1,58 @@
1
1
  # Design
2
2
 
3
- Distinctive, production-grade frontend interfaces with high design quality. Avoid generic AI aesthetics. Read this before any non-trivial visual work — first generation of a site, redesigns, visual overhauls, or vague requests like "make this look better."
3
+ Read this before major visual work: the first design of a site, a redesign, a visual overhaul, or a vague request such as "make this look better". Skip it for bug fixes, refactors and copy changes.
4
4
 
5
- Skip for: bug fixes, refactors, copy changes, or tasks where the user has already specified visual details (exact fonts, colors, layout).
5
+ When the user gives exact visual details (fonts, colors, layout), skip the brief and build what they asked. Do not replace their choices with the taste rules below.
6
6
 
7
- For source-tracked React primitives, see `references/ui.md` plus the detected framework reference. Preserve the application's existing styling, routing, and component conventions. This file is about aesthetic and creative direction.
7
+ Keep the application's styling, routing and component conventions. For tracked React primitives, see `references/ui.md` and the framework reference.
8
8
 
9
9
  ## Brief first, code second
10
10
 
11
- For non-trivial visual work, produce a short design brief before writing code, using the brief template below. Then implement against the brief.
11
+ Before you write code, write a short design brief with the sections in [The brief](#the-brief). Then build against it.
12
12
 
13
- ## Design thinking
13
+ Pick one clear direction and execute it with precision:
14
14
 
15
- Before coding, understand the context and commit to a BOLD aesthetic direction:
15
+ - **Purpose:** what the interface does, and for whom.
16
+ - **Tone:** one strong direction, for example brutally minimal, maximalist, retro-futuristic, organic, luxury, playful, editorial, brutalist, art deco, soft pastel or industrial.
17
+ - **The one thing:** what a visitor will remember.
18
+ - **Constraints:** framework, performance, accessibility.
16
19
 
17
- - **Purpose**: What problem does this interface solve? Who uses it?
18
- - **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. Use these for inspiration but design one true to the aesthetic direction.
19
- - **Constraints**: Technical requirements (framework, performance, accessibility).
20
- - **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
20
+ Bold maximalism and refined minimalism both work: intention matters, not intensity. Match the code to the vision: maximalism needs elaborate code and motion; minimalism needs precise spacing and type.
21
21
 
22
- **Choose a clear conceptual direction and execute it with precision.** Bold maximalism and refined minimalism both work — the key is intentionality, not intensity.
22
+ ## Rules
23
23
 
24
- ## Frontend aesthetics guidelines
24
+ - **Typography:** pair a distinctive display font with a refined body font. Use at most two families. Do not use Inter, Roboto, Arial or system fonts as the design's voice. Vary fonts between sites; do not fall back to a "safe" choice such as Space Grotesk.
25
+ - **Color:** a dominant color with sharp accents, not an even, timid palette. Keep saturated colors for small actionable elements. Keep WCAG AA contrast: 4.5:1 for body text, 3:1 for large text. Put palette values in the project's existing theme tokens (for example Tailwind `@theme` or CSS variables) and use the tokens in components. Do not hard-code colors in components.
26
+ - **Motion:** prefer CSS; use the Motion library in React when the project has it. One orchestrated page load with staggered reveals is better than many small effects. Add scroll reveals and hover states that surprise.
27
+ - **Layout:** asymmetry, overlap, diagonal flow, elements that break the grid. Contrast tight clusters with generous space.
28
+ - **Backgrounds and detail:** give depth and atmosphere (gradient meshes, noise, patterns, layered transparency, strong shadows, decorative borders, grain) instead of flat fills.
29
+ - **Vary:** alternate light and dark themes, fonts and aesthetics between sites.
25
30
 
26
- - **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt for distinctive choices. Pair a distinctive display font with a refined body font. Limit to 2 font families total.
27
- - **Color & Theme**: Commit to a cohesive aesthetic. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. Reserve high-saturation colors for small actionable elements (icons, charts, buttons). Maintain WCAG AA contrast (4.5:1 body, 3:1 large text). Put palette values in the project's existing theme tokens instead of hard-coding colors in components.
28
- - **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions; use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
29
- - **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density. Dramatic whitespace contrast: tight clusters + generous breathing room.
30
- - **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors — gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, grain overlays.
31
-
32
- NEVER use generic AI-generated aesthetics: overused font families (Inter, Roboto, Arial, system fonts), clichéd color schemes (especially purple gradients on white backgrounds), predictable layouts, cookie-cutter design.
33
-
34
- Interpret creatively and make unexpected choices. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
35
-
36
- **Match implementation complexity to the aesthetic vision.** Maximalist designs need elaborate code with extensive animations. Minimalist designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
37
-
38
- ---
31
+ **Generic AI patterns to avoid:** everything centered, purple gradients on white, uniform card grids, a generic hero, gray `slate-900` dark mode (use true or warm blacks), emoji decoration, safe blue pill buttons, a 4-column footer, stock blob illustrations, even spacing everywhere, "Welcome to X" headlines. In a brief, do not paste this list: name what would look wrong for this site.
39
32
 
40
33
  ## Reference anchors
41
34
 
42
- Reference sites to anchor the aesthetic direction. Pull any well-known site, brand, or design studio that fits the project.
43
-
44
- | Category | Example Anchors | Quality Bar |
45
- | ------------------------ | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
46
- | **Creative / Agency** | Awwwards, FWA, CSS Design Awards, Pentagram, Sagmeister & Walsh, Active Theory, Fantasy Interactive, Resn | Would it win Awwwards SOTD? Would Pentagram put this in their portfolio? |
47
- | **SaaS / Product** | Linear, Stripe, Notion, Figma, Raycast, Arc Browser, Supabase, Mercury, Clerk, Loom, Pitch | Is it Linear-polished? Would a developer tweet "their site is so clean"? |
48
- | **Editorial / Blog** | Medium, Substack, The Verge, NYT, The Atlantic, Monocle, It's Nice That, Eye on Design, Wired | Would The Verge's design team respect this? Is it magazine-worthy? |
49
- | **E-commerce** | Apple Store, Shopify Dawn, Gumroad, Everlane, Glossier, SSENSE, Mr Porter, Mejuri, Allbirds | Does it feel Apple Store premium? Would you trust buying from this? |
50
- | **Documentation** | Stripe Docs, Tailwind Docs, Supabase Docs, Prisma Docs, Algolia Docs, Clerk Docs | Is it Stripe Docs clear? Can a developer find what they need in 3 seconds? |
51
- | **Personal / Portfolio** | Read.cv, Paco Coursey, Josh Comeau, Rauno Freiberg, Brian Lovin, Lee Robinson, Linus Rogge | Would Read.cv feature this? Is it memorable and distinctly personal? |
52
- | **Corporate** | Apple, Stripe, Airbnb, Slack, Square, Intercom, Dropbox, Zendesk | Does it feel Airbnb-trustworthy? Premium but not flashy? |
53
- | **Dashboard** | Linear, Figma, Raycast, Retool, Rows, Height, Airtable, Coda | Is it Linear-efficient? Dense but never cluttered? |
54
- | **Landing Pages** | Framer templates, Webflow Showcase, Lapa.ninja, One Page Love, SaaS Landing Page | Would this be featured on Lapa.ninja? Does it convert and delight? |
55
-
56
- ---
57
-
58
- ## AI slop patterns to avoid
59
-
60
- | Pattern to Avoid | Do This Instead |
61
- | --------------------------------- | ---------------------------------------------------------------------- |
62
- | Centered everything | Asymmetry, left-alignment, off-center compositions |
63
- | Purple gradients on white | Unexpected colors: olive, terracotta, deep blue, warm neutrals |
64
- | Uniform card grids | Varied sizes, bento layouts, overlapping elements, broken grids |
65
- | Static pages | Scroll reveals, hover states, page transitions, micro-interactions |
66
- | Inter / Roboto / Arial everywhere | Display fonts for headings, serif accents, personality in type |
67
- | Generic hero layout | Editorial, asymmetric, full-bleed, split-screen, video backgrounds |
68
- | Gray dark mode (slate-900) | True blacks, warm darks (#1A1A1A), tinted backgrounds |
69
- | Emoji overuse (🚀✨🎉) | Subtle iconography, typography-only, or strategic single emoji |
70
- | Safe blue pill buttons | Contextual styling, ghost buttons, text links, unusual shapes |
71
- | Cookie-cutter 4-column footer | Footer as a design moment: personality, newsletter CTAs, minimal |
72
- | Stock blob illustrations | Photography, 3D renders, custom illustrations, or no illustrations |
73
- | Evenly distributed spacing | Dramatic whitespace contrast: tight clusters + generous breathing room |
74
- | Generic "Welcome to X" headlines | Personality, questions, bold statements, single impactful words |
75
- | Converging on Space Grotesk | Vary font choices across generations — never default to a "safe" pick |
76
-
77
- When you list "Avoid" items in a design brief, be specific to the project context. Don't paste these generic items — explain what would look bad for THIS site.
78
-
79
- ---
80
-
81
- ## Design brief template
82
-
83
- Use this structure for the brief produced **before** writing code on a non-trivial visual task. Keep each section short — bullets, not paragraphs.
84
-
85
- ### Vibe
86
-
87
- One sentence describing the aesthetic direction + 2–3 reference anchors.
88
- Example: "**Linear meets Stripe** — polished SaaS with premium editorial touches"
89
-
90
- - Reference 1 (what aspect)
91
- - Reference 2 (what aspect)
92
- - Reference 3 (what aspect)
93
-
94
- ### Typography
95
-
96
- - **Like:** Reference site(s) for typography inspiration
97
- - **Headings:** Font name (e.g., "Satoshi Bold", "Space Grotesk", "Fraunces")
98
- - **Body:** Font name (e.g., "Geist", "Source Serif Pro", "IBM Plex Sans")
99
- - **Hierarchy:** Size contrast notes, weight usage, letter-spacing
100
-
101
- ### Color & Theme
102
-
103
- - **Like:** Reference site(s) for color inspiration
104
- - **Background:** Primary background color (hex)
105
- - **Foreground:** Primary text color (hex)
106
- - **Accent:** Primary accent color (hex)
107
- - **Secondary accents:** Additional colors if needed
108
- - **Dark mode:** Direction for dark mode palette (if applicable)
109
-
110
- Write these into the project's existing theme tokens and reference the tokens from components.
111
-
112
- ### Motion & Interaction
113
-
114
- - **Like:** Reference site(s) for motion inspiration
115
- - **Page load:** Stagger, fade, slide
116
- - **Scroll:** Parallax, reveals, sticky elements
117
- - **Hover:** Card lifts, color shifts, micro-animations
118
- - **Transitions:** Page transitions, state changes
119
-
120
- ### Photography & Media
121
-
122
- - **Like:** Reference site(s) for media direction
123
- - **Style:** Cinematic, lifestyle, abstract, illustrated, minimal
124
- - **Treatment:** Full-bleed, contained, overlays, filters
125
- - **Hero:** Specific direction for hero imagery
126
-
127
- If the user hasn't supplied images and one is needed, run `fimo image generate --prompt "..."` and reuse the returned `url` or `id`. Run `fimo image generate --help` for current flags. Upload any image that exists only as a local file before using it (`SKILL.md` § Non-negotiable boundaries). See `references/assets.md`.
128
-
129
- ### Iconography
130
-
131
- - **Like:** Reference site(s) for icon style
132
- - **Style:** Line icons, filled, duotone, custom
133
- - **Library:** the icon set the project already uses, a custom set, or none
134
- - **Usage:** Sparse and meaningful vs. decorative
135
-
136
- ### Quality Bar
137
-
138
- Pick the row from the Reference Anchors table that matches this project's category and quote its quality-bar question.
139
-
140
- ### Avoid
141
-
142
- List 3–5 specific patterns to NOT use for this project. Be specific to this project's context — don't paste generic items from the AI Slop Patterns table.
35
+ Anchor the direction on 2–3 well-known sites, brands or studios that fit the project. Examples per category, with the quality bar:
36
+
37
+ - **Creative / agency:** Awwwards winners, Pentagram, Active Theory. Would it win Awwwards Site of the Day?
38
+ - **SaaS / product:** Linear, Stripe, Raycast, Supabase, Mercury. Is it Linear-polished?
39
+ - **Editorial / blog:** The Verge, Monocle, The Atlantic, Substack. Is it magazine-worthy?
40
+ - **E-commerce:** Apple Store, Glossier, SSENSE, Everlane. Would you trust buying from it?
41
+ - **Documentation:** Stripe Docs, Tailwind Docs, Supabase Docs. Can a developer find what they need in 3 seconds?
42
+ - **Personal / portfolio:** Read.cv, Rauno Freiberg, Josh Comeau. Is it memorable and personal?
43
+ - **Corporate:** Apple, Airbnb, Slack, Intercom. Premium but not flashy?
44
+ - **Dashboard:** Linear, Retool, Airtable. Dense but never cluttered?
45
+ - **Landing page:** Framer templates, Lapa.ninja features. Does it convert and delight?
46
+
47
+ ## The brief
48
+
49
+ Keep each section to a few bullets.
50
+
51
+ - **Vibe:** one sentence and 2–3 anchors, each with the aspect you take from it (for example "Linear meets Stripe: polished SaaS with editorial touches").
52
+ - **Typography:** the sites you take type from; heading font; body font; hierarchy (size contrast, weights, letter-spacing).
53
+ - **Color & Theme:** the sites you take color from; background, foreground, accent and secondary colors as hex values; dark mode direction. Write them into the theme tokens.
54
+ - **Motion & Interaction:** the sites you take motion from; page load, scroll, hover and transitions.
55
+ - **Photography & Media:** the sites you take media from; style, treatment and hero direction. When the user has no image and one is needed, run `fimo image generate --prompt "..."` and use the returned `url` or `id` (`fimo image generate --help` lists the flags). Do not generate a real photo of a real thing (the team, a product): ask the user for it. Upload a local image file with `fimo assets upload` before you use it (`SKILL.md` § Non-negotiable boundaries lists the files that stay in the repository; `references/assets.md`).
56
+ - **Iconography:** the sites you take icons from; style (line, filled, duotone, custom); the set (the project's existing set, a custom set, or none); sparse and meaningful, or decorative.
57
+ - **Quality Bar:** the anchor category of this project and its question.
58
+ - **Avoid:** 3–5 patterns that would look wrong for this site.