fimo 2.9.0-staging.3 → 2.9.0-staging.4

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

@@ -153,7 +153,7 @@ These fire at specific moments in the project lifecycle. **Surface them proactiv
 - **Bare `fimo init` in a non-interactive shell** — will hang. Always pass `[dir]`, `--no-install` (or `--install`), `--no-skills` (or `--skills`), and `--org`/`--agents` as needed explicitly when scripted.
 - **Hardcoding content / strings / images in code, or committing image and video files** — that's what schemas, `t()`, and the media library are for. See the `fimo-code` skill's non-negotiable boundaries.
 - **Adding another deploy tool**. Fimo handles deploys; don't bolt another platform on.
-- **Committing secrets** — hidden values use `fimo secrets`; public browser-safe values use `fimo vars`. Local env files are ignored and must not become deploy inputs.
+- **Committing secrets or storing API keys as public variables** — server-side keys use `fimo vars add --private`; Fimo-only credentials use `fimo secrets`; public browser-safe values use `fimo vars`. Local env files are ignored and must not become deploy inputs.
 - **Hardcoding tokens in flags** — use the credentials written by `fimo login` (one file per backend at `~/.config/fimo/credentials/<host>-<hash>.json`).
 - **Treating the daily allowance as extra credits** — the allowance section appears only for legacy Premium organizations, and `fimo credits` already includes its spendable credits in "Available now"; it is accounting context, not an amount to add.
 - **Trying to refill credits from the CLI** — `fimo credits` is read-only. Buying/refilling credits belongs in the billing UI for now.

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

@@ -22,7 +22,7 @@ fimo deploy -m "<commit message>" --publish  # also publish a new live version
 - **`fimo deploy`** — commits pending changes, pushes to the current Branch, syncs that Branch's preview sandbox, and links to Fimo Studio.
 - **`fimo deploy --publish`** — same as above, then triggers a live publish and prints the live URL. Runs from the configured Production source Branch only. **Only use `--publish` when the user signals "ship it"** — first-time site completion, or an explicit "publish" / "go live" request. Otherwise stick to plain `fimo deploy`. (For a _versioned_ prod release, use `fimo publish` instead — see below.)
 - **`-m`** is the commit message used when there are uncommitted local changes; required in non-interactive shells. Omit if the working tree is already clean.
-- **`--no-restart`** — tells the sandbox to skip the dev-server restart and let Vite HMR pick up the change. Shaves ~3s per deploy. See "Skipping the dev-server restart" below for when it's safe.
+- **`--no-restart`** — tells the sandbox to skip the dev-server restart and let Vite HMR pick up the change. Shaves ~3s per deploy. A deploy that carries changed variables restarts anyway. See "Skipping the dev-server restart" below for when it's safe.
 
 ## Reading deploy destinations
 
@@ -43,7 +43,7 @@ Read these fields from `data`:
 
 When reporting the result, give the user `studio_url`. If a person or tool needs the hosted site itself, run `fimo preview url` after deploy.
 
-Public project variables managed with `fimo vars add` and `fimo vars update` are injected into preview/build/deploy runtimes. Project secrets are not injected into app builds; agents request secrets separately through their own config. See `references/project-vars-and-secrets.md`.
+Public variables are injected into preview, build, and deploy runtimes. Private variables (`fimo vars add --private`) reach the site's server code at runtime in previews and production, never an env file or the browser bundle. Secrets are not injected into the site; agents request them separately through their own config. See `references/project-vars-and-secrets.md`.
 
 ## Diagnose a failed publication
 

package/assets/skills/fimo-cli/references/project-vars-and-secrets.md

@@ -1,8 +1,10 @@
 # Project Variables And Secrets
 
-Use project variables for values that are safe to expose to the browser. Use project secrets for hidden values such as API keys, tokens, webhooks, and service credentials.
+Three kinds of values, each set per Environment (production, preview, or a custom Environment):
 
-There is no private-variable mode. If leaking the value would be a problem, use `fimo secrets`.
+- **Public variables** — safe to expose to the browser.
+- **Private variables** — API keys and tokens the site's own server code reads. Write-only after saving.
+- **Secrets** — credentials Fimo itself uses for webhooks, schedules, and agents. Never sent to the site.
 
 ## Public Variables
 
@@ -24,8 +26,29 @@ fimo vars pull .env.e2e
 
 Fimo only edits the block between `# fimo:vars:start` and `# fimo:vars:end`. User-authored lines in the file stay untouched.
 
-Variables are public by design. They may use browser-safe prefixes such as
-`VITE_`, `PUBLIC_`, `NEXT_PUBLIC_`, or `NUXT_PUBLIC_`.
+Public variables may use browser-safe prefixes such as `VITE_`, `PUBLIC_`, `NEXT_PUBLIC_`, or `NUXT_PUBLIC_`.
+
+## Private Variables
+
+Use a private variable for any key the site's server code needs: payment, email, search admin, or database credentials.
+
+```bash
+fimo vars add STRIPE_SECRET_KEY --private --stdin
+fimo vars update STRIPE_SECRET_KEY --stdin
+fimo vars unset STRIPE_SECRET_KEY
+```
+
+- The value is never shown again; `fimo vars list` masks it.
+- `fimo vars pull` never writes the value. For each private key not already set in the file, it writes a comment inside the managed block: `# STRIPE_SECRET_KEY is a private variable: add a local value outside this block`. When you see one, ask the user for a local test value (never the production one) and add `STRIPE_SECRET_KEY=...` to `.env.local` **outside** the `# fimo:vars:start` / `# fimo:vars:end` block, where `fimo vars pull` will not overwrite it. Do not paste a value into the managed block; the next pull removes it.
+- If the user has no local value, local server code reading the key gets `undefined`. Previews and production still get the stored value.
+- The site's server code reads it as `process.env.STRIPE_SECRET_KEY` in the Studio preview, hosted previews, production and schedule runs. Fimo never writes it to an env file or the browser bundle.
+- Fimo agents' shell commands do not receive private values, and output that would show one is redacted. Test a server route through the preview instead of reading the key from a shell.
+- A dev server whose Environment is Production never gets production private values.
+- Private variables cannot use browser prefixes (`VITE_`, `PUBLIC_`, `NEXT_PUBLIC_`, `NUXT_PUBLIC_`). Read them only from server code.
+- Set one value per Environment: a test key for preview, the live key for production.
+- Public or private is chosen when the variable is created. To switch, unset it and add it again.
+- A changed or removed variable applies on the next deploy: run `fimo deploy` for previews (with no new commit, it restarts the preview and rebuilds the hosted preview when variables changed) and `fimo publish` for the live site. After changing variables for the user, offer that redeploy.
+- Names that control processes (`PATH`, `NODE_ENV`, `NODE_OPTIONS`, `HTTPS_PROXY`, `GIT_*`, `NPM_CONFIG_*` and similar) are refused for new private variables, and a public variable with such a name never reaches the site's processes or the `.env.local` written by `fimo vars pull`.
 
 ## Secrets
 
@@ -40,10 +63,7 @@ fimo secrets unset FIRECRAWL_API_KEY
 Secret values are hidden after write. Listing secrets shows the key and a masked value, never the plaintext.
 `fimo secrets add` refuses to replace an existing value. Use `fimo secrets update` for an intentional rotation.
 
-Secrets are not written to `.env.local`, preview app env files, browser bundles,
-or generated project files. Secrets cannot use public prefixes such as `VITE_`,
-`PUBLIC_`, `NEXT_PUBLIC_`, or `NUXT_PUBLIC_`; those prefixes are for public
-variables.
+Secrets are for Fimo itself: webhook headers, schedule runs, and agents. They are never sent to the site, its builds, or its env files. Secrets cannot use public prefixes such as `VITE_`, `PUBLIC_`, `NEXT_PUBLIC_`, or `NUXT_PUBLIC_`.
 
 ## Local Env Files
 
@@ -57,5 +77,7 @@ Local env files are ignored by git in Fimo sites. They are for local development
 
 ## Choosing Between Them
 
-- If the value can safely be visible in browser code or page source, use `fimo vars add`.
-- If leaking the value would be a problem, use `fimo secrets add`.
+- Safe to show in browser code or page source: `fimo vars add`.
+- An API key the site's server code calls with: `fimo vars add --private`.
+- A credential only a webhook, schedule, or agent uses: `fimo secrets add`.
+- Never store an API key as a public variable.

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

@@ -36,7 +36,7 @@ Use plain, friendly language. Describe what users see, where they click, and wha
 
 - **Header (desktop):** the site menu (site name; History is here) and the Branch switcher, then the workspaces: Chats, Getting started, Preview, Content, Assets, Analytics, Settings. Only workspaces the user can access appear. Workspaces that do not fit move into **More**. On the right: Earn free credits, Invite, Clone, Publish, and Merge on a Branch.
 - **Phone:** bottom tabs for Chat, Preview and Settings. Invite, Earn free credits and Clone ("Work on this site locally") move into the site menu.
-- **Settings:** General, Domains, Knowledge, SEO and Languages are listed directly. Models, Environments, Secrets, Schedules, Webhooks and Connections are under **Advanced settings**.
+- **Settings:** General, Domains, Knowledge, SEO and Languages are listed directly. Models, Environments, Variables, Secrets, Schedules, Webhooks and Connections are under **Advanced settings**.
 - **Shortcuts:** Alt+1 Preview, Alt+2 Content, Alt+3 Assets, Alt+5 Settings, Alt+E edit mode, Cmd/Ctrl+K command palette.
 
 When a reference says "open X", X can be inside **More** on a narrow window.
@@ -56,6 +56,7 @@ Read the relevant reference file when the user's question matches a topic.
 | AI Chat                  | references/ai-chat.md                   | "What can the AI do?", "How do I give context?"                        |
 | Site Knowledge           | references/knowledge.md                 | "Set brand guidance", "Website goals", "Draft knowledge from the site" |
 | SEO Settings             | references/seo-settings.md              | "How do I set up SEO?", "Favicon, title, share image"                  |
+| Variables & Secrets      | references/variables-and-secrets.md     | "Where do I put an API key?", "Public or private variable?"            |
 | Schedules                | references/schedules.md                 | "Recurring commands", "Run history", "Run now"                         |
 | Webhooks                 | references/webhooks.md                  | "React to forms", "Send events to another service"                     |
 | Connections              | references/connections.md               | "Connect a service", "Add an MCP server"                               |
@@ -77,6 +78,7 @@ Read the relevant reference file when the user's question matches a topic.
 | Webhooks                | Site secrets, Forms, Publishing                                      |
 | Connections             | AI Chat, Site secrets                                                |
 | Schedules               | Site secrets, Environments                                           |
+| API keys                | Variables (private), Site secrets                                    |
 | Visual changes          | Edit Mode (CMS content), AI Chat (layout, styling, and code changes) |
 | Something went wrong    | Version History, AI Chat                                             |
 | Working with others     | Sharing, Collaboration                                               |

package/assets/skills/fimo-studio/references/ai-chat.md

@@ -10,7 +10,7 @@ Chat has its own **Chats** tab in the site header; the tab shows how many chats
 
 Agents and routines appear only when the organization has the agents feature, which is off by default in production. Without it, the **+** above the chat list opens a new chat directly, agent settings have no **Routines**, and existing routines do not run; ask Fimo support to enable it. The plan decides the agents (FIMO-2856): Free has the SEO and GEO default agents, each running only its weekly checkup (**Weekly SEO checkup**, **Weekly AI check**), and its agent settings list the routines Starter adds with **See plans**; Starter (pay-as-you-go) has every default agent with its detailed routines, and a change wakes each routine at most once a day (the changes made meanwhile wait and the next run, a day after the last one started, checks them together; the routine's next run shows when, and **Run now** and schedules never wait); Pro runs them right after each change and adds agents of one's own (**New agent**). In the **+** menu, what the plan does not include shows **Upgrade** and opens the plans. Default agents are Fimo's: their routines follow Fimo's instructions, only switch off and on or get deleted (a deleted one stays deleted), and nothing is added to them (`routine_is_default`); routines of one's own live in a custom agent, on Pro (`routine_needs_pro` below Pro). A default agent's name, description and portrait cannot be changed on any plan, and a custom agent's change only on Pro: below Pro its settings are read-only, say its routines are paused and offer **See plans**, and it can still be deleted. A plan change changes which agents open and which routines run; agents, routines and past runs stay. Fimo support can give an organization Pro's agents on any plan. A routine Fimo retires from a default agent stops running and leaves the list.
 
-An agent is a chat with a job: a name and a description that Fimo reads at the start of every reply in that chat. Agents are shared like any chat and are listed as soon as they are created, with an **Agent** tag after the name. The **+** above the chat list is a menu: **New chat** (blank), **New agent** (a name and a description, then the empty agent opens), and under **Agents** Fimo's default agents (**SEO**, **GEO**, **Content**, **Quality**, **Compliance**); a new site starts with SEO and GEO listed, their routines active from the start; Content, Quality and Compliance, and every default on an older site, are created the first time someone selects them, routines active, the same chat every time after. In an agent, the description shows next to its name in the header (one line) and the empty state introduces the agent by name and job (the description's first three lines); a cut description shows whole on hover, or on tap on a phone, and the message box reads **Message <name>**. The agent's settings page has a **Description** field, shared with everyone; empty means none. The filter icon's **Kind** option shows only chats or only agents; search finds an agent by its name.
+An agent is a chat with a job: a name and a description that Fimo reads at the start of every reply in that chat. Agents are shared like any chat and are listed as soon as they are created, with an **Agent** tag after the name. The **+** above the chat list is a menu: **New chat** (blank), **New agent** (a name and a description, then the empty agent opens), and under **Agents** Fimo's default agents (**SEO**, **GEO**, **Content**, **Quality**, **Compliance**); a new site starts with SEO and GEO listed, their routines active from the start; Content, Quality and Compliance, and every default on an older site, are created the first time someone selects them, routines active, the same chat every time after. In an agent, the header shows the name alone and the empty state introduces the agent by name and job (the description's first three lines); a cut description shows whole on hover, or on tap on a phone, and the message box reads **Message <name>**. The agent's settings page has a **Description** field, shared with everyone; empty means none. The filter icon's **Kind** option shows only chats or only agents; search finds an agent by its name.
 
 The **SEO** default runs six routines backed by Studio's built-in `fimo-seo` skill, which checks the site as a browser renders it and fixes at the source: **Technical SEO** (status, redirects, canonicals, sitemap, robots.txt, language, main heading, and changes since its last run: pages moved without a redirect), **Broken links**, **Meta tags** (titles, descriptions, Open Graph, the site's title ending, length in characters and pixels), **Image SEO** (alt text, file names, images over 200 KB: one in the media library or the site's own files is rendered through Fimo's resizing on its own, a file of the site uploaded first), **Hreflang** (only on a site in more than one language) and **Internal linking** (orphan and deep pages, articles with no link up to a hub or product page or more than eight links). Each default routine wakes on the changes on main that can matter to it, before a publish (CMS edits, code changes, images, languages, forms; the first publish and a new domain for Technical SEO and Cookie consent): a small model reads each change first, so a quiet site runs nothing, and the run checks what changed (the whole site on its first run). Only what changes without anyone touching the site keeps a schedule: Broken links checks outbound links on the 1st of every month, Content refresh runs on the 2nd, Content lifecycle every three months, Privacy and legal pages once a year. A page it changed is left alone for 8 weeks, the time Google takes to show the effect. A fix with one right answer from the page's own words is made without a message (a link only once the new target is checked to be the same content in the same language; a link on words the text already uses to name another page; a 301 from a page's old address once the same page is live at a new one); a change to what visitors read, which page wins a search, whether a page exists, a redirect with more than one possible target, a price or a legal page is asked as a decision; page removals and the robots policy are never changed on its own. A change a person asks for in a chat is made. What a check could not tell (a timeout, a 5xx, a page past the crawl limit) is never acted on: the run retries once, then says the check was incomplete.
 

package/assets/skills/fimo-studio/references/variables-and-secrets.md

@@ -0,0 +1,16 @@
+# Variables and secrets
+
+Both live under **Settings → Advanced settings**. Only members with Full Access can add, change, or remove them. Each value belongs to one Environment (Production, Preview, or a custom Environment), so preview can use test keys and production the live ones.
+
+## Variables
+
+Open **Variables**, then **Add variable**. Pick the Environment, enter an uppercase key such as `STRIPE_SECRET_KEY`, enter the value, and choose:
+
+- **Public** (default): the value stays visible and can be used in browser code with a `VITE_`, `PUBLIC_`, `NEXT_PUBLIC_`, or `NUXT_PUBLIC_` key. Use it for a site URL or a search-only key.
+- **Private**: the value is hidden for good and only the site's server code can read it. Use it for payment, email, or database keys. Private keys cannot use the browser prefixes above.
+
+Agents working on the site do not get private values in their own commands. Public or private is fixed once saved. To switch, delete the variable and add it again. Use the row menu to change a value or delete it. Changes reach previews on the next deploy, even with no code change, and the live site on the next publish.
+
+## Secrets
+
+Open **Secrets** for credentials Fimo itself uses: webhook headers, schedules, and agents. The site never receives them. If the site's code needs the key, use a private variable instead.

package/dist/build/vite/plugins/runtime-env.d.ts

@@ -11,11 +11,11 @@ import type { Plugin } from 'vite';
  * Two injection paths, both needed:
  * - `process.env`, so Vite's own `VITE_*` exposure, `loadEnv`, and server-side
  *   code (`getFimoPaths`, SSR) all see the value.
- * - `define` for the two keys the browser bundle reads. Fimo's own template
- *   `define`s them from `loadEnv` at user-config time — before any plugin can
- *   run — which yields `undefined` on a bare checkout; a plugin's `define`
- *   merges over the user's, so this is what makes the client see the derived
- *   URL. Only for keys nothing else set, so the user's own `define` stays
+ * - `define` for the public runtime keys, explicit or derived. Fimo's own
+ *   template `define`s two of them from `loadEnv` at user-config time — before
+ *   any plugin can run — which yields `undefined` on a bare checkout; a
+ *   plugin's `define` merges over the user's, so this is what makes the client
+ *   see the URL. Never over a non-empty user `define`, which stays
  *   authoritative.
  */
 export default function runtimeEnvPlugin(): Plugin;

package/dist/build/vite/plugins/runtime-env.js

@@ -1,4 +1,5 @@
 import { resolveFimoEditingMetadata } from '../../../runtime/preview/editing-metadata.js';
+import { LOCAL_CONTENT_API_ENV_KEYS, LOCAL_ENV_SELECTOR_KEYS } from '../../../runtime/shared/branch-identity.js';
 import { findStaleFimoOverride, resolveLocalRuntimeEnv, staleOverrideMessage, } from '../../../runtime/shared/local-runtime-env.js';
 /**
  * Point the app at the Fimo env of the current git branch.
@@ -12,11 +13,11 @@ import { findStaleFimoOverride, resolveLocalRuntimeEnv, staleOverrideMessage, }
  * Two injection paths, both needed:
  * - `process.env`, so Vite's own `VITE_*` exposure, `loadEnv`, and server-side
  *   code (`getFimoPaths`, SSR) all see the value.
- * - `define` for the two keys the browser bundle reads. Fimo's own template
- *   `define`s them from `loadEnv` at user-config time — before any plugin can
- *   run — which yields `undefined` on a bare checkout; a plugin's `define`
- *   merges over the user's, so this is what makes the client see the derived
- *   URL. Only for keys nothing else set, so the user's own `define` stays
+ * - `define` for the public runtime keys, explicit or derived. Fimo's own
+ *   template `define`s two of them from `loadEnv` at user-config time — before
+ *   any plugin can run — which yields `undefined` on a bare checkout; a
+ *   plugin's `define` merges over the user's, so this is what makes the client
+ *   see the URL. Never over a non-empty user `define`, which stays
  *   authoritative.
  */
 export default function runtimeEnvPlugin() {
@@ -49,34 +50,37 @@ export default function runtimeEnvPlugin() {
                         ? 'development'
                         : 'production', explicit.FIMO_EDITING_METADATA))),
                 };
-                if (!derived) {
-                    return { define, ssr };
-                }
-                if (command === 'serve') {
+                if (derived && command === 'serve') {
                     const stale = findStaleFimoOverride(explicit, derived);
                     if (stale) {
                         console.warn(staleOverrideMessage(stale));
                     }
                 }
-                // Decide what is missing BEFORE writing to process.env, or the define
-                // step below would see the values this loop just set.
-                const missing = Object.entries(derived.values).filter(([key]) => {
-                    if (explicit[key]) {
-                        return false;
-                    }
+                // `define` every public runtime key, explicit or derived, on every
+                // config pass. Vite only exposes `envPrefix` matches on
+                // `import.meta.env`, so an unprefixed key reaches code that reads
+                // `import.meta.env` — Astro's server runtime reads `FIMO_CONTENT_API_URL`
+                // and `FIMO_ENV` there — only through a `define` or the framework's own
+                // env plugin. Astro's dev plugin caches those values per instance, and
+                // Vite's `.env` restart reuses the instance: a forked preview whose host
+                // rewrote `.env` for its Branch kept requesting the parent's (FIMO-2902).
+                // This hook reruns on that restart, so its `define` carries the new
+                // values. Only this allowlist is defined: every value is a public
+                // tenant URL or a Branch name, never an arbitrary `FIMO_*` secret.
+                for (const key of [...LOCAL_CONTENT_API_ENV_KEYS, ...LOCAL_ENV_SELECTOR_KEYS]) {
                     const defined = config.define?.[`import.meta.env.${key}`];
-                    return defined === undefined || defined === 'undefined' || defined === JSON.stringify('');
-                });
-                for (const [key, value] of missing) {
-                    process.env[key] = value;
+                    if (defined !== undefined && defined !== 'undefined' && defined !== JSON.stringify('')) {
+                        continue;
+                    }
+                    const value = explicit[key] || derived?.values[key];
+                    if (!value) {
+                        continue;
+                    }
+                    if (!explicit[key]) {
+                        process.env[key] = value;
+                    }
+                    define[`import.meta.env.${key}`] = JSON.stringify(value);
                 }
-                // `define` EVERY derived key, not a hand-picked subset. Vite only exposes
-                // `envPrefix` matches on `import.meta.env`, so an unprefixed key set on
-                // `process.env` is invisible to code that reads `import.meta.env` — which
-                // is how Astro's server runtime reads `FIMO_CONTENT_API_URL`. A curated
-                // list silently misses whichever framework reads a key that is not on it.
-                // Every value here is a public tenant URL or an env name; none is secret.
-                Object.assign(define, Object.fromEntries(missing.map(([key, value]) => [`import.meta.env.${key}`, JSON.stringify(value)])));
                 return { define, ssr };
             },
         },

package/dist/cli/bundle.json

@@ -1,7 +1,7 @@
 {
   "bundled": true,
   "bundler": "esbuild",
-  "bundledAt": "2026-10-20T18:36:10.758Z",
+  "bundledAt": "2026-10-21T12:37:26.225Z",
   "cliVersion": "2.8.0",
   "external": [
     "oxc-parser",