fimo 0.11.0-staging.1 → 0.11.0-staging.11

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

@@ -163,6 +163,7 @@ 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`.

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

@@ -27,7 +27,7 @@ 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.

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:
@@ -37,9 +43,9 @@ While the AI works, you see small badges in the chat showing what it is doing. E
 
 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 instead. Open it to inspect the proposal, resolve any conflicts, and merge when it is ready. Until you merge it, the proposal is not part of the environment and later chat messages will not see it.
+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.
 
-Discarding the merge leaves the current environment unchanged and keeps the proposal separate.
+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
 

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,7 @@ 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
 
@@ -29,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
 

package/assets/starters/fimo-site/manifest.json

@@ -0,0 +1,64 @@
+{
+  "name": "fimo-site",
+  "version": 1,
+  "description": "A content-led site with a homepage, contact form, labels, and manual review agents.",
+  "singletons": [
+    {
+      "type": "HomePage",
+      "data": {
+        "eyebrow": "Field notes",
+        "title": "Your website, ready to edit.",
+        "intro": {
+          "type": "doc",
+          "content": [
+            {
+              "type": "paragraph",
+              "content": [
+                {
+                  "type": "text",
+                  "text": "This starter is real website content. Edit the copy in Studio, change the code with your favorite agent, and keep both surfaces in sync."
+                }
+              ]
+            }
+          ]
+        },
+        "primaryCtaLabel": "Read the field notes",
+        "primaryCtaHref": "#stories",
+        "featured": [
+          {
+            "label": "Start here",
+            "title": "A calmer content workflow",
+            "summary": "Keep content, code, previews, and the team in one editable project.",
+            "href": "#stories"
+          },
+          {
+            "label": "For agents",
+            "title": "Build once, keep iterating",
+            "summary": "Give your coding agent a real CMS surface to work with after the first deploy.",
+            "href": "#stories"
+          },
+          {
+            "label": "For teams",
+            "title": "Make every edit reviewable",
+            "summary": "Let teammates shape the site without asking them to open a code editor.",
+            "href": "#stories"
+          }
+        ],
+        "contactHeading": "Make something useful",
+        "contactIntro": "Tell us what you are building and we will help you find the shortest path from first draft to a site your team can own."
+      }
+    }
+  ],
+  "labels": [
+    { "key": "nav.stories", "value": "Field notes", "locale": "en" },
+    { "key": "nav.contact", "value": "Start a conversation", "locale": "en" },
+    { "key": "hero.scroll", "value": "Explore the starter", "locale": "en" },
+    { "key": "contact.name", "value": "Your name", "locale": "en" },
+    { "key": "contact.email", "value": "Email address", "locale": "en" },
+    { "key": "contact.message", "value": "What are you building?", "locale": "en" },
+    { "key": "contact.submit", "value": "Send a note", "locale": "en" },
+    { "key": "contact.sent", "value": "Thanks. Your note is on its way.", "locale": "en" },
+    { "key": "contact.failed", "value": "That did not send. Please try again.", "locale": "en" }
+  ],
+  "forms": ["contact"]
+}

package/assets/starters/fimo-site/template/.fimo/agents/content-guide/GOAL.md

@@ -0,0 +1,8 @@
+# Content guide
+
+Inspect the site's content model and homepage copy. Suggest a small editorial
+backlog that makes the site more useful to its intended audience.
+
+Return three suggestions, each with the content type or field it touches and
+why it matters. Use the existing content as evidence. Do not write files,
+change entries, or create labels.

package/assets/starters/fimo-site/template/.fimo/agents/content-guide/capabilities.yaml

@@ -0,0 +1,2 @@
+- files:read
+- cms:read

package/assets/starters/fimo-site/template/.fimo/agents/content-guide/config.yaml

@@ -0,0 +1,9 @@
+# Keep starter agents manual-only. Adding a schedule or webhook and pushing to
+# main registers an automation for the project.
+version: 1
+description: 'Suggest useful editorial improvements from the existing CMS content.'
+data_sources:
+  - main
+
+triggers:
+  - type: manual

package/assets/starters/fimo-site/template/.fimo/agents/site-review/GOAL.md

@@ -0,0 +1,14 @@
+# Site review
+
+Review the starter project as a teammate would before the first publish.
+
+Read the declared routes, the CMS content, the labels, and the public site.
+Return a short report with:
+
+- one thing that already feels clear;
+- the three highest-value improvements;
+- any missing content or broken route you can prove;
+- one next action that a human or coding agent can review.
+
+This is a read-only review. Do not edit files, change CMS content, create
+branches, or publish anything.

package/assets/starters/fimo-site/template/.fimo/agents/site-review/capabilities.yaml

@@ -0,0 +1,4 @@
+- files:read
+- cms:read
+- i18n:read
+- net:fetch

package/assets/starters/fimo-site/template/.fimo/agents/site-review/config.yaml

@@ -0,0 +1,9 @@
+# Keep starter agents manual-only. Adding a schedule or webhook and pushing to
+# main registers an automation for the project.
+version: 1
+description: 'Review the starter site and return a concise, read-only launch report.'
+data_sources:
+  - main
+
+triggers:
+  - type: manual

package/assets/starters/fimo-site/template/src/forms/contact.json

@@ -0,0 +1,14 @@
+{
+  "name": "contact",
+  "label": "Start a conversation",
+  "fields": {
+    "name": { "type": "text", "label": "Your name", "required": true },
+    "email": { "type": "email", "label": "Email address", "required": true },
+    "message": {
+      "type": "textarea",
+      "label": "What are you building?",
+      "required": true,
+      "validation": { "minLength": 10, "maxLength": 2000 }
+    }
+  }
+}