fimo 0.10.1-staging.4 → 0.11.0-staging.10

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

@@ -0,0 +1,85 @@
+# Project MCP
+
+> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
+
+The **Project MCP** lets an AI coding client use Fimo's project workflows through the Model Context Protocol. It is
+the same Fimo tool surface exposed in two ways:
+
+- **Local MCP**: `fimo mcp` over stdio, for an AI client running next to a checkout.
+- **Remote MCP**: `https://api.fimo.ai/api/mcp` over authenticated Streamable HTTP, for ChatGPT, Claude, and other
+  clients that support OAuth.
+
+The local and remote Project MCP modes share the same catalog. The public Docs MCP at
+`https://fimo.ai/docs/mcp` is separate: it is unauthenticated, read-only, and only provides Fimo documentation.
+
+## Set up the local MCP
+
+Authenticate the CLI first:
+
+```bash
+npx fimo@latest login
+```
+
+Then configure the MCP client to launch:
+
+```text
+npx fimo@latest mcp
+```
+
+For clients that accept a JSON command configuration, the equivalent entry is:
+
+```json
+{
+  "mcpServers": {
+    "fimo": {
+      "command": "npx",
+      "args": ["fimo@latest", "mcp"]
+    }
+  }
+}
+```
+
+Do not add shell output or logging around the command: stdout is reserved for MCP JSON-RPC frames. Diagnostics are
+written to stderr.
+
+## Project and environment scope
+
+When launched inside a linked Fimo project, `fimo mcp` reads the project from `.fimo.settings.json` and uses the
+current git branch as the default environment. This keeps an AI client working against the same project environment as
+the checkout.
+
+Outside a linked project, the server still works, but each project-scoped tool call must provide `projectId` and
+`env`. The client can also pass an environment override when launching the CLI. Never edit `.fimo.settings.json`
+manually to change scope.
+
+The CLI credential represents the signed-in user's Fimo authority. If an MCP server is invoked from a Fimo agent
+session, the session's frozen capability snapshot still limits the operations available to that agent.
+
+## Capabilities
+
+The Project MCP catalog covers:
+
+- **Identity and navigation** — current user, projects, and environments.
+- **Content** — schemas, collection entries, search, create/update/delete, bounded bulk operations, and Singles.
+- **Labels** — list, read, set, batch-set, and delete localized labels.
+- **Media** — list and inspect assets, generate images or videos, create folders, move, and delete assets. Binary
+  upload remains `fimo assets upload`.
+- **Forms** — create, read, update, and delete forms; inspect submissions and statistics.
+- **Files** — read, glob, grep, write, edit, and delete project files within the scoped environment. Sensitive files
+  such as credentials and `.env` files are excluded.
+- **Agents** — list agents, start a run, and inspect run status.
+
+Use the MCP client's tool list as the wire-level source of truth. The catalog is shared with the remote endpoint, so a
+client configured locally sees the same tool names and input shapes as a remote client.
+
+## Local versus remote authorization
+
+Local MCP uses the stored CLI credential (or `FIMO_API_TOKEN` when explicitly configured). It does not use the
+browser OAuth consent screen. Remote MCP uses Fimo OAuth with `read`, `write`, and `agents` scopes; the user selects
+the optional capabilities during consent.
+
+In both modes, Fimo still checks the user's project permissions, environment access, input validation, and file safety
+rules for every operation. MCP does not grant access to projects the user cannot already access.
+
+For ChatGPT, Claude, or another remote MCP client, use the setup guide in the public [MCP documentation](https://fimo.ai/docs/ai/mcp)
+instead of the local stdio configuration above.

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

@@ -62,7 +62,7 @@ fimo agents secrets remove seo-publisher FIRECRAWL_API_KEY
 fimo agents validate
 ```
 
-`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 agents secrets add` edits `.fimo/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 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.
 

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

@@ -2,7 +2,7 @@
 
 > **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
 
-Commands for listing projects across an org, cloning a remote project locally, and managing the lifecycle of a single project (delete, publish, unpublish, rename). Most lifecycle commands operate on the **current project** (read from `.fimo.settings.json` in the cwd) by default; for `delete`, `publish`, and `unpublish` you can pass an explicit `[projectId]` to target another. (`rename` is local-only — it never targets a different project; see below.)
+Commands for listing projects across an org, cloning a remote project locally, and managing the lifecycle of a single project (delete, publish, unpublish, rename). Most lifecycle commands operate on the **current project** (read from `.fimo/project.json`, or the legacy `.fimo.settings.json`, in the cwd) by default; for `delete`, `publish`, and `unpublish` you can pass an explicit `[projectId]` to target another. (`rename` only edits the linked local project; see below.)
 
 ## The `fimo projects` namespace
 
@@ -13,15 +13,15 @@ fimo projects clone [projectId] [dir] [--env <name>] # clone an existing project
 fimo projects delete [projectId] [-C <dir>] [-y] # delete (defaults to current project)
 fimo projects publish [projectId] [-C <dir>]     # make the project live (publish from main)
 fimo projects unpublish [projectId] [-C <dir>]   # take the project offline
-fimo projects rename <name> [projectId] [-C <dir>]   # local-only: set seo.siteName in fimo-config.json
+fimo projects rename <name> [projectId] [-C <dir>]   # set seo.siteName in the linked project config
 ```
 
 - **`list`** — projects you can see in the org. Live projects are marked.
 - **`create`** — identical to `fimo init` (create-new path); see `references/init.md`.
-- **`clone`** — clone a remote Fimo project's git repo to your machine and write the local `.fimo.settings.json`/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 project ID and fail fast instead of prompting. By default it clones `main`; pass `--env <name>` to clone a specific env. The target directory defaults to the project display name/name, or pass `[dir]` explicitly.
+- **`clone`** — clone a remote Fimo project'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 project ID and fail fast instead of prompting. By default it clones `main`; pass `--env <name>` to clone a specific env. The target directory defaults to the project display name/name, or pass `[dir]` explicitly.
 - **`delete`** — destructive; prompts unless `-y`. Removes the remote project.
 - **`publish` / `unpublish`** — toggle the project's public visibility. `publish` flips the current `main` state live (the same "go live" as `fimo deploy --publish`, minus the git push). This is **not** the versioned release path — for that, see `fimo publish` in `references/branches.md`.
-- **`rename`** — **local-only**, unlike the others. It does not touch the remote project record. It requires `.fimo.settings.json` 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). It writes `seo.siteName` into the local `fimo-config.json`; you must commit and run `fimo deploy` to apply the change.
+- **`rename`** — edits only the linked local project immediately. 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). It writes `seo.siteName` into the current or legacy project config; commit and run `fimo deploy` to reconcile the remote `displayName` and deploy the new site name.
 
 ## Top-level clone shortcut
 
@@ -33,15 +33,15 @@ Use the top-level shortcut for the common "get this project onto my machine" wor
 
 ## Top-level shortcuts (current project)
 
-These target the project linked in the cwd's `.fimo.settings.json` — handy from inside a project directory:
+These target the project linked in the cwd's `.fimo/project.json` (or legacy `.fimo.settings.json`) — handy from inside a project directory:
 
 ```bash
 fimo delete [-C <dir>] [-y]      # delete the current project
 fimo unpublish [-C <dir>]        # unpublish the current project
-fimo rename "<Site Name>"        # local edit: set seo.siteName in fimo-config.json
+fimo rename "<Site Name>"        # local edit: set seo.siteName in the project config
 ```
 
-`fimo rename` sets the **site name** (`seo.siteName`) in the local `fimo-config.json` — it is a local edit, not a remote update, so it requires a follow-up commit + `fimo deploy` to take effect. It does **not** change the project's remote display name (the `displayName` shown by `projects list`), which is set once at creation time from the project directory name. See `references/init.md` and `references/deploy.md`.
+`fimo rename` sets the **site name** (`seo.siteName`) in the local project config — it is a local edit, not an immediate remote update, so it requires a follow-up commit + `fimo deploy` to take effect. Deploy reconciles the project's remote `displayName` with the committed site name while pushing the config. See `references/init.md` and `references/deploy.md`.
 
 ## Three "publish" verbs — don't confuse them
 

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

@@ -73,7 +73,7 @@ something else (e.g. `handle`, `permalink`).
 | `reference` | `{ "id": "..." }`, `null`, or an array of reference objects when `many: true` | References to another schema                               |
 | `blocks`    | ordered array of objects                                                      | Fixed groups, repeated sections, or selectable page blocks |
 
-A `date` field currently generates as `any` in the TS client, so for typed access (and the `<Date>` component) prefer a `string` field holding an ISO date — which is what the `publishDate` examples below do.
+A `date` field generates as `string` in the TS client and wraps in `FimoString` at read time — the same source-tracked shape as `string`/`text` — so `<Date value={post.someDate} />` and plain string methods (`.slice()`, template literals, …) both work directly.
 
 ## Enumerated strings
 
@@ -163,10 +163,12 @@ A field may declare `showIf` (every clause must match) or `showIfAny` (one claus
 
 - `blocks.schema.fields` repeats one homogeneous shape.
 - `blocks.schema.oneOf` lets the editor choose exactly one variant per item.
+- Blocks schemas support at most 7 nested `blocks` levels, 40 variants in one `schema.oneOf`, and `min` or `max` values up to 200 items per blocks field.
 - Blocks always read and write arrays. A field with `max: 1` is `[]` or `[item]`, never a bare object.
 - `min` and `max` constrain the total number of blocks. Use `min: 1` to require at least one block; `required: true` has the same minimum-one behavior.
 - Fimo creates a stable `_key` for each item. A `oneOf` item also carries `_type`, matching the variant `uid`.
 - Nested fields support the same defaults and validators as top-level fields.
+- **Each block item's own scalar fields wrap the same way their field type wraps at the top level** — a nested `string`/`text` field is a `FimoString`, a nested `richtext` field is a `FimoRichText`, a nested `media` field is a `FimoMedia`, a nested `boolean` is a `FimoBoolean`, a nested `date` is a `FimoString`, a nested `json` field is a shallow-cloned, source-tagged object, a nested `number` stays a plain `number`, and a nested `blocks` field recurses the same way. Pass those nested values to the matching `fimo/ui` component exactly like a top-level field — `<Text value={section.heading} />` or `<Json value={section.metadata} />` inside a `.map()` over `page.sections` stays inline-editable.
 - Blocks inherit the owning entry's locale.
 - Nested references use one fixed `target`. Unpopulated reads return `{ id, documentId }`, like top-level references.
 - Nested population and filtering are not supported yet.
@@ -516,22 +518,25 @@ Populate is depth-one. It only works for reference fields; trying to populate a
 
 The entry objects a hook returns are **not** plain JS values. The generated client wraps each _trackable_ field in a `fimo/ui` primitive that carries source metadata for inline editing. Which fields wrap, and which stay plain:
 
-| Schema field type | Field value you get                 | Notes                                                                                 |
-| ----------------- | ----------------------------------- | ------------------------------------------------------------------------------------- |
-| `string`          | `FimoString`                        | `extends String` — **not** a primitive `string`                                       |
-| `text`            | `FimoString`                        | Multiline plain text with the same source tracking as `string`                        |
-| `richtext`        | `FimoRichText`                      | Tiptap JSONContent + source metadata                                                  |
-| `boolean`         | `FimoBoolean`                       | class; `.valueOf()` → `boolean`                                                       |
-| `media`           | `FimoMedia` / `FimoMedia[]`         | shape + rendering in `references/assets.md`                                           |
-| `number`          | `number`                            | plain — not wrapped                                                                   |
-| `json`            | `Record<string, any>`               | plain — not wrapped                                                                   |
-| `date`            | `any` (raw ISO date string)         | not wrapped (`FimoDate` is not emitted — see below)                                   |
-| `reference`       | `FimoReference` / `FimoReference[]` | reference object(s) with target `id`; use `populate` when embedded targets are needed |
+| Schema field type | Field value you get                 | Notes                                                                                                                                                                                                                 |
+| ----------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `string`          | `FimoString`                        | `extends String` — **not** a primitive `string`                                                                                                                                                                       |
+| `text`            | `FimoString`                        | Multiline plain text with the same source tracking as `string`                                                                                                                                                        |
+| `richtext`        | `FimoRichText`                      | Tiptap JSONContent + source metadata                                                                                                                                                                                  |
+| `boolean`         | `FimoBoolean`                       | class; `.valueOf()` → `boolean`                                                                                                                                                                                       |
+| `media`           | `FimoMedia` / `FimoMedia[]`         | shape + rendering in `references/assets.md`                                                                                                                                                                           |
+| `number`          | `number`                            | plain — not wrapped. A wrapper would break `<span>{post.views}</span>` (React renders a boxed `String` directly but throws on a boxed `Number`), so it stays untracked and unclickable in the editing surfaces        |
+| `json`            | `Record<string, any>`               | the same shape you wrote, plus a hidden (non-enumerable, symbol-keyed) source tag — render with `<Json>`, see below                                                                                                   |
+| `date`            | `FimoString`                        | same wrapper as `string`/`text`, **not** `FimoDate` — see below                                                                                                                                                       |
+| `blocks`          | array of plain objects              | the array/objects themselves are plain; each item's own scalar fields are wrapped by their own field type (a nested `string` is still `FimoString`, a nested `number` stays a plain `number`, …) — see "Blocks" above |
+| `reference`       | `FimoReference` / `FimoReference[]` | reference object(s) with target `id`; use `populate` when embedded targets are needed                                                                                                                                 |
 
 Rules of thumb:
 
-- **Pass the whole primitive to the matching `fimo/ui` component** — `<Text value={post.title} />`, `<Image value={post.cover} />`, `<RichText value={post.body} />`, `<Boolean value={p.inStock} />`. Don't unwrap first; the component reads the source metadata so the field stays inline-editable in the dashboard.
+- **Pass the whole primitive to the matching `fimo/ui` component** — `<Text value={post.title} />`, `<Image value={post.cover} />`, `<RichText value={post.body} />`, `<Boolean value={p.inStock} />`, `<Date value={post.publishDate} />`, `<Json value={post.metadata} />`. Don't unwrap first; the component reads the source metadata so the field stays inline-editable in the dashboard.
 - **`FimoString extends String`**, so `typeof post.title === 'object'` and `post.title === 'Hi'` is `false`. It stringifies fine inside JSX and template literals; call `.toString()` only when something genuinely needs a primitive `string`.
+- **`number` fields are the one scalar type left unwrapped** — `post.views` is a plain `number`, so `{post.views}` renders directly in JSX, `typeof`/`===`/arithmetic all behave normally, and there is no `<Number>` component. This is deliberate, not a gap: wrapping it would break direct JSX rendering in every existing site.
+- **`json` fields are a shallow clone of what you wrote**, tagged with a hidden source symbol — not the original object, and not a class instance. Reading it behaves exactly like plain JSON (`JSON.stringify` round-trips it unchanged; `for...in`/`Object.keys` see only your own keys). Render it with `<Json value={post.metadata} />` (default renders as a `<span>`; pass `as="pre"` for a formatted block, or a children render function for specific keys) so it stays inline-editable and live-updates in the dashboard preview like every other field.
 - **Never hand-construct** a `FimoString` / `FimoMedia` / etc. — that bypasses source tracking. For a literal string use `t()`; for a literal image use `<StaticImage>`.
 - `t()` also returns a `FimoString` (see `references/labels.md`).
 
@@ -553,7 +558,7 @@ class FimoBoolean {
 }
 ```
 
-> **`FimoDate`:** exported from `fimo/ui` (it's the `<Date>` component's value type), but the generated schema client does **not** wrap `date` fields in it today — they arrive as a raw ISO string. `<Date value={post.someDate} />` accepts that at runtime either way.
+> **`FimoDate`:** exported from `fimo/ui` (it's one of the `<Date>` component's accepted value types), but the generated schema client does **not** wrap `date` fields in it — a `date` field wraps as `FimoString` instead (see the table above), because the generated TypeScript type for a `date` field is `string`, and `FimoString` is what keeps that contract's string methods (`.slice()`, `.includes()`, …) working. `<Date value={post.someDate} />` accepts a `FimoString`, a `FimoDate`, a raw `Date`, or a raw string — all four render correctly.
 
 ## UI code pattern
 
@@ -579,7 +584,7 @@ export function BlogList() {
 }
 ```
 
-For the `<Text>` / `<RichText>` / `<Image>` / `<Date>` components and the rules of thumb, see `references/ui.md`.
+For the `<Text>` / `<RichText>` / `<Image>` / `<Date>` / `<Json>` components and the rules of thumb, see `references/ui.md`.
 
 ## Read path (published app, no auth)
 

package/assets/skills/fimo-code/references/labels.md

@@ -21,11 +21,11 @@ In development, the generated app reloads when DB label values change. In produc
 
 ## Locale behavior
 
-The default label locale is `i18n.defaultLocale` in `fimo-config.json`, falling back to `en` when it is not set. `fimo validate`, the generated app runtime, and `fimo labels set` without `--locale` all use that default locale.
+The default label locale is `i18n.defaultLocale` in `.fimo/config.json`, falling back to `en` when it is not set. `fimo validate`, the generated app runtime, and `fimo labels set` without `--locale` all use that default locale.
 
 For non-default locales, create explicit DB values with `fimo labels set --locale <locale>` or `fimo labels set-many --locale <locale>`. Keep the code shape the same for every locale: `t('hero.title')` declares the key, and the DB decides which locale value is shown.
 
-`fimo-config.json` owns the locale list:
+`.fimo/config.json` owns the locale list:
 
 ```json
 {

package/assets/skills/fimo-code/references/locales.md

@@ -4,7 +4,7 @@ Fimo provides locale utilities that follow the Fimo standard, but they are helpe
 
 ## Configuration
 
-`fimo-config.json` owns the locale list and routing strategy. Keep one locale unless the user asks for multilingual or localized output.
+`.fimo/config.json` owns the locale list and routing strategy. Keep one locale unless the user asks for multilingual or localized output.
 
 ```jsonc
 {
@@ -28,7 +28,7 @@ Locale tags should be structurally valid, for example `en`, `es`, `pt-BR`, or `z
 
 ## Canonical Routes
 
-Keep `fimo-config.json#routes` canonical and unlocalized:
+Keep `.fimo/config.json#routes` canonical and unlocalized:
 
 ```json
 {
@@ -71,7 +71,7 @@ Copyable examples live in `assets/react-router-locales/routes.ts` and `assets/re
 
 Before changing a multilingual app, inspect its locale provider, route table, language switcher, redirects, and current public URLs. Preserve that behavior while migrating.
 
-For React Router projects, prefer converging on one locale contract owned by `fimo-config.json`, `fimoRoutes()`, and `FimoLink`. Move existing providers and language-switcher UI into the framework root instead of replacing them or adding a second locale context. Keep route metadata canonical and reuse page modules across locales.
+For React Router projects, prefer converging on one locale contract owned by `.fimo/config.json`, `fimoRoutes()`, and `FimoLink`. Move existing providers and language-switcher UI into the framework root instead of replacing them or adding a second locale context. Keep route metadata canonical and reuse page modules across locales.
 
 If adopting the standard helper would change established public URLs, do not silently rewrite them. Keep the custom router temporarily, pass its resolved locale to `<FimoProviders locale={locale}>`, and ask the user to choose the canonical URLs and redirects before normalizing the route table.
 
@@ -86,7 +86,7 @@ import { FimoLink } from 'fimo/react-router';
 <FimoLink to="/pricing" locale="es">Spanish pricing</FimoLink>
 ```
 
-`FimoLink` localizes absolute internal paths according to `fimo-config.json#i18n.routing`. It leaves relative, hash, query-only, and external URLs alone. Use React Router's raw `Link` only when you intentionally want to bypass Fimo's locale behavior.
+`FimoLink` localizes absolute internal paths according to `.fimo/config.json#i18n.routing`. It leaves relative, hash, query-only, and external URLs alone. Use React Router's raw `Link` only when you intentionally want to bypass Fimo's locale behavior.
 
 Read the active locale with `useLocale()` when component logic needs it:
 
@@ -125,5 +125,5 @@ When using custom routing, also provide localized internal-link helpers in that
 ## What Not To Do
 
 - Do not create `src/pages/__localized/*` copies just for locales.
-- Do not duplicate every route in `fimo-config.json` per locale.
+- Do not duplicate every route in `.fimo/config.json` per locale.
 - Do not use `/es` as a normal canonical route when `es` is an enabled locale.

package/assets/skills/fimo-code/references/setup-plain-vite.md

@@ -85,16 +85,16 @@ Notes:
 ```
 
 The `seo` plugin rewrites `<title>`, og, twitter, canonical tags from
-`fimo-config.json#seo` at build time. You can leave a placeholder title in
+`.fimo/config.json#seo` at build time. You can leave a placeholder title in
 `index.html`; it'll be replaced.
 
 ## File: `src/main.tsx`
 
-`FimoProviders` (and the runtime primitives it wraps) require **two** contexts:
-a React Router `<Router>` ancestor (it reads `useLocation`/`useNavigate`) and a
-`@tanstack/react-query` `<QueryClientProvider>` (its internal
-`RefreshContentProvider` calls `useQueryClient`). Mount both around
-`<FimoProviders>`:
+`FimoProviders` requires a React Router `<Router>` ancestor (it reads
+`useLocation`/`useNavigate`). It reuses a host app's
+`@tanstack/react-query` client when one exists and supplies a stable fallback
+for adopted SPAs. This recipe still mounts an explicit provider so the app owns
+the shared cache and its configuration:
 
 ```tsx
 import { FimoProviders } from 'fimo/react-router';
@@ -122,8 +122,9 @@ createRoot(document.getElementById('root')!).render(
 
 `react-router` and `@tanstack/react-query` are peer dependencies of `fimo`;
 both are in the install command above. `FimoProviders` is exported only from
-the `fimo/react-router` adapter barrel — there is no router-free (or
-react-query-free) provider surface in the package today.
+the `fimo/react-router` adapter barrel. Keep the explicit QueryClientProvider
+when the app needs custom query defaults or shared cache access; adopted SPAs
+can omit it.
 
 ## File: `src/App.tsx`
 
@@ -139,7 +140,7 @@ export function App() {
 }
 ```
 
-## File: `fimo-config.json`
+## File: `.fimo/config.json`
 
 ```json
 {
@@ -164,7 +165,7 @@ this version field. It also never injects the React Router plugin: in a
 framework-mode project that `reactRouter()` plugin is added by your own
 `vite.config.ts`, not by `fimo/vite`.
 
-## File: `.fimo.settings.json`
+## File: `.fimo/project.json`
 
 ```json
 {
@@ -221,6 +222,6 @@ shows the **deployed** app, not the localhost dev server.
 ## What to do next
 
 - Add a sitemap: pass `fimo({ seo: true, sitemap: true })` and set
-  `fimo-config.json#seo.url` to your production base URL.
+  `.fimo/config.json#seo.url` to your production base URL.
 - Look up exports: see `references/ui.md`.
 - Use schema content: see `references/content.md`.

package/assets/skills/fimo-code/references/setup-react-router.md

@@ -100,6 +100,11 @@ when to render them, and how.
 
 ## File: `src/root.tsx`
 
+The explicit `QueryClientProvider` below is the canonical template shape so the
+app can configure query defaults such as `staleTime`. Adopted SPAs can omit it:
+`FimoProviders` reuses an ancestor client when present and supplies a stable
+fallback otherwise.
+
 ```tsx
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
 import { FimoProviders, FimoScripts, loadFimoMetaData, buildFimoMeta, fimoHtmlProps } from 'fimo/react-router';
@@ -161,7 +166,7 @@ export default fimoRoutes(routes) satisfies RouteConfig;
 Page filenames are your choice; the scaffold uses PascalCase (e.g. `Index.tsx`,
 `Privacy.tsx`).
 
-`fimoRoutes()` is Fimo's React Router helper for path-prefix locales. It is a no-op for single-locale projects and expands concrete locale aliases when `fimo-config.json#i18n.locales` contains more locales. Custom routers can ignore this helper and pass their own locale to `<FimoProviders locale={locale}>`; see `references/locales.md`.
+`fimoRoutes()` is Fimo's React Router helper for path-prefix locales. It is a no-op for single-locale projects and expands concrete locale aliases when `.fimo/config.json#i18n.locales` contains more locales. Custom routers can ignore this helper and pass their own locale to `<FimoProviders locale={locale}>`; see `references/locales.md`.
 
 ## File: `src/pages/Index.tsx`
 
@@ -177,7 +182,7 @@ export default function HomePage() {
 }
 ```
 
-## File: `fimo-config.json`
+## File: `.fimo/config.json`
 
 ```json
 {
@@ -195,7 +200,7 @@ export default function HomePage() {
 }
 ```
 
-## File: `.fimo.settings.json`
+## File: `.fimo/project.json`
 
 ```json
 {
@@ -263,9 +268,9 @@ changes after a `fimo deploy` (the local dev server is localhost-only).
 ## What to do next
 
 - Add more routes: extend `src/routes.ts`, create matching `src/pages/*.tsx`,
-  add route entries in `fimo-config.json#routes`.
+  add route entries in `.fimo/config.json#routes`.
 - Add a sitemap: pass `fimo({ sitemap: true })` (opt-in, off by default; the
   canonical template enables it). To customize the base URL, set
-  `fimo-config.json#seo.url`.
+  `.fimo/config.json#seo.url`.
 - Override SEO per route: see `references/seo-overrides.md`.
 - Look up an export: see `references/api.md`.

package/assets/skills/fimo-code/references/ui.md

@@ -17,6 +17,7 @@ Use these to render content-type field values consistently. They carry source me
 | `<Video>`       | Schema `media` video fields                                         | `<Video value={post.heroVideo} />`                            |
 | `<Date>`        | Schema date fields                                                  | `<Date value={post.publishDate} />`                           |
 | `<Boolean>`     | Schema boolean fields                                               | `<Boolean value={product.inStock} />`                         |
+| `<Json>`        | Schema `json` fields                                                | `<Json value={post.metadata} as="pre" />`                     |
 | `` fimo`...` `` | Compose tracked values (mix `t()` + schema text)                    | ``<Text value={fimo`${t('by')} ${post.author}`} />``          |
 | `useLabels()`   | `t('key')` hook                                                     | see `references/labels.md`                                    |
 | `useLocale()`   | Active locale and route locale metadata                             | see `references/locales.md`                                   |
@@ -26,9 +27,10 @@ Use these to render content-type field values consistently. They carry source me
 1. **Schema text → `<Text>`**, never `<h1>{post.title}</h1>`.
 2. **Schema media → `<Image>` / `<Video>`**, never `<img src={post.coverImage.url} />`. Provide `width` / `height` when known so Fimo can optimize and reserve layout space.
 3. **Non-schema images** (decorative, hard-coded URLs, generated assets referenced directly) → `<StaticImage>`. Never hand-construct a `FimoMedia` to feed `<Image>`.
-4. **Label text → `<Text value={t('key')} />`**, not `<h1>{t(...)}</h1>`. Label values live in the DB for `i18n.defaultLocale` from `fimo-config.json` unless a non-default locale is explicitly targeted. See `references/labels.md`.
+4. **Label text → `<Text value={t('key')} />`**, not `<h1>{t(...)}</h1>`. Label values live in the DB for `i18n.defaultLocale` from `.fimo/config.json` unless a non-default locale is explicitly targeted. See `references/labels.md`.
 5. **Mixed schema + translated text** → the `` fimo`...` `` template literal inside `<Text>`.
 6. **Never hand-roll richtext rendering** — always `<RichText>`. To restyle a node, pass `components={{ heading: ..., link: ..., ... }}`.
+7. **Schema `json` → `<Json>`**, not a hand-rolled `<pre data-fimo-source={getFimoSource(post.metadata)}>{JSON.stringify(post.metadata)}</pre>`. Default renders as a `<span>`; pass `as="pre"` (with a `whitespace-pre-wrap` class) for a formatted block, or a children render function for custom display of specific keys.
 
 ## App code conventions
 
@@ -78,6 +80,7 @@ The template uses **Vite + React 19 + TypeScript + Tailwind v4 + shadcn/ui + rea
 
 - Raw `<a href>` for internal nav → use `<FimoLink>` for locale-aware paths or React Router `<Link>` / `<NavLink>` only when intentionally bypassing Fimo locale helpers.
 - Raw `<img>` for schema media → use `<Image>` (with width/height).
+- Raw `<pre data-fimo-source={getFimoSource(...)}>` for schema `json` fields → use `<Json>`.
 - Hardcoded strings in JSX → wrap in `t('key')` and add the DB value with `fimo labels set`.
 - Calling `t()` with a dynamic first argument → key must be a string literal.
 - Editing generated `.ts` files under `src/schemas/` or `src/forms/` → regenerate them through `fimo validate` or the matching push command.

package/assets/skills/fimo-migration/references/workflow.md

@@ -6,7 +6,7 @@ Use this as the phase contract for complete migrations.
 
 1. Confirm the target path.
 2. If the target path is missing, create exactly one Fimo project there.
-3. If it has `.fimo.settings.json`, reuse it.
+3. If it has `.fimo/project.json` or the legacy `.fimo.settings.json`, reuse it.
 4. If it is non-empty and not a Fimo project, stop and ask for a target path.
 5. Never overwrite user work outside generated migration folders without reading
    the existing files first.

package/assets/skills/fimo-migration/scripts/build-canonical-manifest.mjs

@@ -110,7 +110,7 @@ function buildCanonicalManifest({ projectRoot, urlLedger, urlLedgerPath, sourceL
     forms,
     redirects: normalizeItems(sourceLedger?.redirects, 'redirect'),
     locales: normalizeItems(sourceLedger?.locales, 'locale'),
-    seo: normalizeSeo(urlLedger),
+    seo: normalizeSeo(urlLedger, projectRoot),
     unsupported: normalizeItems(sourceLedger?.unsupported, 'unsupported'),
     unresolved: mergeItems([
       ...normalizeUnresolved(sourceLedger?.unresolved),
@@ -326,14 +326,15 @@ function normalizeUrlForms(forms) {
   }));
 }
 
-function normalizeSeo(urlLedger) {
+function normalizeSeo(urlLedger, projectRoot) {
+  const configPath = resolveProjectConfigPath(projectRoot);
   return asArray(urlLedger?.pages).map((page) => ({
     id: `seo:${page.route}`,
     status: 'discovered',
     route: page.route,
     sourceUrls: compact([page.url]),
     sourceFiles: compact([page.artifacts?.html]),
-    targetFiles: ['fimo-config.json'],
+    targetFiles: [configPath],
     confidence: numberOr(page.confidence, 0.7),
     title: page.seo?.title ?? page.title ?? null,
     description: page.seo?.description ?? null,
@@ -341,6 +342,34 @@ function normalizeSeo(urlLedger) {
   }));
 }
 
+function resolveProjectConfigPath(projectRoot) {
+  if (fs.existsSync(path.join(projectRoot, '.fimo/project.json'))) {
+    return '.fimo/config.json';
+  }
+  if (fs.existsSync(path.join(projectRoot, '.fimo.settings.json'))) {
+    if (fs.existsSync(path.join(projectRoot, 'fimo-config.json'))) {
+      return 'fimo-config.json';
+    }
+    if (fs.existsSync(path.join(projectRoot, 'fimo.config.json'))) {
+      return 'fimo.config.json';
+    }
+    return 'fimo-config.json';
+  }
+  if (
+    fs.existsSync(path.join(projectRoot, '.fimo/config.json')) ||
+    fs.existsSync(path.join(projectRoot, '.fimo/agents'))
+  ) {
+    return '.fimo/config.json';
+  }
+  if (fs.existsSync(path.join(projectRoot, 'fimo-config.json'))) {
+    return 'fimo-config.json';
+  }
+  if (fs.existsSync(path.join(projectRoot, 'fimo.config.json'))) {
+    return 'fimo.config.json';
+  }
+  return '.fimo/config.json';
+}
+
 function normalizeUnresolved(items) {
   return asArray(items).map((item, index) => {
     if (typeof item === 'string') {

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

@@ -9,6 +9,12 @@ The AI chat opens as a floating panel by default. You can dock it to the left or
 3. Press **Enter** or click the **send button**.
 4. The AI responds in a stream. You see tool status badges appear as it works, and the preview updates automatically.
 
+## Responding to Choices and Forms
+
+The AI can place choices, cards, tables, images, and contextual actions directly in its reply. Optional suggestions do not interrupt the conversation.
+
+When the AI needs an answer before it can continue, it shows a form in the chat and waits for your response. Complete the form for a structured answer, or reply normally in the chat to answer in your own words.
+
 ## Attaching Context
 
 Give the AI more to work with:
@@ -33,6 +39,14 @@ To halt the AI mid-generation, use the **Stop button** in the input bar — whil
 
 While the AI works, you see small badges in the chat showing what it is doing. Each badge displays a tool name and its current status. Examples include reading files, writing code, searching your project, or generating images. These badges help you follow along without needing to understand the technical details.
 
+## Reviewing Changes That Could Not Merge
+
+Chat changes are prepared separately and then applied to the environment you are viewing. Most changes merge automatically.
+
+If the project changed in the same place while the AI was working, the response shows a **Review changes** card and an attention banner above the chat input. The banner remains visible when floating chat history is collapsed.
+
+Choose **Auto fix** or keep chatting to let Fimo continue in the retained proposal, resolve the conflict, and retry the merge. Choose **Review manually** to inspect and resolve the proposal yourself. Discarding leaves the current environment unchanged and permanently removes the proposal.
+
 ## Tips for Better Results
 
 - **Be specific**: Mention colors, layout, text content, and spacing when you can.

package/assets/skills/fimo-studio/references/custom-domains.md

@@ -12,7 +12,7 @@ If you're driving Fimo from the terminal, the equivalent commands are `fimo doma
 ## Adding a Custom Domain
 
 1. Open **Settings** from the top navigation bar (gear icon), alongside Preview, Content, Assets, Agents, and Analytics.
-2. In the Settings menu on the left, select **Domains** (globe icon) — listed with General, SEO, and Audit log.
+2. In the Settings menu on the left, select **Domains** (globe icon) — listed with General and SEO.
 3. Click the **Add domain** button (+ icon) in the top-right of the panel. (When domain purchase is enabled, a **Buy domain** button with a shopping-cart icon sits next to it.)
 4. A drawer opens. Type or select a domain — you can enter a subdomain or an apex domain. Domains your organization already owns appear in an autocomplete dropdown, and Fimo checks availability live as you type. For an apex domain, a checkbox lets you also redirect it to the `www` subdomain (on by default). Confirm to add it.
 5. A DNS table appears showing the record(s) you need to add. For a **subdomain** it's a single CNAME record:

package/assets/skills/fimo-studio/references/preview-and-responsive.md

@@ -47,4 +47,4 @@ The preview is one of several workspaces, and only one is shown at a time. Switc
 - **Alt+4** -- Code
 - **Alt+5** -- Settings
 
-When the Preview workspace is open, the visual editor and the changes panel can appear alongside it as the preview's side panels.
+When the Preview workspace is open, the visual editor can appear alongside it as a preview side panel.

package/assets/skills/fimo-studio/references/publish-and-deploy.md

@@ -14,7 +14,13 @@ Every change you make is automatically saved to your project, but saved changes
 
 To push your latest changes live, open the publish panel from the header **Publish** button and click **Publish** inside it again. It redeploys with your latest code and content.
 
-> **Tip:** Before your site has ever been published, the chat shows a one-click **Publish** button that deploys immediately without opening the panel.
+> **Tip:** After completing relevant work, the AI may offer a one-click **Publish** callout in chat. It appears only when publishing is available; the header **Publish** control remains the reliable path at any time.
+
+## Publishing Changes That Need Review
+
+If an AI chat change cannot merge automatically, use the response's **Review changes** card first. Resolve the conflicts and merge the proposal into `main`.
+
+When the AI requested publication, the review dialog offers **Merge and publish** after the conflicts are resolved. Publishing starts only after the merge succeeds, so unresolved or discarded proposals never reach the live site.
 
 ## What You See When You Click Publish
 
@@ -23,6 +29,7 @@ The header **Publish** button itself only shows the label "Publish" (or a spinne
 - **"Not published yet"** — Your site has never been published. The **Publish** button inside the panel is ready to click.
 - **"Publishing"** — Publishing is in progress. A spinner and a **Publishing** status badge show while it builds, and the button is disabled.
 - **"Published"** — Your site is live. A **Published** status badge appears, your live URL is listed under a **Published site** heading as a clickable link, and a **Last published** date and time is shown.
+- **"Couldn't publish · N issues"** — Project validation found issues that must be fixed first. Choose **Fix with Fimo** to send the safe issue list to the project chat and ask Fimo to repair it.
 
 ## Key Concepts