fimo 0.9.0-experimental.1 → 0.9.0-staging.1

package/assets/skills/fimo/SKILL.md

@@ -1,67 +1,30 @@
 ---
 name: fimo
 description: >-
-  How to write code in a Fimo project — the npm package surface. Load when
-  writing JSX that renders schema content, defining schemas or forms (JSON),
-  using `t()` for labels, plugging media into `fimo/ui` components,
-  or applying the project's code conventions. CLI commands and workflows
-  (push, deploy, sync, etc.) live in the `fimo-cli` skill.
+  Working in or with a Fimo project (a content + media + forms + analytics
+  platform for React websites). Load the real, version-locked Fimo skills on
+  demand through the `fimo` CLI before doing Fimo work — writing schema-driven
+  code, running CLI/deploy workflows, using the dashboard, or migrating a site.
 ---
 
 # Fimo
 
-You are writing code in a Fimo project — a content + media + forms + analytics platform for React websites with a CMS dashboard. This skill describes the **`fimo` npm package surface** as installed in this specific project: what's exported from `fimo`, `fimo/ui`, `fimo/vite`; the JSON shapes you write; the generated React Query hooks and Zod schemas you import; and the code conventions for using them.
+Fimo ships its skills through its CLI so they always match the installed `fimo` version. This file is
+just a pointer — do not rely on cached instructions. Fetch the real skill from the CLI when you need it.
 
-This skill is version-locked to this project's installed `fimo` package — the shapes here match what your code can actually use.
+When you are about to do Fimo work:
 
-For CLI commands and workflows (creating a project, pushing schemas/forms, deploying, managing labels, etc.), the **`fimo-cli`** skill is the source of truth. Run every CLI command as `npx fimo <command>` when the project declares a `fimo` dependency (it pins the version matching the project's backend); otherwise use `npx fimo@latest`. If `fimo-cli` isn't loaded for your AI tool, register it with `npx fimo skills install --mode=copy`.
+1. List what's available: `npx fimo@latest skills list`
+2. Load the relevant skill: `npx fimo@latest skills get <name>` (add `--ref <doc>` for a reference doc)
 
-## Critical: NEVER hardcode user-facing things
+Pick by task:
 
-This is the load-bearing rule for every code change. **Fimo's whole point is that content editors edit content in the dashboard, not in code.** Anything hardcoded breaks that.
+- Writing code — schema-driven JSX, schemas/forms JSON, `t()` labels, `fimo/ui` media → `fimo-code`
+- CLI commands and workflows — push, deploy, sync, labels, domains, analytics → `fimo-cli`
+- The Fimo Studio dashboard / web app UI → `fimo-studio`
+- Migrating an existing site into Fimo → `fimo-migration`
 
-- **Content** (posts, products, pages, lists, anything structured) → declare a schema, render collections with generated `useList()` or `useInfiniteList()` hooks + `fimo/ui` components. Use `useGet()` only for legacy fixed array queries. **Never** write `const posts = [...]` in JSX.
-- **Strings** (labels, CTAs, headings, descriptions, any visible text) → wrap in `t('key')` and create the default-locale value with `fimo labels set`. Use `--locale <locale>` only when intentionally writing a non-default locale. **Never** write `<h1>Welcome</h1>` directly — write `<Text value={t('home.title')} as="h1" />`.
-- **Media** (images, videos, files) → use `<Image>` / `<Video>` from `fimo/ui` for schema media, `<StaticImage>` for hard-coded URLs. **Never** use `<img src={...}>`.
-- **Forms** → use the generated Zod schema + `submitX` helper from `@/forms/<name>`. Never hand-roll fetch or validation.
+If a confirmed Fimo platform failure or missing capability materially blocks the task, finish or safely preserve the main work first, then use the built-in `supportReport` tool. Load the `fimo-cli` support instructions for the reporting criteria.
 
-If you find yourself about to hardcode anything user-facing, **stop and use the appropriate Fimo primitive instead.** For pushing the schema/form/asset to the backend, that's CLI territory — see the `fimo-cli` skill.
-
-## When starting code work, load these references up front
-
-These define the package surface for the load-bearing primitives. **Read all six before generating significant code:**
-
-- `references/content.md` — schema JSON shape, field types, Tiptap nodes, generated React Query hooks
-- `references/forms.md` — form JSON spec, generated Zod + `submitX` helper
-- `references/assets.md` — `FimoMedia` shape, how to render assets
-- `references/labels.md` — `t()` helper, `useLabels()`, wrap rules
-- `references/locales.md` — locale routing helpers, `FimoLink`, custom-framework contract
-- `references/ui.md` — `fimo/ui` components + JSX code conventions + app code rules
-
-Workflow / CLI-side concerns (pushing schemas, generating images, managing labels, deploying) live in the **`fimo-cli`** skill's matching references.
-
-## Decision Tree (specific tasks)
-
-- **Setting up Fimo in a new project** — pick the framework:
-  - React Router framework mode (new projects use React Router 8) → `references/setup-react-router.md`
-  - Plain Vite + React (or upgrading a legacy v3 project) → `references/setup-plain-vite.md`
-- Writing schema JSON / picking field types / Tiptap richtext → `references/content.md`
-- Writing form JSON / generated form client / form code → `references/forms.md`
-- Plugging media into a component / `FimoMedia` shape → `references/assets.md`
-- ANY user-facing string in code → `references/labels.md`
-- Locale-aware routes, links, or framework adapters → `references/locales.md`
-- ANY JSX rendering schema content or `t()` output → `references/ui.md`
-- Major visual / redesign / hero section / brand → `references/design.md`
-
-## Anti-Patterns
-
-- **Hardcoding content in JSX** — `<h1>My Blog</h1>` + an array of posts in code. Use schemas + entries + `t()`.
-- **Raw HTML for schema content** — `<img src={post.coverImage.url}>` instead of `<Image value={post.coverImage}>`. The `fimo/ui` components carry metadata for inline editing in the admin.
-- **Raw `<a href>` for internal navigation** — causes full page reloads. Use `<FimoLink>` for locale-aware internal links or React Router `<Link>` when intentionally bypassing locale helpers. Reserve `<a>` for external links.
-- **Pulling stock photos from external URLs** — editors can't manage them. Use a Fimo media task such as `fimo image generate`.
-- **Editing generated `.ts` files** under `src/schemas/` or `src/forms/` — regenerate them through `fimo validate` or the matching push command.
-- **Writing raw HTML in `richtext` fields** — must be Tiptap JSONContent.
-- **Calling `t()` with a dynamic first argument** — the key must be a string literal so the extractor finds it.
-- **Decorating the disposable starter** — `src/pages/Index.tsx` is throwaway scaffolding. On first real generation, replace it entirely.
-- **Skipping legal pages** — `Privacy.tsx` + `Terms.tsx` are required for public sites; the template ships them.
-- **Showing Fimo branding** in the generated site unless the user explicitly asks for it.
+If the project has an `AGENTS.md` (or `CLAUDE.md`), read it too — it carries project-specific context.
+Always fetch the skill fresh from the CLI rather than trusting a copy.

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

@@ -18,7 +18,7 @@ description: >-
 
 The `fimo` CLI is the workflow surface for Fimo. Fimo is a content + media + forms + analytics platform for React websites with a CMS dashboard. The CLI handles project creation, all content / forms / media / labels / locale workflows, deploys, collaboration, account management, AI credit inspection, and AI agent setup.
 
-This skill describes **what the CLI does and the workflows it drives**. For the package surface used IN code (component props, generated hooks, JSON shapes, code-side rules), see the `fimo` skill — its description triggers automatically when the agent is in a Fimo project.
+This skill describes **what the CLI does and the workflows it drives**. For the package surface used IN code (component props, generated hooks, JSON shapes, code-side rules), load the `fimo-code` skill on demand with `npx fimo@latest skills get fimo-code`.
 
 Use `fimo <command> --help` for full flag details on any command.
 
@@ -28,7 +28,7 @@ Use `fimo <command> --help` for full flag details on any command.
 
 Run every command as **`npx fimo@latest <command>`**. It always fetches the latest CLI — no install, nothing to keep up to date, and it can't fall behind and get blocked. Do **not** install `fimo` globally.
 
-The examples in this skill and its references write `fimo <command>` for brevity — mentally prefix them with `npx fimo@latest`. (One exception, because npx has no stable package path to symlink into: install skills with `npx fimo@latest skills install --mode=copy`.)
+The examples in this skill and its references write `fimo <command>` for brevity — mentally prefix them with `npx fimo@latest`.
 
 ## Output for agents: `--json` is the stable contract
 
@@ -55,11 +55,11 @@ A project can have multiple **envs** — each is a git branch _plus_ its own DB,
 
 ```bash
 npx fimo@latest login                          # authenticate via browser
-npx fimo@latest skills install --mode=copy     # install Fimo skills for your AI tools (copy mode: required under npx)
+npx fimo@latest skills install                 # install the global Fimo skill for your AI tools
 npx fimo@latest init my-site --org <id>        # one-stop setup: sign in, create/link a project, install deps + skills. Use the org **id** from `fimo orgs list`, NOT the slug.
 npx fimo@latest init --project-id <id> my-site # link an EXISTING project instead of creating one
 npx fimo@latest clone                          # interactively choose an existing project to clone locally
-cd my-site                                     # the `fimo` project skill auto-loads from here
+cd my-site                                     # then load skills on demand: npx fimo@latest skills get fimo-code
 pnpm dev                                       # run the app locally (use the project's PM: pnpm/npm run/yarn/bun) — your iteration loop
 npx fimo@latest credits                        # inspect the owning org's AI credit balance (read-only)
 npx fimo@latest validate                       # run all checks + codegen; fails on missing DB labels
@@ -73,16 +73,16 @@ The working loop is local: run the app with the project's package-manager `dev`
 
 ## Decision Tree
 
-Load the matching reference when the user's request fires its trigger. Recipes that involve writing code also need the `fimo` skill's package references — they're called out where relevant.
+Load the matching reference when the user's request fires its trigger. Recipes that involve writing code also need the `fimo-code` skill's package references — they're called out where relevant.
 
 - "Create a new Fimo project / scaffold a site / start a new website / link an existing project locally" → `references/init.md`
-- "Add a content type / blog / products / pages / CMS" → `references/content.md` (workflow) **+ load `fimo/references/content.md` for the JSON shape and React hooks**
-- "Add a contact / signup / feedback / newsletter form" → `references/forms.md` (workflow) **+ load `fimo/references/forms.md` for the JSON spec and generated client**
+- "Add a content type / blog / products / pages / CMS" → `references/content.md` (workflow) **+ load `fimo-code/references/content.md` for the JSON shape and React hooks**
+- "Add a contact / signup / feedback / newsletter form" → `references/forms.md` (workflow) **+ load `fimo-code/references/forms.md` for the JSON spec and generated client**
 - "View form submissions / who filled out the contact form / inspect what users sent / how many signups" → `references/forms.md` § Reading submissions
-- "Upload an image / hero / cover / existing media file" → `references/assets.md` (workflow: upload, browse, open, delete) **+ load `fimo/references/assets.md` for the `FimoMedia` shape and rendering**
-- "Generate AI image / video / draft preview / image edit / cover from a prompt" → `references/media.md` (task commands, quality, recipes, and verification) **+ load `fimo/references/assets.md` for the `FimoMedia` shape if you'll plug the result into UI**
-- "Add labels / update static copy / fix missing `t()` values" → `references/labels.md` (workflow) **+ load `fimo/references/labels.md` for the `t()` helper and wrap rules**
-- "Enable locales / configure default locale / route by locale prefix / fix locale route validation" → `references/locales.md` **+ load `fimo/references/locales.md` for code helpers**
+- "Upload an image / hero / cover / existing media file" → `references/assets.md` (workflow: upload, browse, open, delete) **+ load `fimo-code/references/assets.md` for the `FimoMedia` shape and rendering**
+- "Generate AI image / video / draft preview / image edit / cover from a prompt" → `references/media.md` (task commands, quality, recipes, and verification) **+ load `fimo-code/references/assets.md` for the `FimoMedia` shape if you'll plug the result into UI**
+- "Add labels / update static copy / fix missing `t()` values" → `references/labels.md` (workflow) **+ load `fimo-code/references/labels.md` for the `t()` helper and wrap rules**
+- "Enable locales / configure default locale / route by locale prefix / fix locale route validation" → `references/locales.md` **+ load `fimo-code/references/locales.md` for code helpers**
 - "What's in this project / show the project structure / describe the project / what schemas does it have / how many routes / project tree / show me what's here" → `references/describe.md`
 - "Deploy / publish / go live / push my changes" → `references/deploy.md`
 - "Get the preview URL / open the preview / what's the URL for this env / refresh the preview link / I just want to see the site / the preview URL stopped working" → `references/preview.md`
@@ -103,7 +103,7 @@ Load the matching reference when the user's request fires its trigger. Recipes t
 - "Create / scaffold / run / validate / activate / deactivate an agent / agent bundle / list agent templates / view agent runs, reports, or logs (`fimo agents *`)" → `references/agents.md`
 - "Install Fimo for my AI tool / fimo skills install / set up Claude Code or Cursor for Fimo / add an agent to this project" → `references/agent-setup.md`
 - "Refresh / update installed Fimo skills / fimo skills sync / agent missing the latest fimo conventions" → `references/agent-setup.md`
-- "Report a Fimo problem or feature request / contact Fimo support / a Fimo API or command keeps failing / a documented argument is rejected / a supported operation needs an undocumented workaround / a Fimo API is abnormally slow / a missing capability blocks work, forces a fragile or heavily manual workaround, or would materially accelerate a recurring workflow such as bulk create" → `references/support.md`
+- "Report a Fimo problem or blocking feature request / contact Fimo support / a Fimo API or command keeps failing / a documented argument is rejected / a supported operation needs an undocumented workaround / a Fimo API is abnormally slow / a confirmed missing capability blocks completion or forces a fragile or heavily manual workaround" → `references/support.md`
 - "Regenerate rule files / I edited AGENTS.md / fimo rules sync" → `references/agent-setup.md`
 - "Show analytics / visitor stats / traffic / pageviews / how is my site performing / top pages / where do visitors come from" → `references/analytics.md` (7-day preview free for all; longer ranges require paid)
 - "Mark a date on the analytics chart / annotate the chart with a deploy / add a launch note" → `references/analytics.md` § Annotations
@@ -112,7 +112,7 @@ Load the matching reference when the user's request fires its trigger. Recipes t
 
 These fire at specific moments in the project lifecycle. **Surface them proactively** rather than waiting for the user to ask:
 
-- **Right after `fimo init`** → `cd` into the new directory, then `Read` the project's `AGENTS.md` (or `CLAUDE.md` for Claude Code) **and** `.claude/skills/fimo/SKILL.md` (or `.cursor/skills/fimo/SKILL.md` etc. for other agents) to load the project context before generating any code. The new files came into existence mid-session and may not be auto-loaded by the harness. See `references/init.md` § Load the project context.
+- **Right after `fimo init`** → `cd` into the new directory, then `Read` the project's `AGENTS.md` (or `CLAUDE.md` for Claude Code) to load the project context, and run `npx fimo@latest skills get fimo-code` to load the code skill before generating any code. The `AGENTS.md`/`CLAUDE.md` came into existence mid-session and may not be auto-loaded by the harness. See `references/init.md` § Load the project context.
 - **Right after `fimo init`** → suggest `fimo rename "<Display Name>"` to set a human-readable name (the default post-init name is an auto-generated slug). Infer the name from what the user is building (e.g. "Acme Coffee" for a café, "Jane Doe Portfolio" for a personal site). See `references/init.md`.
 - **Right after `fimo init`** → start the app locally with the project's package-manager `dev` script (`pnpm dev` / `npm run dev` / `yarn dev` / `bun dev`) in the background, then ask the developer what they want to build. This localhost server with live reload is your iteration loop — edit, show, repeat. No deploy is needed to see local changes.
 - **When a user-visible unit of work looks done** → **offer** to deploy (`fimo deploy` for a hosted preview / shareable link, `fimo deploy --publish` to go live) and run it only after the developer confirms — or immediately if they ask. Never deploy on your own. See `references/deploy.md`.
@@ -120,7 +120,7 @@ These fire at specific moments in the project lifecycle. **Surface them proactiv
 - **Iterative code-only deploys** → once you are deploying, `fimo deploy --no-restart` skips the sandbox dev-server restart on HMR-safe edits. See `references/deploy.md` § Skipping the dev-server restart for when it's safe.
 - **You need the current preview URL but haven't changed code** (opening it, screenshotting it, handing it to another tool, the previous URL expired) → `fimo preview url`, never a no-op `fimo deploy`. See `references/preview.md`.
 - **When the user wants to try something risky / explore a redesign without touching the live site** → suggest a feature env: `fimo checkout -b <name>` gives an isolated branch + DB + preview. Deploy previews there, then `fimo merge` it back and `fimo publish`. See `references/branches.md`.
-- **When a Fimo API or command still fails after one safe recovery attempt, rejects a documented or previously working argument, needs an undocumented workaround for a supported operation, is repeatedly abnormally slow, or lacks a capability that blocks work, forces a fragile or heavily manual workaround, or would materially accelerate a recurring workflow** → offer to prepare a support report. Show the exact report and wait for explicit approval before running `fimo support report --yes`. See `references/support.md`.
+- **After completing or safely preserving the user's main work, when a confirmed Fimo platform failure still materially blocks the task after one safe recovery attempt, or a confirmed missing capability blocks completion or forces a fragile or heavily manual workaround** → use the built-in `supportReport` tool. Do not wait for the user to ask and do not stop after only describing the gap. See `references/support.md`.
 - **After the first successful `fimo deploy`** → suggest `fimo invite` if the project involves multiple people. Typical roles: `edit` for developers/content editors, `view` or `comment` for clients/stakeholders, `full` for project leads. See `references/invite.md`.
 - **When the user wants to modify the URL of their website** → walk through `references/domains.md`. The CLI surface covers renaming the Fimo-provided subdomain (`fimo domains rename-default`, free), attaching a domain they already own (`fimo domains add`, Premium), and buying a new domain through Fimo (`fimo domains buy`, Premium). The auto-generated default URL on every project is a fallback, not a final choice — proactively offer this after `fimo deploy --publish` if the user mentioned a real brand or domain.
 
@@ -132,7 +132,7 @@ These fire at specific moments in the project lifecycle. **Surface them proactiv
 - **Running `fimo deploy` just to get a fresh preview URL** — that's a commit + push + sandbox sync for what should be a sub-second read. Use `fimo preview url` instead. See `references/preview.md`.
 - **Using `fimo deploy --publish` casually** — `--publish` makes the site live to the public. Plain `fimo deploy` (preview) is the default. Use `--publish` only when the user says "ship it" / "go live" / "publish".
 - **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** — that's what schemas, `t()`, and the media library are for. See the `fimo` skill's anti-patterns.
+- **Hardcoding content / strings / images in code** — that's what schemas, `t()`, and the media library are for. See the `fimo-code` skill's anti-patterns.
 - **Adding another deploy tool (Vercel, Netlify, Cloudflare Pages)** — 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.
 - **Hardcoding tokens in flags** — use the credentials written by `fimo login` (one file per backend at `~/.config/fimo/credentials/<host>-<hash>.json`).

package/assets/skills/fimo-cli/references/agent-setup.md

@@ -2,75 +2,59 @@
 
 > **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
 
-Fimo wires up to AI coding tools in three layers:
+Fimo wires up to AI coding tools in two layers:
 
-1. **Global skills** — `fimo-cli`, `fimo-studio`, and `fimo-migration` skills installed once per user, machine-wide. They describe the CLI workflows, the Fimo Studio web app, and URL/source-backed migrations, and load in any compatible AI tool.
-2. **Per-project rule files** — `AGENTS.md` (universal) plus per-agent variants (`CLAUDE.md`, `.cursor/rules/fimo.mdc`, `.windsurfrules`, `GEMINI.md`, `.claude/settings.json`) generated for the AI tools each project supports.
-3. **Project-scope `fimo` skill** — the code-side skill (npm package surface: schemas, forms, `t()`, `fimo/ui` components) installed under `.claude/skills/fimo/`, `.cursor/skills/fimo/`, etc., **version-locked to the project's installed `fimo` package**.
+1. **One global bootstrap skill** — a tiny, generic `fimo` skill installed once per user, machine-wide (symlinked into each agent's global skills dir). It doesn't contain workflow content itself; it tells the agent to load the real, version-locked skills on demand from the CLI. It never goes stale because it just points at `fimo skills get`.
+2. **Per-project rule files** — `AGENTS.md` (universal) and `CLAUDE.md` ship in the project template. `fimo rules sync` regenerates the other agents' variants (`.cursor/rules/fimo.mdc`, `.windsurfrules`, `GEMINI.md`) from `AGENTS.md`.
 
-Two CLI namespaces manage all three:
+The rich skills (`fimo-code`, `fimo-cli`, `fimo-studio`, `fimo-migration`) are **never installed as files**. They're served on demand straight from the CLI, so they always match the installed version and never land in the project:
 
-- `fimo skills install / sync / uninstall` — skill artifacts (layers 1 + 3)
-- `fimo rules sync` — rule files (layer 2)
+```bash
+npx fimo@latest skills list            # what's available
+npx fimo@latest skills get fimo-code   # writing code: schemas, forms, labels, fimo/ui
+npx fimo@latest skills get fimo-cli    # CLI + workflows (this skill)
+npx fimo@latest skills get fimo-cli --ref deploy   # a reference doc
+```
 
-## Set up skills (no install needed)
+Two CLI namespaces manage the two layers:
 
-Run the CLI via `npx fimo@latest` — do not install `fimo` globally. To set up the Fimo skills for your AI tools, use **copy mode** (npx runs from an ephemeral cache with no stable package path to symlink into):
+- `fimo skills install / sync / uninstall` — the single global bootstrap skill (layer 1)
+- `fimo rules sync` — per-project rule files (layer 2)
 
-```bash
-npx fimo@latest skills install --mode=copy
-```
+## Set up the global skill (no install needed)
 
-This opens the agent picker and installs everything that applies (see below). Then connect your account when you are ready:
+Run the CLI via `npx fimo@latest` — do not install `fimo` globally.
 
 ```bash
-npx fimo@latest login
+npx fimo@latest skills install         # opens the agent picker, installs the global fimo bootstrap
+npx fimo@latest login                  # connect your account when ready
 ```
 
 ## `fimo skills` — install + sync + uninstall
 
 ```bash
-fimo skills install                            # interactive: pick agents, install everything that applies
+fimo skills install                            # interactive: pick agents, install the global bootstrap
 fimo skills install --agents=claude-code,cursor   # explicit list
 fimo skills install -a claude-code -a cursor      # repeatable form
-fimo skills install --agents=claude-code --yes    # skip the install preview prompt (headless / scripts)
-fimo skills install --mode=copy                # copy files instead of symlinking (required under npx)
-fimo skills sync                               # refresh installed skills (global + project, where applicable)
-fimo skills uninstall                          # remove the global skills
+fimo skills sync                               # re-ensure the bootstrap + clean up stale old skills
+fimo skills uninstall                          # remove the global bootstrap
 ```
 
-`fimo skills install` shows a one-screen preview of every path it will touch (`.agents/skills/...`, `.claude/skills/...`, `AGENTS.md`, per-agent rule files, …) before writing. Pass `-y` / `--yes` to skip the confirmation in scripts.
-
-**`fimo skills install` is context-aware**:
-
-- **Outside a Fimo project** — installs only the global `fimo-cli`, `fimo-studio`, and `fimo-migration` skills for the selected agents.
-- **Inside a Fimo project** (`.fimo.settings.json` found by walking up from cwd) — installs the global skills _and_ writes the project `fimo` skill _and_ generates the per-agent rule file (`CLAUDE.md` / `.cursor/rules/fimo.mdc` / `.windsurfrules` / `GEMINI.md`) for each selected agent. One command, full setup.
-
-The command prints exactly which files were written, so the context-aware behavior is never silent magic.
-
-**Adding an agent to an existing project** is the same command — `fimo skills install --agents=cursor` inside the project does global + project skill + rule file for cursor in one shot.
-
-**`fimo skills sync`** is the refresh / update path — no consent prompts, no new agents added. It re-copies whatever is already installed:
-
-- Global skills for whichever agents already have them
-- Project `fimo` skill for whichever agents have rule files (when run inside a Fimo project)
-
-You rarely have to invoke it by hand:
+`fimo skills install` installs the single global `fimo` bootstrap skill for the selected agents (symlinked into each agent's global skills dir; it transparently falls back to a copy when a symlink can't be created, e.g. under `npx`). It writes **nothing** into your project — the working tree stays clean.
 
-- **Global skills auto-refresh** whenever a newer CLI runs — any `npx fimo@latest …` command detects a version change (marker at `~/.config/fimo/last-version`) and re-copies the latest skills.
-- **The project skill auto-refreshes during Fimo-controlled installs** when the `fimo` package version bumps — the package's postinstall hook re-syncs the skill from `node_modules/fimo/assets/skills/fimo/` (which is version-locked to the installed package). For pnpm, `fimo init --install`, sandbox `fimopm install`, and E2E helper installs pass a scoped allow-all-builds flag so the hook can run without persisting build-script approvals in the template. npm / yarn run lifecycle scripts by default and need no extra config.
+Once installed, the agent discovers everything else through the bootstrap: it runs `fimo skills get <name>` to load the real skill for the task at hand.
 
-Invoke `fimo skills sync` explicitly when iterating on skill content locally, when you bumped the package via something other than a fresh install, or any time you want to force a refresh.
+**`fimo skills sync`** re-ensures the global bootstrap for whichever agents already have it, and cleans up stale global skills that older CLI versions used to copy in (`fimo-cli`, `fimo-studio`, `fimo-migration`, and legacy migration skills). You rarely need it: the bootstrap is a symlink, so it always tracks the running CLI, and the real skills are fetched fresh via `fimo skills get`. Run it after upgrading from an old CLI to clear leftovers.
 
-**`fimo skills uninstall`** removes only the global skills. Project files are part of the project — delete the project (or `rm -rf .claude/skills/fimo .cursor/skills/fimo`) if you want them gone.
+**`fimo skills uninstall`** removes the global bootstrap for the selected agents.
 
 ## `fimo rules sync` — rule files only
 
-`fimo init` writes `AGENTS.md` (the universal-spec file) and per-agent variants for the AI tools you selected. Variants and their generators:
+`fimo init` scaffolds `AGENTS.md` (the universal-spec file) and `CLAUDE.md` from the template. Other agents' variants are generated on demand:
 
 | Agent                             | File(s) generated                     |
 | --------------------------------- | ------------------------------------- |
-| claude-code                       | `CLAUDE.md` + `.claude/settings.json` |
+| claude-code                       | `CLAUDE.md` (ships in the template)   |
 | cursor                            | `.cursor/rules/fimo.mdc`              |
 | windsurf                          | `.windsurfrules`                      |
 | gemini-cli                        | `GEMINI.md`                           |
@@ -79,16 +63,16 @@ Invoke `fimo skills sync` explicitly when iterating on skill content locally, wh
 `fimo rules sync` regenerates these variants from the current `AGENTS.md`. Use it when:
 
 - You edited `AGENTS.md` and want variants refreshed (delete the variant first — see below).
-- You added an agent in a different way and need its rule file generated.
+- You added an agent that needs its own rule file generated.
 
 ```bash
 fimo rules sync                       # interactive: pick agents
 fimo rules sync --agents=cursor       # explicit
 ```
 
-`fimo rules sync` is **purely additive** — it creates missing variant files but never overwrites existing ones. Project-specific edits in `CLAUDE.md`, `.cursor/rules/fimo.mdc`, `.claude/settings.json`, etc. are preserved. To regenerate a stale variant, delete the variant file first and re-run.
+`fimo rules sync` is **purely additive** — it creates missing variant files but never overwrites existing ones, so project-specific edits are preserved. To regenerate a stale variant, delete the variant file first and re-run.
 
-**`fimo rules sync` does NOT install skill files.** That's `fimo skills install / sync` territory. The split is deliberate — rules are generated config files, skills are reusable knowledge artifacts.
+**`fimo rules sync` does NOT install skills.** That's `fimo skills` territory. The split is deliberate — rules are generated project config files (committed with the project); skills are fetched on demand and never committed.
 
 ## Selecting agents (interactive vs flags)
 
@@ -98,21 +82,20 @@ Every command that takes agents accepts the same selection inputs:
 - `-a claude-code -a cursor` — repeatable short form
 - No flag → interactive multi-select. The picker has two sections:
   - **Universal** — agents that read `AGENTS.md` natively (codex, opencode, aider, …). Always covered, not toggleable.
-  - **Additional** — agents that need a per-agent rule file or skills dir. The 6 popular ones (`claude-code`, `cursor`, `codex`, `opencode`, `windsurf`, `gemini-cli`) appear at the top of an 8-item scrollable viewport; the full list of 50+ supported agents is below the fold. Each row shows the install path next to the name (e.g. `Claude Code (.claude/skills)`). Agents already present on the machine are pre-checked.
-- `--agents=none` (only `fimo init`) — skip per-agent variants entirely; write only `AGENTS.md`.
-- `--mode=symlink|copy` (only `fimo skills install` and `fimo init`) — pick the install method for the per-agent skills layer. Defaults to symlink so the canonical `.agents/skills/<name>/` is the single source of truth; pass `--mode=copy` to materialize the skill in each per-agent dir.
+  - **Additional** — agents that get the global bootstrap skill installed. The 6 popular ones (`claude-code`, `cursor`, `codex`, `opencode`, `windsurf`, `gemini-cli`) appear at the top of an 8-item scrollable viewport; the full list of 50+ supported agents is below the fold. Agents already set up on the machine are pre-checked.
+- `--agents=none` (only `fimo init`) — skip the global skill entirely.
 
 In headless contexts (CI, AI-tool-spawned commands), pass the flag explicitly. Env-var detection (only Claude Code's `CLAUDECODE` / `CLAUDE_CODE_ENTRYPOINT`) silently targets `claude-code` if the flag is omitted; every other agent must be named explicitly with `--agents` in a headless shell, or the command exits with "No agents detected and no --agents flag passed."
 
-## Version stamping
+## Always current, never stale
 
-Every installed `SKILL.md` (global or project) is stamped with `fimoVersion: <cli-version>` in its YAML frontmatter at install time. That gives the CLI (and you) a way to detect stale installs — compare the stamped version to the currently-running CLI version.
+Because the only installed artifact is a generic pointer, and the real skills are fetched with `fimo skills get`, the content an agent reads always matches the running CLI. There's no version stamp to check and no cached copy to refresh — re-run `fimo skills get <name>` any time to get the current instructions.
 
 ## When to use which
 
 - "I want this AI tool to know about Fimo" → `fimo skills install` (interactive)
-- "I want to add Cursor to this project" → `fimo skills install --agents=cursor` (from inside the project)
-- "The agent doesn't know about my project's latest fimo conventions" → `fimo skills sync`
+- "Load the code / CLI / studio / migration skill now" → `fimo skills get fimo-code` / `fimo-cli` / `fimo-studio` / `fimo-migration`
+- "Clean up skills left by an old CLI version" → `fimo skills sync`
 - "I edited `AGENTS.md` and want variants regenerated" → delete the stale variant + `fimo rules sync`
 - "I'm done with Fimo on this machine" → `fimo skills uninstall`
-- For a fresh project, `fimo init` wires up everything for the AI tools you select at scaffold time.
+- For a fresh project, `fimo init` installs the global skill for the AI tools you select at scaffold time.

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

@@ -18,9 +18,9 @@ Typical flow:
 ```
 fimo agents create <name>     # scaffold agents/<name>/ from a template (local)
 fimo agents secrets add <name> FIRECRAWL_API_KEY  # request a project secret in config.yaml
-fimo secrets set FIRECRAWL_API_KEY --stdin        # store the hidden value in Fimo
-fimo agents validate <name>   # confirm it parses + passes policy (local)
-fimo validate                 # also checks that requested project secrets exist
+fimo secrets add FIRECRAWL_API_KEY --stdin        # store the hidden value in Fimo
+fimo agents validate <name>   # parse + policy + composition + requested secrets
+fimo validate                 # project build and codegen checks
 fimo deploy                   # push the bundle to the env's git branch
 fimo agents activate <name>   # wire its triggers on the env (DB row)
 fimo agents run <name>        # trigger a manual run → sessionId
@@ -45,7 +45,7 @@ fimo agents secrets remove <name> <KEY> [-C <dir>]
 - **`create <name>`** — scaffold `agents/<name>/` from a template (default `_default`, a minimal valid bundle). `--description <text>` writes a one-line tagline into the scaffolded `config.yaml` (surfaces in the dashboard's agents list). When run **without** `-C`, it requires the cwd to be inside a real Fimo project (walks up for `.fimo.settings.json`) and errors out cleanly otherwise, so it never leaks `agents/<name>/` into a stray cwd. If the template declares capabilities, an install-consent flow runs after the copy (`--quiet` skips it; critical caps still abort).
 - **`list`** — list the agents declared under `<project>/agents/`, with each one's trigger types and capability count. Local — the bundle list is the source of truth even if the project isn't linked yet.
 - **`validate [name]`** — run the full validation pipeline: parse → capability vocabulary → composition (cycle / missing sub-agents / invalid grants) → semantic + `fimo.config.json` policy checks. Omit `name` to validate every bundle. `--json` emits a structured `ValidationReport` for CI; exit code is non-zero on any failure.
-- **`secrets add/remove/list`** — edit or inspect the agent's requested secret names in `agents/<name>/config.yaml`. These commands do not create, rotate, or reveal secret values. Store values with `fimo secrets set`; run `fimo validate` to check that required requested secrets exist in the project. See `references/project-vars-and-secrets.md`.
+- **`secrets add/remove/list`** — edit or inspect the agent's requested secret names in `agents/<name>/config.yaml`. These commands do not create, rotate, or reveal secret values. Store values with `fimo secrets add`; run `fimo agents validate` to check that required requested secrets exist in the project. See `references/project-vars-and-secrets.md`.
 - **`integrations <name>`** — preview the agent's `integrations` allowlist from `agents/<name>/config.yaml` and, when linked, overlay project integration status. See `references/integrations.md`.
 
 Agent integration access is configured in `agents/<name>/config.yaml` with an allowlist. Omitted integrations and omitted tools are not available to the agent:

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

@@ -14,7 +14,7 @@ This file covers the **CLI workflow** for content. Use it when the user wants to
 4. Seed entries via `fimo entries create`. Generate cover images first with `fimo image generate` if needed (see `media.md` / `assets.md`).
 5. Write React pages that import from `@/schemas/{Uid}` and render with `fimo/ui` components.
 
-Steps 1, 3, and 5 reference the project skill (`fimo`) for shape and React API. Steps 2 and 4 are CLI commands documented here.
+Steps 1, 3, and 5 reference the `fimo-code` skill (`npx fimo@latest skills get fimo-code`) for shape and React API. Steps 2 and 4 are CLI commands documented here.
 
 ## Schema CLI commands
 
@@ -96,7 +96,7 @@ cat query.sql | fimo entries query --stdin
 
 SQL exposes the raw internal representation. `document_id` is the stable ID used by `fimo entries`, content tools, references, and the API. `id` is the internal ID of one exact locale variant. When query results will feed another Fimo command or tool, select `document_id AS id`; use `locale` to select a variant.
 
-The available columns are `id`, `document_id`, `content_type`, `locale`, `slug`, `data`, `created_at`, and `updated_at`. Schema fields live inside the JSONB `data` column. If a safe read is blocked because a SQL function is unavailable, tell the user which function is missing and follow `references/support.md` to prepare a support report for approval. Do not bypass the restriction with a write.
+The available columns are `id`, `document_id`, `content_type`, `locale`, `slug`, `data`, `created_at`, and `updated_at`. Schema fields live inside the JSONB `data` column. If a safe read is blocked because a SQL function is unavailable, tell the user which function is missing and use the built-in `supportReport` tool when the platform gap materially blocks the task. Do not bypass the restriction with a write.
 
 ### Bulk mutations
 

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

@@ -24,7 +24,7 @@ fimo deploy -m "<commit message>" --publish  # also publish a new live version
 - **`-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.
 
-Public project variables set with `fimo vars set` are injected into preview/build/deploy environments. Project secrets are not injected into app builds; agents request secrets separately through their own config. See `references/project-vars-and-secrets.md`.
+Public project variables managed with `fimo vars add` and `fimo vars update` are injected into preview/build/deploy environments. Project secrets are not injected into app builds; agents request secrets separately through their own config. See `references/project-vars-and-secrets.md`.
 
 ## Warm the sandbox early in a session (optional)
 

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

@@ -13,7 +13,7 @@ This file covers the **CLI workflow** for forms. Use it when the user wants to a
 3. Pre-build generates `src/forms/{name}.ts` (Zod schema + `submitX` helper). See `fimo/references/forms.md` for the generated API.
 4. Write a React component that imports from `@/forms/{name}`.
 
-Steps 1, 3, and 4 reference the project skill. Step 2 is the CLI command.
+Steps 1, 3, and 4 reference the `fimo-code` skill (`npx fimo@latest skills get fimo-code`). Step 2 is the CLI command.
 
 ## CLI commands
 

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

@@ -25,12 +25,11 @@ fimo init [dir] [options]
 | `--env <name>`               | no                            | Env to check out when linking an existing project (defaults to `main`).                                                                            |
 | `--package-manager <pm>`     | no                            | `npm` \| `pnpm` \| `yarn` \| `bun`.                                                                                                                |
 | `--install` / `--no-install` | yes in non-TTY                | Install deps after checkout (or skip it).                                                                                                          |
-| `--skills` / `--no-skills`   | yes in non-TTY                | Set up Fimo skills (or skip it).                                                                                                                   |
-| `--agents <list>`            | no                            | Comma-separated agent IDs (e.g. `claude-code,cursor`). Pass `none` to write only universal AGENTS.md.                                              |
+| `--skills` / `--no-skills`   | yes in non-TTY                | Install the global Fimo skill (or skip it).                                                                                                        |
+| `--agents <list>`            | no                            | Comma-separated agent IDs (e.g. `claude-code,cursor`). Pass `none` to skip installing the global skill.                                            |
 | `-a, --agent <id>`           | alternative                   | Repeatable form: `-a claude-code -a cursor`.                                                                                                       |
-| `--mode <symlink\|copy>`     | no                            | Project skill install method.                                                                                                                      |
 | `--template-root <path>`     | no                            | Override the bundled template (development only).                                                                                                  |
-| `-y, --yes`                  | no                            | Skip the skills install preview confirmation.                                                                                                      |
+| `-y, --yes`                  | no                            | Run non-interactively using defaults (no prompts).                                                                                                 |
 
 In a non-TTY shell the create-new path requires `[dir]`, `--install` / `--no-install`, and `--skills` / `--no-skills` (and `--org` if you have no active org and belong to multiple orgs). Without them the command exits with `Cannot prompt in a non-interactive shell.`
 
@@ -40,7 +39,7 @@ For `--agents`, pass the AI tool you're running in: `--agents=claude-code` for C
 
 ## Linking an existing project
 
-Pass `--project-id <id>` to link an EXISTING project instead of creating one. This clones the project's git repo into `[dir]` and writes the local `.fimo.settings.json` + agent files, the same as `fimo clone` (init's `--project-id` path reuses it). Use `--env <name>` to check out a specific env (defaults to `main`). Without `--project-id`, `fimo init` creates a new project.
+Pass `--project-id <id>` to link an EXISTING project instead of creating one. This clones the project's git repo into `[dir]` and writes the local `.fimo.settings.json`, the same as `fimo clone` (init's `--project-id` path reuses it). Use `--env <name>` to check out a specific env (defaults to `main`). Without `--project-id`, `fimo init` creates a new project.
 
 ## What gets written (create-new)
 
@@ -49,19 +48,14 @@ Pass `--project-id <id>` to link an EXISTING project instead of creating one. Th
 - The project template (Vite + React 19 + TypeScript + Tailwind v4 + shadcn/ui + react-router)
 - `.fimo.settings.json` — links this directory to the remote project (read-only after creation)
 - `.env` — initial env vars (currently just `VITE_API_URL`)
-- `AGENTS.md` — project rules read by all agentskills.io-compatible AI tools (Codex, OpenCode, Aider, etc.)
-- Per-agent variants based on `--agents`:
-  - `claude-code` → `CLAUDE.md` + `.claude/settings.json`
-  - `cursor` → `.cursor/rules/fimo.mdc`
-  - `windsurf` → `.windsurfrules`
-  - `gemini-cli` → `GEMINI.md`
-  - codex / opencode / aider / others → no extra file; AGENTS.md is read natively
-- The project-scope `fimo` skill (npm package surface: schemas, forms, `t()`, `fimo/ui` components) copied into each selected agent's skill dir (`.claude/skills/fimo/`, `.cursor/skills/fimo/`, etc.). Version-locked to the bundled `fimo` package — the installed `SKILL.md` is stamped with `fimoVersion`. Refresh later with `fimo skills sync`. See `references/agent-setup.md`.
-- A git repository with `fimo` as the remote, an initial commit, and an initial push
+- `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.
+- A git repository with `fimo` as the remote, and — after dependencies install — an initial commit (including the lockfile) plus an initial push
 
-Codex, OpenCode, Aider, and similar AGENTS.md-native tools work directly off AGENTS.md without a per-agent variant.
+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`.
 
-`.env` is only the bootstrap app env so local `pnpm dev` works immediately. User-managed public variables are stored with `fimo vars set` and synced into a managed `.env.local` block; hidden values use `fimo secrets set`. See `references/project-vars-and-secrets.md`.
+Codex, OpenCode, Aider, and similar AGENTS.md-native tools work directly off AGENTS.md.
+
+`.env` is only the bootstrap app env so local `pnpm dev` works immediately. User-managed public variables are stored with `fimo vars add` and synced into a managed `.env.local` block; hidden values use `fimo secrets add`. See `references/project-vars-and-secrets.md`.
 
 ## Right after scaffolding
 
@@ -84,17 +78,14 @@ When a unit of work looks done, **offer** to deploy (`fimo deploy` for a hosted
 
 ## Load the project context
 
-After `fimo init` completes, the project root has:
-
-- `AGENTS.md` (universal) plus the per-agent variant for the AI tool you're running in (e.g. `CLAUDE.md` for Claude Code, `.cursor/rules/fimo.mdc` for Cursor)
-- `.claude/skills/fimo/SKILL.md` (or the equivalent per-agent path) — the project-scope `fimo` skill, version-locked to the installed `fimo` package
+After `fimo init` completes, the project root has `AGENTS.md` (universal) and `CLAUDE.md` (for Claude Code) from the template.
 
 **These files came into existence mid-session, so they may not be auto-loaded by the harness.** Explicitly:
 
 1. `cd <project-dir>` — switch into the new project.
 2. `Read` the project rules file: `AGENTS.md` (or `CLAUDE.md` if you're Claude Code).
-3. `Read` the project skill: `.claude/skills/fimo/SKILL.md` (or `.cursor/skills/fimo/SKILL.md` for Cursor, etc.).
-4. From the project skill's "load these references up front" section, batch-read `references/content.md`, `references/forms.md`, `references/assets.md`, `references/labels.md`, `references/locales.md`, `references/ui.md` before generating any significant code.
+3. Load the code skill on demand: `npx fimo@latest skills get fimo-code`.
+4. From the `fimo-code` skill's "load these references up front" section, batch-read the referenced docs (`npx fimo@latest skills get fimo-code --ref content`, `--ref forms`, `--ref assets`, `--ref labels`, `--ref locales`, `--ref ui`) before generating any significant code.
 
 Once those are in context, generation respects the project's conventions (schemas, `t()`, `fimo/ui` components, asset handling).
 
@@ -103,10 +94,11 @@ Once those are in context, generation respects the project's conventions (schema
 If a teammate joins on a different AI tool (e.g. Cursor) after the project was scaffolded for claude-code only:
 
 ```bash
-fimo skills install --agents=cursor       # one command — global skill + project skill + rule file
+fimo skills install --agents=cursor       # install the global Fimo skill for cursor
+fimo rules sync --agents=cursor           # generate cursor's rule file (.cursor/rules/fimo.mdc)
 ```
 
-Run from inside the project. The command detects the project context and wires up everything for the new agent in a single shot. See `references/agent-setup.md`.
+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`.
 
 ## Multi-org accounts
 

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

@@ -9,12 +9,13 @@ There is no private-variable mode. If leaking the value would be a problem, use
 ## Public Variables
 
 ```bash
-fimo vars set VITE_PUBLIC_SITE_URL https://example.com
+fimo vars add VITE_PUBLIC_SITE_URL https://example.com
+fimo vars update VITE_PUBLIC_SITE_URL https://www.example.com
 fimo vars list
 fimo vars unset VITE_PUBLIC_SITE_URL
 ```
 
-`fimo vars set` stores the value in Fimo and refreshes the managed block in `.env.local` so local development can use it immediately. Fimo also injects public variables into preview, build, and deploy environments.
+`fimo vars add` refuses to replace an existing variable. Use `fimo vars update` when the variable already exists. All variable writes refresh the managed block in `.env.local` so local development can use it immediately. Fimo also injects public variables into preview, build, and deploy environments.
 
 To refresh local values later:
 
@@ -30,13 +31,15 @@ Variables are public by design. They may use browser-safe prefixes such as `VITE
 ## Secrets
 
 ```bash
-fimo secrets set FIRECRAWL_API_KEY --stdin
-fimo secrets set SLACK_BOT_TOKEN --value "$SLACK_BOT_TOKEN"
+fimo secrets add FIRECRAWL_API_KEY --stdin
+fimo secrets update FIRECRAWL_API_KEY --stdin
+fimo secrets add SLACK_BOT_TOKEN --value "$SLACK_BOT_TOKEN"
 fimo secrets list
 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_`, or `NEXT_PUBLIC_`; those prefixes are for public variables.
 
@@ -44,7 +47,7 @@ Secrets are not written to `.env.local`, preview app env files, browser bundles,
 
 `fimo init` writes `.env` for bootstrap app runtime values such as `VITE_API_URL`. This lets `pnpm dev` work without a Fimo wrapper.
 
-`fimo vars set` and `fimo vars pull` write public project variables to a managed block in `.env.local`.
+`fimo vars add`, `fimo vars update`, and `fimo vars pull` write public project variables to a managed block in `.env.local`.
 
 Local env files are ignored by git in Fimo projects. They are for local development only; deployment reads project variables from Fimo and injects them into the remote build.
 
@@ -56,15 +59,15 @@ Agents receive only the secrets they request in their own config.
 fimo agents secrets add seo-publisher FIRECRAWL_API_KEY
 fimo agents secrets list seo-publisher
 fimo agents secrets remove seo-publisher FIRECRAWL_API_KEY
-fimo validate
+fimo agents validate
 ```
 
-`fimo agents secrets add` edits `agents/<name>/config.yaml`. It does not create or rotate the secret value. Use `fimo secrets set` for that.
+`fimo agents secrets add` edits `agents/<name>/config.yaml`. It does not create or rotate the secret value. Use `fimo secrets add` to create the value or `fimo secrets update` to rotate it.
 
-`fimo validate` checks that required agent secrets exist in the project. A running agent keeps the environment it started with; the next run reads the deployed agent config again.
+`fimo agents validate` checks that required agent secrets exist in the project. A running agent keeps the environment it started with; the next run reads the deployed agent config again.
 
 ## Choosing Between Them
 
-- If the value can safely be visible in browser code or page source, use `fimo vars set`.
-- If leaking the value would be a problem, use `fimo secrets set`.
-- If an agent needs a secret, first store it with `fimo secrets set`, then request it in that agent config with `fimo agents secrets add`.
+- 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`.
+- If an agent needs a secret, first store it with `fimo secrets add`, then request it in that agent config with `fimo agents secrets add`.